33 KiB
bx-mobile 适配 shanxia2.0 — 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: 将 bx-mobile(Vant H5)对接 shanxia2.0 门户鉴权与 bx 业务 API,在保持现有交互/UI 的前提下,使约定范围内功能与 web-admin 报销管理业务结果一致。
Architecture: 适配层渐进改造——重写 portal/bx 双 HTTP 客户端与 auth store;用 Web「报销管理」menuCode 静态目录过滤首页入口;业务页改 UUID 与新字段;分 P1(鉴权+核心单据)→ P2(发票夹)→ P3(撤回/代申请/标题/审批历史/配置)上线。后端不新增移动专用业务服务。
Tech Stack: Vue 3 + Vant 4 + Pinia + Vue Router + Axios + TypeScript;门户 RSA 登录(jsencrypt);共用 FastAPI backend;可选 vitest 测纯函数。
Spec: docs/superpowers/specs/2026-08-09-bx-mobile-shanxia2-adapt-design.md
文件结构
| 操作 | 文件 | 职责 |
|---|---|---|
| Create | bx-mobile/.env.development |
代理与环境变量(backend :8000) |
| Create | bx-mobile/src/utils/loginRsa.ts |
拉取公钥并加密登录体 |
| Create | bx-mobile/src/api/portalClient.ts |
门户 HTTP(code===200) |
| Create | bx-mobile/src/api/bxClient.ts |
bx 业务 HTTP(code===0) |
| Create | bx-mobile/src/api/portalAuth.ts |
login / current-user / menu-codes / refresh / logout |
| Create | bx-mobile/src/constants/bxMenuCatalog.ts |
menuCode → H5 路由 / 阶段 / 图标 |
| Create | bx-mobile/src/utils/bxPermission.ts |
can(menuCode) |
| Modify | bx-mobile/vite.config.ts |
proxy → localhost:8000 |
| Modify | bx-mobile/package.json |
加 jsencrypt(及可选 vitest) |
| Modify | bx-mobile/src/stores/auth.ts |
门户会话,去掉旧角色码 |
| Modify | bx-mobile/src/api/index.ts |
业务 API 改走 bxClient;删 user/role/menu;补 invoice |
| Modify | bx-mobile/src/api/client.ts |
废弃或 re-export bxClient(避免双轨) |
| Modify | bx-mobile/src/router/index.ts |
meta.menuCodes;删 admin users/roles/menus |
| Modify | bx-mobile/src/views/login/LoginPage.vue |
走门户登录 |
| Modify | bx-mobile/src/views/home/HomePage.vue |
用 catalog + menuCodes 渲染入口 |
| Modify | bx-mobile/src/hooks/useAttachment.ts 等 |
bizId 改为 string |
| Modify | 各业务页 advance/* reimburse/* payment/* approval/* mine/* all/* |
UUID、字段对齐 |
| Create | bx-mobile/src/views/invoice/InvoiceWalletMinePage.vue |
P2 我的发票夹 |
| Create | bx-mobile/src/views/invoice/InvoiceWalletAdminPage.vue |
P2 发票夹管理 |
| Modify | bx-mobile/src/views/reimburse/ReimburseApplyPage.vue |
P2 选票;P3 代申请/日期/标题 |
| Modify | bx-mobile/src/views/admin/ExpenseProjectPage.vue 等 |
P3 配置 API/权限 |
| Modify | docs/business-inventory/03-报销业务明细.md |
去掉「bx-mobile 未迁入」 |
后端: 本期默认不改(发票夹与 withdraw 等已在 PC 落地)。若联调发现缺口,另开任务补 API,不在本计划默认范围内。
阶段与任务索引
| 阶段 | Tasks | 验收焦点 |
|---|---|---|
| P1 | 1–8 | 登录、菜单入口、备用金/报销/审批/支付/视图可跑 |
| P2 | 9–12 | 发票夹 + 报销选票余额闭环 |
| P3 | 13–16 | 撤回/代申请/标题/审批历史/配置页 |
P1 — 鉴权 + 核心单据
Task 1: 环境代理与依赖
Files:
-
Create:
bx-mobile/.env.development -
Modify:
bx-mobile/vite.config.ts -
Modify:
bx-mobile/package.json -
Step 1: 添加环境文件
VITE_API_URL=/api
VITE_API_PROXY_URL=http://localhost:8000
- Step 2: 改 vite 代理
将 bx-mobile/vite.config.ts 中 proxy['/api'].target 改为:
target: process.env.VITE_API_PROXY_URL || 'http://localhost:8000',
- Step 3: 安装 jsencrypt
cd bx-mobile && npm install jsencrypt
Expected: package.json dependencies 含 jsencrypt。
- Step 4: Commit
git add bx-mobile/.env.development bx-mobile/vite.config.ts bx-mobile/package.json bx-mobile/package-lock.json
git commit -m "$(cat <<'EOF'
chore(bx-mobile): point API proxy to shanxia2.0 backend and add jsencrypt
EOF
)"
Task 2: 菜单目录与权限纯函数
Files:
-
Create:
bx-mobile/src/constants/bxMenuCatalog.ts -
Create:
bx-mobile/src/utils/bxPermission.ts -
Create:
bx-mobile/src/utils/bxPermission.spec.ts(可选;若未装 vitest 则跳过测试步骤,改为人工核对表) -
Step 1: 写入菜单目录(与 web-admin
sqxp.tsmenuCode 对齐)
// bx-mobile/src/constants/bxMenuCatalog.ts
export type BxMenuPhase = 1 | 2 | 3
export type BxMenuEntry = {
menuCode: string
title: string
path: string
phase: BxMenuPhase
group: string
icon: string
color: string
}
/** 仅叶子业务入口;用户/角色/菜单管理不收录 */
export const BX_MENU_CATALOG: BxMenuEntry[] = [
{ menuCode: 'bx:advanceApply:list', title: '备用金申请', path: '/advance/list', phase: 1, group: '备用金', icon: 'gold-coin-o', color: '#10b981' },
{ menuCode: 'bx:advanceApprove:list', title: '备用金审批', path: '/advance/approve', phase: 1, group: '备用金', icon: 'passed', color: '#059669' },
{ menuCode: 'bx:advanceIssue:list', title: '备用金发放', path: '/advance/issue', phase: 1, group: '备用金', icon: 'balance-o', color: '#0d9488' },
{ menuCode: 'bx:reimburseApply:list', title: '报销申请', path: '/reimburse/list', phase: 1, group: '报销', icon: 'bill-o', color: '#2563eb' },
{ menuCode: 'bx:reimburseApprove:list', title: '报销审批', path: '/reimburse/approve', phase: 1, group: '报销', icon: 'checked', color: '#1d4ed8' },
{ menuCode: 'bx:payment:list', title: '支付发放冲抵', path: '/payment', phase: 1, group: '报销', icon: 'paid', color: '#7c3aed' },
{ menuCode: 'bx:viewMine:list', title: '我的申请单', path: '/mine', phase: 1, group: '视图', icon: 'user-o', color: '#64748b' },
{ menuCode: 'bx:viewTodo:list', title: '待我审批', path: '/approval', phase: 1, group: '视图', icon: 'todo-list-o', color: '#d97706' },
{ menuCode: 'bx:viewAll:list', title: '全部申请单', path: '/all', phase: 1, group: '视图', icon: 'orders-o', color: '#475569' },
{ menuCode: 'bx:invoiceWallet:mine', title: '我的发票夹', path: '/invoice/mine', phase: 2, group: '发票夹', icon: 'photo-o', color: '#0891b2' },
{ menuCode: 'bx:invoiceWallet:admin', title: '发票夹管理', path: '/invoice/admin', phase: 2, group: '发票夹', icon: 'cluster-o', color: '#0e7490' },
{ menuCode: 'bx:expenseItem:list', title: '费用项目', path: '/admin/expenses', phase: 3, group: '配置', icon: 'cluster-o', color: '#9333ea' },
{ menuCode: 'bx:workflowAdvance:list', title: '工作流(备用金)', path: '/admin/wf-advance', phase: 3, group: '配置', icon: 'setting-o', color: '#7e22ce' },
{ menuCode: 'bx:workflowReimburse:list', title: '工作流(报销)', path: '/admin/wf-reimburse', phase: 3, group: '配置', icon: 'setting-o', color: '#6b21a8' },
]
/** 当前已开放阶段:发版时改为 1 → 2 → 3 */
export const BX_MENU_CURRENT_PHASE: BxMenuPhase = 1
- Step 2: 写入权限工具
// bx-mobile/src/utils/bxPermission.ts
import { BX_MENU_CATALOG, BX_MENU_CURRENT_PHASE, type BxMenuEntry } from '@/constants/bxMenuCatalog'
export function canAccess(
menuCode: string,
opts: { isSuperAdmin: boolean; all: boolean; menuCodes: string[] },
): boolean {
if (opts.isSuperAdmin || opts.all) return true
return opts.menuCodes.includes(menuCode)
}
export function filterVisibleEntries(
opts: { isSuperAdmin: boolean; all: boolean; menuCodes: string[] },
phase: number = BX_MENU_CURRENT_PHASE,
): BxMenuEntry[] {
return BX_MENU_CATALOG.filter(
(e) => e.phase <= phase && canAccess(e.menuCode, opts),
)
}
export function entryByPath(path: string): BxMenuEntry | undefined {
return BX_MENU_CATALOG.find((e) => e.path === path)
}
- Step 3: 人工核对
对照 web-admin/src/router/modules/sqxp.ts 中 bx 叶子 meta.menuCode,确认上表无遗漏、无拼写错误。
- Step 4: Commit
git add bx-mobile/src/constants/bxMenuCatalog.ts bx-mobile/src/utils/bxPermission.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add Web bx menuCode catalog and permission helpers
EOF
)"
Task 3: portalClient + RSA 登录 API
Files:
-
Create:
bx-mobile/src/utils/loginRsa.ts -
Create:
bx-mobile/src/api/portalClient.ts -
Create:
bx-mobile/src/api/portalAuth.ts -
Step 1: portalClient(门户
code === 200)
// bx-mobile/src/api/portalClient.ts
import axios from 'axios'
import { showToast } from 'vant'
export class PortalError extends Error {
code?: number
constructor(message: string, code?: number) {
super(message)
this.code = code
this.name = 'PortalError'
}
}
const portalClient = axios.create({
baseURL: import.meta.env.VITE_API_URL || '/api',
timeout: 60000,
headers: { 'Content-Type': 'application/json' },
})
portalClient.interceptors.request.use((config) => {
const token = localStorage.getItem('accessToken')
if (token) config.headers.Authorization = `Bearer ${token}`
return config
})
portalClient.interceptors.response.use(
(res) => {
const body = res.data
if (body && typeof body.code === 'number' && body.code !== 200) {
const msg = body.message || body.msg || '请求失败'
showToast(msg)
return Promise.reject(new PortalError(msg, body.code))
}
return body
},
(err) => {
const msg = err.response?.data?.message || err.response?.data?.msg || err.message || '网络异常'
if (err.response?.status !== 401) showToast(msg)
return Promise.reject(err)
},
)
export default portalClient
- Step 2: loginRsa(对齐 web-admin)
// bx-mobile/src/utils/loginRsa.ts
import JSEncrypt from 'jsencrypt'
import portalClient from '@/api/portalClient'
export async function buildWebEncryptedLoginBody(username: string, password: string) {
const res: any = await portalClient.get('/web/auth/login-rsa-public-key')
const publicKeyPem = res?.data?.publicKeyPem
if (!publicKeyPem) throw new Error('无法获取登录公钥')
const crypt = new JSEncrypt()
crypt.setPublicKey(publicKeyPem)
const encryptedLogin = crypt.encrypt(
JSON.stringify({ username, password, ts: Date.now() }),
)
if (!encryptedLogin) throw new Error('登录加密失败,请重试')
return { encryptedLogin }
}
- Step 3: portalAuth API
// bx-mobile/src/api/portalAuth.ts
import portalClient from './portalClient'
import { buildWebEncryptedLoginBody } from '@/utils/loginRsa'
export const portalAuthApi = {
login: async (username: string, password: string) => {
const body = await buildWebEncryptedLoginBody(username, password)
return portalClient.post('/web/auth/login', body)
},
currentUser: () => portalClient.get('/web/auth/current-user'),
menuCodes: () => portalClient.get('/web/auth/menu-codes'),
refreshToken: (refreshToken: string) =>
portalClient.post('/web/auth/refresh-token', { refreshToken }),
logout: () => portalClient.post('/web/auth/logout'),
}
- Step 4: 手工冒烟
# 后端已启动于 8000;bx-mobile npm run dev
# 浏览器 Network:GET login-rsa-public-key → 200;POST login → data.token 有值
- Step 5: Commit
git add bx-mobile/src/utils/loginRsa.ts bx-mobile/src/api/portalClient.ts bx-mobile/src/api/portalAuth.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add portal HTTP client and RSA login API
EOF
)"
Task 4: bxClient + 改造 api/index.ts(P1 所需)
Files:
-
Create:
bx-mobile/src/api/bxClient.ts -
Modify:
bx-mobile/src/api/index.ts -
Modify:
bx-mobile/src/api/client.ts(改为 re-exportBizError/bxClient,避免旧 import 断裂) -
Step 1: bxClient
// bx-mobile/src/api/bxClient.ts
import axios, { type InternalAxiosRequestConfig } from 'axios'
import { showToast } from 'vant'
import { portalAuthApi } from './portalAuth'
export class BizError extends Error {
code?: number
constructor(message: string, code?: number) {
super(message)
this.code = code
this.name = 'BizError'
}
}
const BX_COLLECTION_ROOT =
/^\/(reimburses|advances|payments|workflows|expense-items|invoices|invoice-wallets|invoice-ledgers)$/
function normalizeBxUrl(url?: string): string | undefined {
if (!url || url.endsWith('/')) return url
return BX_COLLECTION_ROOT.test(url) ? `${url}/` : url
}
const bxClient = axios.create({
baseURL: import.meta.env.VITE_API_URL || '/api',
timeout: 0,
headers: { 'Content-Type': 'application/json' },
})
let refreshing: Promise<boolean> | null = null
async function tryRefresh(): Promise<boolean> {
const rt = localStorage.getItem('refreshToken')
if (!rt) return false
try {
const res: any = await portalAuthApi.refreshToken(rt)
const token = res?.data?.token
const refreshToken = res?.data?.refreshToken
if (!token) return false
localStorage.setItem('accessToken', token)
if (refreshToken) localStorage.setItem('refreshToken', refreshToken)
return true
} catch {
return false
}
}
bxClient.interceptors.request.use((config: InternalAxiosRequestConfig) => {
if (config.url) config.url = normalizeBxUrl(config.url)
if (config.data instanceof FormData) {
delete (config.headers as any)['Content-Type']
}
const token = localStorage.getItem('accessToken')
if (token) config.headers.Authorization = `Bearer ${token}`
return config
})
bxClient.interceptors.response.use(
(res) => {
if (res.config.responseType === 'blob') return res.data
const body = res.data
if (body?.code !== undefined && body.code !== 0) {
showToast(body.msg || '请求失败')
return Promise.reject(new BizError(body.msg || '请求失败', body.code))
}
return body
},
async (err) => {
if (err.response?.status === 401) {
if (!refreshing) refreshing = tryRefresh().finally(() => { refreshing = null })
const ok = await refreshing
if (ok && err.config) {
err.config.headers.Authorization = `Bearer ${localStorage.getItem('accessToken')}`
return bxClient.request(err.config)
}
localStorage.removeItem('accessToken')
localStorage.removeItem('refreshToken')
showToast('登录已过期,请重新登录')
if (window.location.pathname !== '/login') window.location.href = '/login'
} else {
const msg = err.response?.data?.msg || err.response?.data?.detail || err.message || '网络异常'
showToast(msg)
}
return Promise.reject(err)
},
)
export default bxClient
-
Step 2: 改写
api/index.ts -
全部业务请求改用
bxClient(不再用旧client)。 -
删除
authApi(旧)、userApi、roleApi、menuApi。 -
attachmentApi的bizId/id类型改为string | number(统一按 string 传)。 -
advanceApi/reimburseApi/paymentApi/expenseItemApi/workflowApi路径保持与web-admin/src/api/bx/index.ts一致(含尾斜杠集合根)。 -
P1 暂不强制加
withdraw/ invoice(P2/P3 再补),但getById等 id 参数改为string | number。 -
Step 3:
client.ts兼容
// bx-mobile/src/api/client.ts
export { default, BizError } from './bxClient'
- Step 4: Commit
git add bx-mobile/src/api/bxClient.ts bx-mobile/src/api/client.ts bx-mobile/src/api/index.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add bxClient and retarget business APIs to shanxia2.0
EOF
)"
Task 5: 重写 auth store + LoginPage
Files:
-
Modify:
bx-mobile/src/stores/auth.ts -
Modify:
bx-mobile/src/views/login/LoginPage.vue -
Step 1: 重写 auth store 核心
替换为门户模型(示意,保持 Pinia setup 风格):
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { portalAuthApi } from '@/api/portalAuth'
import { filterVisibleEntries } from '@/utils/bxPermission'
import type { BxMenuEntry } from '@/constants/bxMenuCatalog'
export const useAuthStore = defineStore('auth', () => {
const accessToken = ref(localStorage.getItem('accessToken') || localStorage.getItem('token') || '')
const refreshToken = ref(localStorage.getItem('refreshToken') || '')
const user = ref<any>(null)
const menuCodes = ref<string[]>([])
const isSuperAdmin = ref(false)
const allMenus = ref(false)
const isLoggedIn = computed(() => !!accessToken.value)
const realName = computed(() => user.value?.realName || user.value?.username || '')
const visibleEntries = computed(() =>
filterVisibleEntries({
isSuperAdmin: isSuperAdmin.value,
all: allMenus.value,
menuCodes: menuCodes.value,
}),
)
function persistTokens(token: string, rt?: string) {
accessToken.value = token
localStorage.setItem('accessToken', token)
localStorage.removeItem('token')
if (rt) {
refreshToken.value = rt
localStorage.setItem('refreshToken', rt)
}
}
async function login(username: string, password: string) {
const res: any = await portalAuthApi.login(username, password)
persistTokens(res.data.token, res.data.refreshToken)
await fetchUser()
return true
}
async function fetchUser() {
const res: any = await portalAuthApi.currentUser()
user.value = res.data
const perm: any = await portalAuthApi.menuCodes()
isSuperAdmin.value = !!perm.data?.isSuperAdmin
allMenus.value = !!perm.data?.all
menuCodes.value = perm.data?.menuCodes || []
}
async function logout() {
try { await portalAuthApi.logout() } catch { /* ignore */ }
accessToken.value = ''
refreshToken.value = ''
user.value = null
menuCodes.value = []
isSuperAdmin.value = false
allMenus.value = false
localStorage.removeItem('accessToken')
localStorage.removeItem('refreshToken')
localStorage.removeItem('token')
}
function can(menuCode: string) {
if (isSuperAdmin.value || allMenus.value) return true
return menuCodes.value.includes(menuCode)
}
return {
accessToken, refreshToken, user, menuCodes, isSuperAdmin, allMenus,
isLoggedIn, realName, visibleEntries, login, fetchUser, logout, can,
}
})
删除所有 roleCodes / isAdmin / isFinance / isGeneralManager / menuList / fetchMenus 导出;全仓库 grep 旧符号并改掉。
- Step 2: LoginPage
auth.login 已对接门户;保留现有 UI。确保捕获 PortalError / BizError 不双 toast。
- Step 3: 联调登录
用门户有效账号登录 → 进入首页;错误密码看到后端文案。
- Step 4: Commit
git add bx-mobile/src/stores/auth.ts bx-mobile/src/views/login/LoginPage.vue
git commit -m "$(cat <<'EOF'
feat(bx-mobile): switch auth store and login to portal JWT
EOF
)"
Task 6: 路由守卫 + 删除用户/角色/菜单管理
Files:
-
Modify:
bx-mobile/src/router/index.ts -
Delete or stop importing:
UserManagePage/RoleManagePage/MenuManagePage(可留文件但移除路由) -
Step 1: 路由 meta 改为 menuCodes
示例:
{ path: 'advance/approve', name: 'AdvanceApprove', component: () => import('...'),
meta: { menuCodes: ['bx:advanceApprove:list'] } },
{ path: 'advance/issue', name: 'AdvanceIssue', component: () => import('...'),
meta: { menuCodes: ['bx:advanceIssue:list'] } },
{ path: 'payment', name: 'Payment', component: () => import('...'),
meta: { menuCodes: ['bx:payment:list'] } },
{ path: 'all', name: 'All', component: () => import('...'),
meta: { menuCodes: ['bx:viewAll:list'] } },
// 删除 admin/users、admin/roles、admin/menus
// P1 暂不注册 invoice/* 与 admin/expenses|wf(phase>1);或注册但守卫拒绝(推荐不注册)
- Step 2: beforeEach
router.beforeEach(async (to, _from, next) => {
const auth = useAuthStore()
if (to.meta?.public) return next()
if (!auth.isLoggedIn) return next('/login')
if (!auth.user) {
try { await auth.fetchUser() } catch { return next('/login') }
}
const codes = to.meta?.menuCodes as string[] | undefined
if (codes?.length && !codes.some((c) => auth.can(c))) {
showToast('无权限')
return next('/')
}
next()
})
- Step 3: Commit
git add bx-mobile/src/router/index.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): guard routes by portal menuCodes and drop bx admin IAM pages
EOF
)"
Task 7: 首页入口改为 catalog
Files:
-
Modify:
bx-mobile/src/views/home/HomePage.vue -
Step 1: 用
auth.visibleEntries分组渲染
去掉对 auth.menuList / fetchMenus / 旧 navigateTo(menuCode) 映射表的依赖;改为:
const groupsWithItems = computed(() => {
const map = new Map<string, BxMenuEntry[]>()
for (const e of auth.visibleEntries) {
const list = map.get(e.group) || []
list.push(e)
map.set(e.group, list)
}
return [...map.entries()].map(([menuName, items]) => ({ id: menuName, menuName, items }))
})
function navigateTo(path: string) {
router.push(path)
}
模板中 @click="navigateTo(item.path)",图标用 item.icon / item.color。
-
Step 2: TodoItem.id 改为 string(
id: string),因 UUID。 -
Step 3: 联调
不同角色账号:入口数量与 PC 侧栏报销菜单一致(仅 phase≤1)。
- Step 4: Commit
git add bx-mobile/src/views/home/HomePage.vue
git commit -m "$(cat <<'EOF'
feat(bx-mobile): render home entries from portal-filtered menu catalog
EOF
)"
Task 8: 业务页 UUID 与 P1 闭环联调
Files:
-
Modify:
bx-mobile/src/hooks/useAttachment.ts(bizId: string) -
Modify:
bx-mobile/src/views/advance/*.vue -
Modify:
bx-mobile/src/views/reimburse/*.vue(P1 仍可本地附件) -
Modify:
bx-mobile/src/views/payment/PaymentPage.vue -
Modify:
bx-mobile/src/views/approval/*.vue -
Modify:
bx-mobile/src/views/mine/*.vue -
Modify:
bx-mobile/src/views/all/AllPage.vue -
Modify: 任何
getById(Number(id))/route.params.id as unknown as number -
Step 1: 全库替换 id 类型
cd bx-mobile && rg -n "Number\(.*id|as number|: number.*Id|bizId: number" src
凡业务主键改为 String(id) / 参数类型 string。
- Step 2: 字段兼容
列表/详情读取时兼容后端 camelCase(与 PC 一致):applicantName、createTime、amount 等;若旧字段名仍有引用,加一层 row.xxx ?? row.oldXxx。
-
Step 3: P1 验收(对照设计 §4.2)
-
门户登录 / 刷新 / 登出
-
首页入口按权限
-
备用金申请→审批→发放
-
报销申请→审批→支付/冲抵(附件过渡可接受)
-
我的 / 待办 / 全部有数据
-
无用户/角色/菜单管理入口
-
Step 4: Commit
git add bx-mobile/src
git commit -m "$(cat <<'EOF'
fix(bx-mobile): align business pages with UUID ids for P1 portal API
EOF
)"
P2 — 发票夹完整闭环
Task 9: invoice / invoiceWallet API
Files:
-
Modify:
bx-mobile/src/api/index.ts -
Step 1: 追加 API(与 web-admin 对齐)
export type BxId = string | number
export const invoiceWalletApi = {
mineSummary: (params?: { userId?: BxId }) =>
bxClient.get('/invoice-wallets/mine/summary', { params }),
list: (params: { page: number; pageSize: number; keyword?: string }) =>
bxClient.get('/invoice-wallets', { params }),
}
export const invoiceApi = {
list: (params?: { page?: number; pageSize?: number; userId?: BxId }) =>
bxClient.get('/invoices', { params }),
upload: (formData: FormData) =>
bxClient.post('/invoices', formData),
delete: (id: BxId) => bxClient.delete(`/invoices/${id}`),
ledgers: (params?: { userId?: BxId }) =>
bxClient.get('/invoice-ledgers', { params }),
}
// reimburseApi.submit 改为:
submit: (id: BxId, data?: Record<string, any>) =>
bxClient.post(`/reimburses/${id}/submit`, data),
- Step 2: Commit
git add bx-mobile/src/api/index.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add invoice wallet APIs for P2
EOF
)"
Task 10: 我的发票夹 + 发票夹管理页面
Files:
-
Create:
bx-mobile/src/views/invoice/InvoiceWalletMinePage.vue -
Create:
bx-mobile/src/views/invoice/InvoiceWalletAdminPage.vue -
Modify:
bx-mobile/src/router/index.ts -
Modify:
bx-mobile/src/constants/bxMenuCatalog.ts— 将BX_MENU_CURRENT_PHASE改为2(或发版开关) -
Step 1: 我的发票夹页
Vant 结构:顶部三数字(总额/已用/余额)→「上传发票」→ Tab「发票列表 / 流水」。
上传:FormData 字段 files + amount + 可选 remark(与 PC invoiceApi.upload 一致)。
列表预览走附件 preview。交互参考现有附件网格,不复制 Element 布局。
- Step 2: 发票夹管理页
列表:员工额度汇总 → 点击进入某人详情(代传 targetUserId、删票、流水)。
路由 meta.menuCodes: ['bx:invoiceWallet:admin']。
- Step 3: 注册路由
{ path: 'invoice/mine', name: 'InvoiceWalletMine',
component: () => import('@/views/invoice/InvoiceWalletMinePage.vue'),
meta: { menuCodes: ['bx:invoiceWallet:mine'] } },
{ path: 'invoice/admin', name: 'InvoiceWalletAdmin',
component: () => import('@/views/invoice/InvoiceWalletAdminPage.vue'),
meta: { menuCodes: ['bx:invoiceWallet:admin'] } },
- Step 4: Commit
git add bx-mobile/src/views/invoice bx-mobile/src/router/index.ts bx-mobile/src/constants/bxMenuCatalog.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add mine and admin invoice wallet pages
EOF
)"
Task 11: 报销申请改为选票 + 余额
Files:
-
Modify:
bx-mobile/src/views/reimburse/ReimburseApplyPage.vue -
Modify:
bx-mobile/src/views/reimburse/ReimburseDetailPage.vue -
Modify:
bx-mobile/src/views/reimburse/ReimburseApprovePage.vue(及列表卡片若展示发票数) -
Step 1: 移除申请页本地发票上传
删除 useAttachment 对发票类 reimburse_apply 发票用途的上传 UI(若仍有「其他附件」需求,仅保留非发票附件;以 PC 为准——PC 申请单不再本地传发票,则 H5 同步移除)。
-
Step 2: 选票 UI
-
展示
invoiceWalletApi.mineSummary余额与本次合计对比。 -
多选本人发票:
invoiceApi.list。 -
保存/提交 body 含:
{
// ...existing fields
invoiceIds: string[],
invoiceLinks: { invoiceId: string; attachmentId?: string }[],
}
提交:reimburseApi.submit(id, { invoiceIds, invoiceLinks })。
- Step 3: 详情/审批展示关联发票
读详情 data.invoices(与 PC 字段一致),用现有附件预览组件展示。
-
Step 4: P2 验收
-
上传入账余额增加
-
余额不足不可提交
-
驳回后退回余额
-
管理端代传/删票(有权限)
-
Step 5: Commit
git add bx-mobile/src/views/reimburse
git commit -m "$(cat <<'EOF'
feat(bx-mobile): bind reimburse apply to invoice wallet balance rules
EOF
)"
Task 12: P1→P2 旧草稿说明(文档)
Files:
-
Modify:
docs/business-inventory/03-报销业务明细.md§9(bx-mobile 状态) -
可选:在申请页打开旧草稿时 toast 提示改走发票夹
-
Step 1: 更新业务清单「bx-mobile 未迁入」→「H5 适配进行中 / P2 已对齐发票夹」。
-
Step 2: Commit
git add docs/business-inventory/03-报销业务明细.md bx-mobile/src/views/reimburse/ReimburseApplyPage.vue
git commit -m "$(cat <<'EOF'
docs: note bx-mobile invoice-wallet adaptation progress
EOF
)"
P3 — 能力对齐收尾 + 配置页
Task 13: 撤回 + 审批历史
Files:
-
Modify:
bx-mobile/src/api/index.ts -
Modify:
bx-mobile/src/views/reimburse/ReimburseListPage.vue -
Modify:
bx-mobile/src/views/reimburse/ReimburseDetailPage.vue -
Modify: advance 对应页若 PC 有撤回则同步(以 PC 为准;备用金若无 withdraw API 则跳过)
-
Step 1: API
withdraw: (id: BxId) => bxClient.post(`/reimburses/${id}/withdraw`),
getApprovalHistory: (id: BxId) => bxClient.get(`/reimburses/${id}/approval-history`),
// advance:
getApprovalHistory: (id: BxId) => bxClient.get(`/advances/${id}/approval-history`),
- Step 2: UI
在详情/列表按状态显示「撤回」;确认框后调用 API。
审批时间线:渲染 approval-history 返回列表(字段对齐 PC)。
- Step 3: Commit
git add bx-mobile/src/api/index.ts bx-mobile/src/views/reimburse bx-mobile/src/views/advance bx-mobile/src/views/approval
git commit -m "$(cat <<'EOF'
feat(bx-mobile): add reimburse withdraw and approval history
EOF
)"
Task 14: 代申请 + 报销日期/标题
Files:
-
Modify:
bx-mobile/src/views/reimburse/ReimburseApplyPage.vue -
Modify:
bx-mobile/src/api/index.ts(generateTitle带参) -
Step 1: generateTitle
generateTitle: (reimburseDate?: string, excludeApplyId?: BxId, applicantId?: BxId) => {
const params: Record<string, string> = {}
if (reimburseDate) params.reimburseDate = reimburseDate
if (excludeApplyId) params.excludeApplyId = String(excludeApplyId)
if (applicantId) params.applicantId = String(applicantId)
return bxClient.get('/reimburses/generate-title', { params })
},
-
Step 2: 表单字段
-
applicantId:用户下拉(若门户有用户下拉 API,用现有 admin/用户列表权限接口;否则用 PC 报销页同一数据源——查阅 web-admin 报销申请所用接口并复用路径)。 -
reimburseDate:日期选择;变更时重新generateTitle。 -
提交 body 含
applicantId、reimburseDate。
用户下拉:优先复用门户已有接口(例如 web-admin 报销申请里的用户选择 API)。实施时打开
web-admin/src/views/bx/reimburse/apply/index.vue确认具体 URL,H5 原样调用。
- Step 3: Commit
git add bx-mobile/src/api/index.ts bx-mobile/src/views/reimburse/ReimburseApplyPage.vue
git commit -m "$(cat <<'EOF'
feat(bx-mobile): support proxy applicant and reimburse date title rules
EOF
)"
Task 15: 费用项目 + 工作流配置页
Files:
-
Modify:
bx-mobile/src/views/admin/ExpenseProjectPage.vue -
Modify:
bx-mobile/src/views/admin/WfAdvancePage.vue -
Modify:
bx-mobile/src/views/admin/WfReimbursePage.vue -
Modify:
bx-mobile/src/router/index.ts -
Modify:
bx-mobile/src/constants/bxMenuCatalog.ts—BX_MENU_CURRENT_PHASE = 3 -
Step 1: 路由加 menuCodes 并注册(若 P1 未注册)
{ path: 'admin/expenses', meta: { menuCodes: ['bx:expenseItem:list'] }, ... },
{ path: 'admin/wf-advance', meta: { menuCodes: ['bx:workflowAdvance:list'] }, ... },
{ path: 'admin/wf-reimburse', meta: { menuCodes: ['bx:workflowReimburse:list'] }, ... },
- Step 2: 页面改走 bxClient + UUID
去掉对旧 userApi/数字 id 的依赖;节点审批人选择与 PC 工作流页同一用户数据源。
- Step 3: 验收
有权限可见配置入口;改费用树/节点后 PC 与 H5 两侧数据一致。
- Step 4: Commit
git add bx-mobile/src/views/admin bx-mobile/src/router/index.ts bx-mobile/src/constants/bxMenuCatalog.ts
git commit -m "$(cat <<'EOF'
feat(bx-mobile): enable expense and workflow config pages under portal perms
EOF
)"
Task 16: 全量对照验收 + 文档收尾
Files:
-
Modify:
docs/business-inventory/03-报销业务明细.md -
Modify:
docs/superpowers/specs/2026-08-09-bx-mobile-shanxia2-adapt-design.md(状态改为已实现) -
Step 1: 同一账号 PC ↔ H5 对照
覆盖设计文档 §4.2 全部勾选项;记录缺陷并修。
-
Step 2: 更新文档状态
-
Step 3: Commit
git add docs/business-inventory/03-报销业务明细.md docs/superpowers/specs/2026-08-09-bx-mobile-shanxia2-adapt-design.md
git commit -m "$(cat <<'EOF'
docs: mark bx-mobile shanxia2.0 adaptation complete
EOF
)"
Spec 覆盖自检
| 设计要求 | 对应 Task |
|---|---|
| 保留 Vant H5 / 方案 1 | 全文 |
| 门户 JWT + RSA | 3, 5 |
| menuCode 映射 / 去角色码 | 2, 6, 7 |
| 去掉用户角色菜单 | 6 |
| P1 核心单据 | 8 |
| 发票夹完整 | 9–11 |
| 撤回/代申请/标题/审批历史 | 13–14 |
| 费用项+工作流 | 15 |
| 分阶段 phase 开关 | 2, 10, 15(BX_MENU_CURRENT_PHASE) |
| 更新业务清单 | 12, 16 |
执行说明
- 每阶段结束必须跑该阶段验收清单后再升
BX_MENU_CURRENT_PHASE。 - 提交信息使用完整句子;未要求时不要 push。
- 若发现 backend 缺能力:停手开独立后端任务,勿在 H5 伪造规则。