# 项目文档_配送合同候选范围修复_v1.0

## 1. 项目概述

本次修复平台总后台业务表单直接加载全部配送合同的问题。合同管理列表需要展示完整生命周期，但创建订单和绑定合同气瓶属于受状态约束的业务操作，候选范围必须与服务端最终校验一致。

## 2. 业务规则

- 创建配送订单只显示当前可履约合同：状态为“生效中”、当前时间不早于生效时间、到期时间存在且当前时间早于到期时间。
- 草稿、未到生效时间、已过期、已终止和缺少到期时间的合同不进入订单候选。
- 绑定合同气瓶只显示草稿合同。
- 合同管理列表不携带候选用途参数，继续展示全部合同。
- 没有可用候选时，页面显示对应业务引导并禁止保存。
- 页面重新加载后，严格筛选结果中不存在的旧合同选择会被清空。
- 服务端创建订单和绑定气瓶时继续执行最终校验，前端筛选不构成安全控制。

## 3. 接口兼容

`GET /gasorder_contract` 新增可选查询参数 `candidate`：

- 不传：合同管理全量列表，保持原行为。
- `candidate=order`：仅返回当前可履约合同。
- `candidate=binding`：仅返回草稿合同。

未新增数据库字段、表或迁移，也未修改合同数据。

## 4. 关键文件

```text
backend/api/internal/logic/platform/gasorder/gasorder.go       # 合同候选过滤与订单最终校验
backend/api/internal/logic/platform/gasorder/gasorder_test.go  # 五类合同状态与查询条件测试
frontend/platform_admin/src/api/resources.ts                   # 两类合同候选配置与中文提示
frontend/platform_admin/src/views/resource/use-resource-relations.ts # 字段级筛选参数
frontend/platform_admin/src/views/resource/use-resource-relation-linkage.ts # 失效选择清理和空候选阻断
```

## 5. 变更记录

操作时间：2026-08-13

操作类型：修复

影响模块：配送合同、配送订单、合同气瓶

操作前状态：订单和合同气瓶表单均展示全部合同，用户选中后才由服务端拒绝。

操作后状态：不同业务表单只展示当前允许操作的合同，并继续保留服务端最终校验。

风险评估：管理列表和既有无参数调用保持兼容；候选接口只收窄可选数据，不修改数据事实。

## 6. 验证方式

```bash
cd backend/api
go test ./internal/logic/platform/gasorder
go test ./...
go vet ./...

cd frontend/platform_admin
npm run gasorder-contract-candidates:check
npm run type:check
npm run contract:check
npm run build
```