接口与错误码
# 接口与错误码
# 目的
在仓库中找到真实接口合同、生成客户端类型，并按统一响应和错误码接入。租户前缀为/api/admin/v1，平台前缀为/api/platform/v1，字段使用camelCase。
根合同是api/openapi.yaml；正式工作流的43个操作及来源见工作流API。各功能的开放开关、权限及认证范围以对应操作和手册为准。
# 前置条件
维护合同需要已初始化的fago子模块、锁定前端依赖及本项目Node/pnpm工具链。运行Go验证前从仓库根目录加载scripts/go-env.sh，现有shell脚本已代为加载。
调用业务API前须取得当前realm访问凭据，具备当前权限和套餐能力，并使用配置中的精确Origin。
开发/测试业务JSON默认明文，生产查询与正文使用fago-jwe-v1。健康探测及安全策略发现仍明文；加密规则见日志、脱敏与请求加密。
平台身份不能读取租户工作流，客户端不能通过tenant/Actor字段或租户头选择身份。
# 步骤与规则
# 更新并检查合同
工作流唯一编辑源是fago/fago-server/apps/fago-server/scripts/workflow-openapi.mjs，生成应用模块内的internal/auth/testdata/workflow.openapi.json。
片段本身是完整OpenAPI 3.0.3文档；根聚合合同同时保留其他模块。不要直接改已生成的工作流片段或根合同中的对应操作。
# 外层仓库根目录；只生成正式工作流片段和其根聚合部分，保留其他模块合同。
node scripts/sync-workflow-openapi.mjs
# 校验根合同并生成fago内的schema.d.ts，再检查样例、权限映射和生成物是否漂移。
bash scripts/web.sh contract
# 成功输出包含：工作流合同：43 operations / 62 schemas；样例校验通过。
只验证而不写文件时使用node scripts/sync-workflow-openapi.mjs --check。修改后须提交片段、根合同及生成类型。
普通pnpm contract会先执行漂移检查，旧根合同不能掩盖尚未同步的模块片段。
CLI也能运行既有工具链。从fago/fago-vben5定位根合同须向上两级，不能沿用历史一层路径。
bash scripts/fago.sh openapi lint
bash scripts/fago.sh openapi gen types
# 0表示工具成功；diff只检查根合同相对HEAD的未提交变化，不是API兼容性分析器。
bash scripts/fago.sh openapi diff
# 处理响应与错误
成功业务码为0；普通同步操作常用HTTP 200/201。工作流受理首次发起返回202，不表示审批或外部动作已完成；读取原命令为done时仍可能有运行中的人工审批。
HTTP/1.1 202 Accepted
Content-Type: application/json
{"code":0,"data":{"commandId":"example-start","state":"accepted","result":{"id":"wf-example","definitionKey":"simple-approval","definitionVersion":1,"engineVersion":"fago-form-approval-v2","state":"running","version":1,"needsRun":true,"waiting":[]}},"message":"ok","requestId":"example-request"}
以上是响应结构示意，实例状态以服务器真实检查点为准。生产中相同业务envelope经JWE输出；客户端必须按当前套件及原请求密钥解密，不能回退裸JSON。
失败同时返回HTTP状态和稳定业务码，固定中文提示不携带内部错误链、堆栈、口令、Cookie、访问凭据或数据库连接信息。
HTTP/1.1 409 Conflict
Content-Type: application/json
{"code":409001,"data":null,"message":"记录已变更，请重试","requestId":"example-request"}
401001由统一客户端刷新一次access并重试原请求；403不能通过刷新绕过。工作流网络结果未知时保留原commandId与完整载荷；版本冲突先刷新再决定业务动作。
# 参数
| 内容 | 约束 |
|---|---|
Authorization | 当前realm的Bearer访问凭据，不是共享管理员身份 |
Origin、X-App-Request | 写请求使用精确配置Origin和admin/platform来源，不接受通配符或Referer回退 |
X-Fago-Payload | 生产GET的JWE上下文；真实方法、路径、加密query、时间和一次响应密钥绑定 |
| JSON版本 | integer/int64；浏览器须先检查安全整数，不能舍入CAS |
| 账号/事件ID、路径版本 | 规范十进制字符串，保留完整int64；路径/查询正版本不接受01、零或符号 |
| 工作流分页 | 定义/表单/本人列表用nextCursor，管理任务用next；游标不是授权或固定快照 |
# 失败
lint、样例、源片段或类型生成失败会非零退出。先修复编辑源再同步，不应手工修生成物来消除漂移。 当前Redocly有六条既有OIDC回调2XX警告，来源为实际只返回302/303的回调合同；工作流新增操作通过校验。 业务错误码及处理方式见异常处理与错误码，分页和版本见参数、分页与响应。
# 边界
JSON Schema约束字段、类型、可空和公开样例；重复JSON键、精确原文、拓扑、当前权限、资源绑定、运行池和幂等仍由实际服务端裁决。 合同或类型生成成功不代表功能已开启、生产认证、七数据库认证或完整R3.1验收完成。真实工作流HTTP专项与浏览器布局验收分别记录。