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

1. pom 依赖调整

• 1.1 parent pom.xml 的 <dependencies> 段增加 spring-boot-starter-actuator（由 Spring Boot BOM 托管版本）
• 1.2 parent pom.xml 的 <dependencies> 段增加 org.springdoc:springdoc-openapi-ui:1.6.15
• 1.3 parent pom.xml 移除孤立的 <springfox-boot-starter.version> property

备注：mjava/pom.xml 的 <dependencies> 为空，实际依赖在 parent pom 集中声明，已改为在 parent pom 增加。

2. TraceId 实现

• 2.1 新建 mjava/src/main/java/com/malk/filter/TraceIdFilter.java：OncePerRequestFilter + MDC 写/清 + 响应头回写
• 2.2 新建 mjava/src/main/java/com/malk/core/MdcTaskDecorator.java：TaskDecorator 拷贝 MDC 到子线程
• 2.3 改造 AsyncConfig.java：getAsyncExecutor() 和 aliworkTaskExecutor 两个线程池都 setTaskDecorator(new MdcTaskDecorator())
• 2.4 logback-spring.xml 的 log.pattern 在 [%thread] 后追加 [%X{traceId:-}]

3. OpenAPI 配置

• 3.1 新建 mjava/src/main/java/com/malk/config/OpenApiConfig.java：@ConditionalOnProperty(name="swagger.enable", havingValue="true") 条件加载
• 3.2 application.yml 增加 springdoc.api-docs.enabled / springdoc.swagger-ui.enabled 与 swagger.enable 绑定
• 3.3 application-dev.yml 设 swagger.enable: true 让开发环境默认开

4. Actuator 配置

• 4.1 application.yml 增加 management.endpoints.web.exposure.include: health,info + management.endpoint.health.show-details: when-authorized
• 4.2 ⏳ 启动后手动验证 health 端点（需在 IDE 里启 mjava-guangming 或 mjava-mcli）

5. 验证

• 5.1 openspec validate add-observability-foundation --strict 通过
• 5.2 ⏳ IDE 里 Rebuild Project + 启动冒烟：
  • 访问 http://<host>:<port>/api/actuator/health 返回 {"status":"UP"}
  • 访问 http://<host>:<port>/api/swagger-ui.html（dev profile）看到交互文档
  • 任意请求日志中出现 [traceId-32位十六进制] 字段
  • curl -H "X-Trace-Id: test-123" ... 响应头回带 X-Trace-Id: test-123

冒烟指南

启动后最简验证脚本：

# 1. 健康检查
curl -i http://localhost:9001/dev/actuator/health

# 2. TraceId 自动生成
curl -i http://localhost:9001/dev/actuator/info | grep -i "x-trace-id"

# 3. TraceId 透传
curl -i -H "X-Trace-Id: my-custom-id" http://localhost:9001/dev/actuator/info | grep -i "x-trace-id"

# 4. Swagger UI
open http://localhost:9001/dev/swagger-ui.html