mjava-ai/openspec/changes/init-project-baseline/design.md

设计原则

本次基线沉淀的取舍原则：

1. 文档中心 vs 仓库内 spec：规范主体放在 /Users/malk/Desktop/Tech/claude/后端/mjava-baseline.md，因为那里能被跨仓库（包括 akds / mjava-guangming / 未来新客户项目）共享引用；仓库内 openspec/specs/project-baseline.md 只做指针 + 代码锚点，避免两地维护同一份规范。
2. 保障服务可用优先：现有三家客户（mcli/shunfeng/guangming）均在生产运行，本次任何动作不得影响已部署的 jar 行为。因此禁止任何代码改动、pom 改动、配置改动。
3. YAGNI：第一阶段明确不引入 Redis / Docker / 消息队列 / K8s / 链路追踪中间件。凡有"万一将来要用"的念头，都押后到有真实触发条件时再评估。

技术约束（已在基座固化，本次只是文档化）

维度	约定	实现锚点
HTTP 请求	统一 UtilHttp（Hutool 封装），禁三方 SDK	mjava/src/main/java/com/malk/utils/UtilHttp.java
Token 缓存	统一 UtilToken (TimedCache)，禁每请求重取	mjava/src/main/java/com/malk/utils/UtilToken.java
鉴权参数来源	只读 application-*.yml，禁硬编码/请求入参传入	@ConfigurationProperties
响应结构	Controller 返 McR<T>，第三方映射 VenR	com.malk.server.common/
全局异常	CatchException 拦截；业务抛 McException	com.malk.filter.CatchException
持久化	JPA + QueryDSL + BaseRepository + BasePo；禁 MyBatis 混用	com.malk.base/
链路追踪	TraceIdFilter + logback %X{traceId:-}	com.malk.filter.TraceIdFilter
配置管理	application-{dev,test,prod}.yml；敏感走环境变量	mjava/src/main/resources/

子项目接入模型

java-mcli (根 pom，packaging=pom)
 ├── mjava (基座 jar，无 repackage，可被依赖)
 ├── mjava-mcli (客户模板：最小化 Boot.java + application-*.yml)
 ├── mjava-shunfeng (客户：会议聚合)
 └── mjava-guangming (客户：钉钉 SSO 邮箱)

新客户接入 = 复制 mjava-mcli → 改 artifactId/port/context-path → 根 pom <modules> 追加。

启动类必须 @SpringBootApplication(scanBasePackages = {"com.malk"})，才能扫到 mjava 基座所有 bean。

Non-Goals（本次设计不覆盖）

• Redis 引入后的缓存重构方案
• Docker 镜像与 CI/CD 流水线
• 多租户与权限系统抽象
• 基于 mjava-baseline 做一份 IDE 模板或 archetype

这些话题等有真实需求时再各自立新 change。