html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-09-29 19:55:27 +08:00
parent 606abeb2c6
commit 407abd634c
2 changed files with 7 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
测试环境单机部署与配置契约.md
+2 -2
View File
@@ -2,7 +2,7 @@
更新日期：2026-09-29。当前只有 test，没有开发/生产环境。本文定义目标部署、切换与验收；具体路由、认证、投递契约唯一见[统一认证与服务通信契约](统一认证与服务通信契约.md)。 更新日期：2026-09-29。当前只有 test，没有开发/生产环境。本文定义目标部署、切换与验收；具体路由、认证、投递契约唯一见[统一认证与服务通信契约](统一认证与服务通信契约.md)。
状态：目标已确认，实现仍在迁移。第 0A 批资金消费者本地修复已完成；新 Gateway/Token/投递/Compose 尚未落地或发布。运行服务器、Nacos 发布值、主机资源和真实 MySQL 故障恢复尚未验证。 状态：目标已确认，统一 Gateway/Token、可靠直接投递、单 TEST Compose/Nacos 与四端统一入口已进入源码并完成分批本地验证，后端全量 Maven 回归已通过（4149项，12项跳过，0失败/错误）。尚未发布到测试环境；运行服务器、Nacos 发布值、主机资源和真实 MySQL 故障恢复尚未验证。
## 结论与范围 ## 结论与范围
按“头程和海外仓不再分区域部署、所有服务同机运行、取消独立事件接收服务与海外网关”设计。这里将“事件接收”对应为当前 `event-bridge-service`，不推定要删除业务通知、异步任务或消息队列。 按“头程和海外仓不再分区域部署、所有服务同机运行、取消独立事件接收服务与海外网关”设计。这里将“事件接收”对应为当前 `event-bridge-service`，不推定要删除业务通知、异步任务或消息队列。
@@ -46,7 +46,7 @@
## 测试环境跑通的验收标准 ## 测试环境跑通的验收标准
所有项目初始状态均为“待实施、待验证”。 下表是测试环境验收标准；本地实现与离线测试不代表环境验收，当前所有环境验收项均待验证。
| 验收项 | 操作与预期 | | 验收项 | 操作与预期 |
|---|---| |---|---|
统一认证与服务通信契约.md
+5 -5
View File
@@ -2,7 +2,7 @@
更新日期：2026-09-29。本文是已确认目标的唯一主契约；当前仅有测试环境，所有服务同机部署。部署与切换见[测试环境单机部署与配置契约](测试环境单机部署与配置契约.md)。 更新日期：2026-09-29。本文是已确认目标的唯一主契约；当前仅有测试环境，所有服务同机部署。部署与切换见[测试环境单机部署与配置契约](测试环境单机部署与配置契约.md)。
状态：整体迁移尚未完成。统一 Token/JWKS/Redis 会话、八类业务事件直连与结构化 ACK、有限重试及人工原事件重试已进入源码并完成分批本地验证。构建与部署已收敛为单 TEST 的13个服务，两个旧模块已退出清单；旧模块源码批量清理被自动审批拒绝，尚未删除。撤销并发替代链的定向验证已通过，旧安全投影链清理、逐次投递审计与指标、协议去区域字段及测试环境联调仍在推进。不得混合发布新旧协议或把本地测试视为环境验收。 状态：整体迁移尚未完成。统一 Token/JWKS/Redis 会话、八类业务事件直连与结构化 ACK、有限重试及人工原事件重试已进入源码并完成分批本地验证。构建与部署已收敛为单 TEST 的13个服务，两个旧模块已退出清单；旧模块源码批量清理被自动审批拒绝，尚未删除。撤销并发替代链已通过定向验证，旧安全投影链已移除，逐次投递审计与指标、协议去区域字段已实现，后端全量 Maven 回归已通过（4149项，12项跳过，0失败/错误），真实测试环境尚未部署验收。不得混合发布新旧协议或把本地测试视为环境验收。
下文路径、响应与时序为改造目标。实际业务服务、客户隔离、仓库类型、作业角色与状态机保持原职责；不能将“同机”解释为合并数据库表或绕过权限。 下文路径、响应与时序为改造目标。实际业务服务、客户隔离、仓库类型、作业角色与状态机保持原职责；不能将“同机”解释为合并数据库表或绕过权限。
### A. 唯一路由与消费端映射 ### A. 唯一路由与消费端映射
@@ -72,9 +72,9 @@
统一逻辑状态为待投递、投递中、重试等待、完成、DEAD；可映射到现有表字段，不要求批量改名。初始测试参数：连接超时 3 秒、单次请求超时 15 秒、租约 60 秒、累计自动尝试 12 次、退避从 5 秒翻倍上限 30 分钟，加入小幅抖动；参数需可配置。租约失效后的恢复和最终状态更新必须校验持有者，避免旧任务覆盖新任务。消费超时不能被解释为事务一定回滚。 统一逻辑状态为待投递、投递中、重试等待、完成、DEAD；可映射到现有表字段，不要求批量改名。初始测试参数：连接超时 3 秒、单次请求超时 15 秒、租约 60 秒、累计自动尝试 12 次、退避从 5 秒翻倍上限 30 分钟，加入小幅抖动；参数需可配置。租约失效后的恢复和最终状态更新必须校验持有者，避免旧任务覆盖新任务。消费超时不能被解释为事务一定回滚。
源码配置已统一为 `baiyue.event-delivery.connect-timeout-ms=3000`、`read-timeout-ms=15000`、`max-attempts=12`、`base-delay-seconds=5`、`max-delay-seconds=1800`、`jitter=0.1`、`lease-seconds=60`，供四个业务 Relay 使用。事件 Feign 客户端显式应用 EventDeliveryFeignConfiguration，禁止客户端内部自动重试及重定向，最终构建参数不被旧的全局 Feign 超时覆盖；连接与读取超时之和必须小于租约时长。`retry_count` 表示已失败或租约超时的投递次数；普通领取不递增，领取超时任务或恢复超时租约时计入一次，自动预算耗尽后保持 DEAD。实际投递失败从失败时刻计算下一次重试时间；每次领取使用独立租约 ID 和当前时间，最终写入必须匹配该 ID。DEAD 保留原始事件，不能通过定时扫描自行恢复。当前人工重试、逐次审计和指标仍在实施，未达到停桥部署门槛。 源码配置已统一为 `baiyue.event-delivery.connect-timeout-ms=3000`、`read-timeout-ms=15000`、`max-attempts=12`、`base-delay-seconds=5`、`max-delay-seconds=1800`、`jitter=0.1`、`lease-seconds=60`，供四个业务 Relay 使用。事件 Feign 客户端显式应用 EventDeliveryFeignConfiguration，禁止客户端内部自动重试及重定向，最终构建参数不被旧的全局 Feign 超时覆盖；连接与读取超时之和必须小于租约时长。`retry_count` 表示已失败或租约超时的投递次数；普通领取不递增，领取超时任务或恢复超时租约时计入一次，自动预算耗尽后保持 DEAD。实际投递失败从失败时刻计算下一次重试时间；每次领取使用独立租约 ID 和当前时间，最终写入必须匹配该 ID。DEAD 保留原始事件，不能通过定时扫描自行恢复。人工重试、逐次审计和指标已落地并通过本地事务回归，真实数据库/多服务故障恢复仍未验证，尚未达到停桥部署门槛。
每次尝试记录事件、目标、时间、耗时、结果、错误和下一次重试；按服务/类型提供 pending/DEAD 数量及最老待处理时长。告警接入现有能力，不为本次新增独立监控平台。人工重试采用各生产服务的受保护内部操作与配套运维脚本，不新增公开后台页面：只允许 DEAD 原事件重试，记录操作人/原因，保留 eventId/hash/payload/业务幂等键，禁止修改载荷或伪造新 ID 后重发。 每次尝试在本服务 event_delivery_attempt 表记录事件、目标、时间、耗时、结果、有限错误码和下一次重试；领取与STARTED审计同事务提交后才发HTTP，持有者CAS完成与审计完成同事务，失败一同回滚。过期租约审计为LEASE_EXPIRED并退避，本轮不立即重发。按服务/类型提供 pending/DEAD 数量及最老待处理时长；指标 baiyue.event.delivery.pending/dead/oldest.pending.seconds/sample.timestamp/sample.success 默认30秒采样，Prometheus只读缓存。采样失败保留旧值并标记失败，未知初值为NaN，不误报零积压。告警接入现有能力，不为本次新增独立监控平台。人工重试采用各生产服务的受保护内部操作与配套运维脚本，不新增公开后台页面：只允许 DEAD 原事件重试，记录操作人/原因，保留 eventId/hash/payload/业务幂等键，禁止修改载荷或伪造新 ID 后重发。
人工重试源码接口已冻结：GET `/internal/{firstleg|lastleg|finance}/event-operations/{entryId}` 查询状态，POST 同路径加 `/retry` 提交 `{requestId,operator,reason,expectedPayloadHash}`。使用独立 `X-Event-Operations-Token`，服务配置 `baiyue.event-delivery.operations-token` 对应 `EVENT_OPERATIONS_TOKEN`；缺失或不足32字节时仅关闭该运维能力，不影响业务启动。请求编号为稳定UUID，锁定本服务原Outbox行，DEAD→PENDING和 `event_delivery_retry_audit` 同事务提交；相同请求参数幂等，不同参数冲突，审计失败回滚状态。脚本 `baiyue-firstleg/scripts/event-outbox-operations.mjs` 只接受显式服务源地址与 `CHONGCHONG_ENV=test`，凭据仅从环境读取，不跟随重定向、不自动重试。不得通过公网Gateway或直接改表验收。 人工重试源码接口已冻结：GET `/internal/{firstleg|lastleg|finance}/event-operations/{entryId}` 查询状态，POST 同路径加 `/retry` 提交 `{requestId,operator,reason,expectedPayloadHash}`。使用独立 `X-Event-Operations-Token`，服务配置 `baiyue.event-delivery.operations-token` 对应 `EVENT_OPERATIONS_TOKEN`；缺失或不足32字节时仅关闭该运维能力，不影响业务启动。请求编号为稳定UUID，锁定本服务原Outbox行，DEAD→PENDING和 `event_delivery_retry_audit` 同事务提交；相同请求参数幂等，不同参数冲突，审计失败回滚状态。脚本 `baiyue-firstleg/scripts/event-outbox-operations.mjs` 只接受显式服务源地址与 `CHONGCHONG_ENV=test`，凭据仅从环境读取，不跟随重定向、不自动重试。不得通过公网Gateway或直接改表验收。
@@ -110,7 +110,7 @@ JWT 不携带角色或权限集合，只保留必要身份、客户/应用/仓
平台和客户两级模型、服务端客户隔离、实际收货仓与 FBA 目的仓的区分继续有效。仓管绑定修改须撤销会话；无关平台角色不能通过客户端参数假冒仓绑定。统一认证后，不再用双区域安全投影作为权限来源。 平台和客户两级模型、服务端客户隔离、实际收货仓与 FBA 目的仓的区分继续有效。仓管绑定修改须撤销会话；无关平台角色不能通过客户端参数假冒仓绑定。统一认证后，不再用双区域安全投影作为权限来源。
资金指令当前实现补充：Finance 先单独提交 eventId/hash 身份记录，再在事务内锁定 Inbox 并复核 hash。资金变更、Inbox 最终结果及结果 Outbox 同事务提交；明确业务拒绝在原事务回滚后重新加锁记录，已有最终结果不得覆盖。可重试异常不产生最终 FAILED。当前内部响应维持原接口，统一 DeliveryAck 属于后续通信批次。 资金指令当前实现补充：Finance 先单独提交 eventId/hash 身份记录，再在事务内锁定 Inbox 并复核 hash。资金变更、Inbox 最终结果及结果 Outbox 同事务提交；明确业务拒绝在原事务回滚后重新加锁记录，已有最终结果不得覆盖。可重试异常不产生最终 FAILED。内部消费响应已统一为 ApiResponse<DeliveryAck>，可靠提交后才确认成功。
最终业务拒绝白名单为 FIN-WALLET-INSUFFICIENT、FIN-WALLET-HOLD-409、FIN-IDEMPOTENCY-CONFLICT、FIN-REQ-400；处理中、乐观锁冲突、依赖冻结未到达及未分类异常继续向投递方抛出。基于 H2 的 JDBC 并发与回滚测试已经通过，不替代真实 MySQL 和测试环境全链路验证。 最终业务拒绝白名单为 FIN-WALLET-INSUFFICIENT、FIN-WALLET-HOLD-409、FIN-IDEMPOTENCY-CONFLICT、FIN-REQ-400；处理中、乐观锁冲突、依赖冻结未到达及未分类异常继续向投递方抛出。基于 H2 的 JDBC 并发与回滚测试已经通过，不替代真实 MySQL 和测试环境全链路验证。
@@ -121,4 +121,4 @@ JWT 不携带角色或权限集合，只保留必要身份、客户/应用/仓
- 只允许平台共享、`OVERSEAS`、`ACTIVE` 且启用 `RECEIVING` 的仓作为海外实际收货仓。低频正结果可缓存 30 分钟，空目录、不存在和停用结果不得长缓存。 - 只允许平台共享、`OVERSEAS`、`ACTIVE` 且启用 `RECEIVING` 的仓作为海外实际收货仓。低频正结果可缓存 30 分钟，空目录、不存在和停用结果不得长缓存。
- FBA 目的仓同样只以国内 `warehouse-service` 的平台公共主数据为权威，但语义与海外实际收货仓严格分离：Admin 候选使用 `warehouseType=FBA&status=ACTIVE` 的平台仓库分页；Lastleg 写入通过受内部服务令牌保护的 `/internal/warehouses/0/{warehouseId}/active` 读取当前事实，并继续校验 `warehouseType=FBA` 及 ID/编码/名称一致。`OVERSEAS`、`OVERSEAS_PARTNER` 或 `DOMESTIC` 均不得作为 FBA 目的仓。 - FBA 目的仓同样只以国内 `warehouse-service` 的平台公共主数据为权威，但语义与海外实际收货仓严格分离：Admin 候选使用 `warehouseType=FBA&status=ACTIVE` 的平台仓库分页；Lastleg 写入通过受内部服务令牌保护的 `/internal/warehouses/0/{warehouseId}/active` 读取当前事实，并继续校验 `warehouseType=FBA` 及 ID/编码/名称一致。`OVERSEAS`、`OVERSEAS_PARTNER` 或 `DOMESTIC` 均不得作为 FBA 目的仓。
- 按 FBA 仓拆分的海外派送单在签收完成时，由 Lastleg 在同一事务按关联来源入仓单分别写 `OverseasDeliveryCompleted` V1 Outbox；Event Bridge 定向投递 Firstleg。Firstleg 校验事件信封、客户、来源入仓单/订单、入仓码和 FBA 仓后，只将该来源入仓单从 `LOADED` 推进到 `DELIVERED`；同一 Order 的全部有效入仓单均为 `DELIVERED` 后，才以内部服务身份幂等推进该 Order 到 `COMPLETED`。同车其他 FBA 派送单必须各自签收，不得随整车一起完成。 - 按 FBA 仓拆分的海外派送单在签收完成时，由 Lastleg 在同一事务按关联来源入仓单分别写 `OverseasDeliveryCompleted` V1 Outbox；Lastleg Relay 直接投递 Firstleg 的 `/internal/firstleg/v1/container-events`。Firstleg 校验事件信封、客户、来源入仓单/订单、入仓码和 FBA 仓后，只将该来源入仓单从 `LOADED` 推进到 `DELIVERED`；同一 Order 的全部有效入仓单均为 `DELIVERED` 后，才以内部服务身份幂等推进该 Order 到 `COMPLETED`。同车其他 FBA 派送单必须各自签收，不得随整车一起完成。