docs: add implementation plan for reimburse apply page size options

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-21 14:12:40 +08:00
1 parent 38c830ef99
commit 02a29c3328
@@ -0,0 +1,160 @@
+# 报销申请列表扩大每页条数（试点）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:** 【报销申请】分页选项扩展为 `10/20/30/50/100/200/500`，并仅对 `GET /reimburses/my` 将 `pageSize` 上限显式设为 500。
+
+**Architecture:** 前端改 `el-pagination` 的 `page-sizes`；后端在 `my_reimburses` 用 FastAPI `Query(ge=1, le=500)` 定契约。不改 OpenSpec 全局「最大 100」、不做「全部」分批加载。
+
+**Tech Stack:** FastAPI Query 校验 · Vue 3 · Element Plus `el-pagination`
+
+**Spec:** `docs/superpowers/specs/2026-08-21-reimburse-apply-page-size-options-design.md`
+
+---
+
+## File map
+
+| File | Responsibility |
+|------|----------------|
+| `backend/app/api/bx/reimburse.py` | `my_reimburses` 的 `pageSize` 显式 `ge=1, le=500` |
+| `backend/tests/test_bx_reimburse_my_page_size.py` | 断言该参数的 Query 上下限（无 DB） |
+| `web-admin/src/views/bx/reimburse/apply/index.vue` | `:page-sizes="[10, 20, 30, 50, 100, 200, 500]"` |
+
+---
+
+### Task 1: 后端 `pageSize` 上限 500 + 单测
+
+**Files:**
+- Modify: `backend/app/api/bx/reimburse.py`
+- Create: `backend/tests/test_bx_reimburse_my_page_size.py`
+
+- [ ] **Step 1: 写失败单测（检查 Query 约束）**
+
+创建 `backend/tests/test_bx_reimburse_my_page_size.py`:
+
+```python
+import inspect
+
+from fastapi.params import Query as QueryParam
+
+from app.api.bx.reimburse import my_reimburses
+
+
+def test_my_reimburses_page_size_query_bounds():
+    param = inspect.signature(my_reimburses).parameters["pageSize"]
+    q = param.default
+    assert isinstance(q, QueryParam)
+    assert q.ge == 1
+    assert q.le == 500
+    assert q.default == 10
+```
+
+- [ ] **Step 2: 跑测确认当前失败**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_bx_reimburse_my_page_size.py -v
+```
+
+Expected: FAIL（`pageSize` 仍是裸 `int = 10`，`default` 不是 `QueryParam`，或没有 `le=500`）
+
+- [ ] **Step 3: 改 `my_reimburses` 签名**
+
+在 `backend/app/api/bx/reimburse.py`：
+
+1. 将 import 改为包含 `Query`：
+
+```python
+from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile, status
+```
+
+2. 仅改 `my_reimburses` 的 `pageSize` 参数（约第 195 行），其它列表接口不动：
+
+```python
+def my_reimburses(
+    page: int = 1,
+    pageSize: int = Query(10, ge=1, le=500),
+    status: Optional[str] = None,
+    # ... 其余参数保持不变
+```
+
+- [ ] **Step 4: 再跑测确认通过**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_bx_reimburse_my_page_size.py -v
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/app/api/bx/reimburse.py backend/tests/test_bx_reimburse_my_page_size.py
+git commit -m "$(cat <<'EOF'
+feat(bx): raise my reimburses pageSize max to 500 for apply list pilot
+
+EOF
+)"
+```
+
+---
+
+### Task 2: 前端分页选项
+
+**Files:**
+- Modify: `web-admin/src/views/bx/reimburse/apply/index.vue`（约第 344 行）
+
+- [ ] **Step 1: 更新 page-sizes**
+
+将：
+
+```vue
+:page-sizes="[10, 20, 30]"
+```
+
+改为：
+
+```vue
+:page-sizes="[10, 20, 30, 50, 100, 200, 500]"
+```
+
+仅改这一处；不改 `useServerPaged`、列头过滤或其它分页栏。
+
+- [ ] **Step 2: 手工验收清单**
+
+1. 打开 `/#/` 下报销申请列表
+2. 分页下拉可见 `10/20/30/50/100/200/500`
+3. 选 `100` / `200` / `500` 能正常出数，无 422
+4. 列头过滤仍只作用于当前页
+
+（可选）用浏览器或 curl 对 `GET .../reimburses/my?page=1&pageSize=501` 应得到 422。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web-admin/src/views/bx/reimburse/apply/index.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): expand reimburse apply page size options to 500
+
+EOF
+)"
+```
+
+- [ ] **Step 4: 更新图谱（若本会话改了代码）**
+
+```bash
+./scripts/update-graph.sh backend
+```
+
+（前端仅改 Vue 模板属性时，按仓库习惯可跳过或跑 `frontend`；至少更新 backend。）
+
+---
+
+## Spec coverage check
+
+| Spec 项 | Task |
+|---------|------|
+| page-sizes `10…500` | Task 2 |
+| `GET /reimburses/my` le=500 | Task 1 |
+| `>500` → 422 | Task 1（FastAPI Query） |
+| 不改全局 OpenSpec / 无「全部」 | 无对应改动（故意） |
+| 列头过滤语义不变 | 无对应改动（故意） |