# 项目文档：配送点独立资源页面 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        # 中文字段、状态和详情值展示
    │   ├── avatar.ts                  # 头像上传与配送点鉴权读取
    │   ├── resource-search-contract.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   # 详情业务动作与危险确认
    │   ├── ResourceAccountSummary.vue # 头像选择与账户身份摘要
    │   ├── use-resource-avatar.ts     # 头像预览、上传和清除状态
    │   └── use-unsaved-record.ts      # 未保存离开保护
    └── views/shared/
        ├── ResourceListPage.vue       # 跳转独立页面的标准列表
        ├── ProtectedAvatarThumbnail.vue # 32px 受控头像缩略图
        └── protected-list-avatar-loader.ts # 懒加载、限流、缓存和取消
```

## 4. 核心实现

`resource-route-builder.ts` 根据资源定义中的 `canCreate`、`canEdit` 和页面类型生成隐藏子路由。每条记录拥有稳定 URL，列表查询参数通过 `return_to` 保存，详情返回后可恢复来源列表状态。

`ResourceRecordPage.vue` 通过路由元数据 `recordMode` 在新建、详情、编辑三态间切换。新建成功进入详情，编辑成功返回详情；未保存表单离开时弹出确认。合同等受控资源的业务动作位于详情页，危险操作继续二次确认。

页面布局与平台总后台保持一致：使用灰色页面背景、顶部面包屑和操作栏；详情由“基本信息”“关联记录”“业务操作”分区卡片组成；新建和编辑使用双列响应式表单，并将保存、取消操作固定在表单内容底部。

配送人员和用户账户参考 5173 使用头像身份摘要卡片。新建、编辑时点击头像可选择不超过 2 MB 的 JPG/PNG 文件，保存时先上传到受控头像目录，再把返回 URI 写入资源；详情页通过配送点范围鉴权接口读取头像。未选择新头像时不会清空已有头像。

配送人员和用户账户列表同样参考 5173：联系电话后显示 32px 圆形头像，最多并发 6 个鉴权请求，接近可视区域才加载；当前页缓存结果，刷新或离页时取消请求并释放 Blob URL。404、网络错误和图片解码失败均回退本地默认头像。全部标准资源列表隐藏数据库自增 ID，只展示可复制的系统唯一标识。

配送人员资质列表必须由配送人员列表进入。页面先通过受保护人员详情接口回查姓名，再以当前气站、配送点、`delivery` 角色和人员 ID 四重条件加载资质；缺少、无效或越权人员上下文时停止加载，绝不回退为全部资质。标题和上下文区域显示人员姓名及可复制唯一标识，表格隐藏重复人员列。新建页自动预填所属人员，创建和编辑均锁定该关系，返回地址只接受安全站内路径。

资源搜索由后端 `searchFields` 契约驱动。没有有效字段的配送点资料、用户地址和银行卡页面不渲染搜索区域；其他页面显示“可搜索：具体字段”提示。枚举字段同时接受中文展示名称和内部稳定编码，查询、分页和重置始终保留人员上下文及安全来源参数。

`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 页面能力矩阵自动检查。
- 新增配送人员、用户账户的受控头像缩略图，并移除全部标准列表的数据库自增 ID。
- 新增配送人员资质的强制人员范围、上下文展示、关系预填锁定和安全返回链路。
- 新增后端生成的资源搜索契约，隐藏无效搜索并支持枚举中文名称与稳定编码。
- 新增配送合同受控 PDF 附件上传、鉴权预览、下载、替换和移除流程，列表及接口均不暴露内部路径。
- 保持配送点资料专用只读页面和现有公共后端接口不变。

## 7. 已知边界

独立页面只使用配送端数据范围内的关系查询和 CRUD 能力；头像与合同附件均通过配送点专属鉴权接口读取。合同附件仅接受不超过 10 MiB 的真实 PDF，草稿可上传、替换或确认移除，非草稿只允许预览和下载。页面与配送合同列表响应不得展示或返回内部附件 URI。平台角色和跨组织账户摘要接口仍不在本项目范围内。