# 账户列表受控头像展示操作日志 操作时间：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投影，现有安全契约保持不变。