diff --git a/docs/superpowers/plans/2026-09-02-pl-plan-draft-save.md b/docs/superpowers/plans/2026-09-02-pl-plan-draft-save.md new file mode 100644 index 000000000..cde4f6754 --- /dev/null +++ b/docs/superpowers/plans/2026-09-02-pl-plan-draft-save.md @@ -0,0 +1,540 @@ +# 运输计划「暂存 / 草稿中」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:** 在运输计划新增/编辑弹窗支持【暂存】(跟进状态 `drafting` / 草稿中),列表「待安排/草稿」Tab 默认同时展示待安排与草稿,正式保存将草稿升为待安排。 + +**Architecture:** 跟进状态新增 `drafting`;`create-full` / `PUT` 增加 `saveMode: 'draft' | 'formal'`。draft 仅校验归属公司(创建日期可缺省当天),跳过业务校验;formal 保持全量校验并在原状态为 `drafting` 时升为 `pending_arrange`。前端展示常量、列表 Tab/筛选、弹窗按钮对齐该状态机。 + +**Tech Stack:** FastAPI + SQLAlchemy + Pydantic v2 + pytest;Vue 3 + Element Plus + TypeScript + +**Spec:** `docs/superpowers/specs/2026-09-02-pl-plan-draft-save-design.md` + +**注意:** 工作区可能有无关未提交改动(如 `backend/app.pid`)。只改本计划列出的文件,提交时勿夹带无关 diff。 + +--- + +## 文件结构 + +| 操作 | 文件 | 职责 | +|------|------|------| +| Create | `backend/tests/test_pl_plan_draft_save.py` | `saveMode` / 草稿门禁纯函数单测 | +| Modify | `backend/app/services/pl_plan_service.py` | `validate_draft_min_fields`、`resolve_follow_status_on_save`、`assert_can_save_as_draft` | +| Modify | `backend/app/schemas/pl/plan.py` | `PlanCreateFull` / `PlanUpdate` 增加 `save_mode`;跟进状态注释含 `drafting` | +| Modify | `backend/app/api/pl/plan.py` | create-full / update 的 draft 分支;wait-notice / delete / force 白名单 | +| Modify | `web-admin/src/utils/pl-display.ts` | 选项、默认筛选、Tab 文案与 filter、Tag/Label | +| Modify | `web-admin/src/api/pl/index.ts` | `saveMode` 类型 | +| Modify | `web-admin/src/views/pl/plan/index.vue` | Tab 切入默认值、取消 disabled、canWaitNotice | +| Modify | `web-admin/src/components/business/pl-plan-form-dialog/index.vue` | 【暂存】按钮与 draft 提交路径 | +| Verify | `web-admin/src/views/pl/plan-cert/index.vue` | 默认筛选随 `PL_PLAN_DEFAULT_FOLLOW_STATUSES` 自动含草稿 | + +--- + +### Task 1: 后端纯函数 — 草稿校验与跟进状态决议 + +**Files:** +- Create: `backend/tests/test_pl_plan_draft_save.py` +- Modify: `backend/app/services/pl_plan_service.py` + +- [ ] **Step 1: 写失败单测** + +在 `backend/tests/test_pl_plan_draft_save.py`: + +```python +import pytest +from fastapi import HTTPException + +from app.services.pl_plan_service import ( + DRAFTABLE_FOLLOW_STATUSES, + assert_can_save_as_draft, + resolve_follow_status_on_save, + validate_draft_min_fields, +) + + +def test_validate_draft_min_fields_requires_belongs_company(): + with pytest.raises(HTTPException) as exc: + validate_draft_min_fields(belongs_company="", create_date=None) + assert exc.value.status_code == 422 + assert "归属公司" in str(exc.value.detail) + + +def test_validate_draft_min_fields_allows_missing_create_date(): + validate_draft_min_fields(belongs_company="shanxia", create_date=None) + + +def test_resolve_follow_status_draft_always_drafting(): + assert resolve_follow_status_on_save(save_mode="draft", current="pending_arrange", is_create=False) == "drafting" + assert resolve_follow_status_on_save(save_mode="draft", current=None, is_create=True) == "drafting" + + +def test_resolve_follow_status_formal_promotes_drafting(): + assert resolve_follow_status_on_save(save_mode="formal", current=None, is_create=True) == "pending_arrange" + assert resolve_follow_status_on_save(save_mode="formal", current="drafting", is_create=False) == "pending_arrange" + assert resolve_follow_status_on_save(save_mode="formal", current="arranged", is_create=False) == "arranged" + assert resolve_follow_status_on_save(save_mode="formal", current="wait_notice", is_create=False) == "wait_notice" + + +def test_assert_can_save_as_draft_rejects_arranged(): + assert "drafting" in DRAFTABLE_FOLLOW_STATUSES + assert "pending_arrange" in DRAFTABLE_FOLLOW_STATUSES + with pytest.raises(HTTPException) as exc: + assert_can_save_as_draft("arranged") + assert exc.value.status_code == 400 + assert "不可暂存" in str(exc.value.detail) +``` + +- [ ] **Step 2: 运行确认失败** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_plan_draft_save.py -v +``` + +Expected: FAIL(符号未定义) + +- [ ] **Step 3: 实现纯函数** + +在 `backend/app/services/pl_plan_service.py`(靠近 `validate_create_full`)新增: + +```python +DRAFTABLE_FOLLOW_STATUSES = frozenset({"drafting", "pending_arrange"}) + + +def validate_draft_min_fields(*, belongs_company: Optional[str], create_date) -> None: + if not (belongs_company or "").strip(): + raise HTTPException(status_code=422, detail="请选择归属公司") + # create_date 允许为空,由 create/update 用 _resolve_create_date 兜底当天 + + +def resolve_follow_status_on_save( + *, + save_mode: str, + current: Optional[str], + is_create: bool, +) -> str: + mode = (save_mode or "formal").strip() or "formal" + if mode == "draft": + return "drafting" + if is_create: + return "pending_arrange" + if current == "drafting": + return "pending_arrange" + return (current or "pending_arrange").strip() or "pending_arrange" + + +def assert_can_save_as_draft(current_status: Optional[str]) -> None: + status = (current_status or "").strip() + if status not in DRAFTABLE_FOLLOW_STATUSES: + raise HTTPException(status_code=400, detail="当前状态不可暂存") +``` + +确保已有 `Optional`、`HTTPException` 导入。 + +- [ ] **Step 4: 运行确认通过** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_plan_draft_save.py -v +``` + +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add backend/tests/test_pl_plan_draft_save.py backend/app/services/pl_plan_service.py +git commit -m "$(cat <<'EOF' +feat(backend): add draft save helpers for plan follow status drafting + +Introduce min-field validation and follow_status resolution for saveMode draft/formal. +EOF +)" +``` + +--- + +### Task 2: Schema 增加 `saveMode` + +**Files:** +- Modify: `backend/app/schemas/pl/plan.py` + +- [ ] **Step 1: 更新跟进状态字段说明** + +`PlanBase.follow_status` 的 description 改为: + +`跟进状态 drafting/wait_notice/pending_arrange/arranged/completed/cancelled` + +`PlanForceFollowStatusBody` 同类 description 同步。 + +- [ ] **Step 2: 在 `PlanCreateFull` 与 `PlanUpdate` 增加字段** + +```python +save_mode: Optional[str] = Field( + default="formal", + alias="saveMode", + description="保存模式 draft=暂存 formal=正式(默认)", +) +``` + +后续 update 的 `model_dump(exclude=...)` 必须排除 `save_mode`,勿写入 ORM。 + +- [ ] **Step 3: Commit** + +```bash +git add backend/app/schemas/pl/plan.py +git commit -m "$(cat <<'EOF' +feat(backend): add saveMode field on plan create-full and update schemas +EOF +)" +``` + +--- + +### Task 3: create-full / update 接入 draft / formal + +**Files:** +- Modify: `backend/app/api/pl/plan.py` + +- [ ] **Step 1: 导入 helper** + +从 `pl_plan_service` 增加导入: + +`assert_can_save_as_draft`, `resolve_follow_status_on_save`, `validate_draft_min_fields` + +- [ ] **Step 2: 改造 `create_plan_full`** + +开头: + +```python +save_mode = (getattr(payload, "save_mode", None) or "formal").strip() or "formal" +is_draft = save_mode == "draft" +``` + +草稿分支: + +```python +if is_draft: + validate_draft_min_fields( + belongs_company=payload.belongs_company, + create_date=payload.create_date, + ) + multi_stop = uses_multi_stop_payload(payload.load, payload.deliveries) + qty_warnings: list[str] = [] + load_body = None + delivery_bodies: list = [] + supplier_contracts: list = [] + demander_contracts: list = [] + # 跳过 validate_create_full / validate_plan_party_contracts + # 尝试段校验;失败则只落主表+products,不写段 + if multi_stop and payload.load is not None: + try: + load_body, delivery_bodies = validate_plan_stops_write( + db, tenant_no, payload.load, payload.deliveries, payload.products, + ) + qty_warnings = collect_stop_qty_warnings(payload.products, load_body, delivery_bodies) + except HTTPException: + load_body, delivery_bodies = None, [] + multi_stop = False +else: + # 保持现有 multi_stop / validate_create_full 逻辑 + ... +``` + +创建 `PlPlan`: + +```python +follow_status=resolve_follow_status_on_save( + save_mode=save_mode, current=None, is_create=True +), +``` + +`create_date` 继续 `_resolve_create_date(payload.create_date)`。 +段写入仍:`if multi_stop and load_body is not None: replace_plan_stops(...)`。 +允许 `products` 为空。 + +- [ ] **Step 3: 改造 `update_plan`** + +cancelled 检查之后: + +```python +save_mode = (getattr(payload, "save_mode", None) or "formal").strip() or "formal" +is_draft = save_mode == "draft" +if is_draft: + assert_can_save_as_draft(plan.follow_status) + validate_draft_min_fields( + belongs_company=payload.belongs_company if payload.belongs_company is not None else plan.belongs_company, + create_date=payload.create_date if payload.create_date is not None else plan.create_date, + ) +``` + +`model_dump` 的 `exclude` 增加 `"save_mode"`。 + +草稿时跳过强制 `validate_plan_party_contracts`;段写入同 create:try `validate_plan_stops_write`,失败则 **不调用** `replace_plan_stops`(保留原段)。 + +`db.commit()` 前: + +```python +plan.follow_status = resolve_follow_status_on_save( + save_mode=save_mode, + current=plan.follow_status, + is_create=False, +) +``` + +- [ ] **Step 4: 导入检查** + +```bash +cd backend && source venv/bin/activate && python -c "from app.api.pl import plan; print('ok')" +``` + +- [ ] **Step 5: Commit** + +```bash +git add backend/app/api/pl/plan.py +git commit -m "$(cat <<'EOF' +feat(backend): support saveMode draft/formal on plan create-full and update + +Draft skips business validators and writes follow_status drafting; formal promotes drafting to pending_arrange. +EOF +)" +``` + +--- + +### Task 4: wait-notice / delete / force-follow-status 对齐草稿 + +**Files:** +- Modify: `backend/app/api/pl/plan.py` + +- [ ] **Step 1: `mark_plan_wait_notice`** + +```python +if plan.follow_status not in ("pending_arrange", "drafting"): + raise HTTPException(status_code=400, detail="仅待安排或草稿中状态可标记为等通知") +``` + +- [ ] **Step 2: `delete_plan`** + +```python +if plan.follow_status not in ("pending_arrange", "wait_notice", "drafting"): + raise HTTPException(status_code=400, detail="只能删除待安排、草稿中或等通知且未安排运输的计划") +``` + +- [ ] **Step 3: `ALLOWED_FORCE_FOLLOW_STATUSES`** + +```python +ALLOWED_FORCE_FOLLOW_STATUSES = frozenset( + {"drafting", "wait_notice", "pending_arrange", "arranged", "completed", "cancelled"} +) +``` + +错误文案加上「草稿中」。确认安排成功路径已写 `follow_status = "arranged"`(`pl_plan_service` / `transport.py`),草稿安排后可离开草稿态。 + +- [ ] **Step 4: Commit** + +```bash +git add backend/app/api/pl/plan.py +git commit -m "$(cat <<'EOF' +feat(backend): allow drafting plans for wait-notice, delete, and force status +EOF +)" +``` + +--- + +### Task 5: 前端展示常量与列表 Tab/筛选 + +**Files:** +- Modify: `web-admin/src/utils/pl-display.ts` +- Modify: `web-admin/src/views/pl/plan/index.vue` +- Verify: `web-admin/src/views/pl/plan-cert/index.vue` + +- [ ] **Step 1: 更新 `pl-display.ts`** + +```typescript +export const PL_PLAN_LIST_TABS: { label: string; name: PlPlanListTab }[] = [ + { label: '待安排/草稿', name: 'pending_arrange' }, // name 保留;语义含 drafting + ...PL_PLAN_TYPE_TABS +] + +// 待安排/草稿 Tab 不再返回 followStatus,改由 searchForm 控制,避免与多选冲突 +export function plPlanListTabToFilters(tab: PlPlanListTab): { + planType: string + followStatus?: string +} { + if (tab === 'pending_arrange') { + return { planType: '' } + } + return { planType: plPlanTypeTabToFilter(tab) } +} + +export const PL_PLAN_FOLLOW_STATUS_OPTIONS = [ + { label: '草稿中', value: 'drafting' }, + { label: '等通知', value: 'wait_notice' }, + { label: '待安排', value: 'pending_arrange' }, + { label: '已安排', value: 'arranged' }, + { label: '已完成', value: 'completed' }, + { label: '已取消', value: 'cancelled' } +] as const + +// PL_PLAN_DEFAULT_FOLLOW_STATUSES 仍排除 cancelled,将自动含 drafting +``` + +Tag/Label 增加 `drafting: 'info'` / `'草稿中'`;**保留**旧 `draft → '待安排'` 兼容,勿改成草稿中。 + +- [ ] **Step 2: 更新 `plan/index.vue`** + +1. 删除跟进状态 select 的 `:disabled="activePlanTypeTab === 'pending_arrange'"` +2. 初始与重置:`followStatus: ['pending_arrange', 'drafting']` +3. Tab 切换: + +```typescript +if (nextTab === 'pending_arrange') { + searchForm.followStatus = ['pending_arrange', 'drafting'] +} else if (prevTab === 'pending_arrange') { + searchForm.followStatus = [...PL_PLAN_DEFAULT_FOLLOW_STATUSES] +} +``` + +4. `canWaitNotice`: + +```typescript +function canWaitNotice(row: Plan) { + return ( + (row.followStatus === 'pending_arrange' || row.followStatus === 'drafting') && + row.archiveStatus !== 'archived' + ) +} +``` + +5. 强制改状态选项使用 `PL_PLAN_FOLLOW_STATUS_OPTIONS`。 +6. `fetchData` / export 继续:`followStatus: tabFilters.followStatus || formatFollowStatusParam(searchForm.followStatus)`(pending_arrange Tab 时 tabFilters 无 followStatus,走 searchForm)。 + +- [ ] **Step 3: 核对 plan-cert** + +确认重置使用 `PL_PLAN_DEFAULT_FOLLOW_STATUSES` 即可自动含 `drafting`。 + +- [ ] **Step 4: Commit** + +```bash +git add web-admin/src/utils/pl-display.ts web-admin/src/views/pl/plan/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): show drafting in plan list tab and follow-status filters + +Rename pending tab to 待安排/草稿 and default-select pending_arrange + drafting. +EOF +)" +``` + +--- + +### Task 6: API 类型 + 弹窗【暂存】 + +**Files:** +- Modify: `web-admin/src/api/pl/index.ts` +- Modify: `web-admin/src/components/business/pl-plan-form-dialog/index.vue` + +- [ ] **Step 1: 类型** + +`PlanCreateFullPayload` 增加:`saveMode?: 'draft' | 'formal'` + +- [ ] **Step 2: 弹窗按钮与状态** + +`loadPlanForEdit` 记录 `loadedFollowStatus`;reset/copy 清或带源状态。 + +```typescript +const showDraftButton = computed(() => { + if (!isEdit.value) return true + return loadedFollowStatus.value === 'drafting' || loadedFollowStatus.value === 'pending_arrange' +}) +``` + +Footer 在取消与创建/保存之间: + +```vue + + 暂存 + +``` + +导入 `Document`(`@element-plus/icons-vue`)。 + +- [ ] **Step 3: `handleSubmit('draft')`** + +签名增加 `'draft'`。draft 分支: + +- 只校验 `belongsCompany`、`createDate` 非空;失败 Message + `validateField` 这两项 +- `saveMode: 'draft'` 调 `createFull` / `update` +- 成功「暂存成功」、关窗、`emit('success')`;新建用返回的 planId +- **不**跑 `validateBusinessRules` / 合同 / 安排校验 + +formal 的 save/安排路径传 `saveMode: 'formal'` 或不传(后端默认 formal)。 + +- [ ] **Step 4: Commit** + +```bash +git add web-admin/src/api/pl/index.ts web-admin/src/components/business/pl-plan-form-dialog/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): add plan form draft save button with saveMode drafting +EOF +)" +``` + +--- + +### Task 7: 验收与图谱 + +- [ ] **Step 1: 后端单测** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_plan_draft_save.py -v +``` + +Expected: PASS + +- [ ] **Step 2: 手工验收(spec §7)** + +1. 新建仅公司+日期 → 暂存 → 列表「草稿中」出现在「待安排/草稿」 +2. 编辑草稿 → 保存 → 「待安排」 +3. 编辑待安排 → 暂存 → 「草稿中」 +4. 已安排编辑 → 无【暂存】 +5. Tab 默认两项;多选可再筛 +6. 草稿等通知/安排:失败有校验提示;成功离开草稿 +7. 草稿可删(未安排未归档) + +- [ ] **Step 3: 更新知识图谱** + +```bash +./scripts/update-graph.sh backend +./scripts/update-graph.sh frontend +``` + +- [ ] **Step 4: 若有图谱变更则提交** + +```bash +git add backend/graphify-out web-admin/graphify-out +git commit -m "$(cat <<'EOF' +chore: update graphify after plan draft-save feature +EOF +)" +``` + +--- + +## Spec 覆盖自检 + +| Spec 要求 | Task | +|-----------|------| +| `drafting` 状态与文案 | 1, 5 | +| `saveMode` draft/formal | 2, 3, 6 | +| 暂存仅公司+日期 | 1, 3, 6 | +| 正式保存草稿→待安排 | 1, 3, 6 | +| Tab「待安排/草稿」+ 默认两项 | 5 | +| 多选可用、Tab 不禁用 | 5 | +| 暂存按钮可见性 | 6 | +| wait-notice / delete / force 含 drafting | 4 | +| 列表操作与待安排相同 | 4, 5 | +| 不改 archive draft | 未改 archive 接口 |