docs: 定制产品新增客户信息字段（customerName/contactPhone/departureDate）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-19 13:41:30 +08:00 · 2026-03-19 13:41:30 +08:00 · fbe29dfce1
--- a/changelogs/2026-03/2026-03-19_custom_product_customer_fields.md
+++ b/changelogs/2026-03/2026-03-19_custom_product_customer_fields.md
@ -0,0 +1,163 @@
+# 定制产品新增客户信息字段 - 前端对接指南
+
+> **日期**: 2026-03-19
+> **后端状态**: ✅ 已完成并部署测试环境
+> **影响范围**: 产品创建/更新/保存/详情 接口（管理端）
+
+---
+
+## 变更说明
+
+定制产品（productType=CUSTOM）新增3个客户信息字段，用于记录定制需求的客户基本信息。
+
+**变更原因**：管理端「定制产品」编辑页的「客户信息」区域（客户姓名、联系电话、出发日期）无法保存，因为后端缺少对应字段。
+
+---
+
+## 新增字段
+
+| 字段名 | 类型 | 最大长度 | 必填 | 说明 |
+|--------|------|----------|------|------|
+| customerName | String | 50字符 | 否 | 客户姓名（仅定制产品使用） |
+| contactPhone | String | 20字符 | 否 | 联系电话（仅定制产品使用） |
+| departureDate | String (yyyy-MM-dd) | - | 否 | 出发日期（仅定制产品使用） |
+
+---
+
+## 受影响的接口
+
+| # | 接口 | 方法 | 路径 | 变更内容 |
+|---|------|------|------|----------|
+| 1 | 创建产品 | POST | `/admin/product` | 请求体新增3个字段 |
+| 2 | 更新产品 | PUT | `/admin/product/{productId}` | 请求体新增3个字段 |
+| 3 | 保存产品（创建或更新） | POST | `/admin/product/save` | 请求体新增3个字段 |
+| 4 | 获取产品详情 | GET | `/admin/product/{productId}` | 响应体新增3个字段 |
+| 5 | 获取产品详情（含价格） | GET | `/admin/product/{productId}/with-prices` | 响应体新增3个字段 |
+
+---
+
+## 接口 1：创建产品
+
+```
+POST /admin/product
+```
+
+### 请求体新增字段
+
+```json
+{
+  "name": "丽江5日深度定制游",
+  "productType": "CUSTOM",
+  "tripDays": 5,
+  "departureCity": "昆明",
+  "destinationCity": "丽江",
+  "customizerId": "1893012345678901234",
+  "customerName": "张三",
+  "contactPhone": "13800138000",
+  "departureDate": "2026-07-01"
+}
+```
+
+| 字段 | 类型 | 必填 | 校验规则 | 说明 |
+|------|------|------|----------|------|
+| customerName | String | 否 | 最长50字符 | 客户姓名（定制产品） |
+| contactPhone | String | 否 | 最长20字符 | 联系电话（定制产品） |
+| departureDate | String | 否 | 格式 yyyy-MM-dd | 出发日期（定制产品） |
+
+---
+
+## 接口 2：更新产品
+
+```
+PUT /admin/product/{productId}
+```
+
+### 请求体新增字段
+
+与创建产品相同的3个字段。**选择性更新**：只有传入非null的字段才会更新，不传的字段保持原值不变。
+
+```json
+{
+  "customerName": "李四",
+  "contactPhone": "13900139000",
+  "departureDate": "2026-08-15"
+}
+```
+
+---
+
+## 接口 3：保存产品（创建或更新）
+
+```
+POST /admin/product/save
+```
+
+### 请求体新增字段
+
+与创建产品相同的3个字段。当 `productId` 有值时走更新逻辑（选择性更新），无值时走创建逻辑。
+
+```json
+{
+  "productId": null,
+  "name": "丽江定制游",
+  "productType": "CUSTOM",
+  "customerName": "王五",
+  "contactPhone": "13700137000",
+  "departureDate": "2026-09-01"
+}
+```
+
+---
+
+## 接口 4/5：获取产品详情
+
+```
+GET /admin/product/{productId}
+GET /admin/product/{productId}/with-prices?departureDate=2026-07-01
+```
+
+### 响应体新增字段
+
+```json
+{
+  "code": 200,
+  "data": {
+    "productId": "1893012345678901234",
+    "productType": "CUSTOM",
+    "name": "丽江5日深度定制游",
+    "customerName": "张三",
+    "contactPhone": "13800138000",
+    "departureDate": "2026-07-01",
+    "customizerId": "1893012345678901234",
+    "status": "DRAFT"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| customerName | String | 客户姓名（定制产品，其他类型产品为null） |
+| contactPhone | String | 联系电话（定制产品，其他类型产品为null） |
+| departureDate | String (yyyy-MM-dd) | 出发日期（定制产品，其他类型产品为null） |
+
+---
+
+## 数据库变更
+
+```sql
+ALTER TABLE product
+  ADD COLUMN customer_name VARCHAR(50) NULL COMMENT '客户姓名（定制产品）' AFTER customizer_id,
+  ADD COLUMN contact_phone VARCHAR(20) NULL COMMENT '联系电话（定制产品）' AFTER customer_name,
+  ADD COLUMN departure_date DATE NULL COMMENT '出发日期（定制产品）' AFTER contact_phone;
+```
+
+> 已在本地和测试环境执行完毕。
+
+---
+
+## 前端对接要点
+
+1. **仅定制产品（CUSTOM）类型使用这3个字段**，其他产品类型（CORE/ROUTE/GROUP）这些字段返回null
+2. **更新接口是选择性更新**：不传的字段不会被清空，只有显式传入的字段才会更新
+3. **出发日期格式**：`yyyy-MM-dd`，如 `2026-07-01`
+4. **字段位置**：在产品编辑页的「客户信息」区域展示，与定制师ID（customizerId）关联使用