# 账户资料页项目文档

## 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. 目录结构说明

```text
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. 已知边界

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