OceanWay 业务差异接口需求

以下是新增接口设计提案 v0.1，并非 new-api 已有路由或已实现 API。已有接口足以覆盖时继续沿用，不重复建设；这张表明确跨服务和业务缺口需要什么，具体端点可在实现前评审定版。所有请求/结果都需在 Contracts 补精确 Schema 与错误码。

内部接口使用服务身份并验证用途/归属，不直接暴露公网；客户接口使用客户会话，员工接口校验具体权限。错误需求统一覆盖输入非法、认证失败、权限拒绝、资源不存在、余额不足、幂等冲突、版本冲突、限流和依赖不可用；采用与已有接口一致的包络并给出稳定机器码，不伪装为现有上游错误码。

OW-01 · GET /api/oceanway/pricing/self

身份与范围：客户。

请求字段需求：无可伪造 owner；可选 model。

返回字段需求：生效价格方案、模型计量单价、单位、版本、区间。

业务与幂等：完整展示客户实际价；上游 /api/pricing 无法表达时才补，不泄漏其他客户协议价。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-02 · GET /api/oceanway/admin/pricing/accounts/:id

身份与范围：员工价格权限。

请求字段需求：Path 客户 id。

返回字段需求：当前方案与协议价、生效区间、版本。

业务与幂等：员工限定权限；普通客户不可用。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-03 · PUT /api/oceanway/admin/pricing/accounts/:id

身份与范围：员工价格写权限。

请求字段需求：expected_version、方案引用、模型/计量维度协议价、生效时间、原因。

返回字段需求：新价格版本、审计引用、冲突。

业务与幂等：金额精度、非负、目录存在与有效期检查；不改已开始调用价格，不覆盖并发修改。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-04 · GET /api/oceanway/wallet/ledger

身份与范围：客户。

请求字段需求：p/page_size、起止时间、流水类型、operation_id/order_id。

返回字段需求：流水、入账/扣减/释放、积分单位与关联。

业务与幂等：客户唯一账户过滤；区分实付、赠送、预留与消费，不将 Redis 余额作账单事实。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-05 · GET /api/oceanway/operations/:id

身份与范围：客户。

请求字段需求：Path id。

返回字段需求：本人调用的执行/用量/费用状态和安全错误。

业务与幂等：补充统一调用追踪，禁止枚举他人操作。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-06 · POST /api/oceanway/admin/reconciliations/:id/resolve

身份与范围：员工财务处理权限。

请求字段需求：action、amount/usage_evidence、reason、idempotency_key、expected_version。

返回字段需求：处理记录、账务引用或冲突。

业务与幂等：仅在人工财务范围确定后启用；补扣/退款新增关联流水，不原地篡改原账。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-07 · POST /api/oceanway/auth/handoff

身份与范围：已完成全局认证的用户（含员工；目标权限另校验）。

请求字段需求：已登记 target、state、return_path。

返回字段需求：短期单次 code、失效时间。

业务与幂等：AUTH-G01 已确认：任一平台登录后全平台识别同一身份；此端点为交接实现提案。目标与回调白名单，不在 URL 放长期令牌。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。

OW-08 · POST /internal/v1/auth/handoff/exchange

身份与范围：目标子站服务。

请求字段需求：code、target、state、服务身份。

返回字段需求：授权用户与可建子站会话的结果。

业务与幂等：code 绑定目标、短时、单次，重放/错目标拒绝；不是把 new-api OAuth 客户端当授权服务器。

验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。