From 088ed0f8716a2b50f14733a0b385d0e9615d9615 Mon Sep 17 00:00:00 2001 From: wuzilong <704541015@qq.com> Date: Thu, 29 Oct 2026 16:35:39 +0800 Subject: [PATCH] docs: add implementation plan for other dispatch calendar tab. Co-authored-by: Cursor --- ...2026-10-29-dispatch-calendar-other-kind.md | 368 ++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-29-dispatch-calendar-other-kind.md diff --git a/docs/superpowers/plans/2026-10-29-dispatch-calendar-other-kind.md b/docs/superpowers/plans/2026-10-29-dispatch-calendar-other-kind.md new file mode 100644 index 000000000..f1d34da55 --- /dev/null +++ b/docs/superpowers/plans/2026-10-29-dispatch-calendar-other-kind.md @@ -0,0 +1,368 @@ +# 派车日历「其他日历」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:** 在 Web 与小程序 H5 派车日历页的「碱派车日历」后增加「其他日历」Tab，`calendarKind=other`，功能与样式与酸/碱手工日历一致。 + +**Architecture:** 扩展现有 `calendar_kind` 枚举（`acid | alkali | other`），复用 `ManualCalendar` / API / 权限；仅改校验、类型、入口 Tab 与字段 COMMENT。不建新表、不新增权限码。 + +**Tech Stack:** Python 3.9 / FastAPI / SQLAlchemy / MySQL 5.7 / Vue 3 / Element Plus / Vant / pytest / tsx。 + +**Spec:** `docs/superpowers/specs/2026-10-29-dispatch-calendar-other-kind-design.md` + +--- + +## File map + +| File | Responsibility | +|------|----------------| +| `backend/tests/test_pl_dispatch_calendar.py` | 扩展隔离与校验测试覆盖 `other` | +| `backend/app/services/pl_dispatch_calendar_service.py` | `CALENDAR_KINDS` 与 422 文案 | +| `backend/app/schemas/pl/dispatch_calendar.py` | CreateBody `calendar_kind` 校验 | +| `backend/app/models/pl_dispatch_calendar.py` | 列 COMMENT | +| `docs/sql/migrations/2026-10-29-dispatch-calendar-other-kind.sql` | 幂等更新 COMMENT | +| `docs/sql/migrations/2026-10-26-manual-dispatch-calendar.sql` | 建表 COMMENT 与现状对齐（文档一致性） | +| `docs/sql/migrations/2026-10-27-dispatch-calendar-kind.sql` | ADD COLUMN COMMENT 与现状对齐 | +| `web-admin/src/api/pl/dispatch-calendar.ts` | `DispatchCalendarKind` 加 `'other'` | +| `web-admin/src/views/pl/dispatch-calendar/index.vue` | Web Tab + 主题 | +| `web-admin/src/views/m/pl/dispatch-calendar/index.vue` | H5 Tab | +| `web-admin/scripts/pl-dispatch-calendar.test.ts` | 可选：断言 Tab 文案顺序（若已有入口断言则扩展） | + +不改：`useManualCalendar.ts`、`ManualCalendar.vue` 内部逻辑（已按 prop `calendarKind` 工作）、车辆/产品 API、实际派车信息、菜单权限 SQL。 + +--- + +### Task 1: 后端 — `other` 校验与隔离测试先行 + +**Files:** +- Modify: `backend/tests/test_pl_dispatch_calendar.py` +- Modify: `backend/app/services/pl_dispatch_calendar_service.py` +- Modify: `backend/app/schemas/pl/dispatch_calendar.py` +- Modify: `backend/app/models/pl_dispatch_calendar.py` + +- [ ] **Step 1: 扩展失败测试（先跑应红）** + +在 `test_acid_and_alkali_calendars_stay_separate` 末尾追加 `other` 断言，或新增同文件测试： + +```python +def test_other_calendar_stays_separate_from_acid_and_alkali(db): + _, update, _, svc = modules() + create(db) # acid default + create(db, calendarKind='alkali', origin='碱库') + other = create(db, calendarKind='other', origin='其他库') + other_page = svc.list_records(db, 't1', user(), month='2026-10', calendar_kind='other') + assert other_page['total'] == 1 and other_page['list'][0]['id'] == other.id + assert other_page['list'][0]['calendarKind'] == 'other' + assert svc.list_records(db, 't1', user(), month='2026-10')['total'] == 1 + assert svc.list_records(db, 't1', user(), month='2026-10', calendar_kind='alkali')['total'] == 1 + with pytest.raises(HTTPException) as moved: + svc.update_record(db, 't1', user(), other.id, update(**payload(calendarKind='acid'))) + assert moved.value.status_code == 422 + kept = svc.update_record( + db, 't1', user(), other.id, update(**payload(calendarKind='other', destination='合肥')) + ) + assert kept.destination == '合肥' and kept.calendar_kind == 'other' +``` + +在 `test_http_read_only_manage_permissions_both_clients_and_routes` 中碱断言后追加： + +```python + other = client.post(path, json=payload(calendarKind='other')) + assert other.status_code == 200 and other.json()['calendarKind'] == 'other' + assert client.get(path, params={'month': '2026-10', 'calendarKind': 'other'}).json()['total'] == 1 + assert client.put(f"{path}/{other.json()['id']}", json=payload(calendarKind='alkali')).status_code == 422 +``` + +（`{'calendarKind': 'salt'}` 已在 schema 参数化测试中，保持即可。） + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd backend && source venv/bin/activate && python -m pytest tests/test_pl_dispatch_calendar.py::test_other_calendar_stays_separate_from_acid_and_alkali -q +``` + +Expected: FAIL（schema/service 仍拒绝 `other`）。 + +- [ ] **Step 3: 最小实现** + +`backend/app/services/pl_dispatch_calendar_service.py`： + +```python +CALENDAR_KINDS = ("acid", "alkali", "other") + + +def _calendar_kind(kind: Optional[str]) -> str: + value = kind or "acid" + if value not in CALENDAR_KINDS: + raise HTTPException(status_code=422, detail="日历类型须为 acid、alkali 或 other") + return value +``` + +`backend/app/schemas/pl/dispatch_calendar.py` 的 `validate_calendar_kind`： + +```python + def validate_calendar_kind(cls, value: str) -> str: + if value not in ("acid", "alkali", "other"): + raise ValueError("日历类型须为 acid、alkali 或 other") + return value +``` + +`backend/app/models/pl_dispatch_calendar.py` COMMENT： + +```python + comment="日历类型：acid酸派车 alkali碱派车 other其他", +``` + +- [ ] **Step 4: 跑全文件测试** + +```bash +cd backend && source venv/bin/activate && python -m pytest tests/test_pl_dispatch_calendar.py -q +``` + +Expected: PASS（全部绿）。 + +- [ ] **Step 5: Commit** + +```bash +git add backend/tests/test_pl_dispatch_calendar.py \ + backend/app/services/pl_dispatch_calendar_service.py \ + backend/app/schemas/pl/dispatch_calendar.py \ + backend/app/models/pl_dispatch_calendar.py +git commit -m "$(cat <<'EOF' +feat: allow dispatch calendar kind other on backend. + +EOF +)" +``` + +--- + +### Task 2: SQL COMMENT 迁移 + +**Files:** +- Create: `docs/sql/migrations/2026-10-29-dispatch-calendar-other-kind.sql` +- Modify: `docs/sql/migrations/2026-10-26-manual-dispatch-calendar.sql`（COMMENT 文案） +- Modify: `docs/sql/migrations/2026-10-27-dispatch-calendar-kind.sql`（COMMENT 文案） + +- [ ] **Step 1: 新建幂等迁移** + +```sql +-- 手工派车日历增加 other（其他日历）。仅更新 COMMENT，无结构变更。 +-- MySQL 5.7 / utf8mb4。可重复执行。 +SET NAMES utf8mb4; + +SET @col_exists = ( + SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'pl_dispatch_calendar' + AND COLUMN_NAME = 'calendar_kind' +); +SET @ddl = IF( + @col_exists = 1, + 'ALTER TABLE `pl_dispatch_calendar` MODIFY COLUMN `calendar_kind` varchar(16) NOT NULL DEFAULT ''acid'' COMMENT ''日历类型：acid酸派车 alkali碱派车 other其他''', + 'SELECT 1' +); +PREPARE stmt FROM @ddl; +EXECUTE stmt; +DEALLOCATE PREPARE stmt; +``` + +- [ ] **Step 2: 同步历史迁移文件中的 COMMENT 字符串** + +将两处 `acid酸派车 alkali碱派车` 改为 `acid酸派车 alkali碱派车 other其他`（仅文档/幂等 ADD 文案，不影响已执行库；新环境建表即含完整注释）。 + +- [ ] **Step 3: 在本地库执行一次并复查** + +```bash +# 使用项目惯用方式连接当前库后执行该 SQL；第二次执行应无结构报错 +``` + +Expected: `calendar_kind` COMMENT 含 `other`；重复执行成功。 + +- [ ] **Step 4: Commit** + +```bash +git add docs/sql/migrations/2026-10-29-dispatch-calendar-other-kind.sql \ + docs/sql/migrations/2026-10-26-manual-dispatch-calendar.sql \ + docs/sql/migrations/2026-10-27-dispatch-calendar-kind.sql +git commit -m "$(cat <<'EOF' +docs(sql): note other kind on dispatch calendar_kind. + +EOF +)" +``` + +--- + +### Task 3: 前端类型与双端 Tab + +**Files:** +- Modify: `web-admin/src/api/pl/dispatch-calendar.ts` +- Modify: `web-admin/src/views/pl/dispatch-calendar/index.vue` +- Modify: `web-admin/src/views/m/pl/dispatch-calendar/index.vue` +- Modify: `web-admin/scripts/pl-dispatch-calendar.test.ts`（仅当该文件已断言路由/入口时可追加 Tab 顺序；否则可跳过，改用浏览器手测） + +- [ ] **Step 1: 扩展类型** + +`web-admin/src/api/pl/dispatch-calendar.ts`： + +```typescript +export type DispatchCalendarKind = 'acid' | 'alkali' | 'other' +``` + +- [ ] **Step 2: Web 入口** + +`web-admin/src/views/pl/dispatch-calendar/index.vue` 完整替换为： + +```vue + + + + +``` + +- [ ] **Step 3: H5 入口** + +在 `web-admin/src/views/m/pl/dispatch-calendar/index.vue`： + +模板 Tab 区改为： + +```vue + + + + + + +``` + +内容区改为： + +```vue + + + + +``` + +- [ ] **Step 4: 定向测试与 lint** + +```bash +cd web-admin && pnpm exec tsx --test scripts/manual-dispatch-calendar.test.ts scripts/pl-dispatch-calendar.test.ts +``` + +Expected: 既有测试 PASS。 + +对改动文件跑 ESLint / Prettier（项目惯用命令）。Expected: 无新增错误。 + +- [ ] **Step 5: Commit** + +```bash +git add web-admin/src/api/pl/dispatch-calendar.ts \ + web-admin/src/views/pl/dispatch-calendar/index.vue \ + web-admin/src/views/m/pl/dispatch-calendar/index.vue +git commit -m "$(cat <<'EOF' +feat: add other dispatch calendar tab on web and h5. + +EOF +)" +``` + +--- + +### Task 4: 验证与图谱 + +**Files:** 无新业务文件；执行命令与记录。 + +- [ ] **Step 1: 后端回归** + +```bash +cd backend && source venv/bin/activate && python -m pytest tests/test_pl_dispatch_calendar.py -q +``` + +Expected: PASS。 + +- [ ] **Step 2: 手测清单（Web + H5）** + +1. 四个 Tab 顺序：酸 → 碱 → 其他日历 → 实际派车信息 +2. 「其他日历」新增一条，切到酸/碱看不到；酸/碱记录在「其他」看不到 +3. 编辑保存、删除、筛选车辆、复制当天计划可用；Web 打印可用 +4. 「实际派车信息」筛选/汇总无异常；手工主题色在「其他日历」仍为深蓝 `#1f4e79` + +- [ ] **Step 3: 更新知识图谱** + +```bash +./scripts/update-graph.sh all +# 或按仓库规则：backend + web-admin 增量；根目录 graphify update . +``` + +- [ ] **Step 4: 最终 commit（若有图谱或小修）** + +仅暂存图谱/修复相关文件后： + +```bash +git commit -m "$(cat <<'EOF' +chore: refresh graph after other calendar kind. + +EOF +)" +``` + +--- + +## Spec coverage self-check + +| Spec 要求 | Task | +|-----------|------| +| 两端增加「其他日历」Tab，顺序在碱后、实际前 | Task 3 | +| 功能/样式与酸碱一致，复用 ManualCalendar | Task 3 | +| `calendarKind=other`，产品车辆选择器不变 | Task 1 + 3（不改 options API） | +| 数据隔离、不可改 kind | Task 1 | +| 无新权限码 | 无菜单任务（刻意不做） | +| COMMENT 迁移 | Task 2 | +| 实际派车信息不回归 | Task 4 手测 | +| 测试 / lint / 图谱 | Task 1、3、4 |