docs: add ETC/油卡充值文案改名实现计划。

按展示层替换拆分迁移 SQL、后端 label、web-admin 与小程序任务。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/plans/2026-10-16-pl-vehicle-recharge-oil-card-rename.md

@@ -0,0 +1,457 @@
+# 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:** 将「ETC/加油充值」业务线用户可见文案统一改为「油卡」（菜单、类型展示、导出、微信文案、提示语），存值 `fuel` 与「加油登记」模块不动。
+
+**Architecture:** 仅展示层替换：迁移 SQL 更新 `sys_menu.menu_name` / `sys_dict_data.dict_label` / 既有 `bx_workflow_def.wf_name`；后端改 `RECHARGE_TYPE_LABELS` 与用户可见错误文案；web-admin / miniprogram 改路由 meta、label 映射、表单选项与页面标题。API path、权限码、`recharge_type=fuel` 存值全部不变。
+
+**Tech Stack:** MySQL 迁移 SQL；FastAPI / pytest；Vue 3（web-admin）；uni-app（miniprogram）
+
+**Spec:** `docs/superpowers/specs/2026-10-16-pl-vehicle-recharge-oil-card-rename-design.md`
+
+---
+
+## File map
+
+| 文件 | 职责 |
+|------|------|
+| `docs/sql/migrations/2026-10-16-pl-vehicle-recharge-oil-card-rename.sql` | 菜单名、字典 label、工作流名 |
+| `backend/tests/test_vehicle_recharge_types.py` | 断言 `RECHARGE_TYPE_LABELS["fuel"] == "油卡"` |
+| `backend/app/api/pl/vehicle_recharge.py` | `RECHARGE_TYPE_LABELS`、模块 docstring / tags |
+| `backend/app/api/pl/vehicle_recharge_approval.py` | OpenAPI tags |
+| `backend/app/services/pl_vehicle_recharge_service.py` | 用户可见 detail 中的菜单名 |
+| `backend/app/services/bx/workflow.py` | 默认 `wf_name` |
+| `backend/tests/test_pl_menu_badge_recharge.py` | docstring 称谓 |
+| `backend/tests/test_pl_menu_badge_recharge_approval.py` | docstring 称谓 |
+| `web-admin/src/router/modules/pl.ts` | 路由 meta.title |
+| `web-admin/src/utils/pl-display.ts` | `getPlRechargeTypeLabel` |
+| `web-admin/src/views/pl/vehicle-recharge-apply/columnFilterDefs.ts` | 筛选枚举 label |
+| `web-admin/src/views/pl/vehicle-recharge-apply/index.vue` | 注释、下拉 label |
+| `web-admin/src/views/pl/vehicle-recharge-record/index.vue` | 注释、下拉、ElMessage |
+| `web-admin/src/views/pl/vehicle-recharge-workflow/index.vue` | 文件头注释 |
+| `miniprogram/config/workbench-menus.js` | 工作台入口名 |
+| `miniprogram/pages.json` | navigationBarTitleText |
+| `miniprogram/pages/pl/vehicle-recharge-apply/list.vue` | 标题 + 类型映射 |
+| `miniprogram/pages/pl/vehicle-recharge-apply/form.vue` | 类型选项 |
+| `miniprogram/utils/plVehicleRechargeCopy.js` | 微信复制文案 |
+
+**明确不改：** `vehicle-fuel-register/**`、「加油站/渠道」、API path / perms / `dict_value=fuel`。
+
+---
+
+### Task 1: 后端单测 — fuel 展示为「油卡」
+
+**Files:**
+- Modify: `backend/tests/test_vehicle_recharge_types.py`
+
+- [ ] **Step 1: 更新模块 docstring，并追加 label 断言**
+
+将文件顶部 docstring 改为：
+
+```python
+"""车辆充值类型：ETC + 油卡（存值 fuel）。"""
+```
+
+在文件末尾追加：
+
+```python
+def test_recharge_type_labels_fuel_displays_as_oil_card():
+    from app.api.pl.vehicle_recharge import RECHARGE_TYPE_LABELS
+
+    assert RECHARGE_TYPE_LABELS["etc"] == "ETC"
+    assert RECHARGE_TYPE_LABELS["fuel"] == "油卡"
+```
+
+- [ ] **Step 2: 跑测试确认当前失败**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_vehicle_recharge_types.py::test_recharge_type_labels_fuel_displays_as_oil_card -v
+```
+
+Expected: FAIL（当前 `"fuel": "加油"`，断言期望「油卡」）
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add backend/tests/test_vehicle_recharge_types.py
+git commit -m "test: expect recharge type fuel label to display as 油卡."
+```
+
+---
+
+### Task 2: 后端 label 与用户可见文案
+
+**Files:**
+- Modify: `backend/app/api/pl/vehicle_recharge.py`
+- Modify: `backend/app/api/pl/vehicle_recharge_approval.py`
+- Modify: `backend/app/services/pl_vehicle_recharge_service.py`
+- Modify: `backend/app/services/bx/workflow.py`
+- Modify: `backend/tests/test_pl_menu_badge_recharge.py`
+- Modify: `backend/tests/test_pl_menu_badge_recharge_approval.py`
+
+- [ ] **Step 1: 改 `RECHARGE_TYPE_LABELS`**
+
+在 `backend/app/api/pl/vehicle_recharge.py`：
+
+```python
+RECHARGE_TYPE_LABELS = {"etc": "ETC", "fuel": "油卡"}
+```
+
+同步该文件模块 docstring：`"""车辆 ETC/油卡充值 API"""`。  
+若文件内 OpenAPI `tags=[...]` 含「加油」，改为「油卡」（如 `运输计划-ETC油卡充值`）。
+
+- [ ] **Step 2: 审批路由 tags**
+
+在 `backend/app/api/pl/vehicle_recharge_approval.py` 将 tags 中「ETC加油充值」改为「ETC油卡充值」，例如：
+
+```python
+prefix="/vehicle-recharge-approval", tags=["运输计划-ETC油卡充值审批"]
+```
+
+- [ ] **Step 3: 服务层用户可见提示**
+
+在 `backend/app/services/pl_vehicle_recharge_service.py` 将：
+
+```python
+detail="审批中的申请请在「ETC/加油充值审批」中完成发放登记",
+```
+
+改为：
+
+```python
+detail="审批中的申请请在「ETC/油卡充值审批」中完成发放登记",
+```
+
+模块顶部 docstring 可改为 `"""车辆 ETC/油卡充值业务逻辑"""`（可选）。
+
+- [ ] **Step 4: 工作流默认名**
+
+在 `backend/app/services/bx/workflow.py`：
+
+```python
+"vehicle_recharge": {
+    "wf_name": "ETC/油卡充值审批流程",
+    "remark": "充值申请默认审批流程",
+},
+```
+
+- [ ] **Step 5: 角标单测 docstring**
+
+- `test_pl_menu_badge_recharge.py`：`ETC/加油充值发放管理` → `ETC/油卡充值发放管理`；`ETC + 加油` → `ETC + 油卡`
+- `test_pl_menu_badge_recharge_approval.py`：`ETC/加油充值审批` → `ETC/油卡充值审批`
+
+- [ ] **Step 6: 跑测试确认通过**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_vehicle_recharge_types.py tests/test_pl_menu_badge_recharge.py tests/test_pl_menu_badge_recharge_approval.py -v
+```
+
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add backend/app/api/pl/vehicle_recharge.py \
+  backend/app/api/pl/vehicle_recharge_approval.py \
+  backend/app/services/pl_vehicle_recharge_service.py \
+  backend/app/services/bx/workflow.py \
+  backend/tests/test_pl_menu_badge_recharge.py \
+  backend/tests/test_pl_menu_badge_recharge_approval.py
+git commit -m "fix(pl): show recharge type fuel as 油卡 in API labels."
+```
+
+---
+
+### Task 3: 迁移 SQL（菜单 + 字典 + 工作流名）
+
+**Files:**
+- Create: `docs/sql/migrations/2026-10-16-pl-vehicle-recharge-oil-card-rename.sql`
+
+- [ ] **Step 1: 写入迁移文件**
+
+```sql
+-- ETC/加油充值 → ETC/油卡充值（仅展示名；recharge_type 存值 fuel 不变）
+SET NAMES utf8mb4;
+
+-- 1) Web 菜单
+UPDATE `sys_menu`
+SET `menu_name` = 'ETC/油卡充值管理',
+    `remark` = 'ETC/油卡充值分组',
+    `update_time` = NOW()
+WHERE `id` = 'PL_GROUP_VEH_RECHARGE' AND `del_flag` = 0;
+
+UPDATE `sys_menu`
+SET `menu_name` = 'ETC/油卡充值申请', `update_time` = NOW()
+WHERE `id` = 'PL_VEH_RECHARGE_APPLY' AND `del_flag` = 0;
+
+UPDATE `sys_menu`
+SET `menu_name` = 'ETC/油卡充值审批', `update_time` = NOW()
+WHERE `id` = 'PL_VEH_RECHARGE_APPROVAL' AND `del_flag` = 0;
+
+UPDATE `sys_menu`
+SET `menu_name` = 'ETC/油卡充值发放管理', `update_time` = NOW()
+WHERE `id` = 'PL_VEH_RECHARGE_RECORD' AND `del_flag` = 0;
+
+UPDATE `sys_menu`
+SET `menu_name` = 'ETC/油卡充值审批人设置', `update_time` = NOW()
+WHERE `id` = 'PL_VEH_RECHARGE_WF' AND `del_flag` = 0;
+
+-- 2) 字典：fuel 展示为油卡
+UPDATE `sys_dict_data`
+SET `dict_label` = '油卡', `update_time` = NOW()
+WHERE `id` = 'PL_RECHARGE_TYPE_FUEL'
+  AND `dict_type` = 'pl_recharge_type'
+  AND `dict_value` = 'fuel'
+  AND `del_flag` = 0;
+
+-- 3) 已存在的充值审批流程显示名（ensure_by_biz_type 不会回写已有行）
+UPDATE `bx_workflow_def`
+SET `wf_name` = 'ETC/油卡充值审批流程', `update_time` = NOW()
+WHERE `biz_type` = 'vehicle_recharge'
+  AND `del_flag` = 0
+  AND `wf_name` LIKE '%加油%';
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/sql/migrations/2026-10-16-pl-vehicle-recharge-oil-card-rename.sql
+git commit -m "docs(sql): rename ETC/加油充值 menus and dict label to 油卡."
+```
+
+---
+
+### Task 4: web-admin 路由与展示映射
+
+**Files:**
+- Modify: `web-admin/src/router/modules/pl.ts`
+- Modify: `web-admin/src/utils/pl-display.ts`
+- Modify: `web-admin/src/views/pl/vehicle-recharge-apply/columnFilterDefs.ts`
+
+- [ ] **Step 1: 路由 meta.title**
+
+在 `web-admin/src/router/modules/pl.ts`，将所有 `ETC/加油` 替换为 `ETC/油卡`（管理 / 申请 / 审批 / 发放管理 / 审批人设置，含 `isHide` 隐藏路由）。
+
+可用定点替换确认无残留：
+
+```bash
+rg "ETC/加油" web-admin/src/router/modules/pl.ts
+```
+
+Expected: 无匹配
+
+- [ ] **Step 2: `getPlRechargeTypeLabel`**
+
+在 `web-admin/src/utils/pl-display.ts`：
+
+```typescript
+export function getPlRechargeTypeLabel(type: string) {
+  return type === 'etc' ? 'ETC' : type === 'fuel' ? '油卡' : type
+}
+
+export function getPlRechargeTypeTagType(type: string) {
+  // primary/success 同为翠绿，油卡用 warning（琥珀）区分
+  return type === 'etc' ? 'primary' : type === 'fuel' ? 'warning' : 'info'
+}
+```
+
+- [ ] **Step 3: 列头筛选枚举**
+
+在 `web-admin/src/views/pl/vehicle-recharge-apply/columnFilterDefs.ts`：
+
+```typescript
+const RECHARGE_TYPE_OPTIONS = [
+  { value: 'etc', label: 'ETC' },
+  { value: 'fuel', label: '油卡' }
+]
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web-admin/src/router/modules/pl.ts \
+  web-admin/src/utils/pl-display.ts \
+  web-admin/src/views/pl/vehicle-recharge-apply/columnFilterDefs.ts
+git commit -m "fix(web-admin): rename ETC/加油充值 UI labels to 油卡."
+```
+
+---
+
+### Task 5: web-admin 充值页面表单与提示
+
+**Files:**
+- Modify: `web-admin/src/views/pl/vehicle-recharge-apply/index.vue`
+- Modify: `web-admin/src/views/pl/vehicle-recharge-record/index.vue`
+- Modify: `web-admin/src/views/pl/vehicle-recharge-workflow/index.vue`
+
+- [ ] **Step 1: 申请页**
+
+- 文件头注释：`<!-- ETC/油卡充值申请 -->`
+- 表单：`<el-option label="油卡" value="fuel" />`
+- **不要**改「加油站/渠道」
+
+- [ ] **Step 2: 发放管理页**
+
+- 文件头注释：`<!-- ETC/油卡充值发放管理 -->`
+- `<el-option label="油卡" value="fuel" />`
+- `ElMessage.warning('审批中的申请请到「ETC/油卡充值审批」菜单完成发放登记')`
+- **不要**改「加油站/渠道」
+
+- [ ] **Step 3: 审批人设置页注释**
+
+`<!-- 工作流配置（ETC/油卡充值） -->`
+
+- [ ] **Step 4: 扫残留（仅 vehicle-recharge*，勿扫 fuel-register）**
+
+```bash
+rg "ETC/加油|label=\"加油\"|label: '加油'" web-admin/src/views/pl/vehicle-recharge-* web-admin/src/router/modules/pl.ts web-admin/src/utils/pl-display.ts
+```
+
+Expected: 无匹配（「加油站/渠道」允许保留）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web-admin/src/views/pl/vehicle-recharge-apply/index.vue \
+  web-admin/src/views/pl/vehicle-recharge-record/index.vue \
+  web-admin/src/views/pl/vehicle-recharge-workflow/index.vue
+git commit -m "fix(web-admin): update vehicle recharge form labels to 油卡."
+```
+
+---
+
+### Task 6: miniprogram 申请入口与文案
+
+**Files:**
+- Modify: `miniprogram/config/workbench-menus.js`
+- Modify: `miniprogram/pages.json`
+- Modify: `miniprogram/pages/pl/vehicle-recharge-apply/list.vue`
+- Modify: `miniprogram/pages/pl/vehicle-recharge-apply/form.vue`
+- Modify: `miniprogram/utils/plVehicleRechargeCopy.js`
+
+- [ ] **Step 1: 工作台菜单**
+
+在 `miniprogram/config/workbench-menus.js`：
+
+```javascript
+name: 'ETC/油卡充值申请',
+```
+
+`desc` 字段若含「ETC充值申请」，改为「ETC/油卡充值申请」（「加油登记」保留不动）。
+
+- [ ] **Step 2: pages.json**
+
+两处 `navigationBarTitleText`：
+
+```json
+"navigationBarTitleText": "ETC/油卡充值申请"
+```
+
+（`fuel-register` 的「加油登记」不要动）
+
+- [ ] **Step 3: list.vue**
+
+- `topbar-title`：`ETC/油卡充值申请`
+- 类型映射：`if (v === 'fuel') return '油卡'`
+
+- [ ] **Step 4: form.vue**
+
+```javascript
+{ label: '油卡', value: 'fuel' }
+```
+
+- [ ] **Step 5: 微信复制**
+
+在 `miniprogram/utils/plVehicleRechargeCopy.js`：
+
+```javascript
+fuel: '油卡'
+```
+
+```javascript
+`【${plate} - ETC/油卡充值申请】`,
+```
+
+文件头注释同步为油卡。
+
+- [ ] **Step 6: 扫残留**
+
+```bash
+rg "ETC/加油|fuel: '加油'|return '加油'" miniprogram/pages/pl/vehicle-recharge-apply miniprogram/utils/plVehicleRechargeCopy.js miniprogram/config/workbench-menus.js miniprogram/pages.json
+```
+
+Expected: 无匹配
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add miniprogram/config/workbench-menus.js \
+  miniprogram/pages.json \
+  miniprogram/pages/pl/vehicle-recharge-apply/list.vue \
+  miniprogram/pages/pl/vehicle-recharge-apply/form.vue \
+  miniprogram/utils/plVehicleRechargeCopy.js
+git commit -m "fix(miniprogram): rename ETC/加油充值申请 to 油卡."
+```
+
+---
+
+### Task 7: 回归与手工验收
+
+- [ ] **Step 1: 后端回归**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_vehicle_recharge_types.py tests/test_pl_menu_badge_recharge.py tests/test_pl_menu_badge_recharge_approval.py tests/test_pl_vehicle_ops_list_filters.py -v
+```
+
+Expected: PASS（筛选仍用 `fuel` 存值）
+
+- [ ] **Step 2: 确认未误伤加油登记**
+
+```bash
+rg "加油登记|加油信息汇总|加油站/渠道" web-admin/src/views/pl/vehicle-fuel-register miniprogram/pages/pl/fuel-register | head
+```
+
+Expected: 仍存在原「加油登记」文案（说明未被全局替换误伤）
+
+- [ ] **Step 3: 手工清单（部署迁移 SQL 后）**
+
+1. Web 侧栏：ETC/油卡充值管理及四个子菜单均为「油卡」
+2. 申请/发放表单类型下拉：ETC、油卡；选油卡后 Tag 显示「油卡」
+3. 导出 Excel 充值类型列：`油卡`
+4. 小程序工作台与申请页标题：ETC/油卡充值申请
+5. 复制微信：标题与类型为油卡
+6. 加油登记菜单与「加油站/渠道」字段未变
+
+- [ ] **Step 4: 更新图谱（若本会话改了代码）**
+
+```bash
+./scripts/update-graph.sh backend
+# 若改了 web-admin：
+./scripts/update-graph.sh frontend
+```
+
+- [ ] **Step 5: 最终确认无未提交改动属于本需求后收尾**
+
+无需额外 commit，除非图谱文件有变更需单独提交。
+
+---
+
+## Spec coverage check
+
+| Spec 项 | Task |
+|---------|------|
+| D1 全部菜单统一油卡 | Task 3 + 4 + 6 |
+| D2/D3 fuel 存值不变、展示油卡 | Task 1–2、4–6 |
+| D4 ETC/加油… 文案全改 | Task 2–6 |
+| D5 加油站/渠道不动 | Task 5/6 明确不改 + Task 7 验收 |
+| D6 加油登记不动 | Task 7 验收 |
+| D7 path/perms/dict_value 不变 | 全程不改这些标识 |
+| 工作流名 | Task 2 Step 4 + Task 3 SQL |
+| 验收标准 §5 | Task 7 |
+
+## Placeholder / consistency self-check
+
+- 无 TBD/TODO；替换目标文案写死为「油卡」
+- 存值一律仍为 `fuel`
+- 迁移文件名与 spec 日期一致：`2026-10-16-…`

docs/superpowers/specs/2026-10-16-pl-vehicle-recharge-oil-card-rename-design.md

@@ -1,7 +1,8 @@
 # ETC/加油充值 → ETC/油卡充值（文案改名）— 设计文档
 
 > **日期**: 2026-10-16  
-> **状态**: 待用户审阅（self-review 已过）  
+> **状态**: 已批准  
+> **实现计划**: `docs/superpowers/plans/2026-10-16-pl-vehicle-recharge-oil-card-rename.md`  
 > **方案**: 展示层文案替换（存值 `fuel` 不变）  
 > **范围**: web-admin 车辆管理 · ETC 充值分组；miniprogram · ETC 充值申请；配套字典 / 导出 / 微信文案 / 提示语  
 > **前置**: `2026-09-26-pl-vehicle-recharge-restore-fuel-design.md`（曾恢复类型「加油」；本次仅改展示名称为「油卡」）