重构配送点独立资源页面

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

@@ -0,0 +1,56 @@
+# 操作日志：配送点独立资源页面
+
+操作时间：2026-08-22 20:18:39
+操作类型：扩展、修改
+影响模块：配送点管理系统标准资源列表、独立记录页、前端路由与资源契约
+
+## 操作前状态
+
+配送点标准资源的新建、详情和编辑均在 `CrudListPage.vue` 抽屉中完成，没有稳定的记录 URL；支付和退款前端资源名与配送点后端实际路径不一致。
+
+## 具体操作
+
+1. 新增基于资源能力的路由生成器，为非单例资源生成详情、新建和编辑独立路由。
+2. 新增共享记录页、详情内容、字段表单、业务动作对话框和未保存离开保护。
+3. 新增标准列表页，将新建、详情和编辑入口改为路由跳转，并移除已停用的抽屉页面。
+4. 为可编辑资源增加后端更新字段白名单，保留受控合同编辑限制和危险操作二次确认。
+5. 将配送端支付、退款资源统一为 `payment_order`、`payment_refund`，同步后端契约快照。
+6. 增加页面能力矩阵自动检查，并更新项目文档。
+7. 依据 5173 页面重新对齐灰色页面底、面包屑、分区卡片、详情信息网格、双列表单和底部操作区。
+
+## 操作后状态
+
+17 类资源具备独立详情页，9 类资源具备独立新建页，5 类资源具备独立编辑页。列表查询来源可以恢复，新建和编辑保存后进入详情，未保存离开会提示确认。配送点资料仍使用专用只读卡片。
+
+## 代码变更
+
+- 新增：`src/views/resource/` 下 5 个记录页组件与组合函数。
+- 新增：`src/views/shared/ResourceListPage.vue`。
+- 新增：`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`：通过，2622 个模块完成生产构建。
+- `go test ./internal/logic/delivery`：通过。
+- `lint`：通过；仅报告项目既有警告，未产生失败项。
+- 浏览器回归：工作人员列表、详情、编辑、正式新建地址、返回链路、未保存保护、配送订单新建页、支付列表均通过。
+- 布局回归：工作人员详情、编辑和配送订单新建页已在应用内浏览器逐页截图检查，与 5173 的页面结构和响应式断点一致。
+
+## 风险评估
+
+- 风险：后端新增可编辑字段后，前端白名单可能未同步。缓解：维护指南要求同步白名单并执行页面契约检查。
+- 风险：旧书签若直接指向抽屉状态无法恢复。缓解：原列表 URL 保持不变，新的记录 URL 可稳定收藏。
+- 风险：支付和退款名称修正可能影响依赖旧错误名称的自定义代码。缓解：仅配送端定义改用后端正式名称，菜单地址不变，并由契约检查持续保护。

docs/项目文档_配送点独立资源页面_v1.0.md

@@ -0,0 +1,76 @@
+# 项目文档：配送点独立资源页面 v1.0
+
+## 1. 项目概述
+
+本次将配送点管理系统中标准资源的新建、详情和编辑操作从列表抽屉迁移为独立 URL 页面。页面框架参考平台总后台的共享记录页模式，同时严格使用配送点 JWT 数据范围和配送点后端现有接口。
+
+技术栈为 Vue 3、TypeScript、Vue Router、Arco Design Vue、Vite。运行环境要求 Node.js 20.19.0 及以上，前端默认访问地址为 `http://localhost:5176`。
+
+## 2. 页面能力范围
+
+- 17 类非单例资源提供独立详情页。
+- 9 类具有后端 POST 接口的资源提供独立新建页。
+- 5 类具有后端 PUT 接口的资源提供独立编辑页。
+- 配送点资料继续使用专用只读卡片，不生成记录子路由。
+- `/staff/add` 和 `/gasorder/create` 保留为正式新建地址，其余资源使用列表路径下的 `/new`。
+- 只读资源仅生成详情页；追加型资源生成新建和详情页，不生成编辑页。
+
+## 3. 目录结构
+
+```text
+frontend/delivery_admin/
+├── scripts/
+│   └── check-resource-pages.mjs       # 校验页面矩阵与后端 CRUD 契约
+└── src/
+    ├── api/
+    │   ├── resource-display.ts        # 中文字段、状态和详情值展示
+    │   ├── resource-navigation.ts     # 独立页面路由和安全返回地址
+    │   └── resource-record-form.ts    # 表单初始化、字段白名单和校验
+    ├── router/routes/modules/
+    │   └── resource-route-builder.ts  # 根据资源能力生成独立路由
+    ├── views/resource/
+    │   ├── ResourceRecordPage.vue     # 新建、详情、编辑三态容器
+    │   ├── ResourceDetailContent.vue  # 主记录和集合详情展示
+    │   ├── ResourceFieldForm.vue      # 通用资源字段表单
+    │   ├── ResourceActionDialog.vue   # 详情业务动作与危险确认
+    │   └── use-unsaved-record.ts      # 未保存离开保护
+    └── views/shared/
+        └── ResourceListPage.vue       # 跳转独立页面的标准列表
+```
+
+## 4. 核心实现
+
+`resource-route-builder.ts` 根据资源定义中的 `canCreate`、`canEdit` 和页面类型生成隐藏子路由。每条记录拥有稳定 URL，列表查询参数通过 `return_to` 保存，详情返回后可恢复来源列表状态。
+
+`ResourceRecordPage.vue` 通过路由元数据 `recordMode` 在新建、详情、编辑三态间切换。新建成功进入详情，编辑成功返回详情；未保存表单离开时弹出确认。合同等受控资源的业务动作位于详情页，危险操作继续二次确认。
+
+页面布局与平台总后台保持一致：使用灰色页面背景、顶部面包屑和操作栏；详情由“基本信息”“关联记录”“业务操作”分区卡片组成；新建和编辑使用双列响应式表单，并将保存、取消操作固定在表单内容底部。
+
+`resource-record-form.ts` 为五类可编辑资源声明后端更新字段白名单，防止用户名、合同编号等只读字段出现在编辑页或被无效提交。
+
+支付与退款资源统一使用后端正式名称 `payment_order`、`payment_refund`，菜单地址仍保持 `/finance/payments`、`/finance/refunds`，避免接口路径不一致导致 404。
+
+## 5. 维护指南
+
+新增标准资源时，先同步后端契约，再在 `resources.ts` 中配置资源字段和能力。若后端支持编辑，必须同步维护 `resource-record-form.ts` 的更新字段白名单。完成后运行：
+
+```powershell
+npm.cmd run contract:sync
+npm.cmd run resource-pages:check
+npm.cmd run type:check
+npm.cmd run build
+```
+
+不要为只读或追加型资源手工开放编辑路由。单例资料、树形页面或强业务定制页面应继续使用专用组件，不纳入通用记录页生成器。
+
+## 6. 变更记录
+
+- 新增共享独立记录页、标准列表页、路由生成器和未保存保护。
+- 删除已停用的抽屉式 `CrudListPage.vue`。
+- 修复支付、退款资源与后端契约名称不一致的问题。
+- 新增 17/9/5 页面能力矩阵自动检查。
+- 保持配送点资料专用只读页面和现有公共后端接口不变。
+
+## 7. 已知边界
+
+独立页面只使用配送端已存在的关系查询和 CRUD 能力，不引入平台端头像上传、合同附件上传、平台角色或跨组织账户摘要接口。普通头像和附件 URI 字段仍按原后端文本契约展示或填写。