hl-api-changelog/changelogs/2026-03/2026-03-17_1540_e6c349d_feat.md

接口变更记录 — 2026-03-17 15:40

提交 e6c349d · 作者 wx · 时间 2026-03-17 15:40:15 +0800

feat: 定制需求模块+管理员发票管理接口+Knife4j分组

变更总览

• 订单服务
  • 🆕 AdminInvoice (+5 接口)
  • 🆕 AdminCustomize (+5 接口)
  • 🆕 InternalCustomize (+4 接口)

---

订单服务

🆕 新增: AdminInvoice

GET /admin/invoice/page — 发票分页列表

响应 Result<PageResult<InvoiceVO>>

字段	类型	说明
id	String	发票ID
orderId	String	订单ID
orderNo	String	订单号
amount	String	金额
titleType	String	抬头类型（personal=个人/company=企业）
invoiceTitle	String	发票抬头
taxNumber	String	税号
email	String	接收邮箱
invoiceType	String	发票类型
invoiceContent	String	发票内容
status	String	发票状态
fileUrl	String	发票文件URL
failReason	String	失败原因
contactPhone	String	联系电话
remark	String	备注信息
bankName	String	开户行（企业发票）
bankAccount	String	银行账号（企业发票）
companyAddress	String	企业地址（企业发票）
companyPhone	String	企业电话（企业发票）
invoiceNo	String	发票号码
issuedAt	LocalDateTime	开票时间
issuedBy	String	开票操作人ID
userId	String	用户ID
originalInvoiceId	String	原发票ID(换开时关联)
reissueCount	Integer	换开次数
createdAt	LocalDateTime	创建时间
updatedAt	LocalDateTime	更新时间

GET /admin/invoice/{id} — 发票详情

参数

• {id} (Long) — 路径参数

响应 Result<InvoiceVO>

字段	类型	说明
id	String	发票ID
orderId	String	订单ID
orderNo	String	订单号
amount	String	金额
titleType	String	抬头类型（personal=个人/company=企业）
invoiceTitle	String	发票抬头
taxNumber	String	税号
email	String	接收邮箱
invoiceType	String	发票类型
invoiceContent	String	发票内容
status	String	发票状态
fileUrl	String	发票文件URL
failReason	String	失败原因
contactPhone	String	联系电话
remark	String	备注信息
bankName	String	开户行（企业发票）
bankAccount	String	银行账号（企业发票）
companyAddress	String	企业地址（企业发票）
companyPhone	String	企业电话（企业发票）
invoiceNo	String	发票号码
issuedAt	LocalDateTime	开票时间
issuedBy	String	开票操作人ID
userId	String	用户ID
originalInvoiceId	String	原发票ID(换开时关联)
reissueCount	Integer	换开次数
createdAt	LocalDateTime	创建时间
updatedAt	LocalDateTime	更新时间

PUT /admin/invoice/{id}/issue — 开票完成

参数

• {id} (Long) — 路径参数

请求体 AdminInvoiceIssueRequest

字段	类型	说明
fileUrl	String	发票文件URL
invoiceNo	String	发票号码

响应 Result<InvoiceVO>

字段	类型	说明
id	String	发票ID
orderId	String	订单ID
orderNo	String	订单号
amount	String	金额
titleType	String	抬头类型（personal=个人/company=企业）
invoiceTitle	String	发票抬头
taxNumber	String	税号
email	String	接收邮箱
invoiceType	String	发票类型
invoiceContent	String	发票内容
status	String	发票状态
fileUrl	String	发票文件URL
failReason	String	失败原因
contactPhone	String	联系电话
remark	String	备注信息
bankName	String	开户行（企业发票）
bankAccount	String	银行账号（企业发票）
companyAddress	String	企业地址（企业发票）
companyPhone	String	企业电话（企业发票）
invoiceNo	String	发票号码
issuedAt	LocalDateTime	开票时间
issuedBy	String	开票操作人ID
userId	String	用户ID
originalInvoiceId	String	原发票ID(换开时关联)
reissueCount	Integer	换开次数
createdAt	LocalDateTime	创建时间
updatedAt	LocalDateTime	更新时间

PUT /admin/invoice/{id}/fail — 开票失败

参数

• {id} (Long) — 路径参数

请求体 AdminInvoiceFailRequest

字段	类型	说明
failReason	String	失败原因

响应 Result<InvoiceVO>

字段	类型	说明
id	String	发票ID
orderId	String	订单ID
orderNo	String	订单号
amount	String	金额
titleType	String	抬头类型（personal=个人/company=企业）
invoiceTitle	String	发票抬头
taxNumber	String	税号
email	String	接收邮箱
invoiceType	String	发票类型
invoiceContent	String	发票内容
status	String	发票状态
fileUrl	String	发票文件URL
failReason	String	失败原因
contactPhone	String	联系电话
remark	String	备注信息
bankName	String	开户行（企业发票）
bankAccount	String	银行账号（企业发票）
companyAddress	String	企业地址（企业发票）
companyPhone	String	企业电话（企业发票）
invoiceNo	String	发票号码
issuedAt	LocalDateTime	开票时间
issuedBy	String	开票操作人ID
userId	String	用户ID
originalInvoiceId	String	原发票ID(换开时关联)
reissueCount	Integer	换开次数
createdAt	LocalDateTime	创建时间
updatedAt	LocalDateTime	更新时间

PUT /admin/invoice/{id}/void — 作废发票

参数

