baiyue-firstleg/common-web/AGENTS.md

Common Web 模块指引

数据库访问与中文注释约束

• 强制遵守根 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 Controller → Service → Repository → Mapper，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
• 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。

职责边界

• 提供 Servlet Web 通用能力：请求链路标识、上下文和统一异常响应。
• 不放具体业务 Controller、路由或领域异常编排；业务错误通过 common-core 的契约表达。

快速索引

功能	入口
链路上下文	src/main/java/com/baiyue/common/web/CorrelationContext.java
请求 ID 过滤器	src/main/java/com/baiyue/common/web/CorrelationIdFilter.java
W3C Trace Context	src/main/java/com/baiyue/common/web/TraceParent.java；严格接收 version 00，响应 traceparent、X-Trace-Id 与 MDC traceId 使用同一 trace ID
Feign Trace 传播	FeignTraceRequestInterceptor.java、FeignTracePropagationAutoConfiguration.java；仅 Feign 存在时装配，optional 依赖不向无 Feign 服务传递
可靠事件 HTTP 客户端配置	EventDeliveryFeignConfiguration.java；由业务事件 Feign 客户端显式选择，在最终构建阶段固定连接/读取超时、禁止重定向和客户端内部重试，不作为全局自动配置
投递审计和指标装配	EventDeliveryObservationAutoConfiguration.java、EventDeliveryMetrics.java、EventDeliveryObservation.java；仅EventDeliveryProducer标记的业务Relay装配必需Journal/Metrics，其他JDBC服务不装配；定时采样固定事件白名单，Prometheus仅读内存快照，采样失败保留旧值并暴露失败/时间，错误标签不含载荷或令牌
RestClient Trace 传播	RestClientTraceInterceptor.java、RestClientTracePropagationAutoConfiguration.java；Spring 管理的 Builder 自动装配，原始 Builder 可显式复用拦截器
自动配置入口	src/main/java/com/baiyue/common/web/CommonWebAutoConfiguration.java；为只扫描自身包的服务注册异常处理器和 Correlation 过滤器
全局异常映射与业务失败指标	src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java；指标 baiyue.api.business.failures 按有限 code 标记
过滤器测试	src/test/java/com/baiyue/common/web/CorrelationIdFilterTest.java
异常响应测试	src/test/java/com/baiyue/common/web/GlobalExceptionHandlerTest.java
长整型 JSON 字符串序列化	src/main/java/com/baiyue/common/web/LongIdJacksonConfiguration.java

修改与验证

• 普通 BizException、参数校验和兜底系统异常统一返回 HTTP 200 + 非 "200" body code；查询参数/消息解析失败使用 A0400，Bean Validation 使用 A0422，不要再按 HTTP 400/422 判断业务失败。
• 网关/Servlet Security 的真实 401/403、协议或基础设施错误、Warehouse readiness 503 与 Audit 202 仍保留真实 HTTP 状态；完整边界见 ../docs/统一响应约定改造方案-HTTP200.md。
• 修改自动配置时验证 audit-service 等当前构建内、只扫描自身包的直接消费者仍能加载 GlobalExceptionHandler 和 CorrelationIdFilter；按根 POM 与实际依赖限定范围。
• 修改 Correlation ID 时同步检查当前请求头契约、线程上下文清理和日志链路。
• 入站 Trace 优先级固定为：合法单值 traceparent > 完全缺失 traceparent 时的 32 位非零十六进制 X-Trace-Id > 新 trace。只要 traceparent 已出现但重复、超长、格式非法或含全零 ID，就必须生成新 trace，不得回退信任 X-Trace-Id；请求 ID 独立按 X-Request-Id 校验或生成。
• 同步 Feign 出站固定先移除调用模板中的 X-Request-Id、X-Trace-Id、traceparent，再仅从当前 MDC 的合法请求 ID 和 trace ID 重建；traceparent 沿用当前 trace ID、每次调用生成新非零 span ID、flags 固定 01。不得从业务参数、远端返回头或无效 MDC 建立上下文；本能力不处理 Reactor、异步线程、重试、超时或 fallback。
• 同步 RestClient 出站统一覆盖 X-Request-Id、X-Trace-Id、traceparent，从当前 MDC 生成 child span；MDC 缺失或非法时安全新建 trace。不得从业务参数或远端响应头建立上下文，生产代码应使用 Spring 管理的 RestClient.Builder，原始 Builder 必须显式安装同一拦截器。
• 从父目录运行 mvn -pl common-web -am test。
• 所有对外 Long/long 值统一序列化为 JSON 字符串，避免 19 位雪花 ID 在浏览器中丢失精度；禁止业务模块重复添加局部转换器。