admin
750cf4129d
- Add Auth Context route role guards so doctors cannot directly enter template management, user management, or audit logs. - Add Audit Logs page, sidebar entry, frontend audit API client, and API client test. - Add backend audit log query endpoint with super/admin visibility rules and query filtering. - Extend PostgreSQL integration tests to cover audit log query permissions. - Move Playwright E2E away from localStorage seed data to real backend API login and seed helpers. - Add E2E coverage for route guards and audit log visibility. - Run Playwright backend on port 3100 and proxy Vite API requests there to avoid local port conflicts. - Make server:dev use the compiled NestJS server path, avoiding tsx parameter-property injection issues. - Update README, AGENTS, feature, testing, security, deployment, progress, API, backendization, and auth/user module docs.
77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# 模块文档：认证与用户权限
|
||
|
||
## 涉及文件
|
||
|
||
- `src/pages/Login.tsx`
|
||
- `src/api/client.ts`
|
||
- `src/api/users.ts`
|
||
- `src/api/files.ts`
|
||
- `src/auth/AuthContext.tsx`
|
||
- `src/auth/backendUser.ts`
|
||
- `src/pages/UserManage.tsx`
|
||
- `src/components/Sidebar.tsx`
|
||
- `src/types.ts`
|
||
- `src/utils/storage.ts`
|
||
- `server/src/users`
|
||
- `server/src/files`
|
||
|
||
## 登录流程
|
||
|
||
`Login` 页面挂载时仍执行迁移期初始化，补齐默认模板、默认用户、字段库、图片资源和系统设置。提交登录表单后，前端通过 `AuthContext.login` 调用 `POST /api/auth/login`，后端验证 Argon2 密码哈希并写入 HttpOnly Session Cookie。
|
||
|
||
登录成功后，`AuthContext` 会把后端返回的安全用户 DTO 转成当前前端 `User` 结构，并同步到 `localStorage.currentUser` 和 `localStorage.users`。这是为了兼容字段、设置、用户管理和开发回退逻辑；生产构建默认不会用本地缓存恢复登录态。
|
||
|
||
`AuthProvider` 启动时会调用 `GET /api/auth/me` 恢复后端会话，退出登录调用 `POST /api/auth/logout` 并清理本地 `currentUser`。
|
||
|
||
后端角色 `doctor` 会映射为当前前端历史类型中的 `user`。前端会保留本地签名和已有模板授权字段，避免迁移期丢失医生个人模板或签名。
|
||
|
||
路由层使用 Auth Context 做统一角色守卫：医生不能直接进入模板管理、用户管理和审计日志页面；超级管理员和管理员可进入这些管理页。该守卫只负责前端体验，生产安全边界仍以后端 API 权限校验为准。
|
||
|
||
## 默认账号
|
||
|
||
| 用户ID | 密码 | 角色 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `admin` | `123456` | 超级管理员 | 初始最高权限。 |
|
||
| `manager` | `123456` | 管理员 | 外科管理员。 |
|
||
| `0001` | `123456` | 医生 | 外科医生账号。 |
|
||
|
||
## 权限规则
|
||
|
||
- `super`：可查看和管理全部用户、模板、报告、系统配置。
|
||
- `admin`：可管理同部门医生或自己；不可创建超级管理员；新增用户默认是医生。
|
||
- `user`：只能管理本人报告；不能进入模板管理和用户管理。
|
||
|
||
用户管理中还有这些约束：
|
||
|
||
- 不允许删除默认超级管理员 `admin`。
|
||
- 不允许删除当前登录用户。
|
||
- 一个部门只能存在一个管理员。
|
||
- 创建医生前，该部门必须已有管理员。
|
||
- 禁用管理员类账号需要授权密钥。
|
||
|
||
`UserManage` 页面当前优先调用后端 `Users/Departments` API。只有开发模式或显式开启 `VITE_ENABLE_LOCAL_FALLBACK=true` 时，API 不可用才保留本地列表回退，便于迁移期演示和离线开发；生产安全边界以服务端校验为准。
|
||
|
||
## 用户与部门 API
|
||
|
||
- `GET /api/users`：超级管理员返回全部用户；管理员返回自己和本部门医生；医生只返回自己。
|
||
- `POST /api/users`：超级管理员可创建管理员或医生；管理员只能创建本部门医生；后端校验一个部门只能有一个管理员，且创建医生前部门必须已有管理员。
|
||
- `PATCH /api/users/:id`：超级管理员可改角色、部门、状态和模板授权；管理员只能改本部门医生的基础信息、密码和状态；医生只能改自己的基础资料。
|
||
- `DELETE /api/users/:id`：禁止删除当前账号和默认超级管理员；有业务数据关联时返回冲突，建议改为禁用。
|
||
- `GET /api/departments`：超级管理员返回全部部门；管理员/医生返回本人部门。
|
||
- `PATCH /api/departments/:id/template-permissions`：超级管理员维护部门可用和可管理模板授权。
|
||
|
||
## 模板权限
|
||
|
||
用户有两个模板权限字段：
|
||
|
||
- `manageableTemplates`：可管理的模板 ID。
|
||
- `visibleTemplates`：新建报告时可使用的模板 ID。
|
||
|
||
超级管理员拥有全部模板。管理员可被超级管理员分配部门可管理模板；医生可见模板来自本部门可用模板和自己的个人模板。当前前端仍沿用 `visibleTemplates/manageableTemplates` 字段展示，但后端数据来源是 `TemplateDepartmentPermission`。
|
||
|
||
## 签名
|
||
|
||
用户管理支持上传签名图片，前端会压缩为 JPEG Data URL，再调用 `POST /api/users/:id/signature` 写入后端 `FileResource` 和本地文件目录。后端把 `signatureFileId` 写回用户表，并通过 `/api/files/:id/content` 提供受控读取。报告模板中若存在 `surgeonSignature` 绑定字段，报告编辑器会尝试用当前用户签名 URL 渲染。
|
||
|
||
只有本地回退开启时，API 不可用才会保留本地 `User.signature` 作为迁移期回退；模板图片、关键帧和视频已迁移到同一文件资源体系，后续应继续正规化报告媒体关系。
|