Files
shanxia2.0/docs/superpowers/plans/2026-09-08-bx-date-column-sort.md
T

467 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 报销域日期列头双三角排序 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:** 在有日期列的报销相关列表上,为 `datetime` 列头增加与 CRM 相同的双三角整库排序(视图合并页为拉全量后的客户端排序)。
**Architecture:** 扩展 `ColumnHeaderFilter`:存在 `crmColumnSort` inject 且 `type==='datetime'` 时渲染双三角。页面接入已有 `useColumnSort`。后端复用 `resolve_datetime_order_by`;`applyTime` 映射 `create_time`。视图 mine/todo/all 已 `fetchAllPagedRecords` 合并双边数据,改 `sortMergedRows` 按当前 sort 状态排。
**Tech Stack:** Vue 3、`ColumnHeaderFilter`、`useColumnSort`、FastAPI、SQLAlchemy、`resolve_datetime_order_by`
**Spec:** `docs/superpowers/specs/2026-09-08-bx-date-column-sort-design.md`
---
## 文件结构
| 操作 | 文件 | 职责 |
|------|------|------|
| Modify | `web-admin/src/components/business/column-header-filter/index.vue` | datetime + inject 时显示双三角 |
| Modify | `backend/app/services/bx/base.py` | `get_paged` 支持可选 `order_by` |
| Create | `backend/app/services/bx/list_sort.py` | 各实体白名单封装(调用 crm `resolve_datetime_order_by`) |
| Create | `backend/tests/test_bx_list_sort.py` | 白名单映射单测 |
| Modify | `backend/app/api/bx/advance.py` + `services/bx/advance.py` | 透传 sort → order |
| Modify | `backend/app/api/bx/reimburse.py` + `services/bx/reimburse.py` | 同上 |
| Modify | `backend/app/api/bx/payment.py` + 付款 list 路径 | `applyTime`/`payTime` |
| Modify | `backend/app/api/bx/invoice.py` + `services/bx/invoice.py` | 我的发票/流水 `createTime` |
| Modify | `backend/app/api/bx/export_common.py` | `BxApplyListExportBody` 显式 `sortField`/`sortOrder`(可选,extra=allow 已可透传) |
| Modify | 各 `views/bx/**/index.vue`(见 Task 6–10) | provide + merge query + 藏列 |
**不做:** expense-item、workflow、invoice-wallet/admin;非日期列。
---
### Task 1: `ColumnHeaderFilter` 双三角
**Files:**
- Modify: `web-admin/src/components/business/column-header-filter/index.vue`
- [ ] **Step 1: 改模板根结构**
当前根节点是单个 `el-popover`。改为外包一层,在 popover **之前**插入三角(与 CRM 列头「标题 | 三角 | 漏斗」一致;标题仍由页面 label 提供):
```vue
<template>
<span class="col-header-filter-root">
<span
v-if="showSort"
class="col-header-sort-pair"
@click.stop
>
<button
type="button"
class="col-header-sort-btn"
:class="{ on: sortApi!.isSortActive(prop, 'asc') }"
title="升序"
aria-label="升序"
@click="sortApi!.setSort(prop, 'asc')"
>▲</button>
<button
type="button"
class="col-header-sort-btn"
:class="{ on: sortApi!.isSortActive(prop, 'desc') }"
title="降序"
aria-label="降序"
@click="sortApi!.setSort(prop, 'desc')"
>▼</button>
</span>
<el-popover ...现有内容不变...>
...
</el-popover>
</span>
</template>
```
- [ ] **Step 2: script 增加 inject**
```ts
import { computed, inject, ref, watch } from 'vue'
// ...
const sortApi = inject<{
setSort: (prop: string, order: 'asc' | 'desc') => void
isSortActive: (prop: string, order?: 'asc' | 'desc') => boolean
} | null>('crmColumnSort', null)
const showSort = computed(() => Boolean(sortApi && props.type === 'datetime'))
```
样式 `.col-header-sort-pair` 已在同文件全局 style 中(CRM Task 6 已加),无需重复。可补:
```scss
.col-header-filter-root {
display: inline-flex;
align-items: center;
gap: 4px;
flex-shrink: 0;
}
```
- [ ] **Step 3: 确认无 provide 时不显示三角;CRM 的 `CrmColFilterHeader` 仍自带三角(两套并存可接受)**
- [ ] **Step 4: Commit**
```bash
git add web-admin/src/components/business/column-header-filter/index.vue
git commit -m "feat(web-admin): show dual carets on ColumnHeaderFilter datetime columns."
```
---
### Task 2: BX 排序白名单 helper + `get_paged` 可选 order
**Files:**
- Create: `backend/app/services/bx/list_sort.py`
- Create: `backend/tests/test_bx_list_sort.py`
- Modify: `backend/app/services/bx/base.py`
- [ ] **Step 1: 写失败测试**
```python
# backend/tests/test_bx_list_sort.py
from app.models.bx_models import BxAdvanceApply, BxReimburseApply, BxInvoice, BxInvoiceLedger
from app.services.bx.list_sort import (
order_advance,
order_reimburse,
order_invoice,
order_ledger,
)
def test_advance_apply_time_asc():
expr = order_advance("applyTime", "asc")
assert "create_time" in str(expr).lower()
assert "asc" in str(expr).lower()
def test_advance_issue_time():
expr = order_advance("issueTime", "desc")
assert "issue_time" in str(expr).lower()
def test_advance_invalid_falls_back():
default = BxAdvanceApply.create_time.desc()
assert order_advance("hack", "asc", default=default) is default
def test_reimburse_pay_time():
expr = order_reimburse("payTime", "desc")
assert "pay_time" in str(expr).lower()
def test_invoice_create_time():
expr = order_invoice("createTime", "asc")
assert "create_time" in str(expr).lower()
```
(若模型 import 路径不同,以仓库 `app.models` 实际模块为准。)
- [ ] **Step 2: pytest 应 FAIL**
```bash
cd backend && source venv/bin/activate && PYTHONPATH=. pytest tests/test_bx_list_sort.py -v
```
- [ ] **Step 3: 实现 `list_sort.py`**
```python
# backend/app/services/bx/list_sort.py
from __future__ import annotations
from typing import Any, Optional
from app.models.bx_models import (
BxAdvanceApply,
BxInvoice,
BxInvoiceLedger,
BxReimburseApply,
)
from app.services.crm.list_sort import resolve_datetime_order_by
ADVANCE_WHITELIST = {
"applyTime": BxAdvanceApply.create_time,
"issueTime": BxAdvanceApply.issue_time,
}
REIMBURSE_WHITELIST = {
"applyTime": BxReimburseApply.create_time,
"payTime": BxReimburseApply.pay_time,
}
INVOICE_WHITELIST = {"createTime": BxInvoice.create_time}
LEDGER_WHITELIST = {"createTime": BxInvoiceLedger.create_time}
def order_advance(sort_field: Optional[str], sort_order: Optional[str], default=None):
if default is None:
default = BxAdvanceApply.create_time.desc()
return resolve_datetime_order_by(sort_field, sort_order, ADVANCE_WHITELIST, default)
def order_reimburse(sort_field: Optional[str], sort_order: Optional[str], default=None):
if default is None:
default = BxReimburseApply.create_time.desc()
return resolve_datetime_order_by(sort_field, sort_order, REIMBURSE_WHITELIST, default)
def order_invoice(sort_field: Optional[str], sort_order: Optional[str], default=None):
if default is None:
default = BxInvoice.create_time.desc()
return resolve_datetime_order_by(sort_field, sort_order, INVOICE_WHITELIST, default)
def order_ledger(sort_field: Optional[str], sort_order: Optional[str], default=None):
if default is None:
default = BxInvoiceLedger.create_time.desc()
return resolve_datetime_order_by(sort_field, sort_order, LEDGER_WHITELIST, default)
def parse_sort_params(params: dict) -> tuple:
"""从 request/body dict 取 sortField/sortOrder(兼容 snake)。"""
sf = params.get("sortField") or params.get("sort_field")
so = params.get("sortOrder") or params.get("sort_order")
return (str(sf).strip() if sf else None), (str(so).strip() if so else None)
```
- [ ] **Step 4: `BxCrudService.get_paged` 增加可选 `order_by=None`**
在现有默认 `order_by(sort_order, create_time)` 分支前:
```python
order_by: Optional[Any] = None,
# ...
if order_by is not None:
query = query.order_by(order_by)
elif hasattr(model, "sort_order"):
...
else:
query = query.order_by(model.create_time.desc())
```
- [ ] **Step 5: 测试通过并 Commit**
```bash
git add backend/app/services/bx/list_sort.py backend/tests/test_bx_list_sort.py backend/app/services/bx/base.py
git commit -m "feat(bx): add datetime list sort helpers and get_paged order_by."
```
---
### Task 3: 备用金 API/Service 接排序
**Files:**
- Modify: `backend/app/api/bx/advance.py`
- Modify: `backend/app/services/bx/advance.py`
- Modify: `backend/app/api/bx/export_common.py`(可选显式字段)
- [ ] **Step 1: `BxApplyListExportBody` 增加**
```python
sort_field: Optional[str] = Field(default=None, alias="sortField")
sort_order: Optional[str] = Field(default=None, alias="sortOrder")
```
(`extra=allow` 已有则 GET query 的 `sortField` 进 `_merge_query` 即可;显式字段便于导出 body。)
- [ ] **Step 2: 所有走 `AdvanceService.get_paged` 的 list/export**
在调用前:
```python
from app.services.bx.list_sort import order_advance, parse_sort_params
sf, so = parse_sort_params(params)
order = order_advance(sf, so)
rows, total = AdvanceService.get_paged(..., order_by=order)
```
确认 `AdvanceService.get_paged` 把 `order_by` 传给 `BxCrudService.get_paged`(若当前是薄封装,补参数)。
- [ ] **Step 3: `pending_approval` / `approved_by_me`**
将硬编码 `.order_by(BxAdvanceApply.create_time.desc())` 改为 `order_by(order_advance(sf, so))`;`sf/so` 从该接口的 `params`/`_merge_query` 读取。
- [ ] **Step 4: Commit**
```bash
git commit -m "feat(bx): support datetime column sort on advance lists."
```
---
### Task 4: 报销 API/Service 接排序
**Files:**
- Modify: `backend/app/api/bx/reimburse.py`
- Modify: `backend/app/services/bx/reimburse.py`
镜像 Task 3:`get_paged`、`pending_approval`、`approved_by_me` 及对应 export 使用 `order_reimburse`。白名单含 `applyTime`、`payTime`。
```bash
git commit -m "feat(bx): support datetime column sort on reimburse lists."
```
---
### Task 5: 支付发放冲抵接排序
**Files:**
- Modify: `backend/app/api/bx/payment.py`(及实际 list/export 调用的 service)
待处理/已处理列表对 `BxReimburseApply` 排序时用 `order_reimburse`(`applyTime`/`payTime`)。冲抵记录子表(`BxReimburseOffset.create_time`)**本批不改**(非主列表漏斗列)。
```bash
git commit -m "feat(bx): support datetime column sort on payment lists."
```
---
### Task 6: 我的发票夹后端
**Files:**
- Modify: `backend/app/api/bx/invoice.py`
- Modify: `backend/app/services/bx/invoice.py`
- `list_invoices`:经 `get_paged` 传入 `order_by=order_invoice(sf, so)`;API `_param_get` / merge 取出 sort。
- `list_ledgers`:将 `order_by(BxInvoiceLedger.create_time.desc())` 换为 `order_ledger(sf, so)`。
```bash
git commit -m "feat(bx): support datetime column sort on my invoice wallet lists."
```
---
### Task 7: 接线备用金三页前端
**Files:**
- `web-admin/src/views/bx/advance/apply/index.vue`
- `web-admin/src/views/bx/advance/approve/index.vue`
- `web-admin/src/views/bx/advance/issue/index.vue`
每页:
```ts
import { useColumnSort } from '@/composables/useColumnSort'
const {
setSort, clearSort, isSortActive, sortField, sortOrder,
toQueryParams: toSortQueryParams,
watchVisibleColumns: watchSortVisibleColumns
} = useColumnSort({ onChange: () => { /* 现有 reset page + load */ } })
provide('crmColumnSort', { setSort, clearSort, isSortActive, sortField, sortOrder })
```
列表/导出参数合并 `...toSortQueryParams()`;`watchSortVisibleColumns(visibleFilterProps)`。
审批/发放若双 Tab 共用一套 filters,共用一套 sort 即可。
```bash
git commit -m "feat(bx): wire date column sort on advance apply/approve/issue pages."
```
---
### Task 8: 接线报销申请/审批前端
**Files:**
- `web-admin/src/views/bx/reimburse/apply/index.vue`
- `web-admin/src/views/bx/reimburse/approve/index.vue`
同 Task 7 模式。
```bash
git commit -m "feat(bx): wire date column sort on reimburse apply/approve pages."
```
---
### Task 9: 接线支付页前端
**Files:**
- `web-admin/src/views/bx/payment/index.vue`
同模式;`payTime` 仅已处理 Tab 有漏斗,藏列时 `watchSortVisibleColumns` 清排序。
```bash
git commit -m "feat(bx): wire date column sort on payment page."
```
---
### Task 10: 接线我的发票夹前端
**Files:**
- `web-admin/src/views/bx/invoice-wallet/mine/index.vue`
发票表与流水表各有 `useServerColumnFilters`。推荐:
- 两套 `useColumnSort`(`invoiceSort` / `ledgerSort`)
- `provide` 时按当前 Tab 提供,或给 `ColumnHeaderFilter` 增加可选 `injectKey`(若改组件成本高:切换 Tab 时 `provide` 无法动态——改用 **同一套 sort**,切 Tab 时 `clearSort`,更简单)
**选定更简单:共用一套 `useColumnSort`,切 Tab 时 `clearSort()`,请求分别带 `toSortQueryParams()`。**
```bash
git commit -m "feat(bx): wire date column sort on my invoice wallet page."
```
---
### Task 11: 视图三页(合并列表 · 客户端排序)
**Files:**
- `web-admin/src/views/bx/view/mine/index.vue`
- `web-admin/src/views/bx/view/todo/index.vue`
- `web-admin/src/views/bx/view/all/index.vue`
现状:`sortMergedRows` 固定 `applyTime` 倒序。这些页拉全量后合并,**以客户端排序为准**:
```ts
function sortMergedRows(rows: any[]) {
const field = sortField.value || 'applyTime'
const order = sortOrder.value || 'desc'
return [...rows].sort((a, b) => {
const av = String(a[field] || '')
const bv = String(b[field] || '')
if (!av && !bv) return 0
if (!av) return order === 'asc' ? -1 : 1 // 空值:升序前、降序后
if (!bv) return order === 'asc' ? 1 : -1
const cmp = av.localeCompare(bv)
return order === 'asc' ? cmp : -cmp
})
}
```
仍 `provide('crmColumnSort')` 驱动列头三角;`onChange` → `loadData()`。
可选:请求时仍带 `sortField` 给单边 API(非必须,合并后会再排)。
```bash
git commit -m "feat(bx): wire date column sort on bx view mine/todo/all pages."
```
---
### Task 12: 回归与图谱
- [ ] **Step 1:** `PYTHONPATH=. pytest tests/test_bx_list_sort.py tests/test_crm_list_sort.py -v`
- [ ] **Step 2:** `pnpm dlx vitest run src/composables/useColumnSort.test.ts`
- [ ] **Step 3:** 手工:备用金申请 `applyTime`;发放 `issueTime`;报销申请;支付 `payTime`;我的发票夹;我的申请单合并列表;费用项目无三角。
- [ ] **Step 4:** `./scripts/update-graph.sh all` 后仅提交图谱变更:
```bash
git commit -m "chore: update graphify after BX date column sort."
```
---
## Spec 覆盖自检
| Spec 项 | Task |
|---------|------|
| ColumnHeaderFilter 扩展 | 1 |
| applyTime→create_time 白名单 | 2–5 |
| 备用金/报销/支付/发票夹 | 3–6, 7–10 |
| 视图合并页 | 11(客户端排序,符合现网拉全量架构) |
| 跳过费用项目/工作流/发票夹管理 | 文件结构「不做」 |
| 空值升降序 | 2 helper + 11 sortMergedRows |
| 与 CRM 同 inject key | 1, 7–11 |
无 TBD;视图页明确为客户端排序,避免与「整库服务端」表述冲突——spec §7 已提示 union/合并风险,本计划按现网 `fetchAllPagedRecords` 落地。