外观
Nexo — 2026-09-20 迭代需求文档
范围：落地权限平台首期。总 PRD 见 nexo-im-pc#58（权限平台总 PRD），本文承接其 §6.1 首期范围，只裁剪不扩张；产品语义（五步判定、fail-closed、范围与命名空间、显式拒绝优先等）一律以总 PRD 为准，本文不复述其推导，只登记本期落地口径与降级决策。 验收标准见第 8 节，本文档定义"做什么"与"为什么"；"怎么做"以同目录技术方案（
design.md）为准。
1. 背景与目标
2026-09-13 迭代交付统一账号与认证中心（nexo-account）时，明确挂账了一条架构原则："权限平台未上线前不进行鉴权"——管理接口只要携带合法 Bearer JWT 即放行，不写 ADMIN_USERNAMES、不写 requireAdmin。这不是能力缺失，而是拒绝伪鉴权、等真平台的刻意留白。
本期即偿还这笔账：新建 nexo-perm-api（权限平台后端） 与 nexo-perm-console（权限管理台前端），把生态内权限的维护与验证统一收口——组织/角色/权限点管理、两条授权链路 + 显式拒绝、五步判定鉴权接口、用户状态联动、审计事件投递，一次落全首期范围。
核心目标（对应总 PRD P1-P4）：
- 收口：权限数据与鉴权逻辑收进权限平台，业务方接入 = 注册权限点 + 创建角色，不再各自实现；
- 统一映射：用户身份 → 权限主体在平台统一维护（主体单有效行 + epoch）；
- 即时回收：账号停用联动主体失活，鉴权第一步立即拒绝；
- 全链路可审计：4 类审计事件 100% 产生调用（本期先落本地适配层，见 §4.2）。
2. 承接与已知欠账（承接 2026-09-13 验收）
| 欠账项 | 处理 | 排期 |
|---|---|---|
nexo-account 管理接口"合法 JWT 即放行"，无真实鉴权 | 本期交付权限平台鉴权内核与 SDK；nexo-account 侧的实际接入改造不在本期（避免双平台同期互踩），下期接入 | 平台本期 / 接入下期 |
| 生态无统一"某人有哪些权限"视图 | 本期交付授权管理页按用户视图 + 我的权限只读视图 | 2026-09-20 |
| 人员停用后各业务权限回收各自为政 | 本期交付：账号停用通知联动主体失活 + 定时兜底核对 | 2026-09-20 |
3. 功能需求
FR 与任务映射见 §7；每条 FR 的完整产品语义见总 PRD 对应章节，此处只登记本期落地边界。
FR-1 组织与业务方命名空间管理（总 PRD §4.1/§4.3） 组织全局统一（创建/编辑/停用，停用事务内联动禁用其下角色）；命名空间为独立归属实体，仅平台管理员可创建。
FR-2 权限点注册与生命周期（总 PRD §4.3） （命名空间, 标识）唯一；权限范围（组织权限/通用权限）创建时声明不可改；通用权限仅平台管理员可建；下线（软删，显式拒绝保留永效，同名重建即激活原实体）与硬删除（连删关联，同名重建为全新实体）双能力；硬删除前置影响面统计（N 条显式拒绝 / M 个角色关联 / K 个用户）。
FR-3 角色管理与角色-权限点关联（总 PRD §4.2） 角色绑定组织、分组织角色/业务角色；只软删；组织权限点强制同组织关联校验；组织归属一经创建不可变。
FR-4 角色组合（总 PRD §4.2） 组合关系单独维护，动态聚合（自身 ∪ 来源，变更实时生效）；创建时环检测强拒 + 深度上限强拒（不事后截断）+ 同组织校验。
FR-5 主体管理与超管引导（总 PRD §4.1/§4.5/§4.7） 用户主体（创建时查 nexo-account 确认可用，选主组织）与调用方服务主体（bound_namespace 一经创建不可变）；单有效行 + epoch 单调递增；超管经初始化脚本获平台级管理能力，解"鸡生蛋"。
FR-6 授权三关系与有效期（总 PRD §4.4） 用户-角色（强制同组织）、直接授权（组织权限强制同组织，带可选有效期）、显式拒绝（优先于放行，范围跟随权限点）；创建用户-角色时查一次 nexo-account 确认账号可用。
FR-7 鉴权接口（总 PRD §4.5） 入参三项（调用方标识/用户标识/权限点），出参 (allow, deny_reason) 五类；五步判定顺序、任一前置失败即拒；命名空间从已认证身份推导覆盖自报值；fail-closed 全路径；p99 < 10ms；不远程查账号系统。
FR-8 平台接口自身鉴权（总 PRD §4.5「接口鉴权」） 对外接口对应权限点管控；调用方服务以 app 主体身份调用；管理接口按平台管理员/业务方管理员/组织管理员角色管控，非硬编码特权。
FR-9 用户状态联动（总 PRD §4.7） nexo-account 停用/启用通知联动主体失活/新建行；作废旧有效行（含停用与调岗语义）原子清除通用权限显式拒绝；按主体串行化 + epoch 校验；定时兜底 ≤5min 双方向防错（失活方向 epoch 前置校验、复活方向不翻活旧行 + 消费时复查）。
FR-10 审计事件投递（总 PRD §4.6） 4 类事件（授权变更/拒绝事件/权限点变更/角色结构变更）100% 产生调用；deny 类异步投递不阻塞主流程，失败留存重试；只记 deny 不记 allow。
4. 本期裁剪与降级决策
4.1 审批门控不进本期
总 PRD §4.8 要求全部写操作过审批平台，但审批平台自身仍是长期 PRD（lamolabs-docs#54），未立项。本期写操作直落真实表，预留审批门控开关位；审批回调幂等、epoch 快照校验等契约由总 PRD 持有，审批平台上线迭代再落。随之降级：硬删除的审批联动（K 值漂移比对、审批单展示 deny 快照）降级为管理台影响面展示 + 标识输入双重确认。
4.2 审计平台未建，先落本地投递适配层
总 PRD §4.6 要求调生态审计平台接口、平台不落审计表。审计平台未立项，本期落投递适配层：统一事件入口 + 本地 outbox 留存 + 结构化日志，投递目标可替换；审计平台上线后仅换实现，调用方无感。4 类事件的调用点覆盖率仍按 100% 验收。
4.3 无消息队列基础设施，"事件必达"以 HTTP 通知 + 定时兜底等价落地
部署现实为单机 Docker Compose，无 Kafka/Redis（见 0913 技术方案选型现实）。总 PRD §4.7 的"消息队列必达 + 幂等消费"本期落地为：nexo-account HTTP internal 通知（HMAC 内部通道）+ 收侧幂等 + 按主体串行化消费 + ≤5min 定时兜底核对。通知丢失场景由定时兜底闭合，"必达"语义等价成立。参照 0913 停用通知的既有模式。
4.4 用户状态词汇对齐
nexo-account 已在 0913 彻底清除 HR 词汇，账号状态仅 PENDING/ACTIVE/DISABLED 三态。总 PRD 的"在职/离职/复职/调岗"在本生态映射为：离职 → 账号 DISABLED（主体失活，epoch 不变）；复职 → 账号重新启用（新建主体行，epoch 递增）；调岗 → 主组织变更（作废旧行 + 新建新组织行，epoch 递增）。鉴权判定第一步"主体在职"即"主体 active 且账号未停用联动失活"。
5. 明确不做（Out of Scope）
- 审批平台对接（§4.1；含审批回调签名校验、epoch 快照校验的实现）
- 审计平台本体与其对接切换
nexo-account/nexo-im-api等既有业务方的实际接入改造（下期，避免同期互踩）- 离职用户关联数据自动清理（首期人工确认，总 PRD §6.2）
- 权限点维度（动作 + 限定维度）、批量导入导出、变更消息推送、鉴权缓存（总 PRD §6.2 后续迭代）
- 前端 SDK（
nexo-web-sdk）侧鉴权封装
6. 非功能需求
- 性能：鉴权 p99 < 10ms（实时查询无缓存，本地基准压测取数）
- 安全：fail-closed 全路径含连接层（SDK 统一封装）；跨业务方/跨组织越权防护全部创建时强校验 + 鉴权时严格校验；平台接口自身受管控
- 可用性代价：故障即拒绝——平台故障会级联拒绝业务方请求，本期接受（总 PRD §5.2），本地缓存兜底后置
- 可审计：4 类事件调用覆盖率 100%（适配层留存可查）
7. 任务映射
21 个任务已建 issue 并挂组织 Project，锚点
nexo-2026-09-20:Bxx/Fxx/Txx。
| 编号 | Issue | FR |
|---|---|---|
| B01 | nexo-perm-api#1 服务骨架与核心数据模型 | 全部地基 |
| B02 | nexo-perm-api#2 组织与命名空间管理接口 | FR-1 |
| B03 | nexo-perm-api#3 权限点注册、范围声明与下线/硬删除 | FR-2 |
| B04 | nexo-perm-api#4 角色管理与角色-权限点关联 | FR-3 |
| B05 | nexo-perm-api#5 角色组合环检测与动态聚合 | FR-4 |
| B06 | nexo-perm-api#6 主体管理与超管初始化引导 | FR-5 |
| B07 | nexo-perm-api#7 授权三关系与有效期 | FR-6 |
| B08 | nexo-perm-api#8 鉴权接口五步判定与 fail-closed | FR-7 |
| B09 | nexo-perm-api#9 平台接口自身鉴权 | FR-8 |
| B10 | nexo-perm-api#10 用户状态联动与定时兜底 | FR-9 |
| B11 | nexo-perm-api#11 审计投递适配层 | FR-10 |
| B12 | nexo-backend-sdk#5 SDK 鉴权客户端 | FR-7 |
| F01 | nexo-perm-console#1 管理台骨架与登录态 | 前端地基 |
| F02 | nexo-perm-console#2 组织与命名空间页面 | FR-1 |
| F03 | nexo-perm-console#3 权限点页面与硬删除高危确认 | FR-2 |
| F04 | nexo-perm-console#4 角色管理与组合编辑页面 | FR-3/4 |
| F05 | nexo-perm-console#5 授权管理页面 | FR-6 |
| F06 | nexo-perm-console#6 主体管理页面 | FR-5 |
| F07 | nexo-app#58 壳挂载权限管理台入口 | 前端集成 |
| F08 | nexo-perm-console#7 我的权限只读视图 | FR-6 |
| T01 | lamolabs-docs#77 验收用例编写与预跑归档 | 全部 |
8. 验收标准
- 验收用例见同目录
tc.md（由 T01 维护并预跑归档证据），覆盖：五步判定顺序与五类拒绝原因、同组织校验矩阵、组合环/深度强拒、下线 vs 硬删除双语义、状态联动双方向防错、fail-closed 异常路径、跨业务方探测防护、管理台主流程 - 三项硬阈值实测取数不得估算：鉴权 p99 < 10ms、停用通知到主体失活生效延迟、定时兜底周期 ≤5min
9. 排期与发布（概要）
- 开发窗口 09-15 至 09-19，09-20 验收会；逐日排期与前后端并行策略（前端 09-17 起按契约 mock 先行）见技术方案 §14
- 发布顺序：test 环境全量联调（09-19）→ 验收通过后 prod 发布 + 超管初始化；回滚 = 停服务 + 壳隐藏入口，对现有业务零影响（本期无存量业务方接入改造），见技术方案 §15
10. 待评审收口
| 编号 | 事项 | 倾向口径 |
|---|---|---|
| Q1 | 组合深度上限默认值 | 5（PERM_COMPOSITION_MAX_DEPTH，创建时强拒） |
| Q2 | 管理接口权限点粒度 | 按资源粒度 8 个点（design §9.4），不按端点逐一建，防首期权限点爆炸 |
| Q3 | nexo-account 事件通知覆盖面 | 0913 已有停用通知；enabled/org_changed 若缺，由 B10 在 account 侧开配套 issue 补推送 |
| Q4 | 管理员行权范围过滤（本组织/本命名空间收窄） | service 层按调用者角色上下文过滤，B09 单测重点覆盖 |
11. 候补（登记，本期不做）
nexo-account/nexo-im-api接入 SDK 鉴权改造（下期第一优先，偿还"合法 JWT 即放行"）- 审批平台对接（含回调签名、epoch 快照校验落地）与审计平台投递切换
- 离职关联数据自动清理、权限点维度、批量导入导出、变更消息推送、鉴权缓存（总 PRD §6.2）
- 前端 SDK（
nexo-web-sdk）鉴权封装、组织架构树可视化
12. 风险与降级
| 风险 | 应对 |
|---|---|
| fail-closed 下平台故障级联拒绝业务方 | 本期接受；SDK 明确 exception 可提示重试；缓存兜底后置 |
| 无 MQ，通知丢失窗口内权限未回收 | 定时兜底 ≤5min 闭合；账号停用后登录态已被 nexo-account 收回，窗口风险低 |
| 审批未接，写操作无流程门控 | 全部写操作过接口鉴权（FR-8）+ 审计留存（FR-10）；审批上线后补门控 |
| 双新仓并行，前后端接口契约漂移 | 技术方案 §9 接口契约为冻结源，变更须先改文档再改代码 |
| 后端 12 任务 5 天窗口偏紧 | B01-B08 为验收底线（M1），B09-B12 允许顺延至验收会前一晚；排期见技术方案 §14 |
13. 名词解释
口径与总 PRD §8 完全一致（权限主体/主体类型/组织/命名空间/权限点/权限范围/角色/组合关系/显式拒绝/故障即拒绝/拒绝原因等），本文不重复登记；本生态特有映射见 §4.4。