docs: add ETC/fuel recharge split design and implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-12 19:15:14 +08:00
1 parent a4a8c2de58
commit ed5784d1f7
2 files changed
+720

No files matched your search

@@ -0,0 +1,543 @@
# ETC / 油卡充值管理拆分 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Web 端将混合的「ETC/油卡充值管理」拆成并列的【ETC充值管理】与【油卡充值管理】;前端复制页面并按类型过滤,后端共用接口并新增 `rechargeTypeNe`;审批流程与审批人配置保持一套。
**Architecture:** 后端在现有 list/export/approval/board 过滤链增加 `recharge_type_ne`;油卡前端固定传 `rechargeTypeNe=etc`,ETC 前端固定传 `rechargeType=etc` 并复制四套页面。原分组 path 改为 `fuel-recharge`,新建 `etc-recharge` 分组;顶部 `PlRechargeSummary` 仅油卡路径显示。工作流 `biz_type=vehicle_recharge` 不拆。
**Tech Stack:** FastAPI / SQLAlchemy;Vue 3 / TypeScript / Element Plus;pytest;`node:test` + `tsx`;MySQL 菜单迁移 SQL。
**Spec:** `docs/superpowers/specs/2026-11-12-pl-etc-fuel-recharge-split-design.md`
---
## File map
| File | Responsibility |
| --- | --- |
| `backend/app/services/pl/vehicle_recharge_list_filters.py` | `recharge_type_ne` → `col != value` |
| `backend/app/services/pl_vehicle_recharge_service.py` | `list_applies` / `list_disburse_board`(及 list_records 若已接类型)透传 ne |
| `backend/app/services/pl_vehicle_recharge_approval_service.py` | pending/done 透传 ne |
| `backend/app/api/pl/vehicle_recharge.py` | Query/export body 增加 `rechargeTypeNe` |
| `backend/app/api/pl/vehicle_recharge_approval.py` | pending/done 增加 `rechargeTypeNe` |
| `backend/tests/test_pl_vehicle_ops_list_filters.py` | ne 过滤单测 |
| `web-admin/src/utils/pl-recharge-summary.ts` | 仅 `fuel-recharge` 显示统计 |
| `web-admin/src/utils/pl-recharge-summary.test.ts` | 路由断言更新 |
| `web-admin/src/views/pl/vehicle-recharge-{apply,approval,record,workflow}/` | 油卡侧:排除 etc、文案、默认类型 |
| `web-admin/src/views/pl/etc-vehicle-recharge-{apply,approval,record,workflow}/` | ETC 复制页:固定 etc、无油卡字段、新 table-key |
| `web-admin/src/router/modules/pl.ts` | 分组 path、标题、ETC 子路由、旧 URL redirect |
| `docs/sql/migrations/2026-11-12-pl-etc-fuel-recharge-split-menus.sql` | 改名、改 path、新建 ETC 菜单、角色同步 |
| `web-admin/src/components/core/layouts/art-page-content/index.vue` | 确认 summary 仍指向油卡申请 menuCode(一般无需改逻辑) |
**说明:**
- 「车油卡信息」`PL_VEH_FUEL_CARD` 继续留在油卡分组下(现挂在原充值分组),不迁入 ETC。
- 写入接口本期不按域拆分;类型由前端固定。
- 提交前须有用户明确授权再 `git commit`;下列 Commit 步骤在已授权时执行。
---
### Task 1: 后端 `rechargeTypeNe` 过滤
**Files:**
- Modify: `backend/app/services/pl/vehicle_recharge_list_filters.py`
- Modify: `backend/tests/test_pl_vehicle_ops_list_filters.py`
- Modify: `backend/app/services/pl_vehicle_recharge_service.py`
- Modify: `backend/app/services/pl_vehicle_recharge_approval_service.py`
- Modify: `backend/app/api/pl/vehicle_recharge.py`
- Modify: `backend/app/api/pl/vehicle_recharge_approval.py`
- [ ] **Step 1: 写失败单测**
在 `test_pl_vehicle_ops_list_filters.py` 追加:
```python
def test_recharge_apply_type_ne_filter():
filters = build_recharge_apply_column_filters(recharge_type_ne="etc")
assert len(filters) == 1
sql = _compile(filters[0])
assert "recharge_type" in sql
assert "!=" in sql or "<>" in sql
assert "etc" in sql
def test_recharge_disburse_board_type_ne_filter():
filters = build_recharge_disburse_board_column_filters(recharge_type_ne="etc")
assert any("recharge_type" in _compile(f) for f in filters)
```
- [ ] **Step 2: 跑测确认失败**
```bash
cd backend && source venv/bin/activate
pytest tests/test_pl_vehicle_ops_list_filters.py::test_recharge_apply_type_ne_filter tests/test_pl_vehicle_ops_list_filters.py::test_recharge_disburse_board_type_ne_filter -v
```
Expected: FAIL(未知参数或无 ne 条件)
- [ ] **Step 3: 实现 filter 层**
在 `vehicle_recharge_list_filters.py` 增加:
```python
def _append_ne_filter(filters: list, col, raw: Optional[str]) -> None:
value = (raw or "").strip()
if value:
filters.append(col != value)
```
`build_recharge_apply_column_filters` / `build_recharge_disburse_board_column_filters` 增加参数 `recharge_type_ne: Optional[str] = None`,在现有 `_append_enum_filter(... recharge_type ...)` 之后调用:
```python
_append_ne_filter(filters, PlVehicleRechargeApply.recharge_type, recharge_type_ne)
```
(发放看板同样用 `PlVehicleRechargeApply.recharge_type`。)
- [ ] **Step 4: 透传 service + API**
对以下调用链增加同名可选参数并向下传递(alias `rechargeTypeNe`):
1. `list_applies`(service + `_apply_list_kwargs` / export 解析 + `list_applies` Query)
2. `list_disburse_board`(及 export)
3. `list_records`(若当前已支持 `recharge_type`,一并加 ne;否则仅保证 apply/board/approval)
4. approval `list_pending` / `list_done`(`vehicle_recharge_approval.py` 的 `_param_get` 与 Query)
示例(API Query):
```python
recharge_type_ne: Optional[str] = Query(default=None, alias="rechargeTypeNe"),
```
export body Field 同样加 `rechargeTypeNe`。
- [ ] **Step 5: 跑测确认通过**
```bash
cd backend && source venv/bin/activate
pytest tests/test_pl_vehicle_ops_list_filters.py -v
```
Expected: PASS
- [ ] **Step 6: Commit(需用户授权)**
```bash
git add backend/app/services/pl/vehicle_recharge_list_filters.py \
backend/app/services/pl_vehicle_recharge_service.py \
backend/app/services/pl_vehicle_recharge_approval_service.py \
backend/app/api/pl/vehicle_recharge.py \
backend/app/api/pl/vehicle_recharge_approval.py \
backend/tests/test_pl_vehicle_ops_list_filters.py
git commit -m "$(cat <<'EOF'
feat(pl): add rechargeTypeNe filter for vehicle recharge lists
EOF
)"
```
---
### Task 2: 顶部统计仅油卡路由
**Files:**
- Modify: `web-admin/src/utils/pl-recharge-summary.ts`
- Modify: `web-admin/src/utils/pl-recharge-summary.test.ts`
- [ ] **Step 1: 更新失败测试**
替换 `isRechargeSummaryRoute` 相关用例为:
```ts
it('只对油卡充值业务子页显示,ETC 与其它车辆页不显示', () => {
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/fuel-recharge/vehicle-recharge-apply'),
true
)
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/fuel-recharge/vehicle-recharge-record'),
true
)
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/fuel-recharge/vehicle-recharge-approval'),
true
)
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/fuel-recharge/vehicle-recharge-workflow'),
true
)
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/etc-recharge/etc-vehicle-recharge-apply'),
false
)
assert.equal(
isRechargeSummaryRoute('/vehicle-mgmt/etc-recharge/vehicle-recharge-apply'),
false
)
assert.equal(isRechargeSummaryRoute('/vehicle-mgmt/vehicle-fuel-card'), false)
assert.equal(isRechargeSummaryRoute('/vehicle-mgmt/vehicle'), false)
})
```
- [ ] **Step 2: 跑测确认失败**
```bash
cd web-admin && ./node_modules/.bin/tsx --test src/utils/pl-recharge-summary.test.ts
```
Expected: FAIL(旧路径仍为 true / 新 fuel 路径未匹配)
- [ ] **Step 3: 实现**
```ts
export function isRechargeSummaryRoute(path: string) {
return /\/fuel-recharge\/vehicle-recharge-(apply|approval|record|workflow)\/?$/.test(
path
)
}
```
确认 `art-page-content` 仍用 `menuCode === 'pl:vehicle-recharge-apply:list'` 解析跳转(油卡申请 perms 不变),一般无需改文件。
- [ ] **Step 4: 跑测确认通过**
同 Step 2,Expected: PASS
- [ ] **Step 5: Commit(需用户授权)**
```bash
git add web-admin/src/utils/pl-recharge-summary.ts web-admin/src/utils/pl-recharge-summary.test.ts
git commit -m "$(cat <<'EOF'
fix(web-admin): show recharge summary only on fuel-recharge routes
EOF
)"
```
---
### Task 3: 油卡侧原页面改造(排除 ETC)
**Files:**
- Modify: `web-admin/src/views/pl/vehicle-recharge-apply/index.vue`
- Modify: `web-admin/src/views/pl/vehicle-recharge-approval/index.vue`
- Modify: `web-admin/src/views/pl/vehicle-recharge-record/index.vue`
- Modify: `web-admin/src/views/pl/vehicle-recharge-workflow/index.vue`
- Modify: `web-admin/src/views/pl/vehicle-recharge-apply/columnFilterDefs.ts`(若枚举选项在此定义)
- [ ] **Step 1: 申请页强制排除 etc**
在 `buildListQueryParams`(约 L715)末尾增加:
```ts
params.rechargeTypeNe = 'etc'
return params
```
若用户列筛选选了 `rechargeType` 且包含 `etc`,以 ne 为准仍排除 etc(后端 `!=` 与 `IN` 同时生效时需确认 SQLAlchemy 为 AND)。为避免矛盾:油卡页 `enumOptionsFor('rechargeType')` **过滤掉** `etc` 选项;表单 `<el-option>` 同样不渲染 `etc`。
默认新建类型:
```ts
// handleAdd / formData 初始
formData.rechargeType = 'fuel'
```
文案:文件头注释、导出 filename、提示里的「ETC/油卡」改为「油卡」(审批跳转文案等同理)。
- [ ] **Step 2: 审批页 / 发放页同样传 `rechargeTypeNe=etc`**
在各自组装 list/export/board 参数处增加 `rechargeTypeNe: 'etc'`;充值类型筛选项去掉 etc;文案改为油卡。
发放页中类似:
```ts
ElMessage.warning('审批中的申请请到「油卡充值审批」菜单完成发放登记')
```
- [ ] **Step 3: 审批人设置页**
顶部 `wf-info-bar` 旁或下方增加一行提示(简短即可):
```vue
<span class="form-tip">ETC 与油卡共用同一套审批人配置</span>
```
不改 `biz_type` / API。
- [ ] **Step 4: 本地点验(开发服)**
打开 `/#/vehicle-mgmt/fuel-recharge/vehicle-recharge-apply`(路由 Task 5 完成前可暂用旧 path 带 `rechargeTypeNe` 联调)。确认列表无 etc 行;新建无 ETC 选项。
- [ ] **Step 5: Commit(需用户授权)**
```bash
git add web-admin/src/views/pl/vehicle-recharge-apply \
web-admin/src/views/pl/vehicle-recharge-approval \
web-admin/src/views/pl/vehicle-recharge-record \
web-admin/src/views/pl/vehicle-recharge-workflow
git commit -m "$(cat <<'EOF'
fix(web-admin): restrict legacy recharge pages to non-ETC types
EOF
)"
```
---
### Task 4: 复制并改造 ETC 四套页面
**Files:**
- Create: `web-admin/src/views/pl/etc-vehicle-recharge-apply/`(含 `index.vue`、`columnFilterDefs.ts`)
- Create: `web-admin/src/views/pl/etc-vehicle-recharge-approval/index.vue`
- Create: `web-admin/src/views/pl/etc-vehicle-recharge-record/index.vue`
- Create: `web-admin/src/views/pl/etc-vehicle-recharge-workflow/index.vue`
- [ ] **Step 1: 复制目录**
```bash
cd web-admin/src/views/pl
cp -R vehicle-recharge-apply etc-vehicle-recharge-apply
cp -R vehicle-recharge-approval etc-vehicle-recharge-approval
cp -R vehicle-recharge-record etc-vehicle-recharge-record
cp -R vehicle-recharge-workflow etc-vehicle-recharge-workflow
```
- [ ] **Step 2: ETC 申请页改造清单(在复制后的文件上改)**
1. 注释与标题文案 →「ETC充值申请」等。
2. `buildListQueryParams`:删除 `rechargeTypeNe`;固定 `params.rechargeType = 'etc'`(若用户又选了类型筛选,仍强制 etc,或隐藏类型筛选项)。
3. 表单:充值类型固定 `etc`,可用只读展示或隐藏 select 并在提交时写死;去掉油卡卡号相关表单项与 `useVehicleFuelCard` 展示(ETC 不需要)。
4. `table-key`、`usePersistedListColumns` 的 localStorage key、导出列定义 key → 加 `etc-` 前缀,例如 `pl-etc-vehicle-recharge-apply`、`pl-etc-vehicle-recharge-apply-list-columns-v2`。
5. `columnFilterDefs` 中若 import 路径指向旧目录,改为相对本目录或 `@/views/pl/etc-vehicle-recharge-apply/columnFilterDefs`。
6. 权限指令 / `menuCode` 若页面内有硬编码,改为 ETC 新 perms(与菜单 SQL 一致,见 Task 6):`pl:etc-vehicle-recharge-apply:*`。
7. 统计刷新:可保留 `mittBus.emit('rechargeSummaryRefresh')`(无害);ETC 路由本就不显示 summary。
- [ ] **Step 3: ETC 审批 / 发放页**
- 列表参数固定 `rechargeType=etc`。
- 文案「ETC充值审批」「ETC发放管理」。
- 新 `table-key` / 列偏好 key。
- 发放页跳转提示改为「ETC充值审批」。
- 隐藏或固定类型筛选为 etc;无油卡卡号列亦可保留显示为 —。
- [ ] **Step 4: ETC 审批人设置页**
- 仍调用现有工作流 API / `vehicle_recharge` biz_type(与油卡页相同 service 调用)。
- 增加共用说明文案。
- `table-key` 改为 `pl-etc-vehicle-recharge-workflow`(仅前端偏好隔离)。
- 页面内 perms 复用 `pl:vehicle-recharge-workflow:*`(与设计一致)。
- [ ] **Step 5: Commit(需用户授权)**
```bash
git add web-admin/src/views/pl/etc-vehicle-recharge-apply \
web-admin/src/views/pl/etc-vehicle-recharge-approval \
web-admin/src/views/pl/etc-vehicle-recharge-record \
web-admin/src/views/pl/etc-vehicle-recharge-workflow
git commit -m "$(cat <<'EOF'
feat(web-admin): add dedicated ETC vehicle recharge pages
EOF
)"
```
---
### Task 5: 静态路由与 redirect
**Files:**
- Modify: `web-admin/src/router/modules/pl.ts`
- [ ] **Step 1: 原分组改为油卡**
将 `PL_GROUP_VEH_RECHARGE`:
- `path: 'etc-recharge'` → `'fuel-recharge'`
- `meta.title` → `'油卡充值管理'`
- 子菜单 title:`油卡充值申请` / `油卡充值审批` / `油卡充值发放管理` / `油卡充值审批人设置`
- **保留** `PL_VEH_FUEL_CARD`(车油卡信息)在此分组下
- component 仍指向原 `pl/vehicle-recharge-*`
- [ ] **Step 2: 新增 ETC 分组(插在油卡分组旁)**
```ts
{
id: 'PL_GROUP_VEH_ETC_RECHARGE',
name: 'PlVehicleEtcRechargeGroup',
path: 'etc-recharge',
meta: { title: 'ETC充值管理', keepAlive: false },
children: [
{
id: 'PL_ETC_VEH_RECHARGE_APPLY',
name: 'PlEtcVehicleRechargeApply',
path: 'etc-vehicle-recharge-apply',
component: '/pl/etc-vehicle-recharge-apply/index',
meta: {
title: 'ETC充值申请',
keepAlive: false,
menuCode: 'pl:etc-vehicle-recharge-apply:list'
}
},
{
id: 'PL_ETC_VEH_RECHARGE_APPROVAL',
name: 'PlEtcVehicleRechargeApproval',
path: 'etc-vehicle-recharge-approval',
component: '/pl/etc-vehicle-recharge-approval/index',
meta: {
title: 'ETC充值审批',
keepAlive: false,
menuCode: 'pl:etc-vehicle-recharge-approval:list'
}
},
{
id: 'PL_ETC_VEH_RECHARGE_RECORD',
name: 'PlEtcVehicleRechargeRecord',
path: 'etc-vehicle-recharge-record',
component: '/pl/etc-vehicle-recharge-record/index',
meta: {
title: 'ETC发放管理',
keepAlive: false,
menuCode: 'pl:etc-vehicle-recharge-record:list'
}
},
{
id: 'PL_ETC_VEH_RECHARGE_WF',
name: 'PlEtcVehicleRechargeWorkflow',
path: 'etc-vehicle-recharge-workflow',
component: '/pl/etc-vehicle-recharge-workflow/index',
meta: {
title: 'ETC充值审批人设置',
keepAlive: false,
menuCode: 'pl:vehicle-recharge-workflow:list'
}
}
]
}
```
- [ ] **Step 3: 更新隐藏 redirect**
所有原指向 `/vehicle-mgmt/etc-recharge/vehicle-recharge-*` 的 redirect,改为:
`/vehicle-mgmt/fuel-recharge/vehicle-recharge-*`
(书签落到油卡侧。)
- [ ] **Step 4: Commit(需用户授权)**
```bash
git add web-admin/src/router/modules/pl.ts
git commit -m "$(cat <<'EOF'
feat(web-admin): split etc and fuel recharge router groups
EOF
)"
```
---
### Task 6: 菜单迁移 SQL + 角色同步
**Files:**
- Create: `docs/sql/migrations/2026-11-12-pl-etc-fuel-recharge-split-menus.sql`
- [ ] **Step 1: 编写可重复执行的迁移**
要点(MySQL 5.7,`SET NAMES utf8mb4;` + 事务):
1. 更新原分组与子菜单名称:
- `PL_GROUP_VEH_RECHARGE`:`menu_name='油卡充值管理'`,`path='fuel-recharge'`,remark 更新
- 原子菜单名改为「油卡充值申请/审批/发放管理/审批人设置」
2. 插入 ETC 分组(`parent_id=PL_GROUP_VEHICLE`,`path='etc-recharge'`,`order_num` 建议小于油卡分组以便并列靠前,或紧挨油卡):
- id: `PL_GROUP_VEH_ETC_RECHARGE`
3. 插入 4 个 C 菜单(component / path / perms 与 Task 5 一致):
- Apply/Approval/Record:新 perms `pl:etc-vehicle-recharge-*:list`
- WF:`perms='pl:vehicle-recharge-workflow:list'`(复用)
4. 为 Apply/Approval/Record 复制对应 F 按钮菜单(对照现有 `PL_VRA_*` / `PL_VRR_*` / 审批按钮),id 前缀 `PL_ETC_…`,perms 换新前缀。
5. 角色同步:对已拥有对应油卡菜单(如 `PL_VEH_RECHARGE_APPLY`)的角色,插入 ETC 对等菜单及祖先(模式参考 `docs/sql/migrations/2026-10-25-pl-vehicle-fuel-card.sql` 的 `sys_role_menu` 段);`NOT EXISTS` 防重复;不恢复管理员已软删授权。
6. WF 菜单:对已有 `PL_VEH_RECHARGE_WF` 授权的角色补 `PL_ETC_VEH_RECHARGE_WF` + 分组祖先。
- [ ] **Step 2: 在本地库执行并抽查**
```bash
# 使用项目既有 mysql 方式执行该 migration;执行后:
# SELECT id,menu_name,path,component,perms FROM sys_menu
# WHERE id LIKE 'PL_%RECHARGE%' OR parent_id IN ('PL_GROUP_VEH_RECHARGE','PL_GROUP_VEH_ETC_RECHARGE');
```
Expected: 两组菜单并存;油卡 path=`fuel-recharge`;ETC 指向 `pl/etc-vehicle-recharge-*`。
- [ ] **Step 3: Commit(需用户授权)**
```bash
git add docs/sql/migrations/2026-11-12-pl-etc-fuel-recharge-split-menus.sql
git commit -m "$(cat <<'EOF'
chore(sql): split ETC and fuel recharge menus with role sync
EOF
)"
```
---
### Task 7: 联调验收与回归
**Files:** 无必须改动;按需修漏网文案 / 参数。
- [ ] **Step 1: 后端过滤回归**
```bash
cd backend && source venv/bin/activate
pytest tests/test_pl_vehicle_ops_list_filters.py -v
```
Expected: PASS
- [ ] **Step 2: 前端 summary 单测**
```bash
cd web-admin && ./node_modules/.bin/tsx --test src/utils/pl-recharge-summary.test.ts
```
Expected: PASS
- [ ] **Step 3: 类型检查(可选但推荐)**
```bash
cd web-admin && pnpm build:typecheck
```
Expected: 与本改动相关的错误为 0
- [ ] **Step 4: 手工验收对照设计「验收」清单**
1. 侧栏并列【ETC充值管理】【油卡充值管理】,ETC 4 子菜单;油卡含原 4 项 +「车油卡信息」。
2. ETC 列表仅 etc;新建固定 ETC;无顶部统计。
3. 油卡列表无 etc;有顶部统计;卡片跳转进油卡申请。
4. 两边审批人设置改同一套节点。
5. 旧 URL `/#/vehicle-mgmt/etc-recharge/vehicle-recharge-apply` redirect 到 fuel 路径。
6. 小程序未改。
- [ ] **Step 5: 若有修复,再提交(需用户授权)**
---
## Spec coverage(自检)
| 设计要求 | 任务 |
| --- | --- |
| 并列两模块 + 子菜单 | Task 5–6 |
| 油卡排除 etc、界面现状 | Task 3 |
| ETC 复制页 + 固定 etc + 无统计 | Task 2、4 |
| 后端不整拆 + `rechargeTypeNe` | Task 1 |
| 审批/审批人保持一套 + 双入口 | Task 3–4 workflow |
| 仅 Web | 全程不改 miniprogram |
| 旧 URL redirect | Task 5 |
| 角色默认同步 | Task 6 |
| 车油卡信息归属油卡组 | Task 5–6 明确保留 |
## Placeholder scan
无 TBD/TODO;油卡/ETC 路径、菜单 id、perms、测试命令已钉死。
@@ -0,0 +1,177 @@
# ETC / 油卡充值管理菜单拆分(Web)
## 背景与问题
Web【车辆管理】下现有【ETC/油卡充值管理】(路由前缀 `/vehicle-mgmt/etc-recharge/`)将 ETC 与油卡(及山峡、百链等非 ETC 类型)混在同一套申请 / 审批 / 发放 / 审批人设置页面中。布局层在匹配充值路由时还会展示 `PlRechargeSummary` 顶部统计,该统计面向油卡场景,不适合挂在独立 ETC 模块上。
用户希望:ETC 与油卡分成两个并列模块,前端可独立演进;后端表与接口暂不整模块拆分;审批流程与审批人配置继续共用现有 `biz_type=vehicle_recharge`。
## 已确认决策
| 项 | 结论 |
| --- | --- |
| 产品结构 | 并列【ETC充值管理】与【油卡充值管理】(原名改名) |
| ETC 子菜单 | 申请、审批、发放管理、审批人设置 |
| 油卡侧 | 界面保持现状;列表等不再展示 `rechargeType=etc` |
| ETC 顶部统计 | 不展示(`PlRechargeSummary` 不对 ETC 路由出现) |
| 前端实现 | 复制现有 4 个页面目录再改,便于后续各自演进 |
| 后端实现 | 不拆服务/表;列表与写入靠类型过滤/约束;小改即可 |
| 审批流程 / 审批人 | 保持现状,仍一套 `vehicle_recharge`;两边菜单都进同一配置(方案 A) |
| 修改端 | 仅 Web 管理端;小程序不改 |
| 非 ETC 类型归属 | `fuel` / `shanxia` / `bailian` 等非 `etc` 均留在油卡模块 |
## 范围
**包含**
- `web-admin`:菜单与路由、页面复制与类型固化、顶部统计路由判定、文案与筛选
- `backend`:列表/导出/看板/审批查询落实类型过滤(见后端设计);不拆接口与表
- `docs/sql/migrations/`:菜单改名、新建 ETC 分组与子菜单、角色菜单同步;旧 path 由路由 redirect 兼容
**不包含**
- 小程序 / 移动 H5
- 拆分审批流程 `biz_type`、复制工作流定义、在途单迁移
- 拆分数据表或新建独立后端模块
- 本期不要求油卡与 ETC 审批人可分别配置(后续若需要再单独立项)
## 菜单与路由
### 目标结构(均挂在【车辆管理】`PL_GROUP_VEHICLE` 下)
1. **【ETC充值管理】**(新建分组)
- ETC充值申请
- ETC充值审批
- ETC发放管理
- ETC充值审批人设置
2. **【油卡充值管理】**(原 `PL_GROUP_VEH_RECHARGE` 改名)
- 油卡充值申请 / 审批 / 发放管理 / 审批人设置(原子菜单改名)
### 路径约定
| 模块 | 分组 path | 说明 |
| --- | --- | --- |
| ETC | `etc-recharge` | 语义与产品名一致;组件指向**复制后的** ETC 页面 |
| 油卡 | `fuel-recharge` | 原分组 path 由 `etc-recharge` 改为 `fuel-recharge` |
完整路径(菜单 SQL 与此对齐):
- ETC:`/#/vehicle-mgmt/etc-recharge/etc-vehicle-recharge-{apply|approval|record|workflow}`
- 油卡:`/#/vehicle-mgmt/fuel-recharge/vehicle-recharge-{apply|approval|record|workflow}`
### 兼容
- `web-admin/src/router/modules/pl.ts` 中现有指向 `/vehicle-mgmt/etc-recharge/vehicle-recharge-*` 的 redirect,改为指向 **油卡** 新路径 `/vehicle-mgmt/fuel-recharge/vehicle-recharge-*`(保持书签可用且落到油卡侧)。
- 若另有文档/外链写死旧地址,实现计划中列出并改 redirect 或文档。
### 权限
- 油卡:保留现有菜单 id 与 `perms`(如 `pl:vehicle-recharge-apply:list`),仅改展示名与分组 path/component 若需要。
- ETC:新建菜单 id 与独立 `perms`(如 `pl:etc-vehicle-recharge-apply:list` 等),便于日后分开授权。
- 迁移 SQL:对已拥有原充值相关菜单的角色,同步挂上对应 ETC 菜单,保证上线后默认两边都可用;之后可由管理员单独收回。
- 审批人设置:ETC / 油卡各一条菜单,component 分别指向复制页与原页,均调用同一工作流 API / `biz_type=vehicle_recharge`。ETC 菜单的 `perms` **复用**现有 `pl:vehicle-recharge-workflow:*`,避免配置权被拆成两套。
## 前端设计
### 页面复制
在 `web-admin/src/views/pl/` 复制:
| 原路径 | ETC 复制目标(示例名) |
| --- | --- |
| `vehicle-recharge-apply/` | `etc-vehicle-recharge-apply/` |
| `vehicle-recharge-approval/` | `etc-vehicle-recharge-approval/` |
| `vehicle-recharge-record/` | `etc-vehicle-recharge-record/` |
| `vehicle-recharge-workflow/` | `etc-vehicle-recharge-workflow/`(复制后仅改文案/说明;仍调用同一工作流 API) |
油卡侧继续使用原目录,做「排除 etc」与文案改名。审批人设置菜单的 `component` 分别指向上述两套页面,避免一边改提示文案影响另一边;业务数据仍是同一 `biz_type`。
`columnFilterDefs`、本地 `table-key` / 列偏好 localStorage key:ETC 页使用**新 key**,避免与油卡列配置互相污染。
API 封装:优先继续共用 `web-admin/src/api/pl` 现有 `vehicleRecharge*Api`,在页面请求参数中带类型约束;不为本期再复制一套 API 模块,除非出现仅 ETC 需要的入参。
### 类型与交互
**ETC 页**
- 列表 / 导出 / 待办 / 已办 / 发放看板:固定只查 `rechargeType=etc`(或后端等价过滤)。
- 新增/编辑:充值类型固定为 `etc`,不提供油卡/山峡/百链选项;隐藏油卡卡号等仅油卡字段。
- 文案、导出文件名、空态、跳转提示改为「ETC…」。
- **不展示**顶部 `PlRechargeSummary`。
**油卡页**
- 列表 / 导出 / 审批 / 发放:**排除** `rechargeType=etc`;保留 `fuel` / `shanxia` / `bailian` 等现有非 ETC 类型与筛选(筛选中去掉或禁用单独再选 ETC,避免空结果误导)。
- 顶部统计:**保留**(仍走现有 summary 组件与接口)。
- 其余交互、按钮、审批发放流程与现网一致。
### 顶部统计路由
`isRechargeSummaryRoute`(`web-admin/src/utils/pl-recharge-summary.ts`)及 `art-page-content` 中 `showRechargeSummary` / `rechargeApplyPath`:
- 仅对**油卡**充值相关 path 为 true(例如匹配 `fuel-recharge` 下的 apply/approval/record/workflow)。
- ETC 路径一律不展示。
- `rechargeApplyPath` 解析菜单 code 时指向油卡申请菜单,保证统计卡片跳转仍进入油卡申请页。
相关单测(`pl-recharge-summary.test.ts`)同步改断言。
### 审批人设置(方案 A)
- 两菜单入口都打开同一业务配置(`biz_type=vehicle_recharge`)。
- UI 可增加简短说明:「ETC 与油卡共用同一套审批人配置」,降低「改了一边另一边不变」的误解。
- 流程显示名可暂保持「ETC/油卡充值审批流程」,本期不强制改名。
## 后端设计
### 查询
现有列表已支持 `rechargeType` / `rechargeTypeIn`(见 `vehicle_recharge` API 与 `vehicle_recharge_list_filters`)。本期落实:
- ETC 前端固定传 `rechargeType=etc`。
- 油卡「非 etc」过滤:**采用新增可选查询参数 `rechargeTypeNe=etc`**(filter 层 `!=`),避免字典新增类型时维护白名单;保留现有 `rechargeType` / `rechargeTypeIn` 兼容。
- 审批 pending/done、发放看板、导出与列表使用同一套类型约束,避免一侧漏过滤。
### 写入约束
- 本期**不**引入域请求头,**不**按菜单拆 create/update 接口。
- 类型正确性由前端保证:ETC 页只提交 `etc`;油卡页表单选项与默认值不含 `etc`。
- 后端 create/update 维持现有字段校验即可;防串改列为后续增强,不阻塞本期验收。
### 审批与工作流
- `_BIZ_TYPE_VEHICLE_RECHARGE = "vehicle_recharge"` 不变。
- 不新增 workflow 定义,不做在途迁移。
- summary 接口可保持现行为(油卡统计);不强制为 ETC 提供第二套 summary。
## 数据与兼容
- 表结构不改;历史 `etc` 单据仅在 ETC 菜单可见,非 etc 仅在油卡菜单可见。
- 小程序仍使用原混合入口与文案;可能仍能看到/提交两类数据,与 Web 分栏并存,接受为已知差异,后续另项处理。
## UI 规范
- 沿用现页模式(复杂业务列表)与 Fresh Mint;不新造布局与主色。
- 复制页保持与原页相同的 panel / 工具栏 / 表格 / 弹窗结构;仅改类型范围、文案与统计显隐。
- 菜单标题变更后,若申请页有 `panelTitleBarTextRules` 注册需求,按 Web AGENTS 补齐完整文案。
## 验收
1. 侧栏可见并列【ETC充值管理】【油卡充值管理】,各含 4 个子菜单(文案正确)。
2. ETC 申请/审批/发放仅出现 `rechargeType=etc` 数据;新建只能选/固定 ETC。
3. 油卡对应页面不出现 ETC 数据;`fuel` / `shanxia` / `bailian` 仍可见可操作(在权限与数据允许时)。
4. ETC 各子路由无顶部充值统计;油卡各子路由仍有统计,且卡片跳转进油卡申请。
5. 两边「审批人设置」打开后编辑的是同一套节点;保存一侧,另一侧刷新可见。
6. 旧 URL `/vehicle-mgmt/etc-recharge/vehicle-recharge-apply` 等 redirect 到油卡新路径且可用。
7. 原已授权充值菜单的角色,上线后默认可进 ETC 新菜单(迁移 SQL 生效后)。
8. 小程序行为与菜单未改。
## 风险
- 前端双份页面:同类 Bug 可能需改两处;接受为独立演进的代价。
- 审批人双入口同配置:需文案提示,否则易误解为已拆分。
- 小程序仍混合:与 Web 不一致,需在发布说明中写明。
- `rechargeTypeNe` 需在 list/export/approval/board 全路径接通,漏接会导致某一页仍混入 ETC。
## 状态
会话中已确认:复制前端、后端不整拆、审批配置保持现状且双菜单进同一配置(A)、仅 Web。实现计划:`docs/superpowers/plans/2026-11-12-pl-etc-fuel-recharge-split.md`。