# 运输计划合同完善 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}` 之前，避免被路径参数吞掉。