baiyue-firstleg/common-openapi/AGENTS.md

Common OpenAPI 模块指引

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

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

职责边界

• 为 Spring MVC 服务提供 SpringDoc/OpenAPI 自动配置和统一文档元数据。
• 不在这里维护具体业务接口契约；服务专属 OpenAPI 文件留在对应服务资源目录。

快速索引

功能	入口
自动配置	src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java
baiyue.openapi 配置项	src/main/java/com/baiyue/common/openapi/OpenApiProperties.java
自动配置注册	src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
长整型 OpenAPI 字符串契约	src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java
PDA OpenAPI 分组	src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java 的 pda GroupedOpenApi；固定匹配 /api/pda/**，合同测试 src/test/java/com/baiyue/common/openapi/PdaOpenApiGroupContractTest.java

修改与验证

• 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在 gateway/。
• PDA Controller 必须进入独立 pda 分组；新增或改名 /api/pda/** 路径时同步检查分组合同和目标服务 OpenAPI，不得混入平台或商户分组。
• 普通业务成功和失败在 OpenAPI 中统一描述为 HTTP 200，并提示调用方检查 body code；只为 Security、协议、基础设施、Warehouse 503、Audit 202 和 Event Bridge 内部鉴权等真实状态边界声明非 200 响应。
• 配置项变化直接同步代码、全部消费者和 Nacos 模板；当前正式配置不保留旧配置键兼容。若已有不可变外部配置契约，先单独定义升级规则。
• 从父目录运行 mvn -pl common-openapi -am test。
• 所有 Java Long/long 在 OpenAPI 中统一声明为字符串，与 HTTP JSON 序列化保持一致。