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

账户资料页项目文档 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. 目录结构说明

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

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