TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
wren-dev
leaudit-platform-backend/docs/权限与地区隔离/权限接口矩阵与数据边界清单.md
T

22 KiB
Raw Permalink Blame History

权限接口矩阵与数据边界清单

适用范围：当前 leaudit-platform 已落地后端接口
文档定位：把“接口 -> permission -> data_scope -> 模块策略 -> 风险点”串成联调、改造、测试共用清单。

1. 使用说明

本清单按“模块”组织，每个接口至少标注：

  • 接口路径
  • 当前权限点
  • 是否需要统一数据范围执行器
  • scope 类型
  • 是否存在模块特例策略
  • 当前风险和改造备注

字段解释：

  • 是否需要 scope
    • 是：必须进入统一执行器
    • 否：仅做功能权限即可
  • scope 类型
    • ALL/DEPT/SELF
    • PUBLIC_MIXED
    • RELATION
    • NONE
  • 模块策略
    • 指是否需要 ModulePolicy

2. 认证与会话

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
/auth/login 无 否 NONE 否 登录接口，返回完整 roles/permissions
/auth/me 登录态 否 NONE 否 只返回当前用户信息，不涉及横向数据
JWT 鉴权链路 登录态 否 NONE 否 JWT 只存最小身份，不存完整权限

结论：

  • 认证域不接数据范围执行器
  • 但 /auth/me 建议后续补充“能力快照/有效 scope 摘要”，供前端去角色化

3. 文档模块

控制器：fastapi_modules/fastapi_leaudit/controllers/documentController.py

3.1 文档主接口

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
POST /upload 当前未显式走 permission 是 DEPT/SELF DocumentPolicy 上传时 region 不能越权指定；需补 permission 显式化
GET /documents/list 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 当前在 service 内自行按 is_global/can_manage/created_by 控制
GET /documents/status 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 批量状态接口容易成为绕过列表边界的侧门
GET /documents/{DocumentId} 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 详情必须和列表边界一致
PUT /documents/{DocumentId} 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 写操作应先做资源在 scope 内校验
DELETE /documents/{DocumentId} 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 删除边界必须与详情一致
POST /documents/{DocumentId}/attachments 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 附件追加不能绕过文档属地
POST /upload/upload_contract_template 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 实际依赖文档归属，容易与合同模板域耦合

3.2 评查结果相关

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/review-points/{DocumentId} 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 必须回溯文档归属
PATCH /v3/review-points/{ReviewPointResultId}/audit 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 审核动作要基于文档 scope，不应仅按结果 ID
PATCH /v3/documents/{DocumentId}/confirm 当前未显式走 permission 是 ALL/DEPT/SELF DocumentPolicy 文档确认权限与详情边界需一致

文档模块结论：

  • 当前后端主要依赖 service 内部范围判断，不够显式
  • 应补齐 documents:*:*、review_points:*:* 一类 permission_key 与 scope 执行
  • 文档详情、状态、附件、确认都必须视为“文档主资源的派生资源”

4. 公文模块

控制器：fastapi_modules/fastapi_leaudit/controllers/govdocController.py

4.1 公文文档

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
POST /govdoc/documents 当前未显式走 permission 是 DEPT/SELF GovdocPolicy 上传时 region 需受用户 scope 约束
GET /govdoc/documents 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 现有逻辑与文档模块相似，但未统一
GET /govdoc/documents/{documentId} 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 详情边界必须与列表一致
PATCH /govdoc/documents/{documentId} 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 更新动作必须做资源属地校验
DELETE /govdoc/documents/{documentId} 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 删除不能只凭 ID 存在
GET /govdoc/documents/{documentId}/original 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 原文下载是高风险侧门，必须回溯文档 scope

