platforms/docs/操作日志_账户资料页与头像上传_20260810.md

账户资料页与头像上传操作日志

操作时间：2026-08-10 21:55:14

操作类型：扩展

影响模块：平台总后台工作人员管理、用户账户管理、平台头像上传与读取接口

操作前状态

工作人员和用户账户的详情、编辑均在通用列表抽屉内完成。头像是普通 URL 文本输入框；已有公共上传接口只保存文件，没有 Web 头像组件和受保护读取链路。更新接口未携带头像时会将头像写为空字符串。

具体操作

1. 为安装、配送、运维工作人员和用户账户增加独立资料路由，保留各自菜单权限与列表高亮。
2. 新增复用资料页，上方展示头像与身份摘要，下方只维护现有基本信息；详情默认只读，编辑通过查询参数切换。
3. 列表中的目标资源详情/编辑改为路由跳转，其他资源、新增、审核和归档行为保持不变。
4. 新增头像专用上传接口，限制 JPG/PNG、2MB、4096×4096，并校验真实图片内容。
5. 新增工作人员和用户头像鉴权读取接口，通用详情继续移除头像 URI。
6. 将更新 DTO 的头像字段改为可选，省略头像时保留原值。
7. 新增头像校验、目录穿越和路由注册测试，并同步需求、安全和项目文档。

操作后状态

平台总后台工作人员与用户账户可以在独立资料页查看、编辑资料，并通过本地文件选择更新头像。头像文件地址不会通过普通详情接口暴露，读取仍受 JWT、菜单和工作人员角色范围保护。其他后台和资源继续使用原交互。

代码变更

• frontend/platform_admin/src/views/account/AccountProfilePage.vue：新增账户资料页。
• frontend/platform_admin/src/api/avatar.ts：新增头像上传与读取客户端。
• frontend/platform_admin/src/router/routes/modules/platform.ts：新增隐藏资料路由。
• frontend/platform_admin/src/views/shared/CrudListPage.vue：目标资源改为资料页跳转。
• backend/api/internal/logic/upload/avatar.go：新增头像安全处理。
• backend/api/internal/logic/platform/staff/staff.go、user/user.go：新增头像读取并保护省略头像的更新行为。
• backend/api/internal/routers/platform.go、upload.go：注册受保护路由。
• 对应测试与中文文档同步更新。

验证结果

• 后端目标包：上传、平台路由、工作人员和用户逻辑测试通过。
• 后端全量：go test ./... 通过。
• 前端：TypeScript 类型检查和 Vite 生产构建通过。
• 浏览器：使用真实用户记录验证列表详情跳转、只读资料页、编辑直达、取消恢复和头像本地预览，未提交或修改测试数据，控制台无错误。
• 边界案例：伪造 PNG、超大像素尺寸、外部 URI、非头像 URI、目录穿越均被拒绝。
• git diff --check：通过。

风险评估

• 数据库结构和现有资源路径未改变，公共更新接口保持兼容。
• 本地 Mock 存储尚无孤立文件自动清理；通过保存时才上传降低无效文件数量，生产环境仍需清理机制。
• 完整图片解码可以阻止伪造或损坏图片，但不能替代病毒扫描；生产发布前需接入受控对象存储和恶意内容扫描。
• 影响范围限定为平台总后台，气站后台和配送后台没有行为变化。