产品接入与版本约定
页面动作如何成为可实现和可验证的接口需求
本页的 new-api 路由是固定源码参考，不代表 OceanWay 已部署该接口。现行实现责任按 Core、API Edge、Contracts 分仓；已有契约默认沿用 new-api，新增/变更部分单独定义并验证。
每个页面操作的接口记录
记录：需求 ID、产品、触发动作、用户身份、请求端点、对象归属、输入／输出、失败和重试语义、上游版本、验证证据。路径已有而权限或状态不符时仍是待适配，不标“已完成”。
示例：Console 创建 Key → 本人登录会话 → Core Key 创建接口（参考上游 Token 实现）→ 检查 success/message → 成功后刷新 Key 列表。固定上游创建响应不返回新 Key ID，不能假定直接获得可追踪记录。列表与详情保持掩码，点击复制按记录 ID 请求完整 Key；精确字段和差异由 Contracts 维护。
兼容与聚合
产品消费对应 Core 接口；确有登录交接、数据聚合或协议差异时再增加 BFF。BFF 不另存权威余额、不用管理员凭据绕过客户权限、不让客户端任意指定付款用户。
公共模型协议与管理 API 分别维护；有破坏性改变时提供升级路径和新旧兼容测试。客户端类型由固定 Schema 生成或明确维护，不要求先发布旧 Contracts 包才能开始本地验证。
重试和错误
按接口分别定义可安全重试的条件；稳定操作 ID 只有在后端持久去重时才提供幂等保证。区分输入错误、未登录、无权限、额度不足、限流、提交未知、供应故障和内部错误；面向客户的错误不暴露供应商密钥或内部栈。
文档验收
每个对外示例在声明版本运行；覆盖至少一个成功和相关失败场景；原型 mock 与真实响应分开；文档中的“支持”必须对应实际测试范围。
AUTH-G01 全局身份接入
全局登录是所有平台的必接能力，行为已确认，技术交接待实现。统一主体标识、会话状态查询、目标绑定交接、刷新与撤销由 Core/Contracts 定义；各站不得各建一套密码账户。客户端状态只用于展示，私有接口仍校验统一身份和本平台授权。认证失效与已登录无权限分别处理，Admin 的 403 不循环触发登录。详见身份与验收矩阵。