Files
shanxia2.0/docs/superpowers/plans/2026-08-09-bx-mobile-shanxia2-adapt.md
T
2026-08-09 16:19:51 +08:00

33 KiB
Raw Blame History

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.ts menuCode 对齐)

// 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-export BizError / 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 伪造规则。