diff --git a/AGENTS.md b/AGENTS.md index d2140d24f..57fb7d324 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,10 +107,10 @@ - 跨服务修改先检查调用方 `client/`、被调用方 Controller/DTO、`src/main/resources/openapi/` 和双方契约测试；禁止共享领域 Entity。 - 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 `rg` 定向查找符号及旧参数形态，并同步更新 `src/main/`、`src/test/`、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。 - 所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`；每个持久化服务只允许在启动类使用一次服务根包 `@MapperScan(..., annotationClass = Mapper.class)`，不得新增子域包白名单或分散的 `*MapperConfiguration`。新增、移动 Mapper 或修改扫描配置后运行 `node scripts/mapper-scan-contract.mjs`；全量后端回归已在 Maven 前执行该门禁时复用结果，输入未变不重复执行。 -- 平台后台存在正式列表页时，`*:list` 同时授权列表、详情及只读辅助接口；`create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等操作保持独立。当前未上线，不兼容旧独立 `*:view`，Controller 不得使用 `hasAnyAuthority(list, view)`，OpenAPI 和角色初始化只保留 `*:list`。 +- 平台后台存在正式列表页时，`*:list` 同时授权列表、详情及只读辅助接口；`create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等操作保持独立。当前正式权限契约不保留旧独立 `*:view`；Controller 不得使用 `hasAnyAuthority(list, view)`，OpenAPI 和角色初始化只保留 `*:list`。若外部已有不可变权限契约，先按当前对话建立单独兼容规则。 - 供应商查询接口固定只使用 `platform:supplier:list`；IAM 中 `platform:supplier:list` 是正式菜单资源，`platform:supplier:view` 必须停用/移除，不得重新提升或兼容。 - 权限语义变更必须同步 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。 -- 数据库只访问所属服务库。模块表结构位于 `/src/main/resources/db/`；当前开发阶段直接更新最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql`，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作现有结构来源和开发追溯，部署说明见 `deploy/sql/README.md`。 +- 数据库只访问所属服务库。模块表结构位于 `/src/main/resources/db/`；开发环境按最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql` 收敛，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作结构来源和追溯，部署说明见 `deploy/sql/README.md`；生产升级另按明确发布规则处理。 - 后端同样遵守根指引中的“开发数据和上传文件可丢弃”边界：不得为现有开发库孤儿文件、旧文件归属或历史部分失败新增删除补偿接口、兼容复用、回填或清理链路；只修复当前正式上传与持久化路径，既有开发文件由人工重新上传。 - 通用配置在 `config/nacos/{local,cn}/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。 - Java 签名变更的最低编译门禁是 `mvn -pl -am test-compile`，它必须在部署前完成并覆盖测试源码；有行为变化时继续运行 `mvn -pl -am test`。`-DskipTests` 可跳过测试执行但仍须保留测试编译，`-Dmaven.test.skip=true` 会跳过测试编译，不得作为签名变更的交付验证。全量验证仍使用 `mvn -DskipTests validate`、`mvn test`；不要在本地启动 Java/Nacos/数据库，除非用户明确要求。 @@ -136,10 +136,10 @@ ## 业务域文档入口 - 订单与客户：`../docs/订单与客户/README.md`、`../docs/订单与客户/订单与客户头程订单闭环设计.md` -- 入库测量与计费：`../docs/入库测量与计费/README.md`、`../docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、需求确认清单及联调报告 -- 国内货柜履约：`../docs/国内货柜履约/README.md`、`../docs/国内货柜履约/国内货柜履约开工门禁.md`、`../docs/国内货柜履约/国内货柜履约开发规划.md`、`../docs/国内货柜履约/国内货柜履约需求确认表.md`、页面与原型清单 +- 入库测量与计费：`../docs/入库测量与计费/README.md`；流程细节按 `../docs/头程到尾程/README.md` 指向的当前阶段文档读取，需求确认和联调报告仅在历史追溯或验收证据任务中读取 +- 国内货柜履约：`../docs/国内货柜履约/README.md`、`../docs/国内货柜履约/报关资料与船期价格接入梳理.md`；开发规划、开工门禁、需求确认和验收材料已归档，只有历史追溯或验收证据任务才读取 - 海外仓业务：`../docs/海外仓业务/README.md`；海外入口 `gateway-overseas/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/` - 海外仓全流程：以正式 Controller、前端路由、权限、SQL 与跨区事件契约为范围依据；海外接柜、入仓、库存、库内服务、排车、出库、派送、一件代发、异常退回和客户回访进入 `lastleg-service/`，国内 SKU/箱唛及暂扣协同进入 `order/`、`firstleg/`、`common-event-contract/` - 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束 -全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。 +全量验收需要证据时再读取对应阶段报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。 diff --git a/common-core/AGENTS.md b/common-core/AGENTS.md index 277a9fa7d..0bd37d101 100644 --- a/common-core/AGENTS.md +++ b/common-core/AGENTS.md @@ -18,7 +18,7 @@ ## 修改与验证 -- 公共响应、错误码或基础实体变化会影响所有服务；先检索并同步修改全部消费者、测试和契约，当前开发阶段不保留旧序列化或数据库兼容分支。 +- 公共响应、错误码或基础实体变化会影响所有服务；先检索并同步修改全部消费者、测试和契约。当前正式模型不保留旧序列化或数据库兼容分支；若已有不可变外部契约，先单独定义升级规则。 - `ApiResponse.successful()` 只认字符串 `"200"`。不得恢复旧成功码 `"0"`，也不得把 `code` 改成数字；前端和 Feign 调用方都按字符串严格判断。 - `ResultCode.httpStatus` 保留错误分类元数据，但普通业务异常的实际 HTTP 状态由 `common-web/GlobalExceptionHandler` 统一收敛为 200；真实 HTTP 状态例外见 `../docs/统一响应约定改造方案-HTTP200.md`。 - 新能力只有被多个模块稳定复用时才放入本模块。 diff --git a/common-event-contract/AGENTS.md b/common-event-contract/AGENTS.md index 5f107b109..c1ce19dbe 100644 --- a/common-event-contract/AGENTS.md +++ b/common-event-contract/AGENTS.md @@ -29,7 +29,7 @@ ## 修改与验证 -- 所有字段与事件类型都视为跨仓公共契约；当前开发阶段不保留旧事件字段、旧版本或兼容解析，目标契约变化时直接修改当前模型，并同步更新 `event-bridge-service/`、国内生产者、尾程消费者和全部契约测试。 +- 所有字段与事件类型都视为跨仓公共契约；当前正式模型不保留旧事件字段、旧版本或兼容解析，契约变化时直接修改当前模型，并同步更新 `event-bridge-service/`、国内生产者、尾程消费者和全部契约测试。若存在不可变外部事件契约，先单独定义版本升级规则。 - 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。 - MQ 事件不携带用户 Access Token；生产者和消费者使用 MQ TLS/ACL 或内部服务身份，事件信封负责事件 ID、业务键、来源/目标区域、版本和 Payload 哈希。 - `OVERSEAS_CONTAINER_UNLOADED` 固定从 `OVERSEAS` 发往 `CN`，用于回传海外 PDA 卸柜完成及卸柜照片上传时间；预计报空时间由国内头程按照片上传时间加两天计算，实际报空时间允许后续补充。 diff --git a/common-openapi/AGENTS.md b/common-openapi/AGENTS.md index f91a255d8..41c12e6e7 100644 --- a/common-openapi/AGENTS.md +++ b/common-openapi/AGENTS.md @@ -20,6 +20,6 @@ - 调整分组、标题或安全方案时检查所有 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 模板，当前开发阶段不保留旧配置键兼容。 +- 配置项变化直接同步代码、全部消费者和 Nacos 模板；当前正式配置不保留旧配置键兼容。若已有不可变外部配置契约，先单独定义升级规则。 - 从父目录运行 `mvn -pl common-openapi -am test`。 - 所有 Java `Long/long` 在 OpenAPI 中统一声明为字符串，与 HTTP JSON 序列化保持一致。 diff --git a/common-security/AGENTS.md b/common-security/AGENTS.md index e9e566096..f53733015 100644 --- a/common-security/AGENTS.md +++ b/common-security/AGENTS.md @@ -10,7 +10,7 @@ | 功能 | 入口 | |---|---| | 安全链自动配置 | `src/main/java/com/baiyue/common/security/BaiyueSecurityAutoConfiguration.java` | -| JWT 解码模式 | `JwksJwtDecoderAutoConfiguration.java`（国内与海外统一 RS256/JWKS）；`HmacJwtDecoderAutoConfiguration.java` 仅作当前开发阶段清理前的旧实现定位，不得作为跨区域共享密钥方案 | +| JWT 解码模式 | `JwksJwtDecoderAutoConfiguration.java`（国内与海外统一 RS256/JWKS）；`HmacJwtDecoderAutoConfiguration.java` 仅作清理前的历史实现定位，不得作为跨区域共享密钥方案 | | JWT 过滤与声明映射 | `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java` | | 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java`；海外 PDA 仓范围由 `JwtClaimsMapper.java` 将 `overseas_warehouse_id` 映射为 `overseasWarehouseId` | | 会话与授权来源 | `AccessTokenSessionValidator.java`、`RedisAccessTokenSessionValidator.java`（国内登录 Token 即时失效）、`ClaimsAccessTokenSessionValidator.java`（海外访问 Token 本地短时 Claims）、`RedisTokenKeys.java` | diff --git a/finance/AGENTS.md b/finance/AGENTS.md index f1dad374a..b4b5d848d 100644 --- a/finance/AGENTS.md +++ b/finance/AGENTS.md @@ -3,7 +3,8 @@ ## 模块定位 - 本模块是独立财务服务，拥有客户结算条款、财务费用来源、CNY 账单与明细、客户资金账户及充值申请、应收款月度统计、客户对账确认、收款及分配、成本及分摊、账单修订、单据编号、幂等记录和财务审计状态。 -- 产品范围先读 `../../docs/财务管理/财务管理产品确认表.md` 与 `财务核心五页产品与接口验收契约.md`，跨服务契约再读 `Firstleg-Finance跨服务契约.md`；只有海外仓费用阶段 0A—0E 的设计或实现任务再读取 `../../docs/财务管理/海外仓费用统一接入阶段0技术契约.md`，并明确区分其目标 V2 协议与当前 V1 代码事实。专题 README、证据矩阵和测试环境报告只用于状态或验收问题，不作为普通开发首读。 +- 产品范围先读 `../../docs/财务管理/README.md`、`../../docs/财务管理/财务领域模型与跨服务契约.md` 和 `Firstleg-Finance跨服务契约.md`；产品确认表、五页验收契约和证据矩阵只在状态核对或验收任务中读取。只有海外仓费用阶段 0A—0E 的设计或实现任务再读取阶段技术契约，并明确区分其目标 V2 协议与当前 V1 代码事实。 +- 海外仓费用阶段 0 按需契约：`../../docs/财务管理/海外仓费用统一接入阶段0技术契约.md`；仅在该阶段的实现、接口或验收任务中读取，不作为普通 Finance 任务首读。 - Firstleg 拥有入库/柜次业务费用和履约事实，File 拥有凭证文件；Finance 通过内部接口读取或消费快照，不跨库查询，也不复制上游业务状态机。 ## 快速查询 diff --git a/gateway/AGENTS.md b/gateway/AGENTS.md index bc183918d..b6a5b83b3 100644 --- a/gateway/AGENTS.md +++ b/gateway/AGENTS.md @@ -17,4 +17,4 @@ - 新增路由同步检查本地/Nacos、App Scope、CORS、公开路径和 Swagger；不得暴露内部令牌接口。 - 订单与客户承载登录后 Admin/Client 入口；入库测量与计费接入到仓/测量/计费公开路由但保持内部测量接口隔离；国内货柜履约仅在 Controller、权限和公开访问域契约稳定后新增必要路由，内部 PDA、仓储和服务令牌接口继续不得经 Gateway 暴露。 -- 国内货柜履约先读 `../../docs/国内货柜履约/国内货柜履约开工门禁.md`；网关变更只服务已确认模块，不以路由提前暴露未完成能力。 +- 国内货柜履约先读 `../../docs/头程到尾程/README.md` 和 `../../docs/国内货柜履约/README.md`；网关变更只服务当前维护入口已确认的模块，不以路由提前暴露未完成能力。开工门禁属于归档资料，只有历史追溯时读取。 diff --git a/order/AGENTS.md b/order/AGENTS.md index b88897f4f..e6acbabff 100644 --- a/order/AGENTS.md +++ b/order/AGENTS.md @@ -25,7 +25,7 @@ | 入库号生成 | `config/InboundCodeModeProvider.java`、`mapper/InboundCodeSequenceMapper.java`、`repository/OrderRepository.java`、`service/OrderApplicationService.java` | | 下单计价渠道校验 | `service/OrderPricingChannelGuard.java`、`client/FirstlegPricingClient.java` | | 下单仓库主数据守卫 | `service/OrderMasterDataGuard.java`、`client/WarehouseClient.java`；校验公共收货仓、目的仓类型、状态、地址与收货能力，并保存服务端快照 | -| 统一订单七状态与操作映射 | `../../docs/统一订单主状态与操作契约.md`；`LOADED` 硬门禁和 `DELIVERED` 可信回传同时核对国内货柜履约需求确认表与开工门禁 | +| 统一订单七状态与操作映射 | `../../docs/统一订单主状态与操作契约.md`；`LOADED` 硬门禁和 `DELIVERED` 可信回传按当前契约及 `firstleg` 装柜/出仓入口核对。国内货柜履约需求确认表与开工门禁仅用于历史追溯 | | 货物内部查询与箱唛绑定来源 | `controller/InternalOrderCargoController.java` 向 Firstleg 批量提供箱唛生成的 SKU、尺寸与货件快照；`CargoLabelBinding.skuNo` 对 `ONE_CLICK_DROPSHIP` 为强制字段，`shipmentId` 只取对应货物行，不回退订单顶层字段。Firstleg 消费端为 `../firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.java`，变更两端 DTO 必须同步。 | | 智能装柜待审核候选内部查询 | `controller/InternalPendingReviewOrderController.java`、`service/PendingReviewOrderQueryService.java`、`dto/PendingReviewOrderDtos.java`；Firstleg 消费端为 `../firstleg/src/main/java/com/baiyue/firstleg/client/PendingReviewOrderClient.java`，契约 `src/main/resources/openapi/order-v1.yaml` | | 快照/Outbox | `service/`、`repository/`、`event/` | diff --git a/platform-bom/AGENTS.md b/platform-bom/AGENTS.md index 76ff7aa0a..459558e7a 100644 --- a/platform-bom/AGENTS.md +++ b/platform-bom/AGENTS.md @@ -16,5 +16,5 @@ ## 修改与验证 - 新增条目前先确认制品确实需要被其他仓库按固定版本消费；业务服务依赖不要放入 BOM。 -- 版本变化会影响所有 BOM 消费者；当前开发阶段直接同步本仓与尾程仓消费者，不保留旧坐标或旧版本兼容。 +- 版本变化会影响所有 BOM 消费者；按当前正式依赖基线同步本仓与尾程仓消费者，不为旧坐标或旧版本保留兼容分支。若已有不可变外部依赖，另行建立升级规则。 - 从父目录运行 `mvn -pl platform-bom -am validate`。