crm-backend-matt/.scratch/clue-module/权限与数据可见性-PRD.md

# 权限与数据可见性模型 PRD

## 文档目的

本文档定义 CRM 平台统一的权限与数据可见性模型，覆盖线索、商机、客户、项目等业务模块。模型规定：一个用户在任意页面上能看到哪些数据、能执行哪些操作，由三种机制组合决定。本模型为跨模块通用能力，各业务模块一致遵循。

## 背景

现有权限体系包含两层：功能权限（控制按钮与接口）与数据可见范围（按业务模块配置的部门级数据范围）。两层通过"取交集"组合，只能逐层收窄可见范围。

实际业务出现无法表达的场景：商机需支持"将人员加入团队成员即可查看该商机"，线索公海池需支持"将人员设为负责人/协作人即可管理该池线索"。这类授权针对的是"某一条具体数据"，且需要越过用户所属部门的限制——一名部门数据范围为"本部门"的销售，被拉入一条属于其他部门的商机团队成员后，应当能看到该商机，但现有"取交集"模型会将其挡在部门范围之外。

因此本模型引入第三种机制——行级授权，并明确三者的组合规则。

## 模型总览

用户对数据的访问由三种机制组合决定：

1. **功能权限**：控制用户能否执行某个动作（点击按钮、调用接口）。配置后生效，未配置则放行。
2. **数据可见范围**：控制用户在某业务模块下组织层面能触达的数据上限，即"天花板"。按模块配置四档范围。
3. **行级授权**：针对单条数据将用户单独授权，作为"通行证"越过数据可见范围的天花板。

组合规则：

```
能否执行某动作   = 功能权限（已配置则校验，未配置则放行）

能否看到某条数据 = 页面业务条件
               AND ( 落在数据可见范围内  OR  已被行级授权到该数据 )
```

数据可见性判定的核心是"数据可见范围 OR 行级授权"——满足其一即可见，而非二者同时满足。

## 机制一：功能权限

功能权限控制"能否执行某个动作"，与"能对哪些数据执行"无关，后者由机制二、机制三决定。

- 通过【权限点管理】录入权限点后生效。每个权限点包含两项：
  - **前端按钮编码**：控制按钮是否展示、是否可点击。
  - **后端接口地址（API URL）**：控制接口是否可被调用。
- 未录入的按钮与接口默认放行，不做控制。需要管控的动作在权限点管理中录入对应权限点即可，无需管控的不录入。

## 机制二：数据可见范围

数据可见范围按业务模块（线索、商机、客户、项目，可扩展）分别配置，定义用户在该模块下组织层面能触达的数据上限。

四档范围：

| 档位 | 含义 |
|------|------|
| 仅本人 | 仅归属本人的数据 |
| 本部门 | 本人所属部门（主部门与兼职部门并集）范围内的数据 |
| 本部门及下属 | 本部门及其全部下级部门的数据 |
| 全部 | 全平台数据，不做部门过滤 |

规则：

- **按模块独立配置**：同一用户在不同模块可配置不同档位，互不影响。
- **多角色取最宽**：用户拥有多个角色时，某模块的最终档位取各角色在该模块配置档位中最宽的一档。未为某角色配置某模块时，该角色在此模块按"仅本人"计，不放宽任何范围。
- **性质为上限**：数据可见范围仅定义组织层面的触达上限；具体页面展示哪一类数据，由页面业务条件在此上限内进一步收窄。
- **无部门时的判定**：档位要求按部门过滤、但用户不属于任何部门时，判定为"一律不可见"，不放行任何数据。

## 机制三：行级授权

行级授权针对单条具体数据，将指定用户单独授权，使其能够访问该条数据——即使该数据不在其数据可见范围内。行级授权是加法性质的"通行证"，可越过机制二的天花板。

行级授权由业务动作触发产生，随动作撤销而失效：

