docs: add ETC/fuel recharge split design and implementation plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
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`。
|
||||
Reference in new issue
Block a user