> 状态（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`