From fbe29dfce1f7bb8930988c883d2c6c277de4ac2f Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 19 Mar 2026 13:41:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=9A=E5=88=B6=E4=BA=A7=E5=93=81?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=AE=A2=E6=88=B7=E4=BF=A1=E6=81=AF=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=EF=BC=88customerName/contactPhone/departureDate?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- ...26-03-19_custom_product_customer_fields.md | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 changelogs/2026-03/2026-03-19_custom_product_customer_fields.md diff --git a/changelogs/2026-03/2026-03-19_custom_product_customer_fields.md b/changelogs/2026-03/2026-03-19_custom_product_customer_fields.md new file mode 100644 index 0000000..2f18efd --- /dev/null +++ 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）关联使用