# 运输计划合同完善 · 设计说明

> Demo：`docs/fresh-mint-pl-plan-contract-complete-demo.html`（方案 B 为采纳交互）  
> 日期：2026-08-20  
> 状态：已实现（待联调验收）

## 1. 背景与目标

运输计划新增/编辑时，供需双方合同已改为**非必填**，便于先建计划再补合同。业务上：非内置公司一侧仍应关联合同；内置公司该侧合同可免。

**内置公司（合同可免）：**

- 安庆市山峡化工有限公司
- 安徽云栋化工有限公司

判定逻辑复用现有工具：

- 前端：`web-admin/src/utils/pl-internal-customer.ts` → `isPlInternalCustomerName`
- 后端：`backend/app/services/pl_internal_customer.py` → `is_internal_customer_name`

**目标：** 提供独立的「运输计划合同完善」界面，只列出仍缺合同的未作废计划，并支持在列表行内直接关联已有 CRM 合同（不支持在本页新增/编辑合同）。

## 2. 已确认决策

| 项 | 结论 |
|---|---|
| 实现路径 | 独立菜单页 + 专用列表/保存 API（路径 1） |
| 交互 | 列表「补充」打开弹窗关联本段合同（已由行内展开改为弹窗，见 `docs/fresh-mint-pl-plan-contract-supplement-dialog-demo.html`） |
| 计划范围 | 仅未作废（`follow_status != cancelled`），含待安排/已安排/运输中等；**已归档但未作废的计划仍入列**（未采用「排除归档」） |
| 合同数量 | 每侧可多选（与计划新增/编辑一致） |
| 保存方式 | 两侧各自「保存」；补完一侧即可落库 |
| 菜单角标 | 要；显示当前缺合同条数（对齐危化品证） |
| 非目标 | 本页不新增/编辑/审批合同；不改计划其它字段；不做小程序页 |

## 3. 信息架构与入口

### 3.1 菜单

挂在 **运输管理 → 运输计划** 分组下，与「运输计划」「运输计划归档」并列：

| 项 | 值 |
|---|---|
| 菜单名 | 运输计划合同完善 |
| Hash 路由 | `/#/pl/plan-module/plan-contract` |
| 组件 | `web-admin/src/views/pl/plan-contract/index.vue` |
| menuCode | `pl:plan-contract:list` |
| 更新权限 | `pl:plan-contract:update` |

路由注册：`web-admin/src/router/modules/pl.ts`（`plan-module` children）。  
菜单/权限 SQL：写入 `docs/sql`（与现有 pl 菜单脚本风格一致）。

### 3.2 UI 模式

**P02 复杂业务列表**，参考：

- `web-admin/src/views/pl/plan-cert/index.vue`（待办型衍生列表 + 角标）
- `web-admin/src/views/pl/plan/index.vue`（列表骨架、筛选、日期快捷）

视觉遵循 `docs/web-admin-ui-spec-fresh-mint.md`。

页面骨架：

```
panel
  ├─ panel-top：标题 + 待完善数量
  ├─ filter-block
  ├─ list-toolbar（日期快捷 + 快速搜索 + 刷新；无「新增」）
  ├─ list-table（可展开行）
  └─ pagination
```

## 4. 缺口判定规则

对每条未删除、未作废的运输计划：

1. **供方侧**  
   - 若 `is_internal_customer_name(supplier_name)` → 该侧**不要求**合同（可免）  
   - 否则 → 至少 1 条有效供方侧 `pl_plan_contract`（`side=supplier`, `del_flag=0`）
2. **需方侧**  
   - 对 `customer_name` 同理（`side=demander`）
3. **入列表条件**：供方侧缺口 **或** 需方侧缺口（任一侧不满足要求）

列表/角标口径必须与上述规则一致（前后端同一工具函数）。

## 5. 列表与行内展开

### 5.1 列表列

| 列 | 说明 |
|---|---|
| 计划编号 | 主色链接 → 打开现有计划只读查看 |
| 计划日期 | |
| 供方 | 名称；副文案：已关联 N 份 / 未关联 / 内置可免 |
| 需方 | 同上 |
| 合同缺口 | Tag：`缺供方合同` / `缺需方合同` / `两侧均缺` |
| 跟进状态 | 现有跟进状态 Tag |
| 操作 | 「展开补充」/「收起」；「查看计划」 |

### 5.2 筛选与排序

- 筛选：计划编号、缺口类型（全部 / 仅缺供方 / 仅缺需方 / 两侧均缺）、供方或需方关键词、计划日期区间
- 工具栏：日期快捷 + 快速搜索（计划编号/供方/需方）
- 默认排序：`plan_date DESC`，其次 `create_time DESC`
- 数据权限：与运输计划列表相同（`apply_pl_scope`）

### 5.3 行内展开交互

- 同时仅展开一行；展开另一行时收起当前行
- 展开区左右两栏：供方合同 | 需方合同

| 侧状态 | UI |
|---|---|
| 待补充 | 已选合同卡片（可移除）+「选择合同」+ 该侧「保存」 |
| 已齐 | 展示已关联合同；仍允许改选后保存 |
| 可免（内置） | 灰态说明；无选择器、无保存按钮 |

