5.1 KiB
订单与资源服务v3 金额字段补全 String 序列化（W1 #3965 后续全量补齐）— 修改接口 — 管理后台
变更类型：⚠️ 序列化口径变更（金额 BigDecimal 字段补标
@JsonSerialize(ToStringSerializer)，JSON number → String），无逻辑 / 破坏性变更 端类型：管理后台（订单详情 / 班期 / 结算 / 退款 / 差价 / 折扣 / 配房 / 发票 / 行程 / 资源房型）+ 少量小程序（见 §2） 日期：2026-06-18 服务：hl-order-service-v3 + hl-resource-service PR：wx/HL#3978 、 wx/HL#3979
⚠️ 关键说明
平台铁律「JSON 金额必为 String」此前在 order-v3 / resource 多处 RespVO 漏标 @JsonSerialize(ToStringSerializer)，金额被序列化成 JSON number。W1（#3965）已修订单钱 / 状态热区一批，本批（#3978 共 39 个 VO + #3979 resource RoomTypeVO）经审查全量补齐剩余漏标的金额字段。
字段类型在 Java 内仍是 BigDecimal（未改类型），只是 JSON 输出从裸数字变带引号字符串，对齐平台「金额=String」约定。前端无需改动 —— 金额本就按字符串口径处理（W1 #3965 及其它金额接口已是 String），本批把漏标的几个补回一致即可；JS 对金额做 > < - * / 会自动转数字、照常工作，仅 a + b 直接相加（会变字符串拼接）/ 对原始字段 .toFixed() / === 0·!== 0 严格比较 这三类才需留意，而金额本就不应这样用 → 常规渲染 / 比较 / 运算无需任何改动。
已合并 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 实测）：
{ "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...）；本批为其全量补齐续作。