03 permission model and troubleshooting

权限模型与故障排查

本文说明 后端 API 权限 与 前端路由权限 的两套体系如何对齐，以及常见 403/菜单消失问题的排查步骤。

1. 后端：LimsModulePermission

文件：backend/core/permissions.py

逻辑概要：

1. 未登录 → 拒绝。
2. is_superuser → 允许。
3. ViewSet 未设置 lims_module → 仅登录即可（兼容旧接口）。
4. 已设置 lims_module（如 'system'、'commission'）：
   • 默认将 HTTP 方法映射为 view / create / edit / delete。
   • 自定义 @action 可通过 lims_action_map 映射到某一 action（如 submit → edit）。

判定：User.has_lims_permission(module, action) → 查询 Permission 表中是否存在对应 module + action，且用户任一角色关联。

示例（委托评审）：

• CommissionViewSet.lims_module = 'commission'
• review 动作映射为 approve：lims_action_map = {'submit': 'edit', 'review': 'approve'}
  代码：backend/apps/commissions/views.py

2. 前端：路由 meta.permission

文件：frontend/src/router/index.ts 守卫逻辑：

1. 非公开页需登录（本地 access_token）。
2. userStore.ensureProfile() 拉取 /api/v1/system/me/。
3. getRoutePermission 从最深匹配路由取 meta.permission。
4. canAccessRoutePermission：若未定义 permission 则放行；否则检查 permissions 数组是否包含该字符串或 *。

权限数据来源：/me 返回的 permissions 为数据库 Permission.code 列表（超级用户为全部 code）。

3. 两套体系对齐检查表

检查项	后端	前端
模块名	Permission.module + action	无直接对应，靠 code 字符串
列表页	GET → view	meta.permission 如 commission:... 需与 code 一致
自定义动作	lims_action_map	若仅控制按钮，可用 vPermission 指令

常见不一致：前端使用 entrustment:list，后端 Permission.code 若登记为别的字符串 → 菜单被过滤或接口 403。

4. 故障排查流程（文字图）

现象：点击菜单提示「无权访问该页面」或接口 403
    ↓
[1] 浏览器 Network 查看 /api/v1/system/me/ 是否 200
    - 401 → Token 过期/被踢 → 重新登录
    ↓
[2] 响应体 permissions 是否包含当前路由 meta.permission
    - 不包含 → 角色未分配对应 Permission 行
    ↓
[3] 接口 403 但菜单能进 → 后端 ViewSet lims_module/action 与前端不一致
    - 对比 views.py 的 module 与 Permission 表
    ↓
[4] 仅超级用户正常 → 检查 is_superuser 与 Permission 种子是否完整

5. Django has_perm 与报告工作流

报告编制/审核/批准在 backend/apps/reports/workflow.py 中使用 user.has_perm('reports.compile_report') 等 Django 默认权限，与 LimsModulePermission 的 Permission 表是 不同机制。若需统一，需在数据迁移或自定义 User.has_perm 中桥接（当前代码以 has_perm 为准）。

排查报告流程失败时：除 Permission 表外，还需检查 Django auth_permission / 用户组是否分配了 reports.* 权限。

6. 风险

风险	说明
路由未设置 permission	任何登录用户可访问该页（依赖后端再拦）
仅前端隐藏	恶意直接调 API 仍可能操作 → 必须以服务端为准
code 拼写错误	难以肉眼发现 → 建议以数据库导出或单元测试校验

7. 回滚

• 误改角色权限：通过 assign-permissions 恢复上一组 permission id（事先导出 JSON）。
• 误删 Permission 行：从备份恢复或重新运行种子命令（注意 unique_together on module+action）。

8. 相关路径

• backend/core/permissions.py
• frontend/src/utils/permission.ts
• frontend/src/router/modules/*.ts（各业务模块 permission 字符串）