93 lines
5.2 KiB
Markdown
93 lines
5.2 KiB
Markdown
# 气站标准资源全页管理项目文档 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 行，但按列表编排与记录页编排保持单一职责；后续若继续增加气站专属区块，应优先拆分组合式函数或子组件。
|