cykj/shanxia2.0
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
5c2879914ba6d022b9082bdd66517f6b1bbad4b2
shanxia2.0/docs/superpowers/plans/2026-10-16-pl-vehicle-recharge-oil-card-rename.md
T
wuzilongandCursor 5c2879914b docs: add ETC/油卡充值文案改名实现计划。 
按展示层替换拆分迁移 SQL、后端 label、web-admin 与小程序任务。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:30:09 +08:00

15 KiB
Raw Blame History

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 改为：

"""车辆充值类型：ETC + 油卡（存值 fuel）。"""

在文件末尾追加：

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: 跑测试确认当前失败
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
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：

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油卡充值」，例如：

prefix="/vehicle-recharge-approval", tags=["运输计划-ETC油卡充值审批"]
  • Step 3: 服务层用户可见提示

在 backend/app/services/pl_vehicle_recharge_service.py 将：

detail="审批中的申请请在「ETC/加油充值审批」中完成发放登记",

改为：

detail="审批中的申请请在「ETC/油卡充值审批」中完成发放登记",

模块顶部 docstring 可改为 """车辆 ETC/油卡充值业务逻辑"""（可选）。

  • Step 4: 工作流默认名

在 backend/app/services/bx/workflow.py：

"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: 跑测试确认通过

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
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: 写入迁移文件

-- 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
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 隐藏路由）。

可用定点替换确认无残留：

rg "ETC/加油" web-admin/src/router/modules/pl.ts

Expected: 无匹配

  • Step 2: getPlRechargeTypeLabel

在 web-admin/src/utils/pl-display.ts：

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：

const RECHARGE_TYPE_OPTIONS = [
  { value: 'etc', label: 'ETC' },
  { value: 'fuel', label: '油卡' }
]
  • Step 4: Commit
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）*
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
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：

name: 'ETC/油卡充值申请',

desc 字段若含「ETC充值申请」，改为「ETC/油卡充值申请」（「加油登记」保留不动）。

  • Step 2: pages.json

两处 navigationBarTitleText：

"navigationBarTitleText": "ETC/油卡充值申请"

（fuel-register 的「加油登记」不要动）

  • Step 3: list.vue

  • topbar-title：ETC/油卡充值申请

  • 类型映射：if (v === 'fuel') return '油卡'

  • Step 4: form.vue

{ label: '油卡', value: 'fuel' }
  • Step 5: 微信复制

在 miniprogram/utils/plVehicleRechargeCopy.js：

fuel: '油卡'

`【${plate} - ETC/油卡充值申请】`,

文件头注释同步为油卡。

  • Step 6: 扫残留
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
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: 后端回归
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: 确认未误伤加油登记
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: 更新图谱（若本会话改了代码）
./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-…
Reference in new issue View Git Blame Copy Permalink