platforms/docs/项目文档_账户资料页_v1.0.md

账户资料页项目文档

1. 项目概述

• 项目名称：平台总后台工作人员与用户账户资料页。
• 主要功能：将工作人员、用户账户的详情与编辑从列表抽屉迁移到独立资料页；支持只读/编辑切换、头像本地预览、受控上传和鉴权读取。
• 技术栈：Vue 3、TypeScript、Arco Design、Go、Gin、GORM。
• 运行环境：Node.js 20.19+、Go 1.26.1、项目现有 PostgreSQL 与 JWT 配置。
• 实施范围：仅 frontend/platform_admin（默认开发端口 5173）及必要的平台 API；气站后台和配送后台保持原行为。

2. 目录结构说明

platforms/
├── frontend/platform_admin/src/
│   ├── api/avatar.ts                         # 头像上传和鉴权读取客户端
│   ├── router/routes/modules/platform.ts     # 工作人员、用户账户资料页路由
│   ├── router/typings.d.ts                   # 资料页返回列表元数据
│   └── views/
│       ├── account/
│       │   ├── AccountProfilePage.vue         # 独立资料页与头像交互
│       │   └── AccountProfilePage.less        # 资料页布局与响应式样式
│       └── shared/CrudListPage.vue            # 目标资源跳转入口
├── backend/api/internal/
│   ├── logic/upload/
│   │   ├── avatar.go                         # 头像校验、保存和受控读取
│   │   └── avatar_test.go                    # 图片及路径安全边界测试
│   ├── logic/platform/
│   │   ├── staff/staff.go                    # 工作人员头像读取与可选头像更新
│   │   └── user/user.go                      # 用户头像读取与可选头像更新
│   └── routers/
│       ├── platform.go                       # 账户头像读取路由
│       ├── platform_test.go                  # 平台路由回归测试
│       ├── upload.go                         # 专用头像上传路由
│       └── upload_test.go                    # 上传路由测试
└── docs/                                     # 需求、安全、项目和操作日志

3. 核心文件说明

AccountProfilePage.vue

• 职责：加载工作人员或用户详情，渲染顶部身份卡和“基本信息”表单。
• 主要逻辑：loadProfile 并行加载详情、关系选项和头像；handleAvatarChange 完成本地预览；save 在保存时上传新头像并调用原资源更新接口。
• 页面模式：无 mode 查询参数时只读，?mode=edit 时可编辑；保存后移除参数并留在当前资料页。

avatar.go

• 职责：专用头像文件安全边界。
• 上传限制：JPG/PNG、最大 2MB、最大 4096×4096；同时验证扩展名、真实 MIME、图片配置和完整解码。
• 读取限制：仅接受 /uploads/avatars/ 受控 URI，拒绝外部 URL 和目录穿越；文件响应设置私有且不缓存。

staff.go 与 user.go

• 头像读取方法按账户 identity 查询头像 URI，再交由上传模块读取文件。
• 更新 DTO 将 avatar 改为可选指针：省略字段时保留已有头像，显式空字符串仍可清除，避免普通资料保存误清空头像。

4. 变更记录

• 新增安装、配送、运维工作人员及用户账户的隐藏资料路由。
• 详情按钮进入只读资料页，编辑按钮进入同页编辑模式。
• 新增头像本地选择、预览、保存时上传与鉴权读取。
• 新增图片格式、大小、像素尺寸、完整解码和路径穿越测试。
• 未修改数据库结构，avatar 仍为 VARCHAR(512) 资源 URI。
• 未改变新增账户、审核、归档、钱包及其他资源的弹层行为。
• 未新增第三方依赖。

5. 维护指南

• 新增可使用资料页的账户资源时，必须同时配置独立路由、菜单权限、允许编辑字段和受保护头像读取处理器，不能仅在列表中跳转。
• 生产环境应将 HEQI_UPLOAD_DIR 映射到受控存储，并在上传落盘前接入病毒/恶意内容扫描；当前完整图片解码不能替代专业扫描。
• 头像上传成功但资料更新失败时可能产生孤立文件，生产环境应增加临时文件标记或周期清理任务。
• 不得把 /uploads/avatars/ 配置为无需鉴权的公开静态目录。
• 验证命令：
  • go test ./...
  • npm run build（目录：frontend/platform_admin）
  • git diff --check

6. 已知边界

• 本次不提供头像裁剪、历史头像管理或旧头像自动删除。
• 新增工作人员和用户仍使用现有抽屉。
• 气站后台与配送后台未同步独立资料页。