Skip to content

README.md

Latest commit

 

History

History
119 lines (88 loc) · 10.3 KB

README.md

File metadata and controls

119 lines (88 loc) · 10.3 KB
Raw

API 参考准入与生成规则

状态：准入规则已确认；企业平台 API 和 SDK 尚不存在

本区当前不提供端点、类型或 SDK 方法。当前根入口只是一组最小 Provider 契约工具，其精确发布版本和能力事实由根 README、源码、测试和公开状态页共同证明；旧 v0.0.8 API 草案已归档，不具备发布权威。

为什么不手写未来 API

  • 手写字段会在实现、校验、OpenAPI、SDK 和示例之间形成多份真相。
  • 未实现合同容易把产品规划误读为可用能力。
  • 支付接口的认证、幂等、错误、分页和状态语义需要运行时与负向测试共同证明。

发布准入

某个 API 只有同时满足以下条件才可进入本区：

  1. 采用版本的 Vext route contract 已实现请求、响应、鉴权和错误语义，并可重现生成第一方 typed contract 产物与 OpenAPI 发布快照。
  2. 认证主体、租户边界、权限、输入、输出和错误语义完整。
  3. 写操作具备幂等键、请求摘要冲突和未知结果恢复测试。
  4. 列表具备稳定排序、游标、过滤范围和分页边界测试。
  5. Webhook 具备 raw body、渠道 policy、重放、重复、乱序和快速响应测试。
  6. 外部商户 SDK 从锁定版本的 Public OpenAPI 生成；Vext 第一方 typed artifacts、OpenAPI 和 SDK 与同一 route manifest 在 CI 对账。
  7. 沙箱示例真实运行，生产限制、版本和弃用策略已发布。

契约公共规则

  • 资源标识使用平台 ID；商户和渠道 ID 作为显式关联字段，不复用同一字符串语义。
  • 金额为整数最小单位并总是携带币种。
  • 时间使用带时区的标准格式；账期和渠道本地时间另行明确。
  • 错误 envelope 必须有稳定类别、可读信息、追踪 ID、可否重试和建议动作。
  • accepted、rejected、unknown 必须可区分，HTTP 5xx 不自动等于业务失败。
  • 状态字段与领域状态机同源，API 不创造旁路状态。
  • 敏感字段默认不返回，管理/导出场景按权限和审计开放。

ContractSourceMatrix

“合同真相”按消费者分层，不把作者输入、运行时产物、公开快照和 SDK 混成一份文件：