4.2 审查运行与结果

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
POST /govdoc/runs 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 创建 run 必须先验证文档是否在 scope 内
GET /govdoc/runs/{runId} 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 必须通过 run 反查 document
GET /govdoc/runs/{runId}/result 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/findings 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/entities 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/structure 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/outline 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/paragraphs 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 同上
GET /govdoc/runs/{runId}/report/html 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 报告查看必须回溯文档 scope
GET /govdoc/runs/{runId}/report/docx 当前未显式走 permission 是 ALL/DEPT/SELF GovdocPolicy 报告下载是重点回归项

4.3 规则查看

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /govdoc/rules 当前未显式走 permission 否 NONE 否 更偏规则元数据
GET /govdoc/rules/{ruleId} 当前未显式走 permission 否 NONE 否 不依赖 area

公文模块结论：

  • 最关键不是列表，而是所有 run/result/report/original 派生接口必须继承文档边界
  • 这部分非常容易出现“列表收住了，下载没收住”的问题

5. 使用统计模块

控制器：fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/usage-stats/overview usage_stats:overview:read 是 ALL/DEPT/SELF UsageStatsPolicy 当前 service 内已区分 areaScope=user/document
GET /v3/usage-stats/trends usage_stats:trends:read 是 ALL/DEPT/SELF UsageStatsPolicy 趋势与概览边界必须一致
GET /v3/usage-stats/by-users usage_stats:users:read 是 ALL/DEPT/SELF UsageStatsPolicy SELF 时只能看本人
GET /v3/usage-stats/by-departments usage_stats:departments:read 是 ALL/DEPT UsageStatsPolicy 普通用户是否允许进入，建议改为无权限或只看自身部门汇总
GET /v3/usage-stats/by-areas usage_stats:areas:read 是 ALL/DEPT UsageStatsPolicy 地区汇总对 SELF 没有清晰业务意义，建议禁止
GET /v3/usage-stats/details usage_stats:details:read 是 ALL/DEPT/SELF UsageStatsPolicy 明细接口是高风险越权点

统计模块结论：

  • 当前实现已经比较接近统一策略，但仍是模块内自实现
  • areaScope=document 和 areaScope=user 必须在统一执行器中显式挂接字段映射
  • details 是重点保护接口

6. RAG 模块

控制器：fastapi_modules/fastapi_leaudit/controllers/ragChatController.py

6.1 聊天应用

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/rag/apps rag:app:read 是 PUBLIC_MIXED RagPolicy 当前按 area in (user_area, 省级, '') or is_public
GET /v3/rag/apps/default rag:app:read 是 PUBLIC_MIXED RagPolicy 默认应用与列表边界必须一致
聊天发送相关接口 rag:chat:use 是 PUBLIC_MIXED RagPolicy 发送前要校验目标 app/dataset 可见
会话列表/详情 rag:conversation:read 是 SELF RagPolicy 会话一般只看自己的
会话重命名 rag:conversation:update 是 SELF RagPolicy 仅自己会话
会话删除 rag:conversation:delete 是 SELF RagPolicy 仅自己会话
消息反馈 rag:message:feedback 是 SELF RagPolicy 仅自己消息链路

6.2 知识库读接口

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/rag/datasets/my rag:dataset:read 是 PUBLIC_MIXED RagPolicy 现有命名是 my，但行为已不是纯 self
GET /v3/rag/datasets/{DatasetId} rag:dataset:read 是 PUBLIC_MIXED RagPolicy 详情需继承地区+公开规则
GET /v3/rag/datasets/{DatasetId}/documents rag:dataset:read 是 PUBLIC_MIXED RagPolicy 文档列表需继承数据集可见性
GET /v3/rag/datasets/{DatasetId}/documents/{DocumentId} rag:dataset:read 是 PUBLIC_MIXED RagPolicy 单文档详情要回溯数据集
GET /v3/rag/datasets/{DatasetId}/segments 等派生接口 rag:dataset:read 是 PUBLIC_MIXED RagPolicy 所有派生资源必须回溯 dataset
POST /v3/rag/datasets/{DatasetId}/retrieve rag:dataset:read 是 PUBLIC_MIXED RagPolicy 检索测试属于读权限扩展

