# M2 用户、角色与权限 — FSD（功能设计说明书）

| 项 | 值 |
|---|---|
| 模块 | M2 用户、角色与权限 |
| 文档类型 | FSD（功能设计说明书） |
| 对应 PRD | [requirements/M2](../requirements/M2-用户角色与权限.md) |
| 对应 LDD | [ldd/M2](../ldd/M2-用户角色与权限-设计.md) · [数据字典](../ldd/数据字典.md) |
| 配套 | [业务流程图-M2.txt](业务流程图-M2.txt) · [测试用例-M2.md](测试用例-M2.md) |
| 上级 | [需求分析总纲](../需求分析总纲.md) · [FSD 模板](FSD-模板.md) |

> 逐功能规格；身份/权限数据模型、RBAC/ABAC 机制、数据范围映射、SSO/供给集成见 ldd/M2，字段定义见数据字典，**引用不复制**。类型为逻辑类型，物理类型留待 SDD。本模块为基座（全模块复用其功能权限与数据范围判定），成熟度"已起草待细化"，未定处标"待业务"。

## 1. 概述与范围
统一身份基座：Google + 飞书 SSO 按 email 合并唯一 User；**RBAC 管功能、ABAC 管数据范围**，双层解耦、多角色取并集；员工入离职自动供给、外部账号受限接入。为全模块提供权限判定与数据范围计算。

**PRD 覆盖追溯（FR → 功能）**

| FR | 功能 |
|---|---|
| FR-IAM-01 | §4.1 SSO 登录与身份合并 |
| FR-IAM-02/03 | §4.2 角色与功能权限（RBAC） |
| FR-IAM-04 | §4.3 数据范围（ABAC） |
| FR-IAM-07 | §4.4 多角色并集 |
| FR-IAM-05 | §4.5 权限变更即时生效与越权审计（贯穿 §4.2–§4.4） |
| FR-IAM-06 | §4.6 用户供给（入离职/转岗） |
| FR-IAM-08 | §4.7 外部账号（邀请开通与受限访问） |

**不在本模块**：审批链与缺席委托实现（M9）、各业务功能本体（M1/M3–M13）；本模块只提供其权限判定与范围过滤。角色集合与功能权限映射为**配置项**，随各模块细化持续填充（M2 成熟度：已起草待细化）。

## 2. 角色 × 操作权限矩阵

> RBAC 功能动作以配置为准，下表为基线示意（动态可配，D 见 §4.2.5）。数据范围列由 ABAC 计算（§4.3）。

| 操作 \ 角色 | TAM | CSM | PS/PSE | PS_Leader | Sales/SA | Ops | Admin | Customer_External |
|---|---|---|---|---|---|---|---|---|
| 登录（SSO） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓(邀请后) |
| 立项 / 交付操作 | 依模块 | — | ✓参与项目 | ✓ triage | — | — | ✓ | ✗ |
| 审批 | 依链(M9) | 依链 | — | ✓ | — | — | ✓ | ✗ |
| 配置角色/权限/范围策略 | — | — | — | — | — | — | ✓ | ✗ |
| 邀请外部账号 | ✓(自己客户/项目) | — | — | ✓(PM) | — | — | ✓ | ✗ |
| 查看数据范围 | 自己客户 | 自己客户 | 参与项目 | 团队/Region | 依配置 | 依配置 | 全量 | 仅自己项目/交付物 |
| 受限只读 + 签署 | — | — | — | — | — | — | — | ✓(仅自己相关) |

> 功能权限（可否执行某动作）= RBAC；数据范围（能看到哪些行）= ABAC；二者**独立配置、独立生效**（验收：可各自验证）。多角色时两者均取**并集**（§4.4）。

## 3. 状态流转与业务流程图
> 图见 [业务流程图-M2.txt](业务流程图-M2.txt)。含：① 权限判定流程（登录→SSO 合并→角色解析→RBAC 功能校验 ∩ ABAC 范围过滤→放行/拒绝+审计）；② User 供给状态（未开通→在职启用→转岗调整→离职停用/回收）；③ 外部账号邀请开通泳道；④ 用户入离职供给泳道。

## 4. 功能规格

### 4.1 SSO 登录与身份合并

**4.1.1 功能说明**　用户经 Google 或飞书任一 SSO 登录，系统按 email 归并为同一 User（唯一键=email），不产生重复账号；首次登录若无匹配 User 则依供给记录/邀请建档（§4.6/§4.7）。

