状态：Vext 原生边界已确认；具体模块和基础设施尚未实现
PayPlex 作为 Vext 应用构建，而不是让 Vext 或其他框架接入一个独立 Web 中间件。支付领域核保持内部可测试，但平台入口、服务装配和运营界面遵循 Vext 原生能力。
| 项目 | 冻结结论 |
|---|---|
| 发布证据 | 当前规划依据 vextjs@1.0.1 与 Git tag v1.0.1；移动中的仓库 HEAD、工作树或未发布文档不能作为已采用合同 |
| Node.js | 未来 Vext 平台运行面要求 >=20.19.0；过渡期 Provider 契约内核仍为独立的 >=18 基线，二者不能混写为同一运行时 |
| 依赖锁定 | 平台 bootstrap 时冻结实际采用的 Vext 版本/允许范围和 lockfile；升级前重跑 route、raw body、鉴权、OpenAPI、typed contract、任务与关闭流程兼容探针 |
| 标准 HTTP 运行面 | 首个 PayPlex 生产支持面采用 Vext 默认 Native Adapter；Hono/Fastify/Express/Koa 只是候选，只有通过支付专项资格测试后才能列入支持矩阵 |
| 模块格式 | 平台按 Vext 发布合同使用 ESM；旧内核的包形态不推导未来子路径、CJS 或 Adapter 支持承诺 |
| 默认值 | “Vext 内建”不等于“PayPlex 已启用”；Session、CSRF、安全响应头、OpenAPI Docs access、Cluster 和数据库均需显式配置、测试和发布证据 |
采用基线是可复核的版本合同，不是永久锁死。升级 Vext 时先记录发布说明、行为差异和兼容探针，再更新本表；不得先按未发布 HEAD 改写 PayPlex 业务合同。
依据上表冻结的 Vext 发布证据基线，优先复用：
| Vext 能力 | PayPlex 用途 | 边界 |
|---|---|---|
| 文件路由、校验、响应和 OpenAPI | 商户 API、Webhook 接收、管理 API | 路由只编排，不写资金规则；公开合同按第 9 区分层生成 |
app.services 服务注入 |
领域应用服务、查询服务、任务入口 | 服务依赖显式，避免全局单例 |
| 插件生命周期与 app extension | 渠道、存储、消息、观测适配 | 插件不能改变领域不变量 |
| 配置分层 | 环境、租户默认值、渠道引用和功能开关 | 敏感值按项目策略受控，不写日志 |
| 请求上下文、request id、访问日志 | 租户/主体/追踪上下文 | 不能替代审计事件 |
| 结构化错误 | 稳定错误类别和恢复提示 | 不直接透出渠道敏感错误 |
| Route auth、Session、CSRF 与安全响应头 | 商户/管理入口的框架级保护 | PayPlex 仍拥有主体、租户、资源、动作、职责分离和资金授权；所有保护显式启用并做负向测试 |
vextjs/testing / createTestApp |
路由、校验、中间件和服务集成测试 | 不替代真实渠道沙箱、数据库并发、Cluster、灾备或外部网络测试 |
| Cluster、优雅关闭与滚动重启 | HTTP Worker 生命周期与请求排空 | 不提供持久任务唯一执行、分布式租约或跨站点单活语义 |
config.database / MonSQLize 生命周期 |
MongoDB 候选存储的连接、Model 和关闭装配 | 不自动证明账务原子性、不可变性、outbox 或恢复资格 |
| React 前端运行面 | 运营、财务、风控和审计工作台 | UI 授权不能替代服务端权限 |
不为 Vext 的 Native/Hono/Fastify/Express/Koa adapter 分别维护 PayPlex 业务集成方式；这些是 Vext 自身的 HTTP 运行选择，不改变 PayPlex 产品和领域合同。非 Native Adapter 的资格测试至少覆盖原始 body 字节一致性、请求大小限制、重复 header、连接中断、超时、快速响应、反向代理和优雅关闭；通过前不得宣称 PayPlex 生产支持。
| 模块 | 拥有的数据/规则 | 只读依赖 |
|---|---|---|
| gateway | 认证后的商户请求、开放契约和响应语义 | payment-core、merchant/security |
| payment-core | 支付/退款/出款、幂等、路由、异常 case | channel-adapters、risk decisions |
| ledger | 账户、分录、余额和调账 | 业务来源标识 |
| reconciliation-settlement | 账单、差异、费用、结算批次/单据 | payment-core、ledger、channel facts |
| operations-security | 商户/渠道配置、权限、风险、审计、告警 | 各域只读投影 |
| channel-adapters | 渠道配置引用、调用和原始事实 | 不读取/修改平台账务 |
跨模块只能通过明确服务合同或领域事件协作，禁止共享 collection 后由多个模块任意写入。
实现前必须把第 1 区 OperatingModelMatrix 和 ScopeDecisionRegister 物化为受控配置或部署决策记录。领域服务读取冻结后的模式，不在运行时自行猜测平台是否控制资金、是否支持子商户、是否启用多币种结算或是否进入 PCI 扩展范围。
| 配置/记录 | 所有者 | 影响 |
|---|---|---|
| operating model | 产品 + 财务 + 合规 | 科目表、结算、商户合同、资金责任和报表 |
| legal entity / region | 合规 + 平台管理员 | 数据驻留、保留期限、税务和渠道账户 |
| payment data boundary | 安全 + 渠道适配 | 托管/令牌化、日志掩码、PCI 范围 |
| sandbox scenario set | 平台工程 + API | 模拟成功、拒绝、unknown、争议、退回和账单差异 |
| feature scope decision | 产品 + 领域 owner | included/excluded/conditional 能力是否进入实现 backlog |
- 请求路径只完成鉴权、校验、幂等受理和必要的渠道短调用。
- Webhook 接收、商户通知、主动查询、补偿、对账、结算和报表使用持久化任务。
- 任务必须有稳定任务键、输入版本、租约/心跳、尝试次数、退避、终态和人工恢复入口。
- 业务写入与事件发布使用可恢复的一致性模式，例如本地事务 + outbox；具体实现待基础设施选型后通过单独方案确认。
- 消费者按事件 ID 幂等，不能依赖“消息只投递一次”。
Vext plugin 只装配任务客户端、消费者和 onClose 排空流程。进程内 setInterval、onReady 或每个 Worker 的内存队列只能用于无资金影响的本地维护，不能作为支付、退款、出款、通知、补偿、对账或结算的持久调度真相源。
| 责任 | 唯一真相/机制 | 约束 |
|---|---|---|
| 任务创建 | 领域写入 + 同一本地一致性边界内的 outbox/JobRecord | 业务提交成功但任务不可恢复，或任务存在但业务未提交，均不允许 |
| 到期扫描/派发 | 持久队列、单控制面或 leader-elected dispatcher | 多 Worker/Pod/站点不能各自无协调扫描并执行同一资金任务 |
| 任务领取 | 原子 claim + lease + fencing token | 旧持有者在租约过期后完成也不能覆盖新持有者结果 |
| 执行 | Worker/Pod 可竞争消费，按任务键和业务幂等键防重 | 幂等是最后防线，不能替代唯一领取和 fencing |
| 续租与恢复 | 心跳、有限租期、可观察重试和 dead-letter/人工 case | 进程崩溃、网络分区和滚动重启后由持久事实恢复 |
| 关闭 | 停止领取、等待有界 drain、记录未完成 attempt、释放或等待租约过期 | onClose 或进程退出不等于任务成功 |
| 灾备 | 明确单活、共识 leader 或共享原子 claim 边界 | 两个站点不得同时执行同一支付、退款、出款或结算 instruction |
实现验收必须覆盖 2/4 Worker、多个 Pod、滚动重启、执行中崩溃、租约过期后旧 Worker 恢复、消息重复/乱序、网络分区和灾备切换，并证明同一业务键最多产生一个外部资金副作用。
每个域拥有自己的写模型。查询可使用只读投影，但投影故障不得反向修改领域真相。数据库产品、表/collection 和索引在实现方案中选择；当前文档只冻结业务键、不变量和迁移要求。
任何 schema 迁移必须支持预览、兼容读写、回滚/前滚策略和数据质量核验。账务分录、审计事件和原始渠道事实不得通过普通清理任务删除。
Vext v1.0.1 的 MonSQLize/MongoDB 集成可以作为候选，但框架提供连接、Model、索引和 transaction 入口不等于候选已经满足支付账务要求。账务存储选型必须先提交以下可执行证据：
| 资格维度 | 必须证明 |
|---|---|
| 原子提交 | JournalTransaction、全部 JournalEntry、余额版本、业务幂等记录和 outbox/JobRecord 能在同一原子边界提交；任何一步失败都不留下半笔账 |
| 并发与唯一性 | 稳定业务键和交易 ID 有数据库唯一约束；可用额检查、冻结和过账在并发下不超额、不产生无授权负余额 |
| 隔离与故障语义 | 明确 transaction 隔离、write concern、超时、未知提交结果和重试规则；重试不会重复过账 |
| 不可变历史 | 普通 Model/管理工具不能更新或删除已过账分录；修复只能追加冲正/调账并记录审批和审计 |
| 迁移与恢复 | 索引/schema 变更支持兼容窗口、前滚/回滚和数据核验；备份恢复后分录重算、余额、幂等、outbox 和审计一致 |
| 运行与灾备 | 连接拓扑、容量、监控、主从/分片行为和跨站点切换经过故障注入；不会双活过账或丢失已确认交易 |
资格门的结论可以是采用、附条件采用或拒绝。若候选不能满足账务域，允许账务使用独立存储实现；Vext 继续负责应用宿主和生命周期，不要求所有域共用内建数据库。
统一关联 requestId、traceId、租户、商户、平台订单、渠道订单、账务交易、任务和 case。日志、指标、trace 和审计分工如下：
- 日志：诊断执行过程，允许受控采样。
- 指标：发现趋势、容量和 SLO 风险。
- trace：定位跨服务/渠道延迟和失败。
- 审计：证明谁在何时基于何因执行了什么，不可由普通日志替代。
关键 SLI 包括受理延迟、明确/未知结果比例、通知时延、pending 年龄、任务积压、分录一致性、对账完成率和结算及时率。
- 对渠道、任务消费者和外部依赖做超时、并发隔离、有限重试和熔断。
- 资金写操作的恢复以幂等记录、状态事件、账务分录和渠道查询为依据。
- 备份必须验证可恢复，而不只证明任务成功；恢复演练需复核账务、幂等、任务和审计一致性。
- 灾备切换不得让两个站点同时无协调地执行相同资金任务。
- RTO/RPO、部署拓扑和数据驻留由实际业务地区与合规要求确认后固化。
- 认证、租户解析和授权在 Vext 请求入口建立，领域服务仍验证资源归属和动作权限。
- 内部服务调用传播可信主体与审计上下文，不接受用户伪造 header。
- 渠道凭据、商户通知密钥和加密密钥有独立用途、版本和轮换流程。
- 管理端所有资金/权限动作具备 CSRF/会话保护、再认证或二次确认策略；具体机制在 UI/API 方案中验证。
- HTTP adapter 改变不影响支付领域合同。
- 任一异步任务可幂等重放、观察、暂停和受控恢复。
- 多 Worker/Pod/站点与租约失效场景下，持久资金任务仍只有一个有效执行者，过期持有者受 fencing 拒绝。
- 模块无共享任意写数据；领域事件丢失或重复不会破坏资金不变量。
- 账务存储通过
LedgerStorageQualificationGate，并在原子性、并发、未知提交、迁移和恢复负向场景中保持平衡且不重复过账。 - 故障和灾备演练能从业务订单追溯到渠道、账务、任务和审计证据。