Merge pull request 'docs: 房务订单详情补充团号契约 (#5150)' (#21) from docs/5150-house-detail-team-no into main

changelogs-v2/2026-07/83_5150_房务订单详情补充团号-修改接口-前端待处理-管理后台.md

@@ -0,0 +1,85 @@
+# 房务订单详情：订单概要补充团号
+
+> **服务**: hl-order-service-v3
+> **PR**: [wx/HL#5151](https://git.1814.love:8443/wx/HL/pulls/5151)
+> **Issue**: [wx/HL#5150](https://git.1814.love:8443/wx/HL/issues/5150)
+> **日期**: 2026-07-22
+> **影响范围**: 管理后台 · 房务订单详情弹窗标题/订单概要
+
+---
+
+## 关键变化
+
+房务订单详情响应的 `data.order` 新增 `teamNo`。前端可直接显示订单当前团号；尚未生成团号时字段为 `null`，不要以订单号或其他值拼造团号。
+
+---
+
+## 变更接口
+
+| 接口 | 方法 | 路径 | 变更类型 |
+|------|------|------|----------|
+| 房务订单详情 | GET | `/admin/house/orders/{orderId}` | 响应字段扩展 |
+
+### 出参 `Result<HouseOrderDetailRespVO>`
+
+| 字段路径 | 类型 | 是否新增 | 说明 |
+|----------|------|----------|------|
+| `data.order.teamNo` | `string/null` | 是 | 当前订单团号，取自 `order_main.team_no`；订金支付后生成，未生成时为 `null` |
+
+有团号响应片段：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "order": {
+      "orderId": "2044321098765432100",
+      "orderNo": "HL20260721171011648",
+      "teamNo": "26-0518",
+      "productName": "孔知悦"
+    }
+  },
+  "success": true
+}
+```
+
+尚未生成团号时：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "order": {
+      "orderId": "2044321098765432100",
+      "orderNo": "HL20260721171011648",
+      "teamNo": null,
+      "productName": "孔知悦"
+    }
+  },
+  "success": true
+}
+```
+
+---
+
+## 前端处理
+
+1. 房务订单详情弹窗标题建议按“订单详情 · 订单号 · 团号 · 产品名”展示。
+2. 团号读取 `data.order.teamNo`；有值时显示，无值时隐藏团号片段或显示统一空值占位。
+3. 不要用 `orderNo` 回退为团号，也不要从列表缓存或历史快照读取团号。
+
+---
+
+## 边界与不影响范围
+
+- 本次仅新增只读响应字段，不修改入参、状态机、房务权限和配房流程。
+- 现有响应字段保持兼容。
+- 无团号的存量订单正常返回 `teamNo: null`，无需数据迁移。
+- `D:/work2/hl-ui` 未修改，前端适配由管理后台项目单独处理。
+
+---
+
+## 后端验证
+
+- `HouseDetailAggregatorTest` 覆盖有团号、未生成团号两种场景。
+- 定向测试结果：77 tests passed。