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

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

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-10-16 11:30:09 +08:00
1 parent 19812a1da7
commit 5c2879914b
2 files changed
+459 -1

No files matched your search

@@ -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-…`
@@ -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`(曾恢复类型「加油」;本次仅改展示名称为「油卡」)