63 行
5.1 KiB
Markdown
63 行
5.1 KiB
Markdown
# 订单与资源服务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）经审查全量补齐剩余漏标的金额字段**。
|
||
|
||
**字段类型在 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 实测）：
|
||
|
||
```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...`）；本批为其全量补齐续作。
|