气站标准资源全页管理项目文档 v1.0

1. 项目概述

项目名称：气站管理端标准资源全页管理。
实施范围：frontend/gas_admin（开发端口 5175）及气站 API 必要的只读详情接口。
主要功能：把标准资源的新建、详情和编辑从列表抽屉迁移为独立 URL 页面，同时保留气站端权限、数据范围和业务动作。
技术栈：Vue 3、TypeScript、Vue Router、Arco Design、Vite、Go、Gin、GORM。
页面覆盖：20 类详情页、11 类新建页、8 类编辑页；仪表盘、邀请二维码和短业务动作不改变页面形态。

2. 页面与路由约定

列表路径/new
列表路径/:identity
列表路径/:identity/edit

路由生成器根据资源的 canCreate、canEdit 和列表模式自动创建隐藏子路由。
独立页通过 listRouteName、recordMode、activeMenu 和安全的 return_to 保持返回来源及菜单高亮。
/staff/add 与 /gasorder/create 保持兼容，直接进入独立新建页。
新建和编辑页检测未保存内容，取消、返回或切换路由前要求确认。
配送点账户管理进入隐藏账户列表，再进入账户独立页面。

3. 目录结构说明

platforms/
├── frontend/gas_admin/
│   ├── scripts/check-resource-pages.mjs          # 独立页面覆盖静态检查
│   └── src/
│       ├── api/
│       │   ├── resource-page-rules.ts            # 新建、编辑字段及状态限制
│       │   ├── resource-navigation.ts            # 页面地址与安全返回路径
│       │   ├── resource-record-form.ts           # 表单初始化与校验
│       │   ├── resource-display.ts               # 字段与状态中文展示
│       │   └── resources.ts                      # 气站资源和动作定义
│       ├── router/routes/modules/
│       │   ├── resource-route-builder.ts         # 自动生成独立记录页路由
│       │   └── platform.ts                       # 气站菜单及兼容入口
│       └── views/
│           ├── resource/                         # 共享详情、表单、动作与导航组件
│           └── shared/CrudListPage.vue           # 标准列表及页面跳转入口
└── backend/api/internal/
    ├── logic/gas/gasorder.go                     # 合同子资源受限详情
    ├── logic/gas/finance.go                      # 财务资源受限详情
    └── routers/gas_business.go                   # 气站详情路由注册

4. 核心文件与行为

4.1 独立记录页

ResourceRecordPage.vue 统一承载三种模式。详情始终重新调用单条接口，不依赖列表缓存；编辑保存只提交规则白名单字段；创建成功后进入新记录详情页。

4.2 资源能力规则

resource-page-rules.ts 为 8 类可编辑资源显式声明更新字段，避免把创建字段、用户名、密码或归属字段误提交给更新接口。配送合同仅在草稿且记录状态允许时进入编辑页。

4.3 气站业务适配

保留配送点、工作人员、用户、合同、订单、钱包和工单的数据范围。
保留密码重置、合同启用/续签/终止、合同气瓶解绑和气站订单动作。
工作人员资质按来源角色校验；订单分配只加载配送人员。
头像和 file_uri 继续作为普通字段，不调用平台总后台专属的受控头像或合同附件接口。
支付与退款资源使用后端真实名称 payment_order、payment_refund。

4.4 只读详情接口

新增 11 类 GET /:identity：合同气瓶、合同修订、候选气瓶、钱包、银行卡、支付记录、钱包流水、退款、提现、结算和对账。查询继续附加当前气站、合同、服务关系或钱包归属条件；对账资源当前无气站主体字段，详情与列表一致返回不可见。

5. 变更记录

新增标准资源独立页面路由生成器和共享记录页组件。
列表的新建、详情和编辑入口改为路由跳转。
新增 11 类受数据范围保护的详情接口及路由测试。
同步气站资源契约和独立页面覆盖检查。
未修改数据库模型、状态机、金额规则或现有写接口。

6. 维护指南

新增标准资源时同步维护后端资源契约、气站路由、resources.ts 和页面规则。
新增可编辑资源必须显式声明更新字段，并与后端 DTO 对照。
新增详情页必须使用受气站范围保护的单条接口，禁止用列表记录或前端隐藏代替对象权限。
业务状态流转继续使用专用动作接口，不进入通用编辑表单。
修改后运行 pnpm contract:sync、pnpm contract:check、pnpm resource-pages:check、pnpm type:check、pnpm lint 和 pnpm build。

7. 已知边界

气站 API 暂无受控头像读取和合同附件预览接口，因此对应字段保持原普通文本能力。
财务对账模型没有气站主体归属字段，气站端仍不展示全局对账数据。
两个共享页面文件超过 500 行，但按列表编排与记录页编排保持单一职责；后续若继续增加气站专属区块，应优先拆分组合式函数或子组件。

5.2 KiB Raw Blame History Unescape Escape