# 合同编号支持自定义 - 前端联调方案

## 涉及页面

- CRM - 合同管理 - 新增合同弹窗
- CRM - 合同管理 - 编辑合同弹窗

## 变更概述

"合同编号"字段由"系统自动生成、不可编辑"改为"支持手工录入"，新增和编辑两种模式均可编辑：

- 新增时留空 → 后端自动生成（HT 前缀，与原行为一致）
- 新增时填写 → 使用用户填写的编号
- 编辑时留空 → 保持原编号不变
- 编辑时填写 → 使用用户填写的编号（后端校验唯一性）

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /crm/contract/create | 新增合同，请求体新增 `no` 字段 |
| PUT | /crm/contract/update | 更新合同，`no` 字段可修改 |
| GET | /crm/contract/get | 查询合同详情，响应本就含 `no` 字段（未变） |

**请求参数（POST /crm/contract/create、PUT /crm/contract/update）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| no | String | 否 | 合同编号，最长 100 字符；新增时留空（或不传）由后端自动生成，更新时留空保持原编号 |

其余参数与现状一致，此处不再列出。

**响应（未变更）：**

```json
{
  "code": 0,
  "data": 123,
  "msg": ""
}
```

`data` 为新建合同的 ID。

## 前端修改点

### 1. 合同编号字段（新增弹窗 + 编辑弹窗）

| 事项 | 现状 | 需改为 |
|------|------|--------|
| disabled | 新增禁用、编辑禁用 | 两种模式均可编辑（去掉禁用） |
| placeholder | 保存时自动生成 | 新增：留空则自动生成；编辑：留空则保持原编号 |
| 其他 | — | 可清空、最大长度 100 |

### 2. 保存时提交该字段

新增/编辑保存时，需要把用户在"合同编号"中填写的值一并提交给后端。

### 3. 编辑弹窗的其他字段

除合同编号外，编辑弹窗其余字段保持不变。

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 合同编号 | 新增弹窗 | 用户可填写；留空则由后端生成 |
| 合同编号 | 编辑弹窗 | 用户可修改；留空则保持原编号 |
| 合同编号 | 详情、列表 | 展示后端实际保存的编号 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 新增时填写了编号 | 使用用户填写的编号，首尾空格会被自动去掉 |
| 新增时留空或只填空格 | 后端自动生成 HT 前缀编号 |
| 编辑时填写了编号 | 使用用户填写的编号，首尾空格会被自动去掉 |
| 编辑时留空或只填空格 | 保持原编号不变 |
| 新增/编辑时修改的编号与已有合同重复 | 保存失败，提示：合同编号【xxx】已存在，请更换后重试 |
| 编辑时未改动编号 | 正常保存，不会误报重复 |
| 自动生成的编号重复（极小概率） | 保存失败，提示：生成合同序列号重复，请重试（重新保存即可） |
| 编号超过 100 字符 | 保存失败，提示：合同编号长度不能超过 100 个字符 |
| 由报价单转合同 | 不受影响，仍自动生成编号 |
| Excel 导入合同 | 不受影响，导入本身已支持自定义编号 |

## 注意事项

- 新增接口返回的是合同 ID，不包含最终编号。若新增后需要在界面上显示实际编号，请在保存成功后调用 `GET /crm/contract/get?id={id}` 获取，或直接使用用户自己填写的值。
- 编号唯一性由后端校验，前端无需额外查重；编辑时后端查重会排除合同自身，因此原样提交不会误报重复。
- 编号长度上限 100 字符，前端可做输入长度限制以改善体验。
- 不做前端校验也不影响正确性：新增留空走自动生成、编辑留空保持原值，重复会被后端拦截并返回明确提示。
- 合同编号的变更会计入合同操作日志（更新记录中体现"合同编号：原值 → 新值"）。