mjava-ai/CLAUDE.md

mjava-ai

Java 后端基座 + 客户子项目仓库。Spring Boot 2.2.13 + MySQL，第一阶段不引入 Redis/Docker。

开发前必读

• 仓库基线：openspec/specs/project-baseline.md（代码锚点 + 子项目清单）
• 通用规范：/Users/malk/Desktop/Tech/claude/后端/mjava-baseline.md（11 章，权威）
• 宜搭特化：/Users/malk/Desktop/Tech/claude/后端/yida-serverside.md

OpenSpec 工作流（opsx）

任何规范变更或功能新增，走 change 流程：

命令	用途
/opsx:explore	在改动前做需求/约束梳理
/opsx:propose	新建 change（proposal+design+spec+tasks 四件套）
/opsx:apply	执行 tasks.md 的实现步骤
/opsx:archive	完成后归档到 openspec/changes/archive/

现有 change 状态：

• changes/archive/2026-04-18-extract-dingtalk-standard-api/ — 已归档（crypto-utils 稳态 spec 合并）
• changes/add-observability-foundation/ — 代码已实施，待生产冒烟
• changes/init-project-baseline/ — 基线沉淀，仅 mvn compile 验证阻塞在 Maven 未装
• changes/extend-yida-api-coverage/ — Phase B.1 最高优先级：宜搭表单+流程 API 对齐
• changes/extend-dingtalk-contacts-api/ — Phase B.1：钉钉通讯录 API 对齐
• changes/add-request-auth-replay-guard/ — Phase B.2：基座请求鉴权 + 防重放（mjava-com 的前置依赖）
• changes/add-mjava-pro/ — Phase C：多客户单部署（待 B 完成后）
• changes/add-mjava-com/ — Phase C：通用能力 BaaS（待 B 完成后，依赖 add-request-auth-replay-guard）

快速操作

• 新客户接入：复制 mjava-mcli 模板，详见基线文档第 9 章
• 本地编译：mvn -pl mjava-{module} -am clean compile
• 打包：mvn -pl mjava-{module} -am clean package -Dmaven.test.skip=true

严禁

• ❌ 引入三方 SDK（钉钉/宜搭/飞书 SDK 都禁）—— 统一用 UtilHttp
• ❌ 每请求重新拉 token —— 统一走 UtilToken 缓存
• ❌ 硬编码 appKey/appSecret —— 读 application-{profile}.yml
• ❌ 绕过 JPA 写原生 SQL 字符串拼接

当前活跃目录位置

/Users/malk/server/cur/mjava-ai/（2026-04-18 从 /Users/malk/server/mjava-ai 迁入 cur 层）