实施推进、风险与架构决策

汇总实施阶段、已知风险、待确认事项、架构决策记录与会诊结论。

15. 分阶段实施计划

阶段 0：需求冻结与威胁建模

产出商户规模与流量基线、平台路由清单、Scope 清单、地域清单、后端幂等能力清单、数据合规约束和 STRIDE 威胁模型。没有这些输入，不进行生产定容。

阶段 1：单地域纵向切片

在非生产环境实现控制面最小闭环、Key 生命周期、Key 与 IP 绑定、Scope 授权、本地域配置快照、审计、限流和一条真实平台路由。建议优先以 Zero Confirmation 作为首条纵向切片，因为会议明确提到其多数据库和多地域设计将复用于 BPS。

阶段验收以真实客户端完成创建 Key、绑定 IP、授权调用、错误组合拒绝、轮换和吊销全过程为准。

阶段 2：首批平台统一接入

在非生产环境接入 WebPay Inbox、BPS 和 Zero Confirmation 经各平台负责人确认后的路由；建立每条路由的 required scope、超时、重试、幂等和限流策略；完成商户迁移、影子流量和兼容性测试。

阶段 3：多地域数据面

部署第二地域，打通配置分发、控制面围栏接管、地域版本对账、break-glass、流量路由策略中心的两个执行点、商户地域归属和只读故障转移，完成单可用区和地域级演练。首个生产网关版本只能在本阶段发布门禁全部通过后上线。

阶段 4：受控跨地域写入与平台扩展

仅对已经证明具备全局幂等、唯一约束和明确主地域切换机制的平台开放跨地域支付写入。形成标准接入模板，使未来平台通过路由、Scope、服务注册和验证清单接入。

16. 关键风险与缓解措施

风险	影响	缓解措施
把商户级 IP 误当成 Key 级 IP	同一商户的 Key 与 IP 可被错误混用	数据模型直接建立 `api_key_id` 到 `ip_network` 的绑定，授权矩阵进入发布门禁
信任客户端自带转发头	可伪造来源 IP 绕过绑定	边缘覆盖转发头，只信任受信代理链或 PROXY Protocol
每个请求查询中心数据库	跨地域延迟和中心故障放大	本地域版本化配置快照、版本化事件和周期对账
配置缓存过旧	吊销或权限收缩不能及时生效	高优先级失效事件、10 秒传播目标、短周期版本轮询
控制面故障时无法吊销泄露 Key	攻击凭据在故障窗口内持续有效	各地域 break-glass 只拒绝通道、硬件签名、本地只追加审计和季度演练
控制面双主或版本分叉	区域配置无法确定新旧顺序	单写围栏租约、主动与备用数据库、`(epoch, sequence)` 版本和接管演练
认证响应暴露 Key 或路由存在性	攻击者枚举有效凭据和平台接口	身份与 IP 失败统一 `401`，缺少 Scope 与路由不存在统一 `404`
网关自动重试支付写请求	重复交易	强制幂等键，非幂等写请求不自动重试
网关承担业务数据库双写	跨库事务不一致且难以恢复	网关只路由到一个明确后端，复制与切换由平台负责
单个超级 Scope 权限过大	Key 泄露后横向影响多个平台	按平台、资源、操作拆分 Scope，默认拒绝并定期复核
Secret 出现在日志或后台	长期凭据泄露	一次展示、日志头脱敏、摘要存储、泄露演练和定期轮换
Pepper 轮换导致全部存量 Key 失效	商户请求大面积中断	摘要记录 Pepper 版本，旧 Pepper 保留到对应 Secret 全部失效
静态 Key 被重放	未授权重复读取或支付操作	TLS、Key 级 IP 绑定、支付写入 mTLS 或 Ed25519 请求签名、后端全局幂等
运维配置过宽 CIDR	IP 绑定失去隔离效果	默认只允许单地址，较小网段双人审批，更宽网段拒绝，重叠网段禁止
多地域入口与数据地域不一致	合规违规或读取陈旧数据	显式商户地域策略，不仅依赖地理 DNS
业务流量未知	容量和 SLO 缺少依据	先收集 30 天流量基线，再压测和定容

17. 待业务与平台团队确认

以下信息在两份会议材料中没有出现，当前没有事实依据：