6.3 知识库管理接口

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/rag/datasets/admin rag:dataset:manage 是 ALL/DEPT RagPolicy 当前 controller 按 permission 放行，service 又按 UserRole 二次拒绝
POST /v3/rag/datasets/admin rag:dataset:create 是 ALL/DEPT RagPolicy 创建时 area 指定受 scope 限制
PUT /v3/rag/datasets/admin/{DatasetId} rag:dataset:update 是 ALL/DEPT RagPolicy 目标资源必须在 scope 内
DELETE /v3/rag/datasets/admin/{DatasetId} rag:dataset:delete 是 ALL/DEPT RagPolicy 同上
PATCH /v3/rag/datasets/{DatasetId} rag:dataset:update 是 ALL/DEPT/SELF RagPolicy 需统一 admin 版与通用版接口边界
POST /v3/rag/datasets/{DatasetId}/documents rag:dataset:update 是 ALL/DEPT/SELF RagPolicy 文档上传需继承 dataset scope
POST /v3/rag/datasets/{DatasetId}/documents/{DocumentId}/update-by-file rag:dataset:update 是 ALL/DEPT/SELF RagPolicy 同上
DELETE /v3/rag/datasets/{DatasetId}/documents/{DocumentId} rag:dataset:update/delete 是 ALL/DEPT/SELF RagPolicy 以数据集为主资源边界

RAG 模块结论：

  • 是当前权限改造的第一优先级
  • 最大问题不是 permission 缺失，而是“controller 按 permission、service 按角色”的双轨冲突
  • 所有 UserRole 白名单都要迁到 permission + scope + RagPolicy

7. 交叉评查模块

控制器：fastapi_modules/fastapi_leaudit/controllers/crossReviewController.py

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
POST /v3/cross-review/tasks cross_review:task:create 是 RELATION CrossReviewPolicy 创建任务后需自动建立成员关系
POST /v3/cross-review/tasks/query cross_review:task:read 是 RELATION CrossReviewPolicy 不按 area，而按 task_member
GET /v3/cross-review/tasks/{TaskId}/progress cross_review:progress:view 是 RELATION CrossReviewPolicy 需验证当前用户是任务参与方
GET /v3/cross-review/tasks/{TaskId}/documents cross_review:task:read + cross_review:document:read 是 RELATION CrossReviewPolicy 文档列表由任务关系派生
GET /v3/cross-review/tasks/{TaskId}/can-confirm cross_review:document:complete 是 RELATION CrossReviewPolicy 不能只看 permission，要看用户在任务中的职责
POST /v3/cross-review/tasks/{TaskId}/documents/{DocumentId}/complete cross_review:document:complete 是 RELATION CrossReviewPolicy 高风险写接口
POST /v3/cross-review/tasks/{TaskId}/documents/upload cross_review:document:complete 是 RELATION CrossReviewPolicy 上传文档须确认任务成员关系
POST /v3/cross-review/tasks/{TaskId}/documents/{DocumentId}/attachments cross_review:document:complete 是 RELATION CrossReviewPolicy 同上
POST /v3/cross-review/proposals cross_review:proposal:create 是 RELATION CrossReviewPolicy 提案创建需验证目标文档在任务关系内
POST /v3/cross-review/proposals/{ProposalId}/votes cross_review:proposal:vote 是 RELATION CrossReviewPolicy 投票边界不应只看提案 ID
DELETE /v3/cross-review/proposals/{ProposalId} cross_review:proposal:delete 是 RELATION CrossReviewPolicy 需限定提案创建者或具备特定任务身份
GET /v3/cross-review/documents/{DocumentId}/proposals cross_review:proposal:read 是 RELATION CrossReviewPolicy 通过文档反查任务关系
GET /v3/cross-review/documents/{DocumentId}/pending-votes cross_review:proposal:read + cross_review:document:complete 是 RELATION CrossReviewPolicy 组合权限接口
GET /v3/cross-review/documents/{DocumentId}/proposals/export cross_review:proposal:read 是 RELATION CrossReviewPolicy 导出接口重点防越权

