platforms/docs/操作日志_气站工作人员头像适配_20260818.md

气站工作人员头像适配操作日志

操作时间：2026-08-18 操作类型：扩展 影响模块：气站管理端账户记录页、气站 API 工作人员与用户头像

操作前状态

• 5175 工作人员新建页把头像显示为普通文本输入框。
• 气站 API 没有工作人员和用户的受保护头像读取路由。
• 编辑工作人员或用户资料时，未提交头像也可能把已有头像清空。

具体操作

• 复用 5173 的账户摘要组件和头像组合式逻辑，在新建、详情、编辑页显示头像选择与预览。
• 启用工作人员与用户列表的受保护头像缩略图，替代头像存储路径文本。
• 用户账户列表从当前气站服务关系带出配送点归属，修复配送点唯一标识显示为空。
• 从基础信息表单移除头像文本输入框，保存时仅在选择新头像或恢复默认头像后提交头像字段。
• 新增工作人员、用户头像读取路由，查询始终附加当前气站或服务关系范围。
• 将更新请求的头像字段改为可选指针，未修改头像时不更新数据库列。

操作后状态

• /staff/add 顶部显示账户摘要与头像选择区，布局和交互参考 5173。
• 工作人员与用户列表显示 32 像素圆形头像；无头像或加载失败时回退默认头像。
• 用户账户列表以“所属配送点”为列名并显示配送点业务名称，唯一标识仅用于悬停查看和复制。
• 用户账户详情与编辑页从聚合响应中恢复用户主档和配送点关系，用户名、名称、电话、实名及所属配送点均可正确回填。
• 工作人员与用户的详情、编辑页可安全读取现有头像。
• 普通资料编辑不会误清空头像；主动恢复默认头像仍会提交空值。

代码变更

• frontend/gas_admin/src/views/resource/ResourceRecordPage.vue：启用头像摘要、过滤文本字段、接入上传载荷与未保存检测。
• frontend/gas_admin/src/api/avatar.ts：使用气站 API 前缀读取受保护头像。
• frontend/gas_admin/src/views/shared/protected-list-avatar-loader.ts：开放工作人员与用户缩略图渲染。
• frontend/gas_admin/src/api/resources.ts：用户账户的配送点关系列表以业务名称为主展示，并保留唯一标识复制能力。
• frontend/gas_admin/src/api/resource-display.ts：识别用户聚合详情并合并配送点关系上下文。
• frontend/gas_admin/scripts/check-resource-pages.mjs：新增用户账户配送点名称展示的静态回归检查。
• backend/api/internal/logic/gas/staff.go、user.go：新增范围受限头像读取并保护头像更新语义。
• backend/api/internal/logic/gas/user_test.go：校验用户列表携带配送点关系且保留气站范围。
• backend/api/internal/routers/gas_business.go、gas_test.go：注册并校验头像路由。

验证结果

• go test ./internal/routers ./internal/logic/gas：通过。
• pnpm type:check：通过。
• pnpm contract:check：通过，20 个资源一致。
• pnpm resource-pages:check：通过，详情 20、新建 11、编辑 8。
• pnpm lint：通过，无错误；保留仓库既有提示。
• pnpm build：通过。

风险评估

• 新头像接口只读取数据库中受控上传目录的文件，不暴露外部 URL 或任意文件路径。
• 工作人员头像按 gas_basic_id 限制，用户头像按当前气站服务关系限制，未扩大数据范围。
• 合同附件能力未变更，避免气站端调用不存在的平台专属接口。