OceanWay 开发者用量运行时 R2

状态：LOCAL_DEPLOYMENT_CANDIDATE / CANDIDATE_EVIDENCE / NOT_FORMAL_TEST

结果

/usage 与 /usage/:requestId 已改为只调用同源 /api/developer/usage。接口以当前 oceanway_session 用户为唯一身份，不读取 Retail Portal Cookie、旧 Session 或外部 Portal。原 /api/retail/portal/**、Retail adapter、客户端和契约运行时代码已退役。

当前站点产生的用量从统一 api_credit 预占、结算、释放和定向生成权益投影：消费显示 settled，失败释放显示 released，待核对请求显示 reconciliation_required。详情保持 只读，不触发重试、退款或再次扣费。已经导入目标 PostgreSQL 的用量按 target_user_id 查询，并与当前用量使用同一 API_CREDIT、Token 和媒体计量单位；产品界面不标注数据来源。

迁移 API Key 的 Apply 现在同时写入不可变旧站快照表和正式 developer_api_keys：原 Key 仅在进程内短暂出现，正式表使用独立 OCEANWAY_API_KEY_ENCRYPTION_KEY 加密和 OCEANWAY_API_KEY_HMAC_PEPPER HMAC，稳定 source + source_id 保证重复 Apply 不新增 Key。鉴权不再要求 ow_ 前缀，因此旧 Key 可以按原值认证；新建 Key 仍使用 ow_live_ 前缀。

公开 /v1/models、/v1/chat/completions、/v1/responses、/v1/messages、图片、音频 和视频创建入口已接到现有系统模型代理。公开请求只接受用户 Key，服务端将逻辑模型映射为 后台上游模型，再使用独立 Worker 身份进入同一余额预占、请求指纹、失败释放和安全出站链路； 用户 Key 与内部渠道地址都不会转发或返回。Idempotency-Key / X-Client-Request-Id 会按 Key 作用域生成稳定账务身份，同一身份不同正文会拒绝而不是重复调用。新消费流水会保存 request_source=api 和具体 developer_api_key_id，因此 /usage 可以按 Key 查询新 API 用量。 旧 Key 的 IP 白/黑名单、每分钟请求数和最大并发也会在 Apply 时写入正式 Key 表并由入口执行。 Key 的 quota/used 原值同时保存在不可变审计快照中；Key 级限制不作为第二套钱包，也不改变 用户统一余额。正式切换前仍需完成逐 Key 的限制语义核对。 每分钟请求数使用现有 PostgreSQL 速率限制器，在数据库不可用时降级到进程内保护；流式请求 的并发租约持续到响应读取/取消结束。当前最大并发计数仍是单 Web 进程范围，多实例部署前必须 增加共享租约或把该字段明确限制为单实例契约。

数据语义

• OceanWay 余额是唯一可消费金额；网页与 API 调用共用同一费率快照和账本。
• 余额、消费、退款和商品权益在 PostgreSQL 中使用 NUMERIC(38,18)；所有用户端金额统一 四舍五入显示两位，Token、次数和时长仍显示实际计量。显示精度不写回账本，因此小于 0.01 的 API 消费仍按原始 Decimal 值结算。
• 用户只能查询自己的用量；不存在和不属于当前用户都返回同一 404 语义。
• Key 名称只从当前用户的已迁移 Key 映射读取；内部 Channel、Group、上游账号和 Token 不进入响应。
• 导入审计表位于当前 OceanWay 目标数据库，是一次性数据承接后的本地事实，不构成运行时 依赖；正常登录、Key 鉴权、余额、套餐和用量读取全部由当前 OceanWay 服务完成。
• IP 规则只读取经过 VOZEB_PRO_TRUSTED_PROXY_HOPS 明确信任的转发链；未配置代理跳数时 带 IP allowlist 的 Key 会失败关闭，不能直接信任客户端伪造的 X-Real-IP。

迁移候选已补齐

• Apply 以稳定幂等键把账户余额原值 1:1 写入统一 api_credit opening entry；重复 Apply 不会重置或重复增加余额。账本最多保留 18 位小数，用户端只显示当前余额，不展示迁移来源。 冻结余额仍保持审计状态，不会被误当作可用余额。
• 旧 Group/订阅必须通过 OCEANWAY_SUB2API_PLAN_MAP_JSON 显式映射到 OceanWay 套餐， 重叠订阅逐条保留，并将当前有效项投影为用户套餐；没有映射时 Apply 会失败而不会猜测。
• 源订单写入只读审计表，并在用户订单记录中使用普通订单号和标题展示，不添加来源标签； 不会写入当前支付订单、重复履约、退款或改变当前账务责任。非终态订单仍需按责任方完成 终态增量处理。
• 隔离 PostgreSQL 合成用户已完成登录、原密码、原 Key、余额、套餐、用量、历史订单的首次 Apply、重复 Apply 和五类 fingerprint Verify；当前站点 API 已能读取 Key、历史用量和历史 订单。该结果不代表真实旧库已审计或导入。
• dry-run 会输出密码兼容、账号、冻结/负余额、Key 状态/过期、API/网页用量、套餐映射和 非终态订单分类；订阅 dry-run 不再遇到第一条未映射记录就停止，便于一次补全 plan map， 而 Apply 仍拒绝任何未映射记录。

尚未完成

• 公开网关当前只开放模型查询与生成创建；异步视频/音频任务的公开轮询、取消仍需固定 “任务 ID → 用户/Key/渠道/上游模型”查找契约，不能由客户端直接选择内部渠道；
• 冻结余额的解冻与可消费规则；
• 旧站非终态订单的终态增量责任与对账映射；
• 代表性合成用户通过生产等价 standalone、新 API 网关和配置后的 new-api 使用原 Key 的 完整调用闭环（当前已使用本地 PostgreSQL和协议夹具验证原 Key、0.00000001 扣费、失败 等额退款与幂等重放拒绝，尚无真实 new-api 调用）；
• 多实例公开 API 的共享最大并发租约与正式容量基准；
• 真实旧库只读审计、最终导入、部署、DNS、账本切换和旧服务关闭。

上述事项未完成前，不得把本地候选描述为迁移完成或生产可用。