docs: add implementation plan for plan contract completion

Break down backend gap APIs, menu badge, SQL menu, and the inline-expand web-admin page into sequenced tasks with verification steps.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/plans/2026-08-20-pl-plan-contract-complete.md

@@ -0,0 +1,675 @@
+# 运输计划合同完善 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:** 新增独立菜单页「运输计划合同完善」：只列出未作废且仍缺合同的计划，支持行内展开、分侧多选并各自保存已有 CRM 合同，并显示侧栏待完善角标。
+
+**Architecture:** 后端在 `pl_plan_service` 提供缺口判定与 SQL 过滤，暴露 `GET /transport/plan/contract-gaps` 与 `PUT /transport/plan/{id}/contracts/{side}`；角标复用 `pl_menu_badge_service`。前端新页 `views/pl/plan-contract/index.vue` 用 `el-table` 展开行 + 复用 `PlPlanContractMultiSelect`/`ContractSelector`，不打开合同表单。
+
+**Tech Stack:** FastAPI + SQLAlchemy + MySQL；Vue 3 + Element Plus；现有 `planApi` / 菜单角标
+
+**Spec:** `docs/superpowers/specs/2026-08-20-pl-plan-contract-complete-design.md`  
+**Demo:** `docs/fresh-mint-pl-plan-contract-complete-demo.html`（方案 B）
+
+---
+
+## File map
+
+| 操作 | 文件 | 职责 |
+|------|------|------|
+| Create | `backend/app/services/pl_plan_contract_gap.py` | 缺口判定纯函数 + SQL EXISTS 过滤器 + 列表装配辅助 |
+| Modify | `backend/app/schemas/pl/plan.py` | `PlanContractGapRead`、`PlanSideContractsUpdateBody`、列表响应 |
+| Modify | `backend/app/api/pl/plan.py` | `GET /contract-gaps`（须在 `/{id}` 之前）、`PUT /{id}/contracts/{side}` |
+| Modify | `backend/app/services/pl_plan_service.py` | 复用 `replace_plan_contracts` / `assert_contract_selectable_for_plan` / `load_plan_contracts_grouped`（单侧保存编排可放 gap 模块或本文件） |
+| Modify | `backend/app/services/pl_menu_badge_service.py` | `MENU_CODE_PLAN_CONTRACT` + `count_plan_contract_gaps` |
+| Create | `backend/tests/test_pl_plan_contract_gap.py` | 缺口判定与 EXISTS SQL 编译单测 |
+| Create | `backend/scripts/migrate_20260820_pl_plan_contract_complete_menu.sql` | 菜单 + 按钮权限（幂等） |
+| Modify | `web-admin/src/api/pl/index.ts` | `listContractGaps` / `updatePlanSideContracts` 类型与方法 |
+| Modify | `web-admin/src/router/modules/pl.ts` | `plan-contract` 子路由 |
+| Create | `web-admin/src/views/pl/plan-contract/index.vue` | 列表 + 行内展开 + 查看弹窗 |
+| Modify | `web-admin/src/App.vue`（若需） | `panelTitleBarTextRules` 注册「运输计划合同完善」 |
+| Modify | graphify | 改完后 `./scripts/update-graph.sh all` |
+
+---
+
+### Task 1: 缺口判定纯函数 + 单测
+
+**Files:**
+- Create: `backend/app/services/pl_plan_contract_gap.py`
+- Create: `backend/tests/test_pl_plan_contract_gap.py`
+
+- [ ] **Step 1: 写失败单测（红）**
+
+```python
+# backend/tests/test_pl_plan_contract_gap.py
+from app.services.pl_plan_contract_gap import compute_contract_gap_sides
+from app.services.pl_internal_customer import INTERNAL_CUSTOMER_NAMES
+
+INTERNAL = next(iter(INTERNAL_CUSTOMER_NAMES))
+
+
+def test_both_external_no_contracts_gaps_both():
+    sides = compute_contract_gap_sides(
+        supplier_name="外部供方A",
+        customer_name="外部需方B",
+        supplier_contract_count=0,
+        demander_contract_count=0,
+    )
+    assert sides == ["supplier", "demander"]
+
+
+def test_internal_supplier_external_demander_missing_only_demander():
+    sides = compute_contract_gap_sides(
+        supplier_name=INTERNAL,
+        customer_name="外部需方B",
+        supplier_contract_count=0,
+        demander_contract_count=0,
+    )
+    assert sides == ["demander"]
+
+
+def test_both_internal_no_gap():
+    sides = compute_contract_gap_sides(
+        supplier_name=INTERNAL,
+        customer_name=INTERNAL,
+        supplier_contract_count=0,
+        demander_contract_count=0,
+    )
+    assert sides == []
+
+
+def test_external_with_contracts_no_gap():
+    sides = compute_contract_gap_sides(
+        supplier_name="外部供方A",
+        customer_name="外部需方B",
+        supplier_contract_count=1,
+        demander_contract_count=2,
+    )
+    assert sides == []
+```
+
+- [ ] **Step 2: 跑测确认失败**
+
+```bash
+cd backend && source venv/bin/activate && pytest tests/test_pl_plan_contract_gap.py -v
+```
+
+Expected: FAIL（模块或函数不存在）
+
+- [ ] **Step 3: 实现纯函数**
+
+```python
+# backend/app/services/pl_plan_contract_gap.py
+from __future__ import annotations
+from typing import List, Optional
+
+from app.services.pl_internal_customer import is_internal_customer_name
+
+def compute_contract_gap_sides(
+    *,
+    supplier_name: Optional[str],
+    customer_name: Optional[str],
+    supplier_contract_count: int,
+    demander_contract_count: int,
+) -> List[str]:
+    gaps: List[str] = []
+    if not is_internal_customer_name(supplier_name) and supplier_contract_count <= 0:
+        gaps.append("supplier")
+    if not is_internal_customer_name(customer_name) and demander_contract_count <= 0:
+        gaps.append("demander")
+    return gaps
+
+
+def side_is_exempt(name: Optional[str]) -> bool:
+    return is_internal_customer_name(name)
+```
+
+- [ ] **Step 4: 跑测通过并提交**
+
+```bash
+pytest tests/test_pl_plan_contract_gap.py -v
+```
+
+```bash
+git add backend/app/services/pl_plan_contract_gap.py backend/tests/test_pl_plan_contract_gap.py
+git commit -m "feat(pl): add plan contract gap side computation helpers"
+```
+
+---
+
+### Task 2: SQL EXISTS 过滤器 + Schema
+
+**Files:**
+- Modify: `backend/app/services/pl_plan_contract_gap.py`
+- Modify: `backend/app/schemas/pl/plan.py`
+- Modify: `backend/tests/test_pl_plan_contract_gap.py`
+
+- [ ] **Step 1: 增加 EXISTS 过滤器（供列表 `query.filter(...)`）**
+
+在 `pl_plan_contract_gap.py` 增加：
+
+```python
+from sqlalchemy import and_, exists, func, or_, select
+from sqlalchemy.orm import Session
+from app.models.pl_models import PlPlan, PlPlanContract
+from app.services.pl_internal_customer import INTERNAL_CUSTOMER_NAMES
+from app.services.pl_plan_service import (
+    PLAN_CONTRACT_SIDE_DEMANDER,
+    PLAN_CONTRACT_SIDE_SUPPLIER,
+)
+
+def _side_has_contract_exists(plan_id_col, side: str):
+    return exists().where(
+        and_(
+            PlPlanContract.plan_id == plan_id_col,
+            PlPlanContract.side == side,
+            PlPlanContract.del_flag == 0,
+        )
+    )
+
+def plan_has_contract_gap_exists():
+    """未作废计划中，任一侧（非内置且无合同）构成缺口。"""
+    supplier_gap = and_(
+        ~PlPlan.supplier_name.in_(tuple(INTERNAL_CUSTOMER_NAMES)),
+        ~_side_has_contract_exists(PlPlan.id, PLAN_CONTRACT_SIDE_SUPPLIER),
+    )
+    demander_gap = and_(
+        ~PlPlan.customer_name.in_(tuple(INTERNAL_CUSTOMER_NAMES)),
+        ~_side_has_contract_exists(PlPlan.id, PLAN_CONTRACT_SIDE_DEMANDER),
+    )
+    return or_(supplier_gap, demander_gap)
+```
+
+注意：`supplier_name` / `customer_name` 为 NULL 时，`NOT IN (内置)` 在 SQL 中为 UNKNOWN，不会命中缺口——与「无客户名」极少见一致；若需把空名当缺口，改为 `(name IS NULL OR name NOT IN (...))`。**本计划采用：空名视为非内置 → 缺合同**，实现时写成：
+
+```python
+supplier_not_internal = or_(
+    PlPlan.supplier_name.is_(None),
+    PlPlan.supplier_name == "",
+    ~PlPlan.supplier_name.in_(tuple(INTERNAL_CUSTOMER_NAMES)),
+)
+```
+
+- [ ] **Step 2: 单测编译 SQL**
+
+```python
+def test_plan_has_contract_gap_exists_mentions_contract_and_internal_names():
+    from sqlalchemy.dialects import mysql
+    from app.services.pl_plan_contract_gap import plan_has_contract_gap_exists
+    clause = plan_has_contract_gap_exists()
+    sql = str(clause.compile(dialect=mysql.dialect(), compile_kwargs={"literal_binds": True})).lower()
+    assert "pl_plan_contract" in sql
+    assert "supplier" in sql
+    assert "demander" in sql
+    assert "安庆市山峡化工有限公司" in sql or "shanxia" in sql  # 名称应被绑定进 SQL
+```
+
+（若 dialect 把中文绑成参数导致字面量不出现，改为断言 `pl_plan_contract` + `side` 即可。）
+
+- [ ] **Step 3: Schema**
+
+在 `backend/app/schemas/pl/plan.py` 增加（camelCase alias，与现有一致）：
+
+```python
+class PlanSideContractsUpdateBody(BaseModel):
+    contracts: list[PlanContractLink] = Field(default_factory=list)
+    model_config = {"populate_by_name": True}
+
+
+class PlanContractGapRead(BaseModel):
+    id: str
+    plan_no: str = Field(..., alias="planNo")
+    plan_date: Optional[date] = Field(None, alias="planDate")
+    follow_status: str = Field(..., alias="followStatus")
+    supplier_id: Optional[str] = Field(None, alias="supplierId")
+    supplier_name: Optional[str] = Field(None, alias="supplierName")
+    customer_id: Optional[str] = Field(None, alias="customerId")
+    customer_name: Optional[str] = Field(None, alias="customerName")
+    gap_sides: list[str] = Field(default_factory=list, alias="gapSides")
+    supplier_contract_exempt: bool = Field(..., alias="supplierContractExempt")
+    demander_contract_exempt: bool = Field(..., alias="demanderContractExempt")
+    supplier_contracts: list[PlanContractLink] = Field(default_factory=list, alias="supplierContracts")
+    demander_contracts: list[PlanContractLink] = Field(default_factory=list, alias="demanderContracts")
+    model_config = {"populate_by_name": True, "from_attributes": True}
+
+
+class PlanContractGapListResponse(BaseModel):
+    total: int
+    list: list[PlanContractGapRead]
+```
+
+并从 `app.schemas.pl` / `plan.py` 导出（若 `__init__.py` 有显式导出则补上）。
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add backend/app/services/pl_plan_contract_gap.py backend/app/schemas/pl/plan.py backend/tests/test_pl_plan_contract_gap.py
+git commit -m "feat(pl): add contract-gap SQL filter and response schemas"
+```
+
+---
+
+### Task 3: 列表 API `GET /contract-gaps`
+
+**Files:**
+- Modify: `backend/app/services/pl_plan_contract_gap.py`（或 `pl_plan_service.py`）增加 `list_plan_contract_gaps(...)`
+- Modify: `backend/app/api/pl/plan.py`
+
+- [ ] **Step 1: 服务函数签名（实现要点）**
+
+```python
+def list_plan_contract_gaps(
+    db: Session,
+    *,
+    tenant_no: str,
+    user,
+    page: int = 1,
+    page_size: int = 20,
+    plan_no: Optional[str] = None,
+    gap_type: Optional[str] = None,  # supplier | demander | both | None
+    customer_keyword: Optional[str] = None,
+    plan_date_from: Optional[date] = None,
+    plan_date_to: Optional[date] = None,
+    q: Optional[str] = None,
+) -> tuple[int, list[PlanContractGapRead]]:
+    query = db.query(PlPlan).filter(
+        PlPlan.tenant_no == tenant_no,
+        PlPlan.del_flag == 0,
+        PlPlan.follow_status != "cancelled",
+        plan_has_contract_gap_exists(),
+    )
+    query = apply_pl_scope(query, PlPlan, user, db, tenant_no)
+    # 可选筛选：plan_no / 日期 / 客户关键词 / q
+    # gap_type：在加载合同计数后内存过滤，或额外 AND 侧缺口表达式
+    query = query.order_by(PlPlan.plan_date.desc(), PlPlan.create_time.desc())
+    total = query.count()
+    rows = query.offset((page - 1) * page_size).limit(page_size).all()
+    # load_plan_contracts_grouped → compute_contract_gap_sides → 组装 PlanContractGapRead
+    ...
+```
+
+`gap_type` 推荐在 SQL 侧用与 `plan_has_contract_gap_exists` 相同的侧表达式再 AND，避免分页偏差。
+
+- [ ] **Step 2: 路由（必须写在 `@router.get("/{id}")` 之前）**
+
+```python
+@router.get("/contract-gaps", response_model=PlanContractGapListResponse)
+def list_contract_gaps(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100, alias="pageSize"),
+    plan_no: Optional[str] = Query(None, alias="planNo"),
+    gap_type: Optional[str] = Query(None, alias="gapType"),
+    customer_keyword: Optional[str] = Query(None, alias="customerKeyword"),
+    plan_date_from: Optional[date] = Query(None, alias="planDateFrom"),
+    plan_date_to: Optional[date] = Query(None, alias="planDateTo"),
+    q: Optional[str] = Query(None),
+    db: Session = Depends(get_db),
+    user: DbUserContext = Depends(get_db_current_user),
+):
+    tenant_no = get_tenant_no(db, user.to_tenant_user_dict())
+    total, items = list_plan_contract_gaps(...)
+    return PlanContractGapListResponse(total=total, list=items)
+```
+
+- [ ] **Step 3: 本地用 Swagger `/docs` 或 curl 冒烟（需登录态）**
+
+确认返回仅含缺合同、未作废计划。
+
+- [ ] **Step 4: 提交**
+
+```bash
+git commit -m "feat(pl): add GET transport/plan/contract-gaps endpoint"
+```
+
+---
+
+### Task 4: 单侧保存 API `PUT /{id}/contracts/{side}`
+
+**Files:**
+- Modify: `backend/app/services/pl_plan_contract_gap.py`（或 `pl_plan_service.py`）
+- Modify: `backend/app/api/pl/plan.py`
+
+- [ ] **Step 1: 服务编排**
+
+```python
+def update_plan_side_contracts(
+    db: Session,
+    *,
+    tenant_no: str,
+    plan: PlPlan,
+    side: str,
+    contracts: list[PlanContractLink],
+    user_id: Optional[str],
+    dept_id: Optional[str],
+) -> PlanContractGapRead:
+    if plan.follow_status == "cancelled":
+        raise HTTPException(status_code=400, detail="已作废的计划不能修改")
+    if side not in (PLAN_CONTRACT_SIDE_SUPPLIER, PLAN_CONTRACT_SIDE_DEMANDER):
+        raise HTTPException(status_code=422, detail="side 必须为 supplier 或 demander")
+
+    current_s, current_d = load_plan_contracts_grouped(db, tenant_no, [plan.id]).get(
+        plan.id, ([], [])
+    )
+    links = _normalize_contract_links(contracts)
+    # 校验本侧每份合同（允许空列表）
+    expected_customer_id = plan.supplier_id if side == PLAN_CONTRACT_SIDE_SUPPLIER else plan.customer_id
+    side_label = "供方合同" if side == PLAN_CONTRACT_SIDE_SUPPLIER else "需方合同"
+    resolved: list[PlanContractLink] = []
+    for link in links:
+        c = assert_contract_selectable_for_plan(
+            db, link.contract_id, tenant_no,
+            expected_customer_id=expected_customer_id,
+            side_label=side_label,
+        )
+        resolved.append(PlanContractLink(contractId=c.id, contractNo=c.contract_no or link.contract_no))
+
+    supplier_links = resolved if side == PLAN_CONTRACT_SIDE_SUPPLIER else current_s
+    demander_links = resolved if side == PLAN_CONTRACT_SIDE_DEMANDER else current_d
+    replace_plan_contracts(
+        db,
+        tenant_no=tenant_no,
+        plan_id=plan.id,
+        supplier_contracts=supplier_links,
+        demander_contracts=demander_links,
+        user_id=user_id,
+        dept_id=dept_id,
+    )
+    # 重新 load + compute gap → 返回 PlanContractGapRead
+```
+
+**禁止**对本接口调用「非内置必须有合同」的强制校验。
+
+- [ ] **Step 2: 路由**
+
+```python
+@router.put("/{id}/contracts/{side}", response_model=PlanContractGapRead)
+def put_plan_side_contracts(
+    id: str,
+    side: str,
+    payload: PlanSideContractsUpdateBody,
+    db: Session = Depends(get_db),
+    user: DbUserContext = Depends(get_db_current_user),
+):
+    tenant_no = get_tenant_no(db, user.to_tenant_user_dict())
+    plan = _get_plan(db, tenant_no, id, user)
+    result = update_plan_side_contracts(...)
+    db.commit()
+    return result
+```
+
+- [ ] **Step 3: 手动验证**
+
+1. 只改供方合同，需方关联不变  
+2. 清空非内置侧合同 → 200，且该计划仍出现在 contract-gaps  
+3. 作废计划 → 400  
+
+- [ ] **Step 4: 提交**
+
+```bash
+git commit -m "feat(pl): add PUT plan side contracts for contract completion"
+```
+
+---
+
+### Task 5: 菜单角标
+
+**Files:**
+- Modify: `backend/app/services/pl_menu_badge_service.py`
+
+- [ ] **Step 1: 常量与计数**
+
+```python
+MENU_CODE_PLAN_CONTRACT = "pl:plan-contract:list"
+# 加入 SUPPORTED_MENU_CODES
+
+def count_plan_contract_gaps(db: Session, tenant_no: str, user) -> int:
+    from app.services.pl_plan_contract_gap import plan_has_contract_gap_exists
+    query = db.query(PlPlan).filter(
+        PlPlan.tenant_no == tenant_no,
+        PlPlan.del_flag == 0,
+        PlPlan.follow_status != "cancelled",
+        plan_has_contract_gap_exists(),
+    )
+    query = apply_pl_scope(query, PlPlan, user, db, tenant_no)
+    return query.count()
+```
+
+在 `build_menu_badge_counts` 中：
+
+```python
+if MENU_CODE_PLAN_CONTRACT in requested:
+    counts[MENU_CODE_PLAN_CONTRACT] = count_plan_contract_gaps(db, tenant_no, user)
+```
+
+- [ ] **Step 2: 提交**
+
+```bash
+git commit -m "feat(pl): badge count for plan contract completion menu"
+```
+
+---
+
+### Task 6: 菜单 SQL + 前端路由
+
+**Files:**
+- Create: `backend/scripts/migrate_20260820_pl_plan_contract_complete_menu.sql`
+- Modify: `web-admin/src/router/modules/pl.ts`
+
+- [ ] **Step 1: 幂等菜单脚本**
+
+```sql
+-- 运输计划合同完善：挂在 PL_GROUP_PLAN 下，order_num=3
+INSERT INTO `sys_menu` (
+  `id`, `menu_name`, `parent_id`, `menu_type`, `path`, `component`, `perms`,
+  `is_frame`, `visible`, `status`, `tenant_no`, `order_num`, `remark`,
+  `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
+) VALUES (
+  'PL_PLAN_CONTRACT',
+  '运输计划合同完善',
+  'PL_GROUP_PLAN',
+  'C',
+  'plan-contract',
+  'pl/plan-contract/index',
+  'pl:plan-contract:list',
+  1, '1', '1', 'shanxia2.0', 3,
+  '缺合同运输计划补齐',
+  'system', '', NOW(), NULL, NOW(), 0
+)
+ON DUPLICATE KEY UPDATE
+  `menu_name`=VALUES(`menu_name`),
+  `parent_id`=VALUES(`parent_id`),
+  `path`=VALUES(`path`),
+  `component`=VALUES(`component`),
+  `perms`=VALUES(`perms`),
+  `order_num`=VALUES(`order_num`),
+  `visible`=VALUES(`visible`),
+  `status`=VALUES(`status`);
+
+INSERT INTO `sys_menu` (
+  `id`, `menu_name`, `parent_id`, `menu_type`, `path`, `component`, `perms`,
+  `is_frame`, `visible`, `status`, `tenant_no`, `order_num`, `remark`,
+  `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
+) VALUES (
+  'PL_PLAN_CONTRACT_UPD',
+  '保存合同关联',
+  'PL_PLAN_CONTRACT',
+  'F',
+  '',
+  NULL,
+  'pl:plan-contract:update',
+  1, '1', '1', 'shanxia2.0', 1,
+  NULL,
+  'system', '', NOW(), NULL, NOW(), 0
+)
+ON DUPLICATE KEY UPDATE
+  `perms`=VALUES(`perms`),
+  `parent_id`=VALUES(`parent_id`);
+```
+
+将 `PL_PLAN_CONTRACT` / `PL_PLAN_CONTRACT_UPD` 赋给需要该能力的角色（至少 `super_admin` 对应角色；可复制现有 `PL_PLAN` 的 `sys_role_menu` 角色集合，用新 UUID 插入，脚本内写清）。
+
+- [ ] **Step 2: 路由**
+
+在 `pl.ts` 的 `plan-module` children 中、`plan-archive` 之后增加：
+
+```typescript
+{
+  id: 'PL_PLAN_CONTRACT',
+  name: 'PlPlanContract',
+  path: 'plan-contract',
+  component: '/pl/plan-contract/index',
+  meta: { title: '运输计划合同完善', keepAlive: true, menuCode: 'pl:plan-contract:list' }
+}
+```
+
+- [ ] **Step 3: 本地执行 SQL 后重新登录，确认侧栏出现菜单（角标可能为 0）**
+
+- [ ] **Step 4: 提交**
+
+```bash
+git commit -m "feat(pl): add plan-contract menu SQL and web-admin route"
+```
+
+---
+
+### Task 7: 前端 API
+
+**Files:**
+- Modify: `web-admin/src/api/pl/index.ts`
+
+- [ ] **Step 1: 类型与方法**
+
+```typescript
+export interface PlanContractGapItem {
+  id: string
+  planNo: string
+  planDate?: string
+  followStatus: string
+  supplierId?: string
+  supplierName?: string
+  customerId?: string
+  customerName?: string
+  gapSides: Array<'supplier' | 'demander'>
+  supplierContractExempt: boolean
+  demanderContractExempt: boolean
+  supplierContracts: PlanContractLink[]
+  demanderContracts: PlanContractLink[]
+}
+
+export interface PlanContractGapQuery {
+  page?: number
+  pageSize?: number
+  planNo?: string
+  gapType?: 'supplier' | 'demander' | 'both' | ''
+  customerKeyword?: string
+  planDateFrom?: string
+  planDateTo?: string
+  q?: string
+}
+
+// 在 planApi 上增加：
+listContractGaps: (params?: PlanContractGapQuery) =>
+  request.get<PlListResponse<PlanContractGapItem>>('/transport/plan/contract-gaps', { params }),
+updateSideContracts: (id: string, side: 'supplier' | 'demander', contracts: PlanContractLink[]) =>
+  request.put<PlanContractGapItem>(`/transport/plan/${id}/contracts/${side}`, { contracts }),
+```
+
+确认 `PlanContractLink` 类型已在同文件存在；没有则按 `{ contractId: string; contractNo?: string }` 补上。
+
+- [ ] **Step 2: 提交**
+
+```bash
+git commit -m "feat(pl): frontend API for plan contract gaps"
+```
+
+---
+
+### Task 8: 页面列表 + 行内展开（方案 B）
+
+**Files:**
+- Create: `web-admin/src/views/pl/plan-contract/index.vue`
+- Modify: `web-admin/src/App.vue`（如有 `panelTitleBarTextRules`，加入「运输计划合同完善」）
+
+- [ ] **Step 1: 页面骨架**
+
+对照 `plan-cert/index.vue` + Demo 方案 B：
+
+- `panel-top` 标题 + 「待完善 N 条」（可用 `total`）
+- `filter-block`：计划编号、缺口类型、供方/需方、计划日期
+- `list-toolbar`：`ListToolbarDateShortcuts` + `ListQuickSearchInput` + 刷新（**无新增**）
+- `el-table`：`type="expand"` 或自定义展开行；列：计划编号（`el-link`）、计划日期、供方、需方、合同缺口 Tag、跟进状态、操作
+- 分页：`list-body.list-wrap` + `el-pagination`
+- `PlPlanViewDialog`：编号链接 / 「查看计划」打开（同 plan-cert）
+
+缺口 Tag 映射：
+
+```typescript
+function gapTagLabel(sides: string[]) {
+  if (sides.includes('supplier') && sides.includes('demander')) return { text: '两侧均缺', type: 'danger' }
+  if (sides.includes('supplier')) return { text: '缺供方合同', type: 'warning' }
+  if (sides.includes('demander')) return { text: '缺需方合同', type: 'warning' }
+  return { text: '—', type: 'info' }
+}
+```
+
+跟进状态用现有 `PL_PLAN_FOLLOW_STATUS` / DictTag 方式（与 plan 列表一致）。
+
+- [ ] **Step 2: 展开区**
+
+- `expandedRowId` 仅允许一行；切换前若 `dirty` → `ElMessageBox.confirm`
+- 左右两栏：
+  - 豁免：灰态文案，无按钮
+  - 非豁免：`PlPlanContractMultiSelect`（`:required="false"`），本地 `v-model` 绑定草稿；「保存」调用 `planApi.updateSideContracts`
+- 保存成功：`ElMessage.success`；用返回的 `gapSides` 更新行；若 `gapSides.length===0` 则从 `tableData` 移除并刷新角标（若项目有 `refreshMenuBadges` / store 方法则调用，否则依赖下次进入菜单）
+- 保存按钮：有 `pl:plan-contract:update` 权限才显示（对齐项目权限指令，如 `v-hasPermi`；若本仓库用其它写法，跟随 `plan` 页批量操作权限模式）
+
+- [ ] **Step 3: 手动 UI 验收清单**
+
+1. 列表只有缺合同、未作废计划  
+2. 行内展开互斥；未保存收起有确认  
+3. 单侧保存后对侧不变；两侧齐后行消失  
+4. 无新建/编辑合同入口  
+5. 侧栏角标数字与列表 total 口径一致（同筛选默认条件）  
+6. Fresh Mint：标题竖条、筛选、工具栏「已选」规则本页无批量主按钮即可  
+
+- [ ] **Step 4: graphify + 提交**
+
+```bash
+./scripts/update-graph.sh all
+git add -A && git commit -m "feat(pl): add plan contract completion page with inline expand"
+```
+
+---
+
+### Task 9: Spec 状态与收尾
+
+- [ ] 将 `docs/superpowers/specs/2026-08-20-pl-plan-contract-complete-design.md` 状态改为「已实现（待联调验收）」
+- [ ] 确认增量 SQL 已在目标库执行，角色可见菜单
+- [ ] 提交 docs 状态更新
+
+```bash
+git commit -m "docs: mark plan contract completion design as implemented"
+```
+
+---
+
+## Spec coverage checklist
+
+| Spec 要求 | Task |
+|-----------|------|
+| 独立菜单页路径 1 | 6, 8 |
+| 仅未作废；归档仍入列 | 3（filter 不含 archive_status） |
+| 缺口规则 / 内置可免 | 1, 2 |
+| 行内展开方案 B | 8 |
+| 每侧多选 | 8（ContractSelector multiple） |
+| 两侧各自保存 | 4, 8 |
+| 菜单角标 | 5, 6 |
+| 无合同 CRUD | 8（不引入合同表单） |
+| API contract-gaps / side PUT | 3, 4 |
+| 权限 list/update | 6, 8 |
+
+## Placeholder / 一致性自检
+
+- 路由前缀统一为前端已用的 `/transport/plan/...`（与 `planApi` 一致），对应后端 `app/api/pl/plan.py` router。
+- `side` 字面量：`supplier` / `demander`（与 `PLAN_CONTRACT_SIDE_*` 一致）。
+- `GET /contract-gaps` 必须注册在 `GET /{id}` 之前，避免被路径参数吞掉。