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

## 1. 项目概述

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

## 2. 页面与路由约定

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

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

## 3. 目录结构说明

```text
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 行，但按列表编排与记录页编排保持单一职责；后续若继续增加气站专属区块，应优先拆分组合式函数或子组件。