Mdeical_Sur_Report/docs/modules/auth-and-users.md

模块文档：认证与用户权限

涉及文件

• 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。前端会保留本地签名和已有模板授权字段，避免迁移期丢失医生个人模板或签名。

默认账号

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