0 Fork 0

Files

T

wuzilongandCursor 279e405149 docs: add mini-program bx migration design from bx-mobile.

Document batched C-scope migration with mini:bx:* perms, vant-weapp styling, and API reuse.

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

2026-09-11 23:08:06 +08:00

6.6 KiB

Raw Blame History

小程序报销管理：从 bx-mobile 分批迁移

日期：2026-09-11
状态：待审阅
对齐：docs/superpowers/specs/2026-09-11-mini-db-menu-permission-design.md（移动端菜单权限模式）
源：bx-mobile（Vue3 + Vant 4 H5）→ miniprogram（uni-app）

1. 背景与目标

将 bx-mobile 首页未隐藏的 9 个业务入口迁入 miniprogram 工作台「报销管理」模块；菜单权限与 Web bx:* 分离（mini:bx:*）；接口复用现有门户报销 API；视觉尽可能对齐 bx-mobile。

目标

整包 9 项业务最终全部迁完（选项 C），分多批交付。
移动端权限码独立：mini:bx:*，不复用 Web bx:*。
测试 + 生产数据库 shanxia2.0 均插入移动端菜单并仅授权超级管理员。
前端样式：采用 @vant/weapp（S1），Token/壳层对齐 bx-mobile；允许小程序与 H5 的合理差异。
API：复用 /api/advances、/api/reimburses、/api/expense-items、/api/workflows、发票夹等既有路径（与 bx-mobile / web-admin 同源）。

非目标

本期不迁 bx-mobile 中 hidden: true 的入口（备用金审批/发放、报销审批、支付发放冲抵、待我审批）。
不把 Vant 4 H5 组件原样搬进小程序。
Batch 1 不实现完整业务表单/列表逻辑（仅菜单 + 占位壳）。

2. 已确认产品决策

#	决策
D1	范围：C 九项整包，分批迁移
D2	分批节奏：方案 1（先菜单权限，再申请→视图→发票→配置）
D3	权限码：*独立 `mini:bx:`*，与 Web `bx:` 区分
D4	默认授权：仅超级管理员（`role_name='超级管理员'`）
D5	双库执行：测试（`.env`）+ 生产（`.env.production`），库名 `shanxia2.0`
D6	样式：S1 `@vant/weapp`，保障与 bx-mobile 观感接近（非像素级）
D7	API：直接复用现有后端报销接口，不新造业务 API
D8	工作台过滤：复用已有 `GET /web/auth/menu-codes` + `filterWorkbenchModules`

3. 迁移清单（首页未隐藏）

顺序（方案 1）	菜单	Web perms（对照，勿复用）	移动端 perms	工作台 code
—	报销管理（目录）	—	（空）	模块 `bx`
B2	备用金申请	`bx:advanceApply:list`	`mini:bx:advanceApply:list`	`bx-advance-apply`
B3	报销申请	`bx:reimburseApply:list`	`mini:bx:reimburseApply:list`	`bx-reimburse-apply`
B4	我的申请单	`bx:viewMine:list`	`mini:bx:viewMine:list`	`bx-mine`
B4	全部申请单	`bx:viewAll:list`	`mini:bx:viewAll:list`	`bx-all`
B5	我的发票夹	`bx:invoiceWallet:mine`	`mini:bx:invoiceWallet:mine`	`bx-invoice-mine`
B5	发票夹管理	`bx:invoiceWallet:admin`	`mini:bx:invoiceWallet:admin`	`bx-invoice-admin`
B6	费用项目	`bx:expenseItem:list`	`mini:bx:expenseItem:list`	`bx-expense-item`
B6	工作流（备用金）	`bx:workflowAdvance:list`	`mini:bx:workflowAdvance:list`	`bx-wf-advance`
B6	工作流（报销）	`bx:workflowReimburse:list`	`mini:bx:workflowReimburse:list`	`bx-wf-reimburse`

父节点：sys_menu.id = '1'（移动端）。稳定 id 前缀：MINI_BX_*。

4. 分批定义

Batch 1 — 菜单权限 + 工作台入口 + 占位壳（本迭代设计重点）

幂等 SQL：docs/sql/migrations/2026-09-11-mini-bx-menus.sql
测产双库执行；超管 sys_role_menu 含父 + 9 叶子
workbench-menus.js：报销模块 visible: true；替换为上述 9 入口 + perms；去掉本期不迁的隐藏项占位（或保留 enabled:false 且无 perms，不展示）
pages.json + 9 个占位页：@vant/weapp 基础布局 + 标题说明「业务迁入中」
路由映射写入 WORKBENCH_ROUTE_MAP
无业务 API 调用要求

Batch 2 — 备用金申请

列表 / 申请 / 详情主流程；API：/advances/*
样式对齐 bx-mobile 对应页

Batch 3 — 报销申请

列表 / 申请 / 详情主流程；API：/reimburses/*；附件/发票关联按 bx-mobile 行为复用

Batch 4 — 我的申请单 + 全部申请单

API：/advances/my、/reimburses/my 及 all 视图对应接口

Batch 5 — 发票夹（我的 + 管理）

API：发票夹相关路径（与 bx-mobile invoice 模块一致）

Batch 6 — 费用项目 + 工作流配置（备用金 / 报销）

API：/expense-items/*、/workflows/*

每批结束后：超管可见可走通；无权限用户工作台不显示对应入口。

5. 样式策略（S1）

组件：优先 @vant/weapp（仓库已依赖）。
Token：主色对齐 bx-mobile / 三墙绿（如 #0a9f6d / #10b981 以 bx-mobile 现网 CSS 变量为准），圆角与卡片阴影参考 bx-mobile/src/styles。
验收：并排对照 bx-mobile 同功能页，允许小程序控件高度/弹层差异；不允许主色、信息层级明显跑偏。
地磅 db-ui：不混用为报销主组件体系（避免两套视觉）；公共壳（工作台 Header）仍用现有 mp-shell。

6. API 策略

小程序请求基址仍为现有 BASE_URL（/api）。
业务路径与 bx-mobile bxClient 一致（注意集合根尾斜杠规则：advances/、reimburses/ 等）。
认证继续 /web/auth/*；菜单权限 /web/auth/menu-codes。
不为本迁移新增后端路由；若小程序上传需走既有附件接口，沿用 API_ENCRYPT_EXCLUDE_PATHS 中已排除路径。

7. Batch 1 验收

测产库「菜单管理」：移动端 → 报销管理 → 9 叶子，perms 均为 mini:bx:*。
仅超管默认勾选；其它角色手工勾。
超管工作台可见「报销管理」及 9 入口；无 mini:bx:* 用户不显示该块。
点击入口进入占位页，不报错。
SQL 可重复执行；脚本文件可供核对。

8. 风险

风险	缓解
`@vant/weapp` 与 Vant4 H5 视觉差	Batch 业务迁时对照清单；必要时局部覆写 CSS
占位页上线过早	文案标明「迁移中」；或仅超管环境验收
与地磅 UI 两套组件并存	工作台模块隔离；报销子树统一 vant-weapp

9. 实现入口（Batch 1 → writing-plans）

编写并双库执行 2026-09-11-mini-bx-menus.sql
更新 workbench-menus.js / api.js 路由 / pages.json
9 个占位页 + easycom/@vant/weapp 按需配置
手工验收 §7

6.6 KiB Raw Blame History Unescape Escape