## 设计原则

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

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。