From ed5784d1f76224ec07919963faf773188e797717 Mon Sep 17 00:00:00 2001 From: wuzilong <704541015@qq.com> Date: Thu, 12 Nov 2026 19:15:14 +0800 Subject: [PATCH] docs: add ETC/fuel recharge split design and implementation plan Co-authored-by: Cursor --- .../2026-11-12-pl-etc-fuel-recharge-split.md | 543 ++++++++++++++++++ ...11-12-pl-etc-fuel-recharge-split-design.md | 177 ++++++ 2 files changed, 720 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-12-pl-etc-fuel-recharge-split.md create mode 100644 docs/superpowers/specs/2026-11-12-pl-etc-fuel-recharge-split-design.md diff --git a/docs/superpowers/plans/2026-11-12-pl-etc-fuel-recharge-split.md b/docs/superpowers/plans/2026-11-12-pl-etc-fuel-recharge-split.md new file mode 100644 index 000000000..b9b73612b --- /dev/null +++ b/docs/superpowers/plans/2026-11-12-pl-etc-fuel-recharge-split.md @@ -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` 选项;表单 `` 同样不渲染 `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 +ETC 与油卡共用同一套审批人配置 +``` + +不改 `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、测试命令已钉死。 diff --git a/docs/superpowers/specs/2026-11-12-pl-etc-fuel-recharge-split-design.md b/docs/superpowers/specs/2026-11-12-pl-etc-fuel-recharge-split-design.md new file mode 100644 index 000000000..2c63ce08f --- /dev/null +++ b/docs/superpowers/specs/2026-11-12-pl-etc-fuel-recharge-split-design.md @@ -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`。