feat: 新增账户资料页与头像上传
将工作人员和用户的详情、编辑改为独立账户资料页。 增加受控头像上传与读取、图片安全校验、接口测试，并优化只读及编辑布局。 同步更新平台需求、接口安全说明、项目文档和操作日志。
This commit is contained in:
czl231
@@ -130,6 +130,8 @@
|
||||
|
||||
工作人员支持安装人员 `installer`、配送人员 `delivery`、运维人员 `operations` 三种角色，可关联气站或配送点，并记录在岗/离岗状态。前端按角色提供独立列表和新增入口；后端按菜单和人员实际角色校验详情、修改及资质访问。
|
||||
|
||||
工作人员详情与编辑使用独立资料页，不再使用列表抽屉。资料页默认只读，可切换编辑状态；顶部展示头像、用户名、唯一标识和创建时间，下方维护现有基本信息。头像仅支持 JPG/PNG、本地预览和保存时上传，读取继续受平台 JWT、菜单及人员角色权限保护。
|
||||
|
||||
### 6.3 用户管理
|
||||
|
||||
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||
@@ -140,6 +142,8 @@
|
||||
|
||||
用户页面同时提供配送合同入口。当前后台可直接维护用户、地址和服务关系，但尚未实现邀请二维码注册、服务关系审批和完整历史时间线。
|
||||
|
||||
用户账户详情与编辑复用工作人员资料页布局，默认只读并支持页内编辑。用户头像通过受保护资源接口读取，不在通用详情响应中暴露头像 URI；新增用户仍沿用现有新增抽屉。
|
||||
|
||||
### 6.4 智能气阀管理
|
||||
|
||||
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||
|
||||
@@ -121,6 +121,7 @@
|
||||
- 银行卡号、身份证号、预留手机号使用 `Global.FieldEncryptionKey` 经 HKDF 派生独立 AES-GCM 加密键和 HMAC 指纹键；接口列表只返回末四位掩码。开发占位密钥不得用于生产。
|
||||
- 支付密码独立于登录密码，仅允许六位数字，使用 bcrypt 保存；连续失败达到阈值后在 Redis 短时锁定。绑卡、解绑、余额支付和提现均要求支付密码或限定用途的一次性验证码。
|
||||
- 公共上传接口 `/upload/file` 必须携带平台、气站、配送点、用户或工作人员任一合法 JWT；图片/PDF 最大 10MB，视频上限从配置读取。上传只返回资源 URI，业务接口负责建立关联并记录操作者、采集与接收时间。
|
||||
- 平台账户资料头像使用专用 `/upload/avatar` 上传入口，仅允许真实 JPG/PNG、最大 2MB、最大 4096×4096，并在服务端完成扩展名、MIME、尺寸和完整图片解码校验。头像读取通过 `/heqi/platform/v1/{staff_account|user_account}/:identity/avatar` 受 JWT、菜单和对象角色权限保护；通用列表及详情响应继续移除 `avatar` 字段。
|
||||
- 充值、支付、提现、工单证据、轨迹点、内容确认等写入均携带幂等号；资金入账在数据库事务内锁定钱包并同时写不可变流水。
|
||||
- 钱包可提现余额是当前总余额的子集，始终满足 `0 <= 可提现余额 <= 总余额`。普通消费扣减总余额后，必须同步把可提现余额限制在剩余总余额以内。
|
||||
- 提现申请在同一数据库事务内锁定钱包、同时预扣总余额和可提现余额并写入不可变流水；驳回只返还该申请实际预扣的两类余额，完成打款只确认外部结果，不得再次扣款。
|
||||
|
||||
52
docs/操作日志_账户资料页与头像上传_20260810.md
Normal file
52
docs/操作日志_账户资料页与头像上传_20260810.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# 账户资料页与头像上传操作日志
|
||||
|
||||
操作时间：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 存储尚无孤立文件自动清理；通过保存时才上传降低无效文件数量，生产环境仍需清理机制。
|
||||
- 完整图片解码可以阻止伪造或损坏图片，但不能替代病毒扫描；生产发布前需接入受控对象存储和恶意内容扫描。
|
||||
- 影响范围限定为平台总后台，气站后台和配送后台没有行为变化。
|
||||
49
docs/操作日志_账户资料页视觉优化_20260810.md
Normal file
49
docs/操作日志_账户资料页视觉优化_20260810.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 账户资料页视觉优化操作日志
|
||||
|
||||
操作时间：2026-08-10
|
||||
|
||||
操作类型：修改
|
||||
|
||||
影响模块：平台总后台工作人员与用户账户资料页
|
||||
|
||||
## 操作前状态
|
||||
|
||||
宽屏下顶部资料内容集中在卡片左侧，右侧留白较大；基本信息使用灰色禁用输入框表示查看态，容易与不可用状态混淆；表单内容偏左且必填星号与“名称”标签距离过大。
|
||||
|
||||
## 具体操作
|
||||
|
||||
1. 将顶部资料区改为最大宽度网格，头像和身份信息整体居中。
|
||||
2. 缩小头像、标题、行高、卡片内边距和卡片间距。
|
||||
3. 为只读状态新增 `displayProfileValue` 文本格式化逻辑，编辑状态继续使用原表单控件。
|
||||
4. 将基本信息内容区居中并统一标签、值、输入框和按钮基线。
|
||||
5. 在资料页局部覆盖 Arco 必填符号尺寸，修复星号错位。
|
||||
6. 保留现有头像内容、上传流程、接口、路由和响应式行为。
|
||||
|
||||
## 操作后状态
|
||||
|
||||
用户与工作人员资料页在宽屏下内容集中且层级明确；查看态展示纯文本，编辑态展示输入控件；必填星号紧贴字段标签，保存与取消按钮保持原操作位置。
|
||||
|
||||
## 代码变更
|
||||
|
||||
- `frontend/platform_admin/src/views/account/AccountProfilePage.vue`
|
||||
- 新增 `displayProfileValue`，区分查看与编辑渲染。
|
||||
- 头像显示尺寸由 132px 调整为 120px。
|
||||
- `frontend/platform_admin/src/views/account/AccountProfilePage.less`
|
||||
- 重构顶部网格、表单内容宽度、详情文本、编辑控件和必填符号样式。
|
||||
- `docs/项目文档_账户资料页_v1.1.md`
|
||||
- 记录 v1.1 页面结构、行为差异和维护边界。
|
||||
|
||||
## 验证结果
|
||||
|
||||
- `npm run build`：通过。
|
||||
- 浏览器真实用户资料验证：查看态、编辑态、必填符号、取消恢复均正常。
|
||||
- 必填符号计算宽度为 8px，伪元素内容为 `*`。
|
||||
- 页面控制台无错误；验证过程中未保存或修改测试账户数据。
|
||||
- `git diff --check`：通过。
|
||||
- 文件行数：`AccountProfilePage.vue` 455 行，`AccountProfilePage.less` 209 行，符合单文件尽量不超过 500 行的限制。
|
||||
|
||||
## 风险评估
|
||||
|
||||
- 仅修改共享资料页模板和局部样式，工作人员与用户账户同步生效。
|
||||
- 没有修改数据、接口、上传逻辑、数据库和其他后台页面。
|
||||
- 关联字段只读名称依赖已加载的关系选项；加载失败时回退显示原唯一标识。
|
||||
83
docs/项目文档_账户资料页_v1.0.md
Normal file
83
docs/项目文档_账户资料页_v1.0.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# 账户资料页项目文档
|
||||
|
||||
## 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. 已知边界
|
||||
|
||||
- 本次不提供头像裁剪、历史头像管理或旧头像自动删除。
|
||||
- 新增工作人员和用户仍使用现有抽屉。
|
||||
- 气站后台与配送后台未同步独立资料页。
|
||||
87
docs/项目文档_账户资料页_v1.1.md
Normal file
87
docs/项目文档_账户资料页_v1.1.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# 账户资料页项目文档 v1.1
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
- 项目名称：平台总后台工作人员与用户账户资料页。
|
||||
- 主要功能：工作人员和用户账户使用独立资料页查看、编辑基本信息，并支持头像本地预览、受控上传和鉴权读取。
|
||||
- 本版重点：优化宽屏内容密度、资料卡对齐、查看/编辑状态区分和必填标识位置。
|
||||
- 技术栈：Vue 3、TypeScript、Arco Design、Less、Go、Gin、GORM。
|
||||
- 运行环境：Node.js 20.19+、Go 1.26.1、项目现有 PostgreSQL 与 JWT 配置。
|
||||
- 实施范围：仅 `frontend/platform_admin` 的工作人员和用户账户共享资料页；气站后台、配送后台及后端接口行为不变。
|
||||
|
||||
## 2. 目录结构说明
|
||||
|
||||
```text
|
||||
platforms/
|
||||
├── frontend/platform_admin/src/
|
||||
│ ├── api/avatar.ts # 头像上传和鉴权读取客户端
|
||||
│ ├── router/routes/modules/platform.ts # 工作人员、用户账户资料页路由
|
||||
│ └── views/
|
||||
│ ├── account/
|
||||
│ │ ├── AccountProfilePage.vue # 资料查看、编辑和头像交互
|
||||
│ │ └── AccountProfilePage.less # 资料页布局、状态和响应式样式
|
||||
│ └── shared/CrudListPage.vue # 目标资源跳转入口
|
||||
├── backend/api/internal/
|
||||
│ ├── logic/upload/avatar.go # 头像校验、保存和受控读取
|
||||
│ ├── logic/platform/staff/staff.go # 工作人员头像与资料更新
|
||||
│ ├── logic/platform/user/user.go # 用户头像与资料更新
|
||||
│ └── routers/ # 平台头像读取与上传路由
|
||||
└── docs/ # 需求、安全、项目和操作日志
|
||||
```
|
||||
|
||||
## 3. 核心文件说明
|
||||
|
||||
### `AccountProfilePage.vue`
|
||||
|
||||
- `loadProfile`：加载账户详情、关联选项与受保护头像。
|
||||
- `displayProfileValue`：将普通字段、枚举、布尔值、金额、日期和关联标识转换为只读文本。
|
||||
- `startEdit`、`leaveEditMode`：通过 `?mode=edit` 切换编辑与查看状态。
|
||||
- `save`：验证表单，在需要时上传头像，再复用原资源更新接口。
|
||||
- 查看态只渲染纯文本值；编辑态才创建输入、选择和日期控件，避免将详情误呈现为禁用表单。
|
||||
|
||||
### `AccountProfilePage.less`
|
||||
|
||||
- 顶部使用 `900px` 最大宽度网格，将头像列与身份信息列作为整体居中。
|
||||
- 基本信息表单使用 `760px` 内容宽度，查看态文本和编辑态控件共享标签基线。
|
||||
- 必填符号通过页面局部样式压缩为固定 `8px` 宽，不影响其他 Arco 表单。
|
||||
- 小屏幕下顶部网格切换为单列，表单宽度与标签列同步收缩。
|
||||
|
||||
### 头像服务
|
||||
|
||||
- 头像内容保持原样展示，本版不进行图片语义判断或自动替换。
|
||||
- 上传、鉴权读取、文件类型、大小和像素限制均沿用 v1.0，不修改接口或数据库结构。
|
||||
|
||||
## 4. 变更记录
|
||||
|
||||
### v1.1（2026-08-10）
|
||||
|
||||
- 顶部资料卡内容组居中，减少宽屏右侧无效留白。
|
||||
- 头像缩小为 120px，身份标题调整为 20px，标签和内容统一左基线。
|
||||
- 卡片间距调整为 16px，资料卡和基本信息卡按内容压缩高度。
|
||||
- 查看态由禁用输入框改为纯文本，编辑态保留原表单控件。
|
||||
- 表单内容区扩展并居中，输入框宽度和按钮基线保持一致。
|
||||
- 修复必填星号与“名称”标签分离问题。
|
||||
- 工作人员和用户账户共享同一优化结果。
|
||||
- 未修改头像数据、后端接口、路由、数据库或其他后台页面。
|
||||
|
||||
### v1.0
|
||||
|
||||
- 新增账户独立资料页、头像上传与鉴权读取能力。
|
||||
- 新增安装、配送、运维工作人员及用户账户资料路由。
|
||||
|
||||
## 5. 维护指南
|
||||
|
||||
- 新增字段时必须同时检查 `displayProfileValue` 的只读格式与编辑控件类型。
|
||||
- 页面布局宽度统一在 `AccountProfilePage.less` 维护，不应在模板中写内联尺寸。
|
||||
- 必填符号覆盖仅限 `.profile-form`，禁止改动 Arco 全局样式。
|
||||
- 头像仍是业务资源内容；合法但内容特殊的 PNG/JPG 应原样显示。
|
||||
- 验证命令：
|
||||
- `npm run build`（目录：`frontend/platform_admin`）
|
||||
- `git diff --check`
|
||||
- 浏览器验证：检查用户和工作人员资料页的查看态、编辑态、取消恢复及宽屏/小屏布局。
|
||||
|
||||
## 6. 已知边界
|
||||
|
||||
- 本版不新增头像裁剪、删除或语义识别。
|
||||
- 不改变新增账户、审核、归档和钱包操作。
|
||||
- 气站后台与配送后台仍使用原有页面交互。
|
||||
Reference in New Issue
Block a user