交叉评查模块结论：

  • 不能硬塞 ALL/DEPT/SELF
  • 但必须接入统一执行框架
  • 最终统一的是“决策入口”，不是“所有模块都长得一样”

8. RBAC 管理域

控制器：fastapi_modules/fastapi_leaudit/controllers/rbacAdminController.py、rbacController.py

8.1 当前用户菜单

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /rbac/user/routes 登录态 + 数据库路由 否 NONE 否 主要是菜单授权，不直接做数据范围

8.2 角色、用户、授权管理

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/rbac/roles rbac:roles:read 否 NONE RbacAdminPolicy 角色列表本身通常不按 area 分裂
POST /v3/rbac/roles rbac:roles:create 否 NONE RbacAdminPolicy 但角色可配置的 data_scope 要受管控
PUT /v3/rbac/roles/{RoleId} rbac:roles:update 否 NONE RbacAdminPolicy 系统角色修改需附加约束
DELETE /v3/rbac/roles/{RoleId} rbac:roles:delete 否 NONE RbacAdminPolicy 同上
GET /v3/rbac/users rbac:users:read 是 ALL/DEPT RbacAdminPolicy 当前 service 内按 u.area 收敛
GET /admin/users/organizations/tree rbac:users:read / rbac:org:read 是 ALL/DEPT RbacAdminPolicy 组织树也要受 area 控制
GET /v3/rbac/roles/{RoleId}/users rbac:role_users:read 是 ALL/DEPT RbacAdminPolicy 角色关联用户列表受 area 约束
POST /v3/rbac/users/{UserId}/roles rbac:user_roles:write 是 ALL/DEPT RbacAdminPolicy 不能给越权地区用户分配角色
DELETE /v3/rbac/users/{UserId}/roles/{RoleId} rbac:user_roles:write 是 ALL/DEPT RbacAdminPolicy 同上
GET /v3/rbac/users/{UserId}/roles rbac:user_roles:read 是 ALL/DEPT RbacAdminPolicy 同上
GET /v3/routes rbac:routes:read 否 NONE RbacAdminPolicy 路由元数据接口
GET /rbac/roles/{RoleId}/routes rbac:role_routes:read 否 NONE RbacAdminPolicy 配置域接口
PUT /rbac/roles/{RoleId}/routes rbac:role_routes:write 否 NONE RbacAdminPolicy 配置域接口
GET /v3/rbac/role-permissions rbac:role_permissions:read 否 NONE RbacAdminPolicy 配置域接口
POST /v3/rbac/role-permissions rbac:role_permissions:write 否 NONE RbacAdminPolicy 可直接影响 scope，需审计
POST /v3/rbac/roles/{RoleId}/access rbac:role_access:write 否 NONE RbacAdminPolicy 原子保存授权接口
GET /v3/routes/{RouteId}/permissions rbac:route_permissions:read 否 NONE RbacAdminPolicy 配置域接口

RBAC 域结论：

  • 角色/路由/权限配置本身更多是功能权限
  • 用户相关接口则需要显式纳入 area scope
  • 当前 _assertManagePermission 与 _assertPermission 双层耦合，需统一

9. 合同模板模块

控制器：fastapi_modules/fastapi_leaudit/controllers/contractTemplateController.py