层级 权威输入/产物 消费者 禁止事项
领域合同 支付、账务、对账和安全文档 + 领域测试 领域服务、审计与评审者 OpenAPI 或前端类型不得创造旁路状态和资金规则
HTTP 作者真相 实际采用 Vext 版本识别的 route contract：输入校验、响应 schema、auth、错误和 docs metadata Vext 运行时与生成器 不在手写文档、handler 返回值和 SDK 中分别维护字段
第一方 typed contract 同一 route manifest 生成的 route-contract.json、client-contract.json、api.generated.ts 等版本化产物 PayPlex 管理端、类型探针和内部工具 按受众控制生成/打包，不把 src/services/** 或 Internal 路由元数据带入公开客户端，不直接作为商户 SDK 发布
外部发布合同 构建生成、审查并锁定的 Public OpenAPI snapshot 商户、外部工具和 SDK 生成器 不包含 Admin/Internal/渠道入站路径、schema 或权限信息
商户 SDK 只由已发布 Public OpenAPI 生成的版本化包 商户应用 不从 Admin/Internal typed artifacts 或移动中的 route 源码生成

Vext 低层响应 schema 写法必须以实际采用版本为准。文档不永久绑定 docs.responses 或 RouteOptions.responses 等具体语法；升级 Vext 时通过可执行探针证明请求、响应、OpenAPI 和 typed artifacts 仍来自预期 route contract，缺失响应 schema 导致的 unknown 必须在发布门中可见。

生成一致性门至少验证：相同 route manifest 产生稳定合同产物；所有公开成功/错误响应都有闭合 schema；Public OpenAPI 与第一方 route contract 的方法、资源、状态和错误一致；生成 SDK 可编译并通过沙箱合同测试。

若采用版本的 Vext typed client 不能原生按 source 生成，PayPlex 必须在构建/打包阶段按消费者过滤，或只把完整产物留在受控内部工具链。类型可见性不构成路由授权，但公开商户包和公开前端 bundle 仍不得携带 Admin/Internal 路径、schema 或操作名称。

API 与文档面隔离

文档面 内容 访问与发布 SDK/文档策略
Public Merchant 商户可调用的支付、退款、查询、通知管理等已发布合同 独立 Public source 和不可变 OpenAPI snapshot；运行时仍执行商户认证、租户和 scope 唯一允许生成外部商户 SDK 的输入
Admin 运营、财务、风控、审计和受控人工动作 独立 Admin source；强认证、细粒度权限、职责分离和操作审计 仅第一方管理端使用，不进入商户 SDK
Internal 任务、补偿、诊断、健康、恢复和内部控制面 默认不可见或仅内网受权 source；不能因隐藏菜单而省略运行时鉴权 不公开 reference 或外部 SDK
Channel ingress 渠道 Webhook 与机构回调 按渠道签名、网络和租户/渠道账户 policy 保护，默认排除在交互文档与 Try it out 外 只发布必要的渠道配置说明，不暴露内部处理 schema

采用 Vext v1.0.1 时使用显式 openapi.docs.sources 区分 Public/Admin/Internal，并同时控制 source 与 operation access。生产环境要求 docs.access.mode = enforce 且 docs.access.openapiJson = filtered，让 canonical OpenAPI 同样经过权限过滤；visibility-only 仍可能保留完整公开 /openapi.json，不能作为安全隔离。Docs 可见性也不能替代路由的 RouteOptions.auth 和 PayPlex 资源授权。

资金写操作的 Try it out 默认关闭；确需在受控非生产环境开放时，仍要求真实认证、最小权限、环境隔离、限额和审计。发布负向验证必须证明 Public source、canonical JSON、source-aware data、search、code docs、公开前端 bundle 和生成 SDK 均不含 Admin/Internal 路径、schema、示例、操作名称或敏感错误。

内部 API/SDK/沙箱契约蓝图

本节是 internal-only 蓝图，用于后续实现前评审消费者语义。它不是公开 API reference，不提供字段级 schema、端点路径或 SDK 方法名；任何公开材料仍必须从已实现的 Vext route contract 和隔离后的 Public OpenAPI 生成。

资源域 规划动作 状态来源 必须先冻结
Merchant / Credential 创建、审核、启用、暂停、轮换、吊销 商户生命周期和凭据版本 租户上下文、scope、环境隔离、合规状态
PaymentOrder create、query、close、list 支付核心状态机 幂等摘要、requires_action、unknown 恢复
ChannelAttempt / ExternalFact query、诊断、受控重放 执行层和渠道事实 attempt 可见范围、敏感原始事实掩码
RefundOrder create、query、list 退款状态机 可退额、部分退款、unknown 先查单
PayoutOrder / PayoutInstruction create/request、approve、query、cancel 出款状态机和结算指令 收款人版本、审批、资金冻结、退回事实
Balance / Ledger query、statement、journal drilldown 账务分录和余额快照 经营模式、币种、asOf、不可变分录
Reconciliation / Settlement batch、case、statement、download 对账和结算状态 账期、时区、规则版本、明细下钻
WebhookEvent / MerchantNotification list、retry、replay、verify evidence 渠道入站和商户出站通知 签名 policy、去重键、授权重放
ExceptionCase / DisputeCase open、assign、action、close、export evidence 异常中心和争议状态 允许动作、审批、审计、资金影响

消费者公共语义

主题 蓝图要求
认证与租户 请求身份只来自 Vext 可信上下文；body/query/header 不能覆盖租户或商户
幂等 写操作要求稳定幂等键和请求摘要；相同键不同摘要返回冲突
错误 至少区分 validation、auth、permission、conflict、risk_review、channel_rejected、channel_unknown、platform_unavailable、internal_error
查询与分页 列表有稳定排序、游标、租户过滤和 asOf 语义；不可用时返回最近可信状态和诊断
Webhook 入站渠道 Webhook 与出站商户通知分离；重放是新投递尝试，不重复记账
版本 OpenAPI 版本与部署版本绑定；未发布蓝图可收敛，不承诺兼容
SDK 外部商户 SDK 只从锁定 Public OpenAPI 生成；第一方 Vext typed artifacts 不扩大公开业务合同
沙箱 必须模拟成功、业务拒绝、unknown、requires_action、Webhook 重复/乱序、部分退款、争议、出款退回和账单差异

版本与兼容

  • Public OpenAPI 版本与部署版本绑定，并保留 route manifest、采用的 Vext 版本和其他可复现生成输入。
  • 兼容性判断先证明合同是否已发布及是否有真实消费者。
  • 弃用必须给替代路径、时间、观测和移除条件；未发布草案可直接收敛，不背负虚假兼容层。
  • breaking change 需要迁移说明、消费者扫描和沙箱验证。

生成链

领域合同 -> Vext route contract
                    |-> 第一方 typed artifacts -> 管理端/内部工具
                    |-> Public OpenAPI snapshot -> 商户 SDK -> 示例与公开参考页
                    |-> Admin/Internal docs sources -> 受权第一方文档面

生成页只解释字段和操作，不复制领域不变量；支付、账务、对账和安全规则回链到各自领域页。

验收边界

  • route contract、第一方 typed artifacts、Public OpenAPI 和商户 SDK 对相同资源/状态/错误没有漂移，缺失响应 schema 会阻止发布。
  • Public Merchant、Admin、Internal 和 Channel ingress 在路由、OpenAPI source、文档数据、搜索和 SDK 生成中保持隔离。
  • 第一方 typed artifacts 按消费者受控生成或打包，公开客户端和商户包不包含 Admin/Internal 合同元数据。
  • 未认证或越权主体即使知道 Admin/Internal 路径也不能调用；隐藏 Docs UI 不是授权证据。
  • Vext 升级后先通过 contract generation 和隔离负向探针，再更新采用基线或发布 API。