# 账户资料页项目文档 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. 已知边界

- 本版不新增头像裁剪、删除或语义识别。
- 不改变新增账户、审核、归档和钱包操作。
- 气站后台与配送后台仍使用原有页面交互。