docs(pl): 明确工单8的列表一致性范围与筛选实施方案。

2026-11-01 19:11:46 +08:00
1 parent 3d0f678713
commit 0b558e7063
@@ -0,0 +1,27 @@
+# 工单 #8 列表一致性实施计划
+
+> **For agentic workers:** Use subagent-driven-development; implement disjoint backend and frontend changes, then independent review.
+
+**Goal:** 三个 Web 列表复用运输计划工具栏与漏斗并提供正确筛选。
+**Architecture:** 计划列表使用现有服务端筛选 composable，证件/资料完整集合使用客户端筛选；不改业务写接口。
+**Tech Stack:** Vue 3 / Element Plus / TypeScript；FastAPI / SQLAlchemy；Node tsx / pytest。
+
+### 1. 计划列表服务端筛选
+
+Files: `backend/app/services/pl_quota_overview.py`, `backend/app/api/pl/quota_cert.py`, `backend/tests/test_pl_quota_overview_filters.py`。
+- [ ] 先写跨20条分页、租户/删除/取消、组合编号车号日期及多状态测试，并运行确认失败。
+- [ ] `list_plans(..., plan_no=None, license_plate=None, plan_date_from=None, plan_date_to=None, quota_status_in=None)` 可选参数在count/offset之前应用。接口别名planNo/licensePlate/planDateFrom/planDateTo/quotaStatusIn。拒绝非法状态/日期范围。
+- [ ] 使用独立SQLite测试，不连接测试或生产库：backend内 `ENV_FILE=/dev/null <主目录>/backend/venv/bin/python -m pytest tests/test_pl_quota_overview_filters.py tests/test_pl_quota_api.py -q`。
+
+### 2. 三页列表组件
+
+Files: `web-admin/src/views/pl/{plan-quota,quota-cert,legal-use-document}/index.vue`；所需列表筛选定义及专项测试。
+- [ ] 复用运输计划公共工具栏、ListTable、漏斗、列设置；保留已有详情/维护逻辑和权限。
+- [ ] 计划列表新漏斗参数传后端；另外两页在完整集合先筛再分页；隐藏列清漏斗，条件变化回首页，刷新保留条件。
+- [ ] 新增真实筛选/组件handler专项测试：组合、清空、跨页、旧响应失效；H5保持原能力。
+
+### 3. 审查与交付
+
+- [ ] 按改动运行专项pytest/Node测试及Web构建；合成API验证三页检索和漏斗交互、截图对比参考组件。
+- [ ] 独立代码审查，修复实际问题后重验；重新读取工单评论。
+- [ ] 保存实际证据/版本和剩余限制；保留待用户测试，未获授权不推送合并/关闭工单。
@@ -0,0 +1,20 @@
+# 工单 #8：计划用证三个 Web 列表一致性修复
+
+来源：https://gitea.aichengyan.com/cykj/shanxia2.0/issues/8 。2026-11-01 已读取最新正文和全部评论（0条），无图片。用户确认三个页面为计划用证、购买证与运输证、合法使用证明，并明确直接复用运输计划组件，不另做 Figma。
+
+## 范围与视觉依据
+
+仅修改 Web 列表；H5 共享计划组件保留移动分支与原查询语义。采用 P01/P02，主参考 `web-admin/src/views/pl/plan/index.vue`，遵循 Fresh Mint。
+
+统一使用 ListQuickSearchInput、ListToolbarEndActions、ListTable、ColumnHeaderFilter 和已有列表布局类。保留业务按钮权限及详情操作。工具栏内快速检索和业务动作同排，尾部刷新/列设置；不复制运输计划专属新增/导出等无对应业务的操作。
+
+## 筛选行为
+
+- 计划用证按服务端分页，在分页前应用编号、车号、计划日期起止和用证状态多选；关键词/漏斗共同生效，查询变化回首页，刷新保留条件。
+- 证件档案与合法使用证明接口返回完整授权集合，复用客户端列筛选，在分页前过滤。文本、状态、日期、数量列按字段类型匹配；数量保留原证面单位展示。
+- 隐藏列时清除对应漏斗，重置清除关键词与漏斗。异步列表响应不覆盖新条件或销毁后的页面。
+- 后端新增可选查询参数，默认参数行为与原有调用兼容；不改变租户、数据范围、额度账本、附件保存或 SQL。
+
+## 验收
+
+三页检索/工具栏与运输计划采用同组件；每个有意义的业务列有可用漏斗；筛选结果和分页总数一致；跨页数据可筛到；清空、组合条件、日期边界、状态多选、快速切换及失效响应有回归覆盖。默认 Agent 专项测试及合成页面视觉验证，真实业务写入与生产环境不在范围内。