接口 当前权限点 是否需要 scope scope 类型 模块策略 备注
GET /v3/contract-templates/categories contract_template:list:read / contract_template:search:read 否 NONE 否 分类基本可视为元数据
GET /v3/contract-templates contract_template:list:read 是 ALL/DEPT/SELF ContractTemplatePolicy 当前 service 内按 is_global/can_manage/region/created_by 控制
POST /v3/contract-templates contract_template:create:write 是 ALL/DEPT ContractTemplatePolicy 当前前端还写死 role === admin 才能上传
GET /v3/contract-templates/search contract_template:search:read 是 ALL/DEPT/SELF ContractTemplatePolicy 搜索与列表边界必须一致
GET /v3/contract-templates/{TemplateId} contract_template:detail:read / contract_template:list:read 是 ALL/DEPT/SELF ContractTemplatePolicy 详情要回溯模板属地
DELETE /v3/contract-templates/{TemplateId} contract_template:delete:delete 是 ALL/DEPT/SELF ContractTemplatePolicy 删除不能只靠按钮隐藏

合同模板模块结论：

  • 后端已有一定范围逻辑，但前端仍强依赖角色名
  • 是典型“后端可改，前端也必须同步去硬编码”的模块

10. 首页与入口模块

相关实现：homeServiceImpl.py

接口/能力 当前权限点 是否需要 scope scope 类型 模块策略 备注
首页入口模块列表 登录态 / 配置域权限 是 ALL/DEPT HomePolicy 当前有 super_admin 绕过 areas 配置逻辑
入口模块地区配置 配置域权限 否 NONE HomePolicy 主要是管理配置，不是数据读取

首页域结论：

  • 不是典型数据表 scope
  • 但入口是否可见，实质上仍是一种 area 边界
  • 后续应复用统一能力快照，而不是继续写 bypass_area

11. 规则、规则配置、评查点分组

控制器：ruleController.py、ruleConfigController.py、evaluationPointGroupController.py

接口类型 当前权限点 是否需要 scope scope 类型 模块策略 备注
规则列表/版本/内容 rules:*:* 否 NONE 否 偏元数据和配置域
规则校验/发布/回滚 rules:*:* 否 NONE 否 高权限但不依赖 area
规则绑定 rules:*:* 否 NONE 否 配置域
评查点分组列表 evaluation_group:list:read / rules:list:read 否 NONE 否 当前主要走功能权限
评查点分组增删改 evaluation_group:*:* 否 NONE 否 配置域

结论：

  • 这一组接口主要关注功能权限，不是本轮统一 scope 的重点
  • 但要进入接口矩阵，防止后续误把它们也做成地区隔离

12. 风险接口总表

以下接口属于本轮改造最需要重点回归的高风险接口：

  1. 文档详情、文档删除、附件追加、评查确认
  2. 公文原文下载、报告下载、run 结果查看
  3. 使用统计明细接口 details
  4. RAG 管理接口 /datasets/admin*
  5. 交叉评查导出接口 /documents/{DocumentId}/proposals/export
  6. RBAC 用户角色分配接口
  7. 合同模板创建与删除接口

这些接口共同特征是：

  • 容易绕过列表边界
  • 多数不是“菜单是否可见”能防住的
  • 很多地方当前还依赖 service 内部硬编码角色

13. 改造原则

接口矩阵层面建议统一采用以下原则：

  1. 列表、详情、下载、导出、删除、更新属于同一资源链路，必须复用同一 scope 决策
  2. 组合权限接口应先判功能权限，再判资源边界
  3. 任何通过子资源 ID 访问父资源内容的接口，都必须回溯父资源做 scope 校验
  4. 前端按钮可见性不能替代后端数据边界
  5. RAG 和交叉评查虽然是特例模块，也必须进入统一执行框架

14. 本清单的使用方式

研发使用：

  • 作为统一执行器接入清单
  • 明确哪些接口先接、哪些接口只做功能权限

测试使用：

  • 作为接口级回归矩阵底稿
  • 按模块逐项校验“列表/详情/下载/导出/删除”一致性

产品和实施使用：

  • 明确哪些功能受角色去硬编码影响
  • 明确哪些模块需要前端同步联调
Reference in New Issue View Git Blame Copy Permalink