84 lines
4.6 KiB
Markdown
84 lines
4.6 KiB
Markdown
# 账户资料页项目文档
|
||
|
||
## 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. 已知边界
|
||
|
||
- 本次不提供头像裁剪、历史头像管理或旧头像自动删除。
|
||
- 新增工作人员和用户仍使用现有抽屉。
|
||
- 气站后台与配送后台未同步独立资料页。
|