chenxing
7eeaea55f8
Local review candidate only. Explicitly selected inherited prerequisites and prior repair patches; unrelated WIP and independent MQ fixes are excluded. No push or deployment authorized.
2.9 KiB
流程定义精确表单版本契约（2026-10-23，R2 / R1）
流程关联表单时必须同时绑定 formUuid 与正整数 formVersion。保存显式关联、发布、启用统一调用
GET /oapi/form/schema?schId=&uuid=&version=，核对返回 UUID 和版本；不回落到当前版本。
未关联表单的独立流程（Mode C）仍可使用；孤立版本号不是未关联流程，必须拒绝。
UUID-only 存量定义不能发布或启用，必须重新选择明确版本。当前开发阶段不做存量迁移。
本轮不修改任何数据库；部署前核查 def68 的现有绑定即可。
FC 精确 schema 只返回 publish_time != null 的版本行。草稿不能作为发布契约。
已发布历史版本仍可按坐标读取，不要求它是头表当前版本；停用/软删的历史读取与原授权边界保持。
FC 将不存在、不可读、未发布版本统一为 PARAM_ERROR(2)，FL 不通过文案猜测资源存在性。
稳定错误码与恢复动作
API 信封 code 使用下列数值；msg 仅用于展示，消费方不得解析文案判断重试。
| code / 名称 | 含义 | 恢复动作 |
|---|---|---|
46101 VERSION_REQUIRED |
已指定 UUID，未指定版本 | 重新绑定；发布/启用均阻断，不调用 FC |
46102 INVALID_COORDINATE |
半个坐标、版本非正整数/非整数/溢出 | 修正请求；不盲目重试 |
46103 SCHEMA_UNAVAILABLE |
网络、空响应、服务端故障等拉取失败 | 可重试；客户端每次最多请求 2 次 |
46104 SCHEMA_CONTRACT_VIOLATION |
返回 UUID/版本缺失、不合法或不匹配 | 阻断；检查契约或重新选择坐标，不盲目重试 |
46105 RESOURCE_UNAVAILABLE |
FC 业务码 2 或 HTTP 404，指定发布资源不存在或不可读 | 检查资源/发布版本/读授权，不盲目重试 |
46106 ACCESS_DENIED |
SDK 身份/授权业务码 3、4 | 修复身份/授权后重试，不自动重放 |
坐标核验失败、资源不可用与身份拒绝均不在客户端重试循环内重复请求。
SchemaUnavailableException 与 SchemaContractViolationException 在公共边界分别翻译成错误码，
保留 cause；不存在被公共包装吞掉后无法命中的分类 catch。
启用只核验绑定，不覆盖此前发布的 formContract 快照；运行期继续使用流程版本里的原快照。
验证与边界
FlFormBindingTest 覆盖发布/启用缺版本、非法版本、孤立版本、四类失败码和不落库、启用保留快照。
FlowDefAdminServicePublishContractTest 全部关联夹具带 v3，原表达式键查、类型桶查、域查红牌继续验证。
FormCenterSchemaClientTest 覆盖不合法返回版本、UUID 不符、按业务码分类及重试次数。
FC OapiSchemaPublishedVersionTest 验证真实服务层的草稿阻断和历史已发布版可读；其中仓储是桩，
不是数据库或 160 验收。