changelog: 055da2c - feat: 定制需求接口文档完善 — Map<String,Object> 替换为强类型 DTO/VO

2026-03-19 12:42:36 +08:00 · 2026-03-19 12:42:36 +08:00 · a64174435f
--- a/changelogs/2026-03/2026-03-19_1242_055da2c_feat_M.md
+++ b/changelogs/2026-03/2026-03-19_1242_055da2c_feat_M.md
@ -0,0 +1,245 @@
+# 接口变更记录 — 2026-03-19 12:42
+
+> **提交** `055da2c` · **作者** wx · **时间** 2026-03-19 12:42:36 +0800
+>
+> feat: 定制需求接口文档完善 — Map<String,Object> 替换为强类型 DTO/VO
+
+## 变更总览
+
+- **小程序聚合服务**
+  - MpCustomize (改6)
+
+---
+
+## 小程序聚合服务
+
+### MpCustomize
+
+> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 定制需求接口」**
+
+### ✏️ `POST` /mp/custom/submit — 提交定制需求
+
+- 返回类型: `Result<Map<String, Object>>` → `Result<MpCustomizeRequestVO>`
+- 🆕 新增请求体 `MpCustomizeSubmitRequest`
+
+**请求体变更** `MpCustomizeSubmitRequest`:
+
+  - 🆕 `designerId` (`Long`) — 指定定制师ID（可为空=系统分配）
+  - 🆕 `destination` (`String`) — 目标地区
+  - 🆕 `travelPurpose` (`String`) — 旅游目的（字典：travel_purpose）
+  - 🆕 `requestType` (`String`) — 需求类型（字典：customize_request_type）
+  - 🆕 `startDate` (`LocalDate`) — 期望出发日期
+  - 🆕 `endDate` (`LocalDate`) — 期望结束日期
+  - 🆕 `days` (`Integer`) — 期望天数
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `budget` (`String`) — 预算范围（字典：customize_budget）
+  - 🆕 `requirements` (`String`) — 详细需求描述
+  - 🆕 `contactPhone` (`String`) — 联系电话
+  - 🆕 `contactName` (`String`) — 联系人
+- 🆕 新增响应类型 `MpCustomizeRequestVO`
+
+**响应变更** `MpCustomizeRequestVO`:
+
+  - 🆕 `requestId` (`Long`) — 请求ID
+  - 🆕 `userId` (`Long`) — 用户ID
+  - 🆕 `designerId` (`Long`) — 指定定制师ID
+  - 🆕 `destination` (`String`) — 目标地区
+  - 🆕 `travelPurpose` (`String`) — 旅游目的（字典：travel_purpose）
+  - 🆕 `requestType` (`String`) — 需求类型（字典：customize_request_type）
+  - 🆕 `startDate` (`LocalDate`) — 期望出发日期
+  - 🆕 `endDate` (`LocalDate`) — 期望结束日期
+  - 🆕 `days` (`Integer`) — 期望天数
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `budget` (`String`) — 预算范围（字典：customize_budget）
+  - 🆕 `requirements` (`String`) — 详细需求描述
+  - 🆕 `contactPhone` (`String`) — 联系电话
+  - 🆕 `contactName` (`String`) — 联系人
+  - 🆕 `status` (`String`) — 状态（字典：customize_request_status）：PENDING=待处理, ACCEPTED=已接受, DESIGNING=设计中, QUOTED=已报价, COMPLETED=已完成, CANCELLED=已取消
+  - 🆕 `statusLabel` (`String`) — 状态标签（中文）
+  - 🆕 `designerName` (`String`) — 定制师姓名
+  - 🆕 `designerAvatar` (`String`) — 定制师头像URL
+  - 🆕 `productId` (`Long`) — 关联产品ID（定制完成后返回）
+  - 🆕 `reply` (`String`) — 定制师回复内容
+  - 🆕 `repliedAt` (`LocalDateTime`) — 回复时间
+  - 🆕 `createTime` (`LocalDateTime`) — 创建时间
+  - 🆕 `updateTime` (`LocalDateTime`) — 更新时间
+
+### ✏️ `GET` /mp/custom/list — 定制需求列表
+
+- 返回类型: `Result<PageResult<Map<String, Object>>>` → `Result<PageResult<MpCustomizeRequestListVO>>`
+- 🆕 新增响应类型 `MpCustomizeRequestListVO`
+
+**响应变更** `MpCustomizeRequestListVO`:
+
+  - 🆕 `requestId` (`Long`) — 请求ID
+  - 🆕 `userId` (`Long`) — 用户ID
+  - 🆕 `destination` (`String`) — 目标地区
+  - 🆕 `travelPurpose` (`String`) — 旅游目的（字典：travel_purpose）
+  - 🆕 `requestType` (`String`) — 需求类型（字典：customize_request_type）
+  - 🆕 `startDate` (`LocalDate`) — 期望出发日期
+  - 🆕 `days` (`Integer`) — 期望天数
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `budget` (`String`) — 预算范围（字典：customize_budget）
+  - 🆕 `status` (`String`) — 状态（字典：customize_request_status）：PENDING=待处理, ACCEPTED=已接受, DESIGNING=设计中, QUOTED=已报价, COMPLETED=已完成, CANCELLED=已取消
+  - 🆕 `statusLabel` (`String`) — 状态标签（中文）
+  - 🆕 `designerName` (`String`) — 定制师姓名
+  - 🆕 `designerAvatar` (`String`) — 定制师头像URL
+  - 🆕 `createTime` (`LocalDateTime`) — 创建时间
+
+### ✏️ `GET` /mp/custom/detail — 定制需求详情
+
+- 返回类型: `Result<Map<String, Object>>` → `Result<MpCustomizeRequestVO>`
+- 🆕 新增响应类型 `MpCustomizeRequestVO`
+
+**响应变更** `MpCustomizeRequestVO`:
+
+  - 🆕 `requestId` (`Long`) — 请求ID
+  - 🆕 `userId` (`Long`) — 用户ID
+  - 🆕 `designerId` (`Long`) — 指定定制师ID
+  - 🆕 `destination` (`String`) — 目标地区
+  - 🆕 `travelPurpose` (`String`) — 旅游目的（字典：travel_purpose）
+  - 🆕 `requestType` (`String`) — 需求类型（字典：customize_request_type）
+  - 🆕 `startDate` (`LocalDate`) — 期望出发日期
+  - 🆕 `endDate` (`LocalDate`) — 期望结束日期
+  - 🆕 `days` (`Integer`) — 期望天数
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `budget` (`String`) — 预算范围（字典：customize_budget）
+  - 🆕 `requirements` (`String`) — 详细需求描述
+  - 🆕 `contactPhone` (`String`) — 联系电话
+  - 🆕 `contactName` (`String`) — 联系人
+  - 🆕 `status` (`String`) — 状态（字典：customize_request_status）：PENDING=待处理, ACCEPTED=已接受, DESIGNING=设计中, QUOTED=已报价, COMPLETED=已完成, CANCELLED=已取消
+  - 🆕 `statusLabel` (`String`) — 状态标签（中文）
+  - 🆕 `designerName` (`String`) — 定制师姓名
+  - 🆕 `designerAvatar` (`String`) — 定制师头像URL
+  - 🆕 `productId` (`Long`) — 关联产品ID（定制完成后返回）
+  - 🆕 `reply` (`String`) — 定制师回复内容
+  - 🆕 `repliedAt` (`LocalDateTime`) — 回复时间
+  - 🆕 `createTime` (`LocalDateTime`) — 创建时间
+  - 🆕 `updateTime` (`LocalDateTime`) — 更新时间
+
+### ✏️ `POST` /mp/custom/{requestId}/cancel — 取消定制需求
+
+- 返回类型: `Result<Map<String, Object>>` → `Result<MpCustomizeRequestVO>`
+- 🆕 新增响应类型 `MpCustomizeRequestVO`
+
+**响应变更** `MpCustomizeRequestVO`:
+
+  - 🆕 `requestId` (`Long`) — 请求ID
+  - 🆕 `userId` (`Long`) — 用户ID
+  - 🆕 `designerId` (`Long`) — 指定定制师ID
+  - 🆕 `destination` (`String`) — 目标地区
+  - 🆕 `travelPurpose` (`String`) — 旅游目的（字典：travel_purpose）
+  - 🆕 `requestType` (`String`) — 需求类型（字典：customize_request_type）
+  - 🆕 `startDate` (`LocalDate`) — 期望出发日期
+  - 🆕 `endDate` (`LocalDate`) — 期望结束日期
+  - 🆕 `days` (`Integer`) — 期望天数
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `budget` (`String`) — 预算范围（字典：customize_budget）
+  - 🆕 `requirements` (`String`) — 详细需求描述
+  - 🆕 `contactPhone` (`String`) — 联系电话
+  - 🆕 `contactName` (`String`) — 联系人
+  - 🆕 `status` (`String`) — 状态（字典：customize_request_status）：PENDING=待处理, ACCEPTED=已接受, DESIGNING=设计中, QUOTED=已报价, COMPLETED=已完成, CANCELLED=已取消
+  - 🆕 `statusLabel` (`String`) — 状态标签（中文）
+  - 🆕 `designerName` (`String`) — 定制师姓名
+  - 🆕 `designerAvatar` (`String`) — 定制师头像URL
+  - 🆕 `productId` (`Long`) — 关联产品ID（定制完成后返回）
+  - 🆕 `reply` (`String`) — 定制师回复内容
+  - 🆕 `repliedAt` (`LocalDateTime`) — 回复时间
+  - 🆕 `createTime` (`LocalDateTime`) — 创建时间
+  - 🆕 `updateTime` (`LocalDateTime`) — 更新时间
+
+### ✏️ `GET` /mp/custom/product/{productId} — 查询已完成的定制产品详情
+
+- 返回类型: `Result<Map<String, Object>>` → `Result<MpCustomProductDetailVO>`
+- 🆕 新增响应类型 `MpCustomProductDetailVO`
+
+**响应变更** `MpCustomProductDetailVO`:
+
+  - 🆕 `productId` (`String`) — 产品ID
+  - 🆕 `productType` (`String`) — 产品类型：CUSTOM=定制产品
+  - 🆕 `name` (`String`) — 产品名称
+  - 🆕 `subtitle` (`String`) — 副标题
+  - 🆕 `tripDays` (`Integer`) — 行程天数
+  - 🆕 `tripNights` (`Integer`) — 行程晚数
+  - 🆕 `departureCity` (`String`) — 出发城市
+  - 🆕 `destinationCity` (`String`) — 目的地城市
+  - 🆕 `destinationCities` (`List<String>`) — 途经城市列表
+  - 🆕 `adultCount` (`Integer`) — 成人人数
+  - 🆕 `childCount` (`Integer`) — 儿童人数
+  - 🆕 `youngChildCount` (`Integer`) — 小童人数
+  - 🆕 `babyCount` (`Integer`) — 婴儿人数
+  - 🆕 `paymentMode` (`String`) — 支付模式：FULL=全款 DEPOSIT=定金+尾款
+  - 🆕 `status` (`String`) — 产品状态：COMPLETED=已完成, ORDERED=已下单
+  - 🆕 `coverImageUrl` (`String`) — 封面图URL
+  - 🆕 `carouselImages` (`List<String>`) — 轮播图列表
+  - 🆕 `routeMapUrl` (`String`) — 路径图URL
+  - 🆕 `creatorAvatarUrl` (`String`) — 定制师头像URL
+  - 🆕 `creatorIntro` (`String`) — 创作者寄语
+  - 🆕 `startPrice` (`BigDecimal`) — 起步价
+  - 🆕 `tags` (`List<String>`) — 产品标签列表
+  - 🆕 `itineraryDays` (`List<Object>`) — 行程天列表（包含每天的景点、酒店、餐厅、活动等安排）
+  - 🆕 `pricing` (`Object`) — 定价配置
+  - 🆕 `staffConfigs` (`List<StaffConfigItem>`) — 人员配置列表（定制产品专属：导游、领队、摄影师等）
+  - 🆕 `families` (`List<FamilyItem>`) — 家庭分组列表（定制产品专属：按家庭分配人员和房间）
+  - 🆕 `costItems` (`List<Object>`) — 成本项列表
+  - 🆕 `customFees` (`List<Object>`) — 自定义费用项列表
+  - 🆕 `createTime` (`LocalDateTime`) — 创建时间
+  - 🆕 `id` (`String`) — 记录ID
+  - 🆕 `staffType` (`String`) — 人员类型：GUIDE=导游, GUIDE_ASSISTANT=助理导游, PHOTOGRAPHER=摄影师, LEADER=领队, OTHER=其他
+  - 🆕 `staffTypeName` (`String`) — 人员类型名称（中文）
+  - 🆕 `quantity` (`Integer`) — 数量
+  - 🆕 `sortOrder` (`Integer`) — 排序序号
+  - 🆕 `familyIds` (`List<String>`) — 所属家庭ID列表
+  - 🆕 `familyId` (`String`) — 家庭ID
+  - 🆕 `familyName` (`String`) — 家庭名称（如：家庭1）
+  - 🆕 `adultCount` (`Integer`) — 成人数
+  - 🆕 `childCount` (`Integer`) — 儿童数
+  - 🆕 `youngChildCount` (`Integer`) — 小童数
+  - 🆕 `babyCount` (`Integer`) — 幼童数
+  - 🆕 `sortOrder` (`Integer`) — 排序序号
+
+### ✏️ `GET` /mp/custom/products — 我的已完成定制产品列表
+
+- 返回类型: `Result<List<Map<String, Object>>>` → `Result<List<MpCustomProductListVO>>`
+- 🆕 新增响应类型 `MpCustomProductListVO`
+
+**响应变更** `MpCustomProductListVO`:
+
+  - 🆕 `productId` (`String`) — 产品ID
+  - 🆕 `productType` (`String`) — 产品类型：CUSTOM=定制产品
+  - 🆕 `name` (`String`) — 产品名称
+  - 🆕 `subtitle` (`String`) — 副标题
+  - 🆕 `tripDays` (`Integer`) — 行程天数
+  - 🆕 `tripNights` (`Integer`) — 行程晚数
+  - 🆕 `departureCity` (`String`) — 出发城市
+  - 🆕 `destinationCity` (`String`) — 目的地城市
+  - 🆕 `tags` (`List<String>`) — 产品标签列表
+  - 🆕 `coverImageUrl` (`String`) — 封面图URL
+  - 🆕 `startPrice` (`BigDecimal`) — 起步价
+  - 🆕 `paymentMode` (`String`) — 支付模式：FULL=全款 DEPOSIT=定金+尾款
+  - 🆕 `routeMapUrl` (`String`) — 路径图URL
+  - 🆕 `creatorAvatarUrl` (`String`) — 定制师头像URL
+
+---
+
+<details>
+<summary>📁 全部变更文件 (点击展开)</summary>
+
+```
+M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCustomizeController.java
+A	hl-mp-service/src/main/java/com/hulalv/mp/dto/MpCustomizeSubmitRequest.java
+M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java
+M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java
+M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java
+M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java
+A	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java
+A	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductListVO.java
+A	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomizeRequestListVO.java
+A	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomizeRequestVO.java
+```
+</details>