# 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**

```markdown
# 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**

```markdown
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**

```bash
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)**

```bash
# 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**

```ts
// 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**

```python
# 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**

```bash
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**

```ts
// 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)**

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

- [ ] **Step 3: Implement issue action parity (actualAmount + remark + refresh)**

```ts
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**

```bash
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**

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

- [ ] **Step 2: Align reimburse approve behavior and approval history**

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

- [ ] **Step 3: Align payment actions (pay/offset/batch offset/records)**

```ts
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**

```bash
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**

```ts
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**

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

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

```ts
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**

```bash
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)**

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

- [ ] **Step 2: Expense tree CRUD parity**

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

- [ ] **Step 3: Workflow CRUD + node save parity**

```ts
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**

```bash
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**

```markdown
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**

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

- [ ] **Step 3: Log blockers and owner if any**

```markdown
- 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**

```bash
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.