身份与权限
全局登录、会话、产品如何识别用户、平台角色与产品角色
产品要求
在任一 OceanWay 产品（Site、Console、Admin、Studio、Drama、Commerce）登录后，所有产品都识别为同一个用户，无需再次输入凭据。具体要求：
- 登录可以从任何产品发起，登录后回到发起时的页面。
- 已打开的其他产品页面，在下次请求受保护内容时识别出同一用户，用户不需要手动“同步登录”。
- 公开内容（Site、Console 的模型与文档页）未登录也能看；登录后显示统一的账户入口。
- 登录只回答“你是谁”，每个产品再判断“你能做什么”。普通客户打开 Admin，看到的是“已登录但没有权限”，而不是再次被要求登录。
- 账号停用或会话撤销后，所有产品都要失效。
- 2026-10-02 用户明确：Studio、Drama、Commerce、Console共用用户登录会话，任意一站退出须结束当前浏览器在所有平台的登录状态；Site/Admin沿用同一规则。登录统一不改变既有角色和动作权限。
- 全局退出撤销平台权威会话；其他站点的下一次受保护请求立即拒绝，不允许以产品缓存继续访问、开始执行或扩大预算。跨主域入口也必须绑定同一全局会话及撤销状态。
- “退出所有设备”是另一个单独操作；默认全局退出结束当前浏览器跨平台会话，不自动结束其他设备。
方案：主域名共享 Cookie
首个正式主域名为 oceanway.tech（2026-10-02 用户确定）。主域名、产品入口、Origin 与返回地址白名单从配置读取，不写死在代码。具体子域名称仍待确定。
同一主域名下的受控产品共享主域 Cookie。后续需要支持 oceanway.ai 等其他受控主域，并继续使用同一套用户账号、钱包和平台会话权威。浏览器不能将 .oceanway.tech Cookie直接共享给.oceanway.ai；新增主域须通过统一登录授权跳转建立该域自己的会话 Cookie，全局注销/封禁仍由平台会话权威统一校验。跨主域授权协议、一次性交接及撤销流程需在T-04明确并验证，不能仅把Cookie Domain改成两个域名或复制长期凭据进URL。
域名扩展仅限显式配置并由OceanWay控制的第一方入口；oceanway.ai是后续接入需求示例，本轮未配置DNS、证书或上线。
- 登录由平台完成。 登录页由平台提供，产品把用户带到登录页时附上返回地址；平台只接受白名单内的返回地址。
- 平台写入会话 Cookie。 Cookie 的作用域设为主域名、
Path=/，并设置HttpOnly、Secure、SameSite=Lax。具体名称、刷新与访问凭据分工在基线审计后确定；不能直接复用默认仅限刷新路径的 Cookie。 - 产品后端向平台确认身份。 产品收到请求后，把会话 Cookie 转给平台的身份接口，取得用户 ID、状态和角色。产品可以短时间缓存结果，但账号停用后的失效时间要有上限。
- 防跨站请求伪造。 修改数据的请求除了 Cookie，还要校验来源（Origin）或 CSRF Token。
new-api 已有登录、会话、刷新、撤销和 Token 鉴权，平台在此基础上补充：主域名 Cookie、返回地址白名单、供产品调用的身份接口。
共享 Cookie 的主域名只能包含受控的第一方服务；客户自定义域名和不可信内容站不加入该作用域。产品仅转发指定的身份 Cookie，不转发整份 Cookie/Header，也不共享平台的会话签名密钥。来自兄弟子域名的请求不能仅因 SameSite 判定而放行：写操作校验允许的 Origin 与 CSRF 防护，缺少来源时使用明确的服务鉴权路径。
身份缓存键必须绑定会话，账户切换后清除旧用户数据。首期身份请求直接核验平台权威会话，不启用此前提出的30秒身份缓存。受保护内容、新付费/开始/新增预算、管理写入必须核验当前身份；注销或封禁后下一次请求立即拒绝。已打开页面的退出提示可通过通知/重新查询同步，但页面展示不作为任何授权依据。T-03当前已直接读取权威会话，多主域撤销传播仍需T-04实现与验收。身份或权限校验失败时拒绝新的受保护写入；Admin 的资金和权限操作重新向平台核验，不仅依赖产品缓存。全局退出会撤销平台会话并清除同名、同路径、同域 Cookie；缓存失效上限在验证阶段确定。
产品服务凭据（待定）
用户在各产品使用同一套账号和登录状态。这里的“产品服务凭据”由产品后端持有，仅证明发起调用的是Studio、Drama还是Commerce；用户不需要输入或分别登录，不创建第二套用户账号。独立撤销/轮换产品凭据影响对应产品的后端调用能力，不自动注销用户或改变其他产品的登录状态。用户退出则统一撤销全局用户会话；产品凭据不能绕过撤销替该用户创建新操作、开始新执行或追加预算，只可按原授权恢复已发出任务的结果和账务。
产品后端代表用户调用平台（调模型、扣费）时，需要一种服务认证凭据。候选方式：
| 方式 | 做法 | 适合 |
|---|---|---|
| A. 用户 Cookie + 产品服务凭据 | Cookie 证明用户会话，受限服务凭据证明来源产品和允许的动作 | 用户正在操作时，产品后端创建同步调用或付费操作 |
| B. 产品服务凭据 + 已授权操作 | 服务凭据绑定产品与允许的动作；后台请求引用平台已经授权并登记的操作，用户从操作记录读取 | 用户可能已不在线的后台查询、结果登记和结算 |
| C. 每用户每产品一个 Key | 平台为用户在每个产品下自动签发一个 API Key | 产品需要长期保存调用凭据的场景 |
建议同步请求用 A，后台任务用 B。第 1 阶段先完成最小可行性验证，第 2 阶段确定最终凭据格式；上述候选不表示原版 new-api 已提供代用户接口。
在产品集成接口中，单独的用户 Cookie 可用于身份查询，不足以声明可信产品来源或创建受限产品付费操作。Console/Admin 直接调用平台业务接口仍按各自的会话、CSRF 与权限鉴权，不要求浏览器持有产品服务凭据。
委托调用必须满足的约束
- 产品服务凭据只证明调用产品，不能单独授权它对任意用户扣费。创建业务操作时，平台必须校验有效用户会话或已绑定该用户的委托凭据，再保存用户、产品、业务任务、请求指纹和允许的动作。
- 普通请求 Header/Body 中的
user_id、product或角色不能覆盖已验证身份。来源产品由服务凭据或受控的用户 Key 元数据推导；公共 API 默认记录为 API，客户不能伪造产品来源。 - 后台查询、结算和释放引用平台
operation_id，校验服务凭据的产品和动作与原操作一致。跨用户、跨产品、同键不同输入必须拒绝。一个应用承载三个子站也要分别区分产品作用域。 - 用户退出后，已授权且已发出的任务仍需恢复、登记结果与完成原账务；退出不授权新的付费调用。封禁停止新的执行；已经发生的成本和退款按原操作核对，不遗失任务或强行标失败。
- 服务凭据仅存服务器，可轮换、撤销，不发给浏览器。产品工作人员没有平台财务权限时，不得通过产品接口变更余额。
具体使用不透明操作引用还是受限签名凭据，待验证后定稿；权限边界保持一致。
角色与权限
| 类型 | 例子 | 由谁校验 |
|---|---|---|
| 平台角色 | 普通用户、员工、财务、超级管理员 | 平台 |
| 产品角色 | studio:admin、drama:admin、commerce:operator | 产品向平台查询，产品自己执行 |
- 员工和客户使用同一套账号体系，不另建员工账号。
- 产品角色由员工在 Admin 中分配，产品通过平台接口查询当前用户的角色。
- new-api 已有 user / admin / root 三级角色和基于 Casbin 的权限规则，作为扩展基础。
- 企业首期使用专属账户，不做多人协作和成员邀请。
验收场景
| 场景 | 预期 |
|---|---|
| 以每个产品为登录起点 | 登录后回到原页面；再访问其他产品无需登录，识别为同一用户 |
| 已打开多个产品，在其中一个登录 | 其他产品在下次受保护请求时识别该用户 |
| 普通客户进入 Admin | 显示已登录但无权限，不循环跳转登录 |
| 非白名单的返回地址 | 拒绝跳转 |
| 账号停用、会话撤销、切换账号 | 各产品在约定时间内失效或更新，不残留前一个账户的数据 |
| 身份服务故障 | 显示可恢复的错误，不形成重定向循环，不重复提交支付或生成 |
每个产品都要分别作为起点和终点验证。
待定事项
- 首个主域名已确定为
oceanway.tech；各产品子域名、后续主域接入配置与跨主域SSO交接协议待定。 - 产品服务凭据的最终方式。
- 首期身份不缓存、下一次受保护请求即时核验已确定；主动通知已打开页面、跨主域会话交接及全局撤销实现仍需验收。