| 触发动作 | 授权效果 |
|----------|----------|
| 将用户加入商机团队成员 | 该用户可访问此商机 |
| 将用户设为线索公海池负责人 | 该用户可管理此池及池内线索 |
| 将用户设为线索公海池协作人 | 该用户可管理此池及池内线索 |
| 将线索分配/指派给销售 | 被指派销售可访问该线索 |
| 用户关注某条数据 | 该用户可在"我的关注"访问该数据 |

行级授权为平台级通用能力，各业务模块共用同一套授权关系，不逐模块单独实现。授权关系按"用户 + 资源"维度存储与检索。

## 组合规则与示例

页面最终展示的数据由以下条件组合：

```
最终可见数据 =
      页面业务条件                    -- 页面自身定义展示哪一类数据
  AND (
          落在数据可见范围内           -- 机制二，组织天花板
       OR 已被行级授权到该数据         -- 机制三，通行证
      )
```

三段说明：

- **页面业务条件**：由各页面业务语义定义。例："我的线索"页限定归属本人；"线索公海"页限定状态为待领取且属于用户可触达的公海池；"我的关注"页限定用户已关注；"线索管理"页按筛选条件。
- **数据可见范围 OR 行级授权**：常规数据经数据可见范围放行；被单独授权的数据经行级授权放行，越过天花板。二者取并集。
- **最外层取交集**：既满足页面业务语义，又具备访问该条数据的资格。

### 示例一：我的线索页

销售张三，线索模块数据范围为"本部门"，打开"我的线索"：

```
  归属人 = 张三
AND ( 线索所属部门 ∈ 张三所属部门  OR  张三被行级授权到该线索 )
```

页面业务条件已限定归属本人，天花板不额外收窄。

### 示例二：团队成员查看跨部门商机

销售李四，商机模块数据范围为"本部门"，被加入一条属于 B 部门的商机团队成员：

```
  （商机列表页业务条件）
AND ( 商机所属部门 ∈ 李四所属部门        -- 该商机属 B 部门，李四属 A 部门，天花板不放行
      OR 李四被行级授权到该商机 )          -- 李四在团队成员中，行级授权放行
```

结果：李四可看到该商机。

## 与现有系统的关系

| 机制 | 现状 | 本次改动 |
|------|------|----------|
| 功能权限（权限点管理） | 已有：录入按钮编码与 API URL，配置后生效 | 沿用，不改动 |
| 数据可见范围（按模块四档、多角色取最宽） | 已有：线索、商机、客户、项目已注册为可配置模块 | 沿用，不改动 |
| 行级授权 | 暂无，现有模型仅有部门级天花板 | 本次新增：通用行级授权关系 + 查询时作为并集通道并入 |

补充说明：

- 行级授权为平台级通用能力，商机团队成员、线索公海池负责人/协作人及后续客户、项目的同类需求共用同一套实现。
- 行级授权数据稀疏（团队成员、协作人为少量点名），按"用户 + 资源"维度建立索引，不影响列表查询性能。
- 通行证逻辑集中实现并统一注入查询，各业务页面无需分别处理，避免授权逻辑散落。

## 待确认事项

1. 行级授权触发动作清单是否完整（见"机制三"表格），是否有需补充或删除的动作。
2. 被行级授权的用户对该条数据的权限边界：仅可查看，还是可执行操作（编辑、分配、删除）；查看与操作是否分级（例如团队成员只读、协作人可管理）。
3. 移除行级授权（移出团队成员/协作人）后立即失效的行为确认。

## 术语

- **数据权限模块**：可独立配置数据范围的业务模块（线索、商机、客户、项目等），存于注册表，以 code 标识。
- **数据范围档位**：仅本人 / 本部门 / 本部门及下属 / 全部。
- **主部门 / 部门集合**：用户唯一正式归属部门 / 主部门与兼职部门并集；数据范围按部门集合计算。
- **一律不可见**：档位要求按部门过滤、但用户无任何部门时的判定结果，不放行任何数据。
- **功能权限点**：权限点管理中录入的按钮编码与 API URL，配置后生效。
- **行级授权**：针对单条数据将用户单独授权的通行证，可越过部门级天花板。