diff --git a/docs/superpowers/plans/2026-10-16-pl-vehicle-recharge-oil-card-rename.md b/docs/superpowers/plans/2026-10-16-pl-vehicle-recharge-oil-card-rename.md new file mode 100644 index 000000000..eb2be1974 --- /dev/null +++ b/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: 申请页** + +- 文件头注释：`` +- 表单：`` +- **不要**改「加油站/渠道」 + +- [ ] **Step 2: 发放管理页** + +- 文件头注释：`` +- `` +- `ElMessage.warning('审批中的申请请到「ETC/油卡充值审批」菜单完成发放登记')` +- **不要**改「加油站/渠道」 + +- [ ] **Step 3: 审批人设置页注释** + +`` + +- [ ] **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-…` diff --git a/docs/superpowers/specs/2026-10-16-pl-vehicle-recharge-oil-card-rename-design.md b/docs/superpowers/specs/2026-10-16-pl-vehicle-recharge-oil-card-rename-design.md index 04afeaa6c..0ea04c3b1 100644 --- a/docs/superpowers/specs/2026-10-16-pl-vehicle-recharge-oil-card-rename-design.md +++ b/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`（曾恢复类型「加油」；本次仅改展示名称为「油卡」）