feat: 账户列表展示受控头像

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

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