- 「选择合同」复用 `ContractSelector`（多选；可选状态与计划页一致：已审批 / 执行中）；按该侧 `customerId` 过滤
- **不提供**新建/编辑合同入口
- 保存只提交**该侧**合同列表；成功后刷新该行；若两侧均已满足缺口规则，该行从列表移除并刷新角标
- 有未保存变更时收起：二次确认

组件复用：优先复用 `PlPlanContractMultiSelect` / `ContractSelector` 的选择与卡片展示能力。

## 6. API 设计

建议挂在运输计划模块下（路径示例，实现时可微调前缀，须注册到 `app/api` + `main`）：

### 6.1 缺合同分页列表

`GET /api/pl/plans/contract-gaps`

Query：分页 + `planNo`、`gapType`（`supplier` | `demander` | `both`）、客户关键词、`planDate` 起止、快速搜索等。

固定过滤：`del_flag=0`、`follow_status != cancelled`、存在合同缺口（**不**按 `archive_status` 排除）。

响应行至少包含：

- 计划基础字段（编号、日期、供需方 id/name、跟进状态等）
- `gapSides: ("supplier" | "demander")[]`
- `supplierContractExempt` / `demanderContractExempt`
- `supplierContracts` / `demanderContracts`（`PlanContractLink[]`，展开回填）

### 6.2 单侧保存合同

`PUT /api/pl/plans/{planId}/contracts/{side}`

- `side` ∈ `supplier` | `demander`
- Body：`{ "contracts": PlanContractLink[] }`（可多份；空数组表示清空该侧）

服务端：

1. 校验计划存在、未作废、租户与数据权限  
2. 校验合同可选（归属该侧客户、状态允许等），复用 `assert_contract_selectable_for_plan` / `validate_plan_party_contracts` 中与合同相关的能力；**本接口不因「非内置且空列表」直接 422**（允许先清空；列表是否仍展示由缺口规则决定）  
3. 加载对侧现有合同 + 本侧请求列表 → 调用现有 `replace_plan_contracts` 整体替换关联表  
4. 返回：更新后两侧合同 + 最新 `gapSides`（及豁免标记）

**不走**完整 `PlanUpdate`；不修改产品、运输、客户等字段。

### 6.3 与现有「合同非必填」的关系

计划创建/全量更新已不再强制非内置侧必须有合同。本页是事后补齐通道；主计划编辑页仍可改合同，行为保持一致。

## 7. 菜单角标

- `menuCode`：`pl:plan-contract:list`
- 在 `backend/app/services/pl_menu_badge_service.py` 增加计数函数，口径与列表默认条件一致
- 加入 `SUPPORTED_MENU_CODES`；前端侧栏展示数字（对齐 `pl:plan-cert:list`）

## 8. 权限

| 权限码 | 用途 |
|---|---|
| `pl:plan-contract:list` | 进入页面、拉列表、角标 |
| `pl:plan-contract:update` | 单侧保存合同 |

「查看计划」复用现有计划查看能力（与 `plan-cert` 跳转查看一致，通常依赖 `pl:plan:list` 或已有详情权限）。

## 9. 前端文件（预期）

| 文件 | 职责 |
|---|---|
| `web-admin/src/views/pl/plan-contract/index.vue` | 页面 |
| `web-admin/src/router/modules/pl.ts` | 路由 |
| `web-admin/src/api/pl/*` | list gaps / save side |
| （可选）小组件 | 行内展开双侧合同区，避免单文件过大 |

## 10. 后端文件（预期）

| 文件 | 职责 |
|---|---|
| `app/api/pl/plan.py` 或独立 router | 两个端点 |
| `app/services/pl_plan_service.py`（或小服务模块） | 缺口查询、单侧保存编排 |
| `app/schemas/pl/plan.py` | 请求/响应模型 |
| `app/services/pl_menu_badge_service.py` | 角标 |
| `docs/sql/*` | 菜单与权限 |

## 11. 错误与边界

- 已作废计划：列表不出现；若 ID 直调保存 → 400/422，提示不可修改  
- 合同不属于该侧客户或状态不可选 → 422，明确文案  
- 并发：单侧保存以「读对侧最新 + 写本侧」再 `replace_plan_contracts`；后写覆盖该次替换结果（可接受；不做乐观锁，除非后续有冲突投诉）  
- 内置侧误传合同：允许关联（不强制拒绝），UI 默认不展示选择器  

## 12. 测试要点

- 缺口判定：双非内置无合同 → 入列；一侧内置一侧外部无合同 → 仅缺外部侧；双侧内置 → 不入列  
- 单侧保存后对侧合同不变  
- 补齐后行消失、角标减一  
- 作废计划不出现在列表与角标  
- 数据权限用户看不到范围外计划  
- 前端：展开互斥、未保存收起确认、无新建合同入口  

## 13. 非目标（明确不做）

- 合同 CRUD / 审批  
- 修改运输计划主数据、产品、运输安排  
- 小程序「合同完善」页  
- 主计划列表增加「缺合同」Tab（本设计采用独立页）