**4.1.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §一。要点：选择 SSO→IdP 校验→取回 email→按 email 查 User→命中即合并登录/未命中按供给或邀请处理→解析角色与范围→建会话。

**4.1.3 界面设计**
- **登录页**：两个 SSO 入口（Google / 飞书），无本地账号密码注册（禁止自助注册）。
- 首登引导：内部用户直接进工作台；外部账号仅进受限视图（§4.7）。
- 合并提示：同 email 二次经另一 SSO 登录时静默合并，不重复建号、不打断。

**4.1.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| email | 文本 | 是 | 唯一、非空、合法邮箱 | SSO(IdP) | 只读 | User 唯一键；合并锚点 |
| sso_provider | 枚举 | 系统 | google / feishu | SSO | 只读 | 本次登录来源，仅记录不影响身份 |
| roles | 引用[多] | 系统 | 角色须存在 | 供给/配置 | 仅 Admin | 决定 RBAC/ABAC（§4.2–§4.4） |
| account_status | 枚举 | 系统 | 启用/停用 | 供给(§4.6) | 系统/Admin | 停用则拒绝登录 |

**4.1.5 业务规则**
- User 唯一键=email，Google 与飞书两条 SSO 均按 email 合并（ldd/M2 §1、§4）。
- 合并正确率=100%：同一 email 不得产生重复账号（验收）。
- 无自助注册：账号仅由供给（§4.6）或外部邀请（§4.7）产生。

**4.1.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| IdP 返回无 email | "登录失败：未获取到邮箱，请联系管理员" | 阻断，不建号 |
| email 无匹配 User 且非邀请/供给 | "账号未开通，请联系管理员" | 阻断 + 记日志 |
| 账号已停用 | "账号已停用，无法登录" | 拒绝 + 记审计 |
| 两条 SSO 出现同 email | （静默） | 合并到同一 User，不重复建 |

**4.1.7 权限控制**　全员可经 SSO 登录；外部账号仅在被邀请且启用后可登录；停用账号一律拒绝。

### 4.2 角色与功能权限（RBAC）

**4.2.1 功能说明**　RBAC 管**功能**：角色绑定可执行的功能动作（立项/审批/配置等），Admin 动态维护角色集合与权限映射（不 hard-code）；权限判定在每次功能动作前执行。

**4.2.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §一（RBAC 段）。要点：动作请求→解析用户角色→查角色→功能权限并集→命中放行 / 未命中拒绝+审计。

**4.2.3 界面设计**
- **角色管理页**（Admin）：角色列表（增删改）、每角色的功能权限勾选矩阵（动作分组）。
- **用户-角色分配页**（Admin）：给 User 赋一个或多个角色。
- 无权限的功能入口默认**隐藏**；直达时给拒绝提示。

**4.2.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| role.name | 枚举 | 是 | 取值见 FR-IAM-02（TAM/PS/PS_Leader/Resident_Engineer/CSM/Sales/SA/Ops/Admin/Customer_External，可扩展） | 配置 | 仅 Admin | 动态可加，不写死 |
| role.function_permissions | 引用[多] | 否 | 动作须在动作字典内 | 配置 | 仅 Admin | RBAC 核心；见数据字典 Role |
| user.roles | 引用[多] | 否 | 角色须存在 | 供给/配置 | 仅 Admin | 多角色取并集（§4.4） |
| 功能动作项 | 枚举 | 是 | 立项/审批/配置/邀请/… | 动作字典 | 仅 Admin | 具体动作集待各模块细化 |

**4.2.5 业务规则**
- RBAC 只管功能、不管数据范围；与 ABAC（§4.3）**解耦、可各自独立配置与验证**（验收）。
- 角色集合与功能权限映射动态可配（D：FR-IAM-02/03、ldd/M2 §2）；完整映射矩阵随各模块细化（PRD 遗留：待细化）。
- 权限变更即时生效（§4.5）。

**4.2.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 无功能权限执行动作 | "您无权执行该操作" | 拒绝 + 记审计（FR-IAM-05） |
| 分配不存在的角色 | "该角色不存在" | 阻断 |
| 删除仍被引用的角色 | "该角色仍有用户/策略引用，无法删除" | 阻断，提示先解绑 |

**4.2.7 权限控制**　仅 Admin 可维护角色与功能权限映射、可给用户赋角色；其余角色只按所赋权限执行功能。

### 4.3 数据范围（ABAC）

