mjava-ai/openspec/changes/add-observability-foundation/proposal.md

状态（2026-04-18 重新索引）：代码实施完成，待生产冒烟验证 tasks.md 中 4.2 健康端点启动冒烟、5.2 IDE 启动回归两项待执行；其余已 [x]。后续由 /opsx:apply 续做冒烟，完成后 /opsx:archive。

Why

mjava 基座作为新业务的标准脚手架，当前有三个可观测性短板：

1. 无 API 文档生成 —— swagger.enable: false 和 pom 里孤立的 springfox version 都说明"曾打算做但没落地"，新成员无法自助理解接口
2. 无请求链路 TraceId —— logback pattern 没有 %X{...}，生产故障排查全靠时间戳+人肉定位
3. 无健康检查端点 —— Docker/K8s 探针、运维监控没有抓手

这三件都是"标准 Spring Boot 项目的最低可观测性配置"，缺一样新业务就要自己补。应一次性在基座做完。

What Changes

• 新增 spring-boot-starter-actuator 依赖；开放 /actuator/health 和 /actuator/info，其他端点默认关闭
• 新增 springdoc-openapi-ui 1.6.x 依赖（选它而非 springfox 3：与 Spring Boot 2.2 兼容更稳，官方推荐路线）；新增 mjava/config/OpenApiConfig.java 受 swagger.enable 开关控制
• 新增 mjava/filter/TraceIdFilter.java + TaskDecorator 实现：从 header X-Trace-Id 读取或生成 UUID，写入 MDC 并回写响应头
• 修改 mjava/src/main/resources/logback-spring.xml 日志 pattern 增加 [%X{traceId}] 字段
• 移除 parent pom 中未使用的 <springfox-boot-starter.version> property（清理)

Capabilities

New Capabilities

• observability-foundation: 基座可观测性三件套（OpenAPI 文档、TraceId 链路、Actuator 健康检查）

Modified Capabilities

Impact

• pom 变更：mjava/pom.xml 增加 actuator + springdoc 依赖；parent pom 清理 springfox 属性
• 代码新增：OpenApiConfig.java (~30 行)、TraceIdFilter.java (~40 行)、AsyncTraceIdDecorator.java (~15 行)
• 配置变更：application.yml 打开 swagger.enable（默认仍 false，prod 可覆盖）；management.endpoints.web.exposure.include=health,info
• logback 变更：pattern 加 [%X{traceId:-}]
• 对业务模块影响：零破坏，业务不用改一行；重启即可看到效果
• URL 路径：因 server.servlet.context-path: /api，文档位于 /api/swagger-ui.html，健康检查位于 /api/actuator/health