# 模块文档：认证与用户权限 ## 涉及文件 - `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` 作为迁移期回退；模板图片、关键帧和视频已迁移到同一文件资源体系，后续应继续正规化报告媒体关系。