**4.3.1 功能说明**　ABAC 管**数据范围**：由用户属性（角色、所属 Region、绑定客户、参与项目）计算可见数据集，对列表/详情做行级过滤；TAM/CSM 见自己客户，PS 见参与项目，Manager 见本 Region，Customer_External 仅见自己相关项目/交付物。

**4.3.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §一（ABAC 段）。要点：数据请求→取用户 scope_attributes→按角色映射范围规则→生成可见集→过滤返回；越界访问拦截+审计。

**4.3.3 界面设计**
- **数据范围策略页**（Admin）：查看/配置各角色属性→可见范围映射（ldd/M2 §3 的规则表可视化）。
- 业务列表默认只呈现范围内数据；范围外对象直达时不可见/拒绝，不泄露存在性。

**4.3.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| scope_attributes.region | 枚举 | 否 | 合法 Region | 供给/绑定 | 仅 Admin | Manager 维度 |
| scope_attributes.own_customers | 引用[多] | 否 | 客户须存在 | 绑定(M1) | 系统/Admin | TAM/CSM 范围来源 |
| scope_attributes.joined_projects | 引用[多] | 否 | 项目须存在 | 参与(M6) | 系统 | PS 范围来源 |
| 可见范围规则 | 枚举 | 是 | 见 ldd/M2 §3 | 配置 | 仅 Admin | 角色属性→范围映射 |

**4.3.5 业务规则**
- 范围映射：TAM/CSM=自己绑定客户；PS=自己参与项目；Manager=本 Region；Customer_External=自己相关项目/交付物（FR-IAM-04、ldd/M2 §3）。
- ABAC 与 RBAC 解耦、可独立配置与验证（验收）。
- 越界可见记录数=0（验收）；越权访问拦截率=100% 且全量记日志（§4.5）。

**4.3.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 访问范围外数据 | "无权访问该数据" 或直接不可见 | 拦截 + 记审计，不泄露存在性 |
| scope 属性缺失（如无绑定客户） | （空态）"暂无可见数据" | 返回空集，不报错 |
| 范围规则未配置 | "数据范围策略未配置，请联系管理员" | 默认拒绝（最小权限，NFR-03） |

**4.3.7 权限控制**　仅 Admin 可配数据范围策略与用户 scope 属性；own_customers/joined_projects 随业务绑定（M1/M6）系统维护；各角色仅见其范围内数据。

### 4.4 多角色并集

**4.4.1 功能说明**　一人多角色（如 TAM 兼 CSM）时，功能权限（RBAC）与数据范围（ABAC）均取**并集**：可执行动作=各角色动作之并，可见数据=各角色范围之并；无遗漏、无越权。

**4.4.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §一（并集段）。要点：解析用户全部角色→RBAC 动作取并→ABAC 各角色范围取并→合并判定。

**4.4.3 界面设计**
- 用户详情/我的权限页：展示该用户的全部角色及合并后的功能与可见范围概览。
- 无需用户手动切换角色；系统按并集一次性呈现。

**4.4.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| user.roles | 引用[多] | 否 | 角色须存在 | 供给/配置 | 仅 Admin | 并集输入 |
| 有效功能权限 | 引用[多] | 系统 | =各角色 function_permissions 并集 | 派生 | 只读 | RBAC 并集结果 |
| 有效数据范围 | 结构 | 系统 | =各角色范围并集 | 派生 | 只读 | ABAC 并集结果 |

**4.4.5 业务规则**
- 功能权限与数据范围均取并集（D：FR-IAM-07 已敲定、ldd/M2 §2）。
- 并集正确率=100%：无遗漏（少给）、无越权（多给）（验收）。
- 并集是叠加，不做角色互斥/降级处理（本期无 deny 覆盖规则）。

**4.4.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 并集出现重复权限/范围 | （静默） | 去重合并，效果等价 |
| 某角色被停用/删除 | （静默） | 从并集移除该角色贡献，即时重算（§4.5） |

**4.4.7 权限控制**　角色分配由 Admin 维护；并集判定由系统统一执行，用户不可自选生效角色。

### 4.5 权限变更即时生效与越权审计

**4.5.1 功能说明**　角色/功能权限/数据范围策略/角色分配的任何变更**即时生效**并留审计；所有越权访问被拦截并 100% 记日志，供审计追溯（NFR-04）。

**4.5.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §一（判定与审计贯穿）。要点：Admin 变更→即时重算有效权限/范围→下一次请求生效；越权请求→拦截→写审计日志。