WebPay Inbox、BPS 和 Zero Confirmation 的完整 API 路由、协议和版本。
各平台实际的读写语义、幂等能力、超时上限和重试约束。
生产地域、可用区、专线和公网入口清单。
逐字稿提及的 Zero Confirmation 三个数据库是否准确，以及其拓扑、复制方式、写入主节点和切换流程。
BPS 是否已经具备多数据库或多地域能力。
商户数量、API Key 数量、每 Key IP 数量、峰值 QPS 和报文大小。
商户是否都有稳定出口 IP，是否存在共享 NAT、动态 IP 或第三方平台代理。
API Key 由内部人员创建还是允许商户自助创建，以及审批责任人。
访问日志和审计日志的法定保留周期、数据驻留和隐私要求。
现有 Kubernetes、PostgreSQL、Redis、消息总线、KMS、WAF 和全局流量管理产品清单；全局流量产品将作为流量路由策略中心的入口执行点。
对外域名、证书体系和旧入口迁移兼容期。
建议 SLO、Key 有效期、24 小时轮换窗口和 15 分钟离线快照策略是否可接受。
外部 TLS 在 WAF 终止还是透传到网关，以及各终止点的日志、密钥和访问控制责任。
支付写请求采用 mTLS 还是 Ed25519 请求签名；只读接口是否接受 TLS 与 IP 绑定下的剩余重放风险。
各平台读取一致性等级、复制延迟信号来源、信号有效期和自动读取故障转移阈值。
认证前可用于入口地域选择的路由提示机制，以及提示信息的防枚举和隐私边界。
固定首选、主备故障转移和权重或就近路由分别适用于哪些商户、平台和请求类型。

上述事项不阻塞逻辑架构评审，但会阻塞生产定容、详细接口契约、跨地域支付写入和最终技术选型。其中第 1、2、4、8、14、15、16、17 项应在阶段 1 开始前完成确认。

18. 架构决策记录

ADR-001：统一 Gateway，平台授权保持细粒度

决策：所有平台共享统一入口和授权模型，每条 Key 与每条路由保持明确 Scope。
原因：满足会议提出的跨平台统一入口，同时避免一个平台的 Key 自动获得其他平台权限。
后果：需要统一的路由与 Scope 注册流程，各平台不能私自绕过网关发布商户入口。

ADR-002：IP 绑定到具体 API Key

决策：IP 绑定记录以 api_key_id 为外键，不使用商户级隐式白名单。
原因：直接解决同一商户多个 Key 和多个 IP 被混用的问题。
后果：商户新增 Key 时必须显式配置 IP；相同 IP 复用到多个 Key 时需要多条审计记录。

ADR-003：控制面集中、数据面区域自治

决策：配置事实源集中管理，通过版本化事件分发到各地域的配置快照缓存，请求热路径不访问跨地域数据库。
原因：兼顾统一控制、多地域低延迟与区域故障隔离。
后果：必须建设可靠的配置传播、吊销失效、版本对账和有界陈旧策略。

ADR-004：网关不负责平台数据库双写

决策：网关为每个请求选择一个明确后端，不直接写入多个业务数据库。
原因：API Gateway 不具备解决支付业务跨库事务和数据冲突的上下文。
后果：跨地域支付写入必须由平台先提供幂等、复制和主地域切换能力。

ADR-005：成熟代理与独立 API Key 验证服务分离

决策：使用成熟 L7 代理处理网络与流量治理，使用独立 API Key 验证服务处理 Secret 摘要、Key 状态、环境和 Key-IP 绑定，并向网关返回 Scope 集合；网关权限策略执行路由可见性和 required scope。
原因：减少自研代理风险，同时让凭据验证与路由权限决策各自保持可测试性和演进空间。
后果：API Key 验证服务成为关键依赖，必须多实例部署、使用低延迟缓存并采用失败关闭策略。

ADR-006：认证失败与路由不可见性优先

决策：Key、状态、环境和 IP 绑定失败统一返回 401；缺少 required scope 与路由不存在统一返回 404。
原因：避免利用状态码探测有效 Key、来源 IP 绑定和未授权平台路由。
后果：商户只能通过 request_id 请求内部支持团队查看精确 reason code，不能从对外错误直接判断 IP 或 Scope 配置。

ADR-007：控制面采用围栏式单写容灾

决策：控制面跨地域主动与备用部署，使用单写租约和 (epoch, sequence) 版本，旧主未围栏时禁止接管。
原因：普通单调序号无法解决网络分区后的双主版本分叉。
后果：控制面接管可能牺牲部分管理可用性，但不会让两个地域同时发布互相冲突的配置。

ADR-008：支付写请求增加持有证明

决策：生产支付写路由在 API Key 与 IP 绑定之外，必须使用 mTLS 或 Ed25519 请求签名。
原因：静态 Bearer Key 即使通过 TLS 传输，仍无法抵御凭据在受信网络或 TLS 终止点泄露后的重放。
后果：商户需要管理客户端证书或签名私钥，网关需要证书吊销、公钥生命周期、时钟和 Nonce 状态能力。

ADR-009：业务幂等由后端平台拥有

决策：网关只强制并透传 Idempotency-Key，不保存请求结果或判断内容冲突。
原因：区域本地去重状态无法保证跨地域支付写入的一致性。
后果：平台必须提供全局幂等和唯一约束，网关只透传后端产生的 409。

19. Codex 与 Claude 架构会诊记录

19.1 审查方式

