platforms/docs/操作日志_账户列表受控头像展示_20260811.md

账户列表受控头像展示操作日志

操作时间：2026-08-11 11:32:28 操作类型：扩展 影响模块：平台总后台工作人员、用户账户、平台账户列表

操作前状态

• 工作人员、用户和平台账户资源定义均包含 avatar 字段，通用列表据此生成“头像”列。
• 后端安全投影会从通用列表和详情响应中删除 avatar，前端又把空值格式化为“－”，因此头像列无法显示图片。
• 独立账户资料页已有按账户身份读取头像的鉴权接口，但列表没有缩略图组件、懒加载、并发控制或 Blob URL 回收逻辑。

具体操作

• 扩展 frontend/platform_admin/src/api/avatar.ts，为头像读取增加可选取消信号，原调用方式保持兼容。
• 新增受控列表头像加载器：
  • 仅允许 staff_account、user_account、platform_account 三类资源。
  • 当前列表生命周期内按“资源＋唯一标识”缓存请求。
  • 同时最多执行 6 个头像请求。
  • 刷新、翻页、筛选、资源切换或离开列表时取消任务并清理缓存。
• 新增 32px 圆形头像缩略图组件：
  • 默认先展示资料页现有默认头像。
  • 接近可视区域时才调用现有鉴权接口。
  • 404 保持默认头像；权限、网络或图片解码异常回退默认头像并显示“头像暂不可用”提示。
  • 组件卸载或记录变化时取消请求并释放 Blob URL。
• 修改通用列表头像单元格，保持头像列位于联系电话之后、角色之前，列宽调整为 72px并居中；头像不增加跳转或弹层操作。
• 把列表样式提取到独立 Less 文件，控制通用列表组件体积。

操作后状态

• 工作人员、用户和平台账户列表可在不暴露头像 URI的前提下显示真实头像缩略图。
• 没有头像的账户稳定显示默认头像，异步加载不会改变表格行高。
• 气站账户、配送点账户和生产商账户没有头像字段及受控读取接口，继续不显示头像列。
• 通用列表与详情响应的敏感字段保护规则、后端接口和数据库结构均未改变。

代码变更

• frontend/platform_admin/src/api/avatar.ts：头像读取支持取消信号。
• frontend/platform_admin/src/views/shared/ProtectedAvatarThumbnail.vue：列表缩略图、懒加载、异常回退与资源回收。
• frontend/platform_admin/src/views/shared/protected-list-avatar-loader.ts：资源白名单、限流、缓存和任务取消。
• frontend/platform_admin/src/views/shared/CrudListPage.vue：接入受控头像单元格。
• frontend/platform_admin/src/views/shared/CrudListPage.less：列表布局样式。
• docs/05-平台总后台需求.md、docs/11-数据接口与安全.md、docs/项目文档_标准资源全页管理_v1.0.md：同步功能和安全边界。

验证结果

• npm.cmd run type:check：通过。
• npm.cmd run build：通过，Vite 生产构建完成。
• npm.cmd run resource-pages:check：通过，覆盖详情 46 类、新建 25 类、编辑 23 类。
• npm.cmd run account-roles:check：通过，三套后台既有角色和账户摘要规则保持完整。
• npm.cmd run contract:check：通过，48 个资源契约一致。
• 浏览器回归：
  • 安装人员列表真实头像通过 Blob URL加载，原图 220×168，表格中按 32×32 圆形展示，头像列左右各保留 20px并居中。
  • 用户账户列表共10条记录，其中1条显示真实头像、9条无头像记录显示默认头像，所有缩略图均为32px。
  • 点击列表“刷新”后真实头像生成新的 Blob URL，确认当前页缓存已清除并重新读取。
  • 平台账户列表保留头像列，无头像的 root 账户显示默认头像；工作人员、用户和平台账户替代文本均包含显示名称。
  • 工作人员、用户和平台账户列表控制台均无警告或错误，页面无额外横向溢出。

风险评估

• 当前列表每页最多 50 条记录；懒加载和最多6个并发请求可降低数据库与网络瞬时压力，但首次滚动仍会产生按记录读取请求。
• 头像 Blob仅在当前列表生命周期内缓存，避免跨页面长期占用内存；刷新会重新请求最新头像。
• 平台账户头像接口仍执行现有对象权限校验，权限不足时只显示“头像暂不可用”，不会通过列表接口绕过限制。
• 本次不新增批量头像接口、公开静态资源或头像 URI投影，现有安全契约保持不变。