决策与待定事项
新架构的有效决策与尚待确定的实现选择
2026-09-20 全项目路线复盘
用户已确认按本次复盘执行：继续现有 Core / Edge / 产品多仓路线，纠正计费实现来源，不整体重启为完整 new-api 客户后台。 决策 D-CORE-EDGE-USAGE-BILLING-CONFIRMED，与“不修改 uumi 代码”共同作为执行基线。首批离线计算器已交付，见迁入记录；计费主链和生产仍未切换，商业参数也未因此自动确认。
上一轮“完整 new-api 客户后台 + uumi 更快”的建议主要针对纯文本 API 转售，未充分计入全局身份、统一文本/媒体钱包、客户差异价以及已经接入的 Console/Admin，不能作为整个项目的最终结论。反过来，已有代码也不是必须原样保留的理由：新平台尚未生产运行，仍须按实际验证决定模块取舍。
不随实现方式摇摆的边界
| 边界 | 固定原则 |
|---|---|
| 产品 | 开发者与创作者两条线都完成；产品可分批上线，不删减长期范围 |
| 客户事实 | Core 唯一持有新平台客户身份、Key、销售价格与客户钱包；Admin 权限独立于全局登录 |
| 供应 | uumi 继续维护供应商、渠道与模型转换；本次不要求它新增 quota 回执或改响应；媒体网关继续独立 |
| 入口 | Edge 负责公共协议、鉴权协作、流式转发、用量证据采集；不拥有客户钱包或供应商后台 |
| 计费 | 不部署第二套客户钱包，不用后台同步两份余额；客户售价与 uumi 网关侧账目分别核算 |
| 产品任务 | 产品仓维护业务 Workflow；Core 同仓 Worker 承接共享任务和账务恢复；不先建通用 Workflow 平台 |
| 工程 | 产品分仓不等于每个领域独立微服务；保留现有 Core/Edge 运行边界，首期可同环境部署，不新增计费/身份/价格服务 |
三条路线的取舍
| 路线 | 实际优势 | 仍然需要承担的工作 | 结论 |
|---|---|---|---|
| 现有 Core/Edge，迁入 new-api 计量与计价模块 | 保留账户、价格版本、持久结算和前端接口；统一文本与媒体账务 | 完整 usage 集成、恢复、生产鉴权/支付、热路径并发优化 | 全项目推荐 |
| 完整 new-api 客户后台 + uumi | 纯 API 转售较快复用完整 Relay/管理/计费 | 重新接入 OceanWay 自定义接口、SSO、协议价和媒体恢复；转换后的用量完整性仍需验证 | 若产品目标明确缩成独立 API 转售站才优先，当前不重启 |
| 保留 Core 钱包再加完整 new-api 客户计费服务 | 表面同时复用两套功能 | 双身份、双余额、预扣/退款分叉，或逐个替换上游直接写账路径 | 不采用 |
new-api 本身也有缺失 usage 估算、资金/Key 分步调整和异步退款路径，完整复制不等于跨进程恢复及精准计费全部解决。现有 Core 的持久操作、价格快照和幂等流水有独立价值；但当前多处目录全局锁、loopback 联调入口和测试资金又意味着它尚未生产成熟。两边的优缺点都必须纳入判断。
真正需要修改的是计费主链
目标：客户请求 → Core 准入并冻结价格/预留 → Edge → uumi → 原协议响应及完整 usage → Core 按冻结销售规则计算并结算。正常请求不查询 uumi 日志；日志只作低频异常核对，受其现有权限、限流与保留窗口限制。
- Edge 收集普通响应或完整流式用量证据，记录来源协议、终态与 uumi 请求ID；不能把增量/累计用量盲相加，不能从客户传入字段接受用量或金额。
- Core 迁入固定版本 new-api 的用量语义、缓存口径和计价实现及对应测试，接入自己的价格快照和唯一钱包。
relaykit/dto中已有billing_usage、CanonicalUsage()；pkg/billingexpr有可复用部分。首批 DTO/合并、常规文本倍率和舍入已离线迁入，表达式引擎及运行主链尚未接入。 service/text_quota.go包含渠道、配置、Gin、日志和钱包依赖，不能直接作为无副作用函数整份复制；需要明确依赖边界，保留来源及舍入测试。常规倍率、缓存和阶梯等规则不能只迁表达式引擎后就宣称全覆盖。- 固定源码能携带原始计量语义，不代表运行中的 uumi 每种模型/路径都实际返回完整字段。统一 OpenAI 路径下的 Claude/Gemini 缓存与推理用量须实测；换成完整外层 new-api 同样绕不过这一步。
- 客户标准销售价格和协议价由 Core 版本化管理，可从现有配置初始化；不逐请求拉价，不让供应调价静默改写在途客户价。客户费用不以 uumi 最终 quota 完全一致为定义。
- 对缺少必要字段的功能不宣称支持；执行中证据不足则待核对，不把估算或零值当精确最终账单，不自动重发付费调用。
已有成果如何处理
| 成果 | 处理 |
|---|---|
| Core 身份、Key、客户、模型许可、价格版本/报价 | 保留并补生产验收，业务规则不因 Relay 选型重做 |
| Core 钱包、预留、操作、幂等结算 | 保留唯一写入方；替换用量/价格求值接入，并审查锁粒度、故障恢复与真实资金政策 |
| Edge 四协议与 SSE、Core Client | 保留；补完整计量和真实公共服务入口，不再逐模型手写独立转发栈 |
capture-chat-v1、uumi-log-v1 | 保留作为测试/历史证据；后者退出目标生产正常结算路径，当前代码尚未切换 |
| Console、Admin、Contracts | 保留产品与已验证 API；只修订真正变化的计量/结算契约，不再次全量替换 |
| Studio、Drama、Commerce、媒体网关 | 保留各自代码和业务边界，按首条流程接身份与单一钱包 |
接下来按结果推进
- 固定一次用量/计价集成验证。 同一 OpenAI 入口覆盖代表性的 OpenAI/Claude/Gemini，普通/SSE、缓存写入/命中及推理口径。采集同一回包，离线分别交给原实现与迁入计算器，使用相同价格/规则比较，避免通过重复真实请求要求结果碰巧一致。
- 替换计费主链并做失败验收。 正常请求对
/api/log/token的调用次数为零；Core 接收完整证据、冻结价格、去重结算；缺 usage、断流、重启、余额不足、改价覆盖。旧 profile 不静默混用，新契约与版本显式标记。 - 完成可售文本平台。 恢复 Worker、正式积分/充值规则、生产服务鉴权、SSO/员工权限、支付、Console/Admin 对账，以及 PostgreSQL/锁粒度/限流/容量验证。race 测试不代替容量报告。
- 接一条媒体与产品流程，再逐产品扩展。 证明文本和媒体只扣同一客户钱包一次；产品自己的流程保留，不先抽象所有产品。
- 迁移与发布。 核对 sub2api 余额购买力、旧价覆盖及回退方案，先小批客户；uumi 既有模型对接客户迁移范围仍按业务决定，不自动停服或搬账。
以上是现有 NEXT 队列的技术修正，不增加一套并行实施编号。不同客户价格、全局登录是用户需求；逐模型覆盖优先级、权益批次、周期订阅、通用资源抽象等文档建议不能全部当作首发已批准范围。企业多人协作、通用 Workflow 引擎、复杂营销和额外视觉重做继续后置。
后续架构修改必须说明新的硬约束、可复现实证、保留/迁移成本和被替代决定；不能由一次调用失败或局部实现便利触发全仓重写。最近真实结果见协议与缓存验证；四协议透传成功不等于四协议独立计费已经完成。
管理入口与功能归属（2026-09-27）
本轮用户要求以 Studio 管理功能为基座拆分，并开始确定和固化多平台管理归属。管理形态采用一个入口进入公共管理及 Studio/Drama/Commerce/Site 空间；供应后台首期独立使用，不接入该入口；Console 是客户自助后台，不属于管理员空间；不把所有功能塞进同一个菜单，也不让各产品复制客户和钱包。具体工作基线见管理空间架构与26 项归属表。
原 CA-A01–20 保留为公共客户商业切片；新增模块迁移由 ADM-P09 承接，其他产品计划增加各自管理接口与接入任务。公共内容持久化归属、页面部署、首批范围等仍按 MG-D01–06 讨论；本轮只固化文档，不代表迁移完成、全部功能首发或生产发布。现行统一身份决定保持，不恢复历史 Workforce 方案。
当前实现决定
D-NEWAPI-REUSE-FIRST：大部分代码和接口优先直接复用 new-api，当前技术栈完全一致；按多仓职责迁入，仅补职责拆分和业务差异。D-CORE-EDGE-PRIORITY：现在重点开展 Core 与 API Edge，既有产品需求与原型作为配套输入，不等待全量页面完成。来源为 2026-09-12 当前用户明确要求。
最新最终决定
D-RESTORE-FIRST-POLYREPO：2026-09-12 用户明确恢复最初多仓设计、代码重点参考 new-api，直接修改第一版文档。替代单体二开与 Core/Edge 内部模块建议；独立网关和后续产品商业决定继续有效。原始第一版结构恢复，不据此恢复旧代码或旧验收。
已确认
| 决策 ID | 内容 |
|---|---|
| D-GLOBAL-LOGIN | 任一 OceanWay 平台登录，全平台共享同一用户登录状态；平台权限分别校验 |
| D-LOCAL-FIRST | 三人团队、用户负责开发，本机协调优先，计划与设计不依赖 GitHub Issue |
| D-DUAL-PRODUCT-LINES | 创作者线和开发者线都要完成 |
| D-NEWAPI-FOUNDATION | 以官方 new-api 后台能力为基础建设平台 |
| D-NEWAPI-BACKEND-ONLY | 上游前端可以全部重做，不约束 OceanWay 前端 |
| D-CONSOLE-DEVELOPER-MERGE | 2026-09-22：Developer Center 合入 Console，公开阅读和私有管理同仓同站，取代 D-DEVELOPER-PUBLIC 的独立站安排 |
| D-NEWAPI-CLEAN-RESTART | 原先建立的官方固定工作区保留为源码参考；最终服务按多仓实现，旧代码不自动恢复 |
| D-DOCS-V2 | 曾按候选方向重组文档；当前目录已按最终决定恢复第一版并修订，候选方案归档 |
| D-UI-SHADCN | 原型使用 shadcn，沿用 OceanWay 风格；客户页面参考 new-api 二次修改 |
| D-KEY-COPY | 掩码旁复制按钮直接获取完整 Key 并复制 |
| D-CNY-CREDITS | 人民币充值、系统内积分；具体套餐待定 |
| D-ENTERPRISE-ACCOUNT | 企业专属账户与协议价，首期不做多人协作 |
| D-UNIFIED-CUSTOMER-PLATFORM | 零售迁入新平台，sub2api 迁移后退役；模型对接客户是否迁入按 D-CUSTOMER-SEGMENTS 单列，不再强制所有客户迁入 |
| D-CUSTOMER-SEGMENTS | 零售、FDE、模型对接为三类客户；前两类消费倍率 1、充值非 1:1，模型对接客户在 uumi 充值 1:1、多组多倍率 |
| D-GATEWAY-UPSTREAM-BOUNDARY | 独立 new-api 网关无终端客户，供 OceanWay 模型调用并跟随上游升级；客户平台独立定制 |
| D-POLYREPO-NEWAPI-STACK | 多仓同栈方向恢复有效；Core/Edge/Contracts 分仓，独立网关原则保留 |
记录来源为当前统筹会话及本机 coordination/decisions.md。旧 B0–B6 和 ADR-028–032 是历史设计；不能将其中 Core、Edge、Contracts 的旧依赖直接作为新方案前置条件。
三类客户背景与本轮讨论已固化到客户定价。零售与 FDE 进入统一平台、模型对接客户暂留 uumi 是当前推荐方案；模型对接客户最终迁移选择、旧价承诺范围及具体套餐仍待定。
待设计或待选择
- 全局登录已确认；域名部署、交接协议、访问令牌生命周期、撤销时限与服务调用上下文仍待设计。
- 组织、项目协作需要哪些权限，哪些产品先使用。
- 各仓实际工作树、分支与部署实例映射；Core/Edge/Contracts 分仓已确定，不再作为待选择项。
- 自研媒体网关的真实端点、输入／状态／费用映射与取消能力。
- 首期模型、定价规则、产品功能范围和目标容量。
- 后续正式域名调整、历史账号和业务数据处理。
这些事项进入对应需求或设计包，不用空值或推测伪装定案。修改一项决定时记录替代关系、受影响页面／接口和验证要求。
D-CONTRACTS-CONTENT-REPLACEMENT
2026-09-12 用户决定保留原仓库结构、整体替换旧 Contracts 内容。保留 Git 历史与目录职责；当前契约以固定 new-api 原接口和 OceanWay 必要差异重新建立，不继承旧包的过期协议限制。新工作树为本地候选，旧发布和消费者尚未切换。