**4.5.3 界面设计**
- 审计日志页：权限/角色变更、越权拦截记录（时间/主体/动作/对象/结果），可筛选导出。
- 变更提示：变更保存后提示"已生效"。

**4.5.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| audit.actor | 引用 | 系统 | User 存在 | 系统 | 只读 | 操作/被拒主体 |
| audit.action | 枚举 | 系统 | 权限变更/角色分配/越权拦截/… | 系统 | 只读 | — |
| audit.target | 引用 | 系统 | — | 系统 | 只读 | 被访问/被改对象 |
| audit.result | 枚举 | 系统 | 允许/拒绝 | 系统 | 只读 | 拒绝即越权记录 |
| audit.at | 日期时间 | 系统 | — | 系统 | 只读 | 时间戳 |

**4.5.5 业务规则**
- 权限变更即时生效（D：FR-IAM-05）；生效延迟目标趋近即时（**具体延迟阈值待业务**）。
- 越权拦截率=100% 且 100% 记日志（验收、NFR-03/04）。
- 审计覆盖权限变更、越权访问（与总纲 NFR-04 全量审计一致）。

**4.5.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 变更后旧会话仍持旧权限 | （静默） | 下一次判定即重算，不依赖重登 |
| 审计写入失败 | （对用户静默） | 告警 + 重试（NFR-06），不放行未记账的越权动作 |

**4.5.7 权限控制**　仅 Admin 可改权限并查看全量审计；其余角色不可查看/篡改审计日志。

### 4.6 用户供给（入离职 / 转岗）

**4.6.1 功能说明**　与 HR/IdP 经 SCIM 或等价机制同步（INT-13）：员工入职自动开通账号、离职/转岗自动回收或调整权限，减少人工开销并防权限滞留。

**4.6.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §四（供给泳道）。要点：HR/IdP 事件→入职建 User+赋初始角色→转岗调整角色/范围→离职停用+回收权限→写审计。

**4.6.3 界面设计**
- **供给记录页**（Admin）：同步事件列表（入职/转岗/离职）、处理结果、异常项。
- 转岗/离职后受影响的角色与范围变更展示（联动 §4.5 审计）。

**4.6.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| provisioning.event | 枚举 | 系统 | 入职/转岗/离职 | HR/IdP(SCIM) | 只读 | 触发源 |
| user.account_status | 枚举 | 系统 | 启用/停用 | 供给 | 系统/Admin | 离职→停用 |
| user.email | 文本 | 是 | 唯一、合法 | HR/IdP | 只读 | 与 SSO 合并键一致 |
| user.roles | 引用[多] | 否 | 角色存在 | 供给/配置 | 系统/Admin | 入职赋初始、转岗调整、离职回收 |

**4.6.5 业务规则**
- 入职自动开通、离职/转岗自动回收/调整权限（D：FR-IAM-06、ldd/M2 §4、INT-13）。
- 供给的 email 即 SSO 合并键（§4.1），保证同一人身份一致。
- 权限回收/调整即时生效并留审计（§4.5）。

**4.6.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| SCIM 同步接口失败 | "用户供给同步失败，已告警" | 重试 + 告警（NFR-06），保留上次状态 |
| 离职事件到达 | （系统）"账号已停用并回收权限" | 停用 + 撤角色 + 记审计 |
| 供给 email 与既有 User 冲突 | （系统）合并 | 按 email 归并，不重复建号 |

**4.6.7 权限控制**　供给由系统任务执行；Admin 可查看供给记录与手动干预异常项；普通角色不可见。

### 4.7 外部账号（邀请开通与受限访问）

**4.7.1 功能说明**　Customer_External 账号由 **TAM 或 PM 邀请**开通；数据范围仅限其相关项目/交付物，能力为**受限只读 + 签署**（不可执行其它写操作）。非 TAM/PM 发起的开通一律阻断。

**4.7.2 业务流程**　见 [业务流程图-M2.txt](业务流程图-M2.txt) §三（外部账号邀请泳道）。要点：TAM/PM 发起邀请→校验发起人角色→生成邀请→外部用户 SSO 首登建 Customer_External→绑定其相关项目/交付物→受限只读+签署。

**4.7.3 界面设计**
- **邀请入口**（TAM/PM）：选客户/项目→填外部联系人 email→发送邀请。
- **外部受限视图**：仅展示其相关项目/交付物；仅"查看 + 签署"控件，无立项/编辑/配置入口。
- 非授权发起人不可见邀请入口。