• {id} (Long) — 路径参数

响应 Result<InvoiceVO>

字段	类型	说明
id	String	发票ID
orderId	String	订单ID
orderNo	String	订单号
amount	String	金额
titleType	String	抬头类型（personal=个人/company=企业）
invoiceTitle	String	发票抬头
taxNumber	String	税号
email	String	接收邮箱
invoiceType	String	发票类型
invoiceContent	String	发票内容
status	String	发票状态
fileUrl	String	发票文件URL
failReason	String	失败原因
contactPhone	String	联系电话
remark	String	备注信息
bankName	String	开户行（企业发票）
bankAccount	String	银行账号（企业发票）
companyAddress	String	企业地址（企业发票）
companyPhone	String	企业电话（企业发票）
invoiceNo	String	发票号码
issuedAt	LocalDateTime	开票时间
issuedBy	String	开票操作人ID
userId	String	用户ID
originalInvoiceId	String	原发票ID(换开时关联)
reissueCount	Integer	换开次数
createdAt	LocalDateTime	创建时间
updatedAt	LocalDateTime	更新时间

🆕 新增: AdminCustomize

GET /admin/order/customize/page — 定制请求列表

响应 Result<PageResult<CustomizeRequestListVO>>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
createTime	LocalDateTime	创建时间

GET /admin/order/customize/{requestId} — 定制请求详情

参数

• {requestId} (Long) — 路径参数

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

PUT /admin/order/customize/{requestId}/accept — 接受定制请求

参数

• {requestId} (Long) — 路径参数

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

PUT /admin/order/customize/{requestId}/reply — 回复/报价

参数

• {requestId} (Long) — 路径参数

请求体 AdminReplyRequest

字段	类型	说明
reply	String	回复内容
productId	Long	关联产品ID（定制产品已创建时传入）

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

PUT /admin/order/customize/{requestId}/complete — 标记完成

参数

• {requestId} (Long) — 路径参数

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

🆕 新增: InternalCustomize

POST /internal/mp/customize/submit — 提交定制请求

参数

• userId (Long) — 查询参数

请求体 CreateCustomizeRequestDTO

字段	类型	说明
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	联系人

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

GET /internal/mp/customize/list — 定制请求列表

参数

• userId (Long) — 查询参数
• page (int) — 查询参数
• pageSize (int) — 查询参数

响应 Result<PageResult<CustomizeRequestListVO>>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
createTime	LocalDateTime	创建时间

GET /internal/mp/customize/{requestId} — 定制请求详情

参数

• {requestId} (Long) — 路径参数
• userId (Long) — 查询参数

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

POST /internal/mp/customize/{requestId}/cancel — 取消定制请求

参数

• {requestId} (Long) — 路径参数
• userId (Long) — 查询参数

响应 Result<CustomizeRequestVO>

字段	类型	说明
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）
statusLabel	String	状态标签
designerName	String	定制师姓名
designerAvatar	String	定制师头像
productId	Long	关联产品ID
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

---

📦 其他数据对象变更

以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应

订单服务

🆕 AdminCustomizeQueryRequest

字段	类型	说明
keyword	String	搜索关键词（联系人/目标地区/需求描述）
status	String	状态（字典：customize_request_status）
designerId	Long	定制师ID
sortBy	String	排序字段（createTime/startDate）
sortDir	String	排序方向（desc/asc）

🆕 AdminInvoiceQueryRequest

字段	类型	说明
status	String	发票状态（字典：invoice_status）
orderNo	String	订单编号（模糊搜索）
userId	Long	用户ID

🆕 CustomizeRequest

字段	类型	说明
requestId	Long	请求ID
userId	Long	用户ID
designerId	Long	指定定制师ID（可为空=系统分配）
destination	String	目标地区
travelPurpose	String	旅游目的
requestType	String	需求类型
startDate	LocalDate	期望出发日期
endDate	LocalDate	期望结束日期
days	Integer	期望天数
adultCount	Integer	成人数
childCount	Integer	儿童数
budget	String	预算范围
requirements	String	详细需求描述
contactPhone	String	联系电话
contactName	String	联系人
status	String	状态：PENDING/ACCEPTED/DESIGNING/QUOTED/COMPLETED/CANCELLED
designerName	String	定制师姓名（冗余）
designerAvatar	String	定制师头像（冗余）
productId	Long	关联产品ID（定制师创建的定制产品）
reply	String	定制师回复
repliedAt	LocalDateTime	回复时间
deletedAt	LocalDateTime	删除时间（软删除）
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

📁 全部变更文件 (点击展开)

M	hl-order-service/src/main/java/com/hulalv/order/OrderServiceApplication.java
M	hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java
A	hl-order-service/src/main/java/com/hulalv/order/controller/AdminInvoiceController.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/constant/CustomizeConstants.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/controller/AdminCustomizeController.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/controller/InternalCustomizeController.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/dto/AdminCustomizeQueryRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/dto/AdminReplyRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/dto/CreateCustomizeRequestDTO.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/entity/CustomizeRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/mapper/CustomizeRequestMapper.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/service/CustomizeRequestService.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/vo/CustomizeRequestListVO.java
A	hl-order-service/src/main/java/com/hulalv/order/customize/vo/CustomizeRequestVO.java
A	hl-order-service/src/main/java/com/hulalv/order/dto/AdminInvoiceFailRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/dto/AdminInvoiceIssueRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/dto/AdminInvoiceQueryRequest.java
A	sql/customize_request.sql