platforms/docs/操作日志_配送点独立资源页面_20260822.md

操作日志：配送点独立资源页面

操作时间：2026-08-22 20:18:39 操作类型：扩展、修改 影响模块：配送点管理系统标准资源列表、独立记录页、前端路由与资源契约

操作前状态

配送点标准资源的新建、详情和编辑均在 CrudListPage.vue 抽屉中完成，没有稳定的记录 URL；支付和退款前端资源名与配送点后端实际路径不一致。

具体操作

1. 新增基于资源能力的路由生成器，为非单例资源生成详情、新建和编辑独立路由。
2. 新增共享记录页、详情内容、字段表单、业务动作对话框和未保存离开保护。
3. 新增标准列表页，将新建、详情和编辑入口改为路由跳转，并移除已停用的抽屉页面。
4. 为可编辑资源增加后端更新字段白名单，保留受控合同编辑限制和危险操作二次确认。
5. 将配送端支付、退款资源统一为 payment_order、payment_refund，同步后端契约快照。
6. 增加页面能力矩阵自动检查，并更新项目文档。
7. 依据 5173 页面重新对齐灰色页面底、面包屑、分区卡片、详情信息网格、双列表单和底部操作区。
8. 将配送人员和用户账户的头像文本框替换为 5173 头像摘要卡片，新增上传、预览、恢复默认头像和配送点范围鉴权读取能力。
9. 修正配送人员、用户编辑接口：没有提交头像字段时保留旧头像，避免编辑其他资料时误清空。
10. 配送人员和用户账户列表增加 32px 受控头像缩略图，复用 5173 的懒加载、并发 6、当前页缓存、取消和 Blob URL 回收策略。
11. 删除全部标准资源列表的数据库自增 ID 列，只保留系统唯一标识；同时把该规则加入自动检查。
12. 配送人员头像读取补充 role_code = delivery 范围限制，并新增 SQL 范围测试。
13. 修复配送人员资质列表未应用人员筛选的问题，增加气站、配送点、配送角色和人员 ID 四重范围校验。
14. 资质列表新增人员姓名上下文、安全返回、重复人员列隐藏；新建预填所属人员，创建和编辑锁定归属。
15. 新增后端生成的 searchFields 契约；无有效字段时隐藏搜索区，枚举字段支持中文名称和内部编码。
16. 标准列表搜索标签统一为“模糊搜索”，输入框继续提示当前资源的具体可搜索字段。
17. 配送合同附件由文本 URI 升级为受控 PDF：列表脱敏、详情预览下载、草稿上传替换移除，并增加配送点范围鉴权接口。

操作后状态

17 类资源具备独立详情页，9 类资源具备独立新建页，5 类资源具备独立编辑页。列表查询来源可以恢复，新建和编辑保存后进入详情，未保存离开会提示确认。配送点资料仍使用专用只读卡片。

代码变更

• 新增：src/views/resource/ 下 5 个记录页组件与组合函数。
• 新增：src/views/shared/ResourceListPage.vue。
• 新增：ProtectedAvatarThumbnail.vue、protected-list-avatar-loader.ts 和配送人员角色范围测试。
• 新增：src/router/routes/modules/resource-route-builder.ts。
• 新增：src/api/resource-display.ts、resource-navigation.ts、resource-record-form.ts。
• 修改：platform.ts、ResourcePage.vue、resources.ts、路由类型、资源契约和包脚本。
• 删除：src/views/shared/CrudListPage.vue（已无活动引用，可由 Git 恢复）。

行为变化

• 变更前：列表抽屉承载记录操作，浏览器地址不随记录变化。
• 变更后：每个允许的操作拥有独立 URL，详情页集中承载业务动作。
• 兼容性：现有列表菜单地址和响应结构保持不变；人员资质列表现在必须提供人员标识，修复了原先可能扩大到本点全部资质的范围错误。

验证结果

• resource-pages:check：通过，详情 17、新建 9、编辑 5。
• contract:check：通过，18 个资源与后端契约一致。
• profile:check：通过，资料专用只读页未回退。
• type:check：通过。
• build：通过，2634 个模块完成生产构建。
• go test ./internal/logic/common ./internal/logic/delivery ./internal/logic/platform ./internal/routers ./cmd/cli：通过，包含搜索枚举、配送人员头像角色范围和资质人员范围测试。
• lint：通过；仅报告项目既有警告，未产生失败项。
• 浏览器回归：工作人员列表、详情、编辑、正式新建地址、返回链路、未保存保护、配送订单新建页、支付列表均通过。
• 布局回归：工作人员详情、编辑和配送订单新建页已在应用内浏览器逐页截图检查，与 5173 的页面结构和响应式断点一致。
• 头像回归：配送人员新建、编辑页已确认不再显示头像文本框，头像选择按钮、格式大小提示、默认头像和身份摘要均正常；后端头像路由测试通过。
• 列表头像回归：配送人员、用户账户显示受控圆形头像，其他资源不生成无效头像列；数据库 ID 列已从全部标准列表移除；点击刷新后头像重新加载正常。
• 资质关联回归：有效人员仅返回本人资质，标题和上下文显示服务端姓名及唯一标识；新建页预填并锁定人员，缺少上下文自动返回，伪造人员标识显示错误且不渲染表格。
• 搜索回归：资质页提示“可搜索：资质类型、资质编号”；银行卡页不显示关键字、查询和重置，仅保留刷新。
• 合同附件回归：Go 测试、附件路由检查、前端类型检查和生产构建通过；登录后的视觉回归记录在专项操作日志中。

风险评估

• 风险：后端新增可编辑字段后，前端白名单可能未同步。缓解：维护指南要求同步白名单并执行页面契约检查。
• 风险：旧书签若直接指向抽屉状态无法恢复。缓解：原列表 URL 保持不变，新的记录 URL 可稳定收藏。
• 风险：支付和退款名称修正可能影响依赖旧错误名称的自定义代码。缓解：仅配送端定义改用后端正式名称，菜单地址不变，并由契约检查持续保护。