Codex 基于两份会议材料形成第一版设计并执行本地一致性检查。
Claude Code 版本为 2.1.201，请求模型与实际模型均为 claude-fable-5，effort 为 medium。
Claude 仅使用 Read、Grep 和 Glob 读取会议材料与设计文档，没有获得写入或 Shell 权限，没有修改文件。
第一轮执行对抗性架构审查，第二轮逐项验证问题闭环，第三轮只复核审查后收口的三项残余风险。

19.2 已接受并修正

认证与路由处理顺序会通过状态码暴露 Key 或路由存在性，已由 ADR-006 和第 6 节关闭。
控制面缺少跨地域容灾、单写围栏和无分叉版本，已由第 7.5 节和 ADR-007 关闭。
控制面故障时无法紧急封禁泄露 Key，已由第 10.3 节的区域只拒绝通道关闭。
Pepper 轮换无法验证存量 Key，已增加 pepper_version 与旧版本保留规则。
网关与后端的幂等职责不清，已由第 6 节和 ADR-009 明确。
Redis 故障时限流行为、环境隔离、CIDR 上限、SLI 测量、Bearer 重放防护、读取一致性信号和逐字稿证据强度均已补齐。
第二轮遗留的紧急拒绝续期、Redis 故障下扩缩容配额和幂等键适用范围，已在最终限定复核前收口。

19.3 已拒绝的质疑

授权组件故障时改为失败开放：拒绝。支付入口必须失败关闭，不能用可用性目标换取授权绕过。
把 Key 级 IP 绑定简化为商户级白名单：拒绝。该方案直接违背会议关于多 Key、多 IP 不得混用的要求。
由网关协调后端三个数据库写入：拒绝。跨库事务和账务一致性属于平台边界。
在缺少基础设施证据时直接锁定某一产品栈：拒绝。本文只保留可替换的推荐技术基线。

19.4 收敛结论

三轮只读审查后未发现未关闭的 blocker 或实质性矛盾。本文可以进入业务与工程评审，但状态仍是“设计建议”，不是“生产就绪”。第 17 节列出的事实缺口必须在对应实施阶段前关闭，所有建议 SLO、技术选型和故障策略必须通过真实基础设施、压测和演练验证。

第三轮仅留下两个非阻塞的详细设计事项：规定 break-glass 单次续期时长与累计续期审计口径；为 Redis 长时间故障叠加扩容时的吞吐下降编写人工处置手册。这两项不改变当前逻辑架构和交付结论。

19.5 流量路由策略中心专项会诊

Claude Code 版本为 2.1.201，请求模型与实际模型均为 claude-fable-5，effort 为 medium，仅使用 Read、Grep 和 Glob，没有修改文件。
第一轮专项审查发现两个 blocker：入口地域选择与认证后后端选择被合并，以及认证前路由提示被误作可信身份。本文已采用“一份策略、两个执行点”关闭这两个问题。
第一轮提出的入口失败语义、候选集过滤、有界陈旧、合规约束、术语一致性和建议选项标识六项实质性问题均已修正。
第二轮对实际文件复核后确认没有剩余 blocker 或实质性问题，置信度为高，可以进入业务与工程评审。
终审提出的两项非阻塞措辞改进已在终审后本地采纳：补充认证前误送写请求的 writer 门禁兜底，并明确 reason_code 仅用于内部日志与审计。两项调整不改变架构语义，因此未再发起外部复核。

19.6 抽象分层与节点展开专项会诊

第一轮只读审查接受“8 节点总览 + 6 个抽象节点展开 + 1 张跨节点时序”的方向，并给出 8 项必须修改：入口执行点锚定、治理顺序、身份头清洗、访问控制双组件边界、break-glass 输入、审计职责拆分、总览悬空输入清理、mTLS 与 Ed25519 边界拆分。
本文已逐项落实全部必须修改。静态检查确认 8 个 Mermaid 块与 HTML 中 8 个 Mermaid 容器一一对应，总览恰好 8 个节点，6 个展开小节均可定位，旧版地域相关歧义术语为零。
第二轮只读复核逐项检查 10 项事实，结论为 accept，置信度为高；未发现 blocker、实质性问题、无根板块、重复责任或错误连线。
第二轮提出的两项非阻塞可读性建议已在复核后本地采纳：把时序图描述改为“抽象边界与关键依赖”，并把已验证身份节点明确放在 API Key 验证服务与网关权限策略两个组件框之间。
原始单页 HTML 在本轮前未取得浏览器级视觉验收证据：Chrome 自动化拒绝本地 file:// URL，Mermaid CLI 缺少指定版本的 Headless Chrome。本轮已通过本机 HTTP 预览补齐验证：概览首页、主题导航和全部 8 张 Mermaid 图均完成真实浏览器渲染检查。该验证只覆盖本机静态站，不代表生产就绪；对外部署前仍须在目标部署环境复核。