BX Mobile 对齐 Web 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: Make bx/bx-mobile functionally equivalent to bx/bx-web menu-by-menu, with mobile-specific interaction allowed but identical business outcomes.

Architecture: Keep API access centralized in bx/bx-mobile/src/api/index.ts, align route/page capability with web menus, and implement in four batches (advance, reimburse/payment, personal views, admin pages). Each page is completed with a fixed 5-point acceptance checklist and role-based regression.

Tech Stack: Vue 3 + TypeScript + Vite + Vant 4 (bx-mobile), FastAPI (bx-backend), Axios API client.

File Structure / Responsibility Map

bx/bx-mobile/src/router/index.ts: route availability, role guard, menu entry mapping.
bx/bx-mobile/src/api/index.ts: endpoint contracts and parameter adaptation.
bx/bx-mobile/src/views/**: page-level behavior and UI actions.
bx/bx-mobile/src/components/mobile/**: reusable list/card/action components.
bx/bx-mobile/src/stores/auth.ts: current user, role codes, menu list.
bx/bx-backend/app/routers/**: API endpoint capability gaps.
bx/bx-backend/app/services/**: business logic gaps (approve/issue/pay/offset details).

Web->Mobile Capability Matrix (must be maintained during execution)

web menu code	mobile route/page	API group	key actions
`advance-apply`	`/advance/list`, `/advance/apply`, `/advance/:id`	`advanceApi`, `attachmentApi`	create, edit, submit, view
`advance-approve`	`/advance/approve`	`advanceApi`	pending list, approve, reject
`advance-issue`	`/advance/issue`	`paymentApi`	issue, issue remark, issue record
`reimburse-apply`	`/reimburse/list`, `/reimburse/apply`, `/reimburse/:id`	`reimburseApi`, `expenseItemApi`, `attachmentApi`	create, edit, submit, view
`reimburse-approve`	`/reimburse/approve`	`reimburseApi`	pending list, approve, reject
`payment`	`/payment`	`paymentApi`	pay, offset, batch offset, records
`mine`	`/mine`	`advanceApi`, `reimburseApi`	filter, paginate, detail
`todo`	`/approval`, `/approval/:bizType/:id`	`advanceApi`, `reimburseApi`	aggregated pending, jump to approval
`all`	`/all`	`advanceApi`, `reimburseApi`	role-scoped global query
`user-manage`	`/admin/users`	`userApi`	list/create/edit/delete/reset pwd
`role-manage`	`/admin/roles`	`roleApi`, `menuApi`	CRUD, assign users, assign menus
`menu-manage`	`/admin/menus`	`menuApi`	tree, create/edit/delete
`project`	`/admin/expenses`	`expenseItemApi`	tree CRUD
`wf-advance`	`/admin/wf-advance`	`workflowApi`	workflow CRUD, nodes save
`wf-reimburse`	`/admin/wf-reimburse`	`workflowApi`	workflow CRUD, nodes save

Acceptance Checklist Template (per page, mandatory)

Entry reachable from Home menu and direct route.
List/query data correct under same account and same filters as web.
Detail data fields and status labels equivalent to web.
Key actions succeed and return expected user feedback.
Status/writeback visible in list + detail after action.

Task 1: Baseline Gap Inventory and Lock

Files:

Modify: bx/docs/superpowers/specs/2026-04-29-bx-mobile-align-web-design.md
Create: bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
Test: manual verification doc only
[ ] Step 1: Create parity matrix file with all 15 menu rows

# BX Mobile-Web Parity Matrix
| menu | web page | mobile page | APIs | action parity | status |
|---|---|---|---|---|---|
| advance-apply | AdvanceApplyPage | AdvanceApplyPage | advanceApi, attachmentApi | create/edit/submit | todo |

Step 2: Fill current status (done/partial/missing) for every row

Run: cd bx/bx-mobile && npm run build Expected: build passes (baseline), matrix updated.

Step 3: Freeze batch scope

Batch-1: advance-apply, advance-approve, advance-issue
Batch-2: reimburse-apply, reimburse-approve, payment
Batch-3: mine, todo, all
Batch-4: admin six pages

Step 4: Commit

git add bx/docs/superpowers/specs/2026-04-29-bx-mobile-align-web-design.md bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
git commit -m "docs: add mobile-web parity matrix baseline"

Task 2: API Contract Alignment Layer

Files:

Modify: bx/bx-mobile/src/api/index.ts
Modify: bx/bx-mobile/src/api/client.ts
Optional Modify: bx/bx-backend/app/routers/*.py
Optional Modify: bx/bx-backend/app/services/*.py
Test: bx/bx-mobile build + smoke calls
[ ] Step 1: Write failing contract checklist tests (manual + curl collection)

# Example contract checks
curl -s "http://localhost:8000/api/payments/pending?page=1&pageSize=10" | jq '.code,.data'
curl -s "http://localhost:8000/api/reimburses/generate-title" | jq '.code,.data'

Step 2: Normalize mobile parameter mapping to web-equivalent shape

// src/api/index.ts (pattern)
advanceIssues: (params?: Record<string, any>) =>
  client.get('/payments/advance-issues', {
    params: params
      ? { page: params.page, pageSize: params.pageSize, issue_status: params.issueStatus, keyword: params.keyword }
      : undefined,
  })

Step 3: Add backend compatibility endpoints only if missing

# routers/payments.py pattern
@router.get("/reimburse/{reimburse_id}/offset-records")
def list_reimburse_offset_records(reimburse_id: int, ...):
    ...

Step 4: Verify all matrix APIs are callable

Run: cd bx/bx-mobile && npm run build Expected: PASS

Step 5: Commit

git add bx/bx-mobile/src/api/index.ts bx/bx-mobile/src/api/client.ts bx/bx-backend/app/routers bx/bx-backend/app/services
git commit -m "feat: align mobile api contracts with web parity"

Task 3: Batch-1 Advance Flow Parity

Files:

Modify: bx/bx-mobile/src/views/advance/AdvanceListPage.vue
Modify: bx/bx-mobile/src/views/advance/AdvanceApplyPage.vue
Modify: bx/bx-mobile/src/views/advance/AdvanceDetailPage.vue
Modify: bx/bx-mobile/src/views/advance/AdvanceApprovePage.vue
Modify: bx/bx-mobile/src/views/advance/AdvanceIssuePage.vue
Modify: bx/bx-mobile/src/hooks/useAttachment.ts
Test: page flow E2E manual
[ ] Step 1: Implement apply/edit/submit + attachment bind parity

// submit pattern
await advanceApi.create(payload)
await attachmentApi.bindBiz(uploadedIds, 'advance', createdId)
await advanceApi.submit(createdId)

Step 2: Implement approval action parity (approve/reject/opinion/history)

await advanceApi.approve(id, { approvalOpinion: form.opinion })
// or reject(...)

Step 3: Implement issue action parity (actualAmount + remark + refresh)

await paymentApi.issueAdvance(advanceId, { actualAmount, issueRemark })
await refreshList()

Step 4: Run batch acceptance checklist for 3 pages

Run: cd bx/bx-mobile && npm run build Expected: PASS + checklist all checked in matrix.

Step 5: Commit

git add bx/bx-mobile/src/views/advance bx/bx-mobile/src/hooks/useAttachment.ts bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
git commit -m "feat: complete advance flow parity on mobile"

Task 4: Batch-2 Reimburse + Payment Parity

Files:

Modify: bx/bx-mobile/src/views/reimburse/ReimburseListPage.vue
Modify: bx/bx-mobile/src/views/reimburse/ReimburseApplyPage.vue
Modify: bx/bx-mobile/src/views/reimburse/ReimburseDetailPage.vue
Modify: bx/bx-mobile/src/views/reimburse/ReimburseApprovePage.vue
Modify: bx/bx-mobile/src/views/payment/PaymentPage.vue
Modify: bx/bx-mobile/src/hooks/useExpenseItemTree.ts
Test: reimburse/payment closed-loop
[ ] Step 1: Align reimburse apply fields and title generation

const titleRes = await reimburseApi.generateTitle()
form.title = titleRes.data

Step 2: Align reimburse approve behavior and approval history

const approvals = await reimburseApi.getApprovals(id)
await reimburseApi.approve(id, { approvalOpinion: opinion })

Step 3: Align payment actions (pay/offset/batch offset/records)

await paymentApi.pay(id, { actualAmount, payRemark })
await paymentApi.batchOffset(id, { items, payAmount, remark })

Step 4: Verify end-to-end status transitions

Run: cd bx/bx-mobile && npm run build Expected: PASS + reimburse/payment rows marked done.

Step 5: Commit

git add bx/bx-mobile/src/views/reimburse bx/bx-mobile/src/views/payment/PaymentPage.vue bx/bx-mobile/src/hooks/useExpenseItemTree.ts bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
git commit -m "feat: complete reimburse and payment parity on mobile"

Task 5: Batch-3 Mine/Todo/All Views Parity

Files:

Modify: bx/bx-mobile/src/views/mine/MinePage.vue
Modify: bx/bx-mobile/src/views/mine/ApplyList.vue
Modify: bx/bx-mobile/src/views/approval/ApprovalPage.vue
Modify: bx/bx-mobile/src/views/approval/ApprovalDetailPage.vue
Modify: bx/bx-mobile/src/views/all/AllPage.vue
Modify: bx/bx-mobile/src/views/home/HomePage.vue
Test: role-based read/operate checks
[ ] Step 1: Align mine filters/pagination/detail routes

await advanceApi.my({ page, pageSize, status, keyword })
await reimburseApi.my({ page, pageSize, status, keyword })

Step 2: Align todo aggregation and route jumps by biz type

if (bizType === 'advance') router.push('/advance/approve')
if (bizType === 'reimburse') router.push('/reimburse/approve')

Step 3: Align all-page role scope and combined filters

meta: { roles: ['ADMIN', 'GENERAL_MANAGER'] }

Step 4: Verify red dot and counter consistency

Run: cd bx/bx-mobile && npm run build Expected: PASS + mine/todo/all rows done.

Step 5: Commit

git add bx/bx-mobile/src/views/mine bx/bx-mobile/src/views/approval bx/bx-mobile/src/views/all/AllPage.vue bx/bx-mobile/src/views/home/HomePage.vue bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
git commit -m "feat: complete mine todo all parity on mobile"

Task 6: Batch-4 Admin Capability Parity

Files:

Modify: bx/bx-mobile/src/views/admin/UserManagePage.vue
Modify: bx/bx-mobile/src/views/admin/RoleManagePage.vue
Modify: bx/bx-mobile/src/views/admin/MenuManagePage.vue
Modify: bx/bx-mobile/src/views/admin/ExpenseProjectPage.vue
Modify: bx/bx-mobile/src/views/admin/WfAdvancePage.vue
Modify: bx/bx-mobile/src/views/admin/WfReimbursePage.vue
Test: admin action suite
[ ] Step 1: User/Role/Menu actions parity (CRUD + assign)

await roleApi.assignUsers(roleId, userIds)
await roleApi.assignMenus(roleId, menuIds)

Step 2: Expense tree CRUD parity

await expenseItemApi.tree()
await expenseItemApi.create(payload)

Step 3: Workflow CRUD + node save parity

await workflowApi.getByBizType('advance')
await workflowApi.saveNodes(id, nodes)

Step 4: Validate "ability not downgraded" on all 6 pages

Run: cd bx/bx-mobile && npm run build Expected: PASS + all admin rows done.

Step 5: Commit

git add bx/bx-mobile/src/views/admin bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
git commit -m "feat: complete admin capability parity on mobile"

Task 7: Role Regression + Closure Report

Files:

Modify: bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md
Create: bx/docs/superpowers/plans/2026-04-29-bx-mobile-parity-test-report.md
Test: full regression by role
[ ] Step 1: Execute role matrix regression

Roles: ADMIN, FINANCE, GENERAL_MANAGER, APPLICANT
Flows: advance full chain, reimburse full chain, admin capability checks

Step 2: Record every page's 5-point checklist result

| page | reachable | list | detail | actions | writeback | result |
|---|---|---|---|---|---|---|
| /payment | yes | yes | yes | yes | yes | PASS |

Step 3: Log blockers and owner if any

- blocker: reimburse offset rounding mismatch
- owner: backend payment service
- eta: 1 day

Step 4: Final verification commands

Run: cd bx/bx-mobile && npm run build Expected: PASS

Run: cd bx/bx-mobile && npm run dev Expected: dev server starts successfully.

Step 5: Commit

git add bx/docs/superpowers/plans/bx-mobile-web-parity-matrix.md bx/docs/superpowers/plans/2026-04-29-bx-mobile-parity-test-report.md
git commit -m "test: finalize mobile-web parity regression report"

Self-Review Checklist (for this plan)

Spec coverage: all 15 menu items included in matrix and task batches.
Placeholder scan: no TBD/TODO placeholders.
Type consistency: API/action names consistent with current bx-mobile/bx-web usage.
Scope: focused on parity goal, excludes unrelated refactor.

2026-04-29-bx-mobile-align-web-implementation.md 13 KB لینک دائمی تاريخچه خام

BX Mobile 对齐 Web Implementation Plan

File Structure / Responsibility Map

Web->Mobile Capability Matrix (must be maintained during execution)

Acceptance Checklist Template (per page, mandatory)

Task 1: Baseline Gap Inventory and Lock

Task 2: API Contract Alignment Layer

Task 3: Batch-1 Advance Flow Parity

Task 4: Batch-2 Reimburse + Payment Parity

Task 5: Batch-3 Mine/Todo/All Views Parity

Task 6: Batch-4 Admin Capability Parity

Task 7: Role Regression + Closure Report

Self-Review Checklist (for this plan)

2026-04-29-bx-mobile-align-web-implementation.md 13 KB

لینک دائمی تاريخچه خام