**4.7.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| invite.inviter | 引用 | 是 | 须为 TAM/PM | 系统 | 只读 | 发起人角色校验点 |
| invite.email | 文本 | 是 | 合法邮箱 | 输入 | 邀请时填 | 外部账号身份键 |
| invite.scope | 引用[多] | 是 | 项目/交付物须存在且属发起人范围 | 输入/绑定 | 发起时定 | 该外部账号可见范围 |
| user.role(external) | 枚举 | 系统 | =Customer_External | 派生 | 只读 | 受限只读+签署 |
| account_status | 枚举 | 系统 | 待接受/启用/停用 | 系统 | 系统/发起人 | — |

**4.7.5 业务规则**
- 仅 TAM/PM 可邀请开通（D：FR-IAM-08 已敲定、ldd/M2 §4）；非 TAM/PM 发起阻断率=100%（验收）。
- 数据范围仅自己相关项目/交付物；可执行的非只读/签署写操作数=0（验收）。
- 签署复用 M8 签署能力；范围外对象不可见。

**4.7.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 非 TAM/PM 发起开通 | "仅 TAM/PM 可邀请外部账号" | 阻断 + 记审计 |
| 外部账号越权写 | "外部账号仅可查看与签署" | 拒绝 + 记审计（写操作数=0） |
| 外部账号访问他人项目 | "无权访问该数据" / 不可见 | 拦截 + 记审计（越界=0） |
| 邀请范围超发起人自身范围 | "只能邀请到您负责的项目/交付物" | 阻断 |

**4.7.7 权限控制**　TAM/PM/Admin 可邀请；外部账号仅受限只读 + 签署，且仅限自己相关项目/交付物；其余一切写操作被拒。

## 5. 接口与集成

| 接口 | 方向 | 触发/频率 | 字段映射 | 失败处理 |
|---|---|---|---|---|
| Google + 飞书 SSO（INT-04） | 登录读 | 用户登录时 | email（合并键）/ provider | 登录失败重试；无 email 阻断 |
| HR/IdP SCIM（INT-13） | 供给读 | 入离职/转岗事件 | event / email / roles / status | 重试 + 告警可重放（NFR-06） |
| 飞书（INT-05） | 写 | 邀请/权限变更通知 | 邀请链接/通知 | 通知失败重试 |
| M8 签署能力 | 复用 | 外部账号签署时 | 签署记录（signer/version/at） | 见 M8 |
| 全模块 | 判定被调用 | 每次功能动作/数据请求 | RBAC 动作 / ABAC 范围 | 默认拒绝（最小权限，NFR-03） |

## 6. 测试用例
> 见 [测试用例-M2.md](测试用例-M2.md)。覆盖 SSO 合并、RBAC/ABAC 独立生效、多角色并集、权限变更即时生效、越权拦截+审计、用户供给、外部账号邀请/受限的正常/边界/异常；关键路径 100%、异常路径 ≥90%、硬约束（合并正确率=100%、越界可见=0、越权拦截=100% 记日志、外部非只读写=0、非 TAM/PM 开通阻断=100%）100% 覆盖。

## 7. 风险与依赖

| 风险/依赖 | 影响 | 缓解 | 责任方 |
|---|---|---|---|
| 角色-功能权限完整映射未定（PRD 遗留） | RBAC 无法全量落地 | 随各模块细化逐步填充配置 | PM/各模块 |
| SCIM/HR 接口能力与字段未定（INT-13） | 供给自动化落地待定 | 详设阶段对接 HR/IdP；先支持手动开通兜底 | 后端/PM |
| 权限变更生效延迟阈值待业务 | 验收指标不明确 | 业务确认目标值；实现趋近即时 | PM |
| ABAC 范围规则依赖 M1 绑定/M6 参与数据 | 范围计算依赖上游 | 与 M1/M6 对齐属性口径 | 后端 |

## 8. 遗留 / 待详设（TBD）
- 角色集合与**功能权限完整映射矩阵**待细化（PRD 遗留、M2 成熟度：已起草待细化）。
- Permission / DataScopePolicy 独立 schema 未定（数据字典标"字段待详设"），留待 SDD。
- 权限变更**生效延迟目标值**待业务确认（趋近即时）。
- SCIM 具体字段映射、转岗的角色/范围调整细则待详设（INT-13）。
- 各页面线框/视觉稿（UX）：登录页、角色管理、数据范围策略、供给记录、外部受限视图。