diff --git a/changelogs-v2/2026-06/18_3978_订单与资源v3金额字段补全String序列化-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3978_订单与资源v3金额字段补全String序列化-修改接口-管理后台.md new file mode 100644 index 0000000..d9355e8 --- /dev/null +++ b/changelogs-v2/2026-06/18_3978_订单与资源v3金额字段补全String序列化-修改接口-管理后台.md @@ -0,0 +1,60 @@ +# 订单与资源服务v3 金额字段补全 String 序列化(W1 #3965 后续全量补齐)— 修改接口 — 管理后台 + +> 变更类型:⚠️ 序列化口径变更(金额 BigDecimal 字段补标 `@JsonSerialize(ToStringSerializer)`,JSON number → String),无逻辑 / 破坏性变更 +> 端类型:管理后台(订单详情 / 班期 / 结算 / 退款 / 差价 / 折扣 / 配房 / 发票 / 行程 / 资源房型)+ 少量小程序(见 §2) +> 日期:2026-06-18 +> 服务:hl-order-service-v3 + hl-resource-service +> PR:https://git.1814.love:8443/wx/HL/pulls/3978 、 https://git.1814.love:8443/wx/HL/pulls/3979 + +--- + +## ⚠️ 关键说明 + +平台铁律「JSON 金额必为 String」此前在 order-v3 / resource 多处 RespVO 漏标 `@JsonSerialize(ToStringSerializer)`,金额被序列化成 JSON number。W1(#3965)已修订单钱 / 状态热区一批,**本批(#3978 共 39 个 VO + #3979 resource RoomTypeVO)经审查全量补齐剩余漏标的金额字段**。 + +**这些字段从「数字」变为「带引号字符串」,前端解析金额必须按字符串处理(`new Decimal(str)` / `parseFloat(str)`),勿假设为 number。** 已合并 dev-v3、部署测试服双实例 health UP、9443 + 真 admin token 实测订单详情金额返回字符串通过。 + +注:仅金额字段(金额 / 价 / 费 / 差价 / 成本 / 预算 / 应收实付 / 退款额);比率字段(profitRate / ratingAvg 等)不受影响。 + +--- + +## 1. 🔴 受影响接口 / VO(按域,金额字段 number → String) + +| 域 | 端点(示例) | VO / 金额字段 | +|---|---|---| +| 订单详情·主 | `GET /v3/admin/order/{id}` | OrderMainVO.totalAmount / paidAmount / balanceAmount / depositAmount / singleRoomSurcharge | +| 订单详情·Tab | `.../contract-insurance`、`.../service-standard` | ContractInsuranceVO.insurancePremium、ServiceStandardVO.RefundItem.amount | +| 创单 | `POST /v3/admin/order` | OrderCreateRespVO.totalAmount / depositAmount | +| 班期 | `GET /v3/admin/order/group-batch/{id}`、`/{id}/orders`、`/{id}/settlement` 等 | GroupBatchDetailRespVO(advanceAmount/totalReceivable/totalReceived)、GroupBatchOrderItemRespVO(paidAmount/balanceAmount)、GroupBatchSettlementSummaryRespVO(6 金额含 SharedCostByTypeVO.total)、BatchCostRespVO.amount、GroupBatchSuppliesRespVO.unitPrice | +| 差价 / 调价 | `.../adjustment/snapshot`、`/submit` | AdjustmentSnapshotRespVO(orderAmount/surchargeAmount/discountAmount/balanceAmount)、AdjustmentSubmitRespVO.priceDelta、SurchargeVO.amount、DiscountVO.amount、HotelDayDefaultVO.budget | +| 退款 | 退款申请、终止退款预览 | RefundApplicationVO(paidAmount/calculatedAmount/actualAmount/appealAmount)、RefundPreviewVO(paidAmount/calculatedAmount)、OrderTerminateRefundPreviewRespVO.paidAmount、TerminateRefundItemVO(dealPrice/totalAmount) | +| 配房 | 抢单 / 询价 / 换酒店 / 酒店列表 / 候选 / 配房详情 | HouseGrabPageItemRespVO.totalAmount、InquiryHistoryRespVO.replyPrice、HouseHotelListItemVO.protoPrice、SwapPreviewRespVO / SwapCommitRespVO / SwapCandidatesRespVO(各 diff / protoPrice / sellPrice)、HouseOrderDetailRespVO、HotelCandidateRespVO.protoPrice | +| 合同 / 发票 | 合同列表、发票 | ContractVO.totalAmount、InvoiceVO.amount | +| 行程 / 排班 | 行程详情、节点实配、签单文档 | ItineraryVO(plannedCost/plannedDailyFee/budget)、AssignmentVO(unitPrice/totalAmount/costPrice)、EditLogVO.amountDelta、LogTimelineVO.amount、OrderItineraryDocumentVO.Header.totalAmount、VehicleCandidateVO.dailyFee | +| 资源·房型(#3979) | `GET /admin/hotel/room-type/{id}`、`/{hotelId}/room-types` | RoomTypeVO.basePrice | + +示例(订单详情,已测试服 9443 实测): + +```json +{ "code": 200, "data": { "main": { "totalAmount": "8355.00", "paidAmount": "1500.00", "balanceAmount": "6855.00", "depositAmount": "1500.00", "singleRoomSurcharge": "0.00" } } } +// 此前 totalAmount 等为 8355.00(数字),现为 "8355.00"(字符串) +``` + +--- + +## 2. 小程序端同步(少量,口径同上) + +以下小程序(C 端)端点的金额字段同批补标 String: + +| 端点 | VO / 字段 | 备注 | +|---|---|---| +| 老客户订单查询 | OrderLookupRespVO.totalAmount | 该端点当前仍为 Mock 占位,真实化后生效 | +| 发票申请 / 详情 / 列表 | MpInvoiceApplyRespVO.amount、InvoiceDetailVO.amount、OrderInvoiceListItemVO.amount | | + +--- + +## 备注 + +- 纯序列化注解补标,无字段增删、无逻辑变更、零 DDL。 +- 跳过 `/internal/` Feign DTO(服务间 round-trip 不丢精度)与所有入参 ReqVO。 +- 关联 W1:#3965(已发 changelog `18_3965_订单v3接口契约审计修复W1-金额String...`);本批为其全量补齐续作。