40 行
2.9 KiB
Markdown
40 行
2.9 KiB
Markdown
# 房务日历：新增「已完成」状态点，finalize 完成的团不再误显「进行中」
|
||
|
||
> 模块：房务管家 · 日历视图（管理后台）
|
||
> 类型：后端修复 + 前端对接（日历 statusDots 新增第 5 类取值）
|
||
> 日期：2026-06-29
|
||
> 关联：PR #4624（已合并 dev-v3 + 部署测试服 + API 实测闭环）
|
||
|
||
## 背景
|
||
房务手测发现：订单详情显示「已完成」的团，在日历视图里却显示「进行中」——口径不一致。
|
||
根因：日历此前只有 4 类状态点（异常/待配房/进行中/询房中），缺「已完成」桶；finalize 完成的需求（house_status=CONFIRMED）其配房行 confirm_status 仍是 CONFIRMED，被归进「进行中」。
|
||
|
||
## 后端改动（已上线测试服）
|
||
`GET /admin/house/calendar` 与 `GET /admin/house/calendar/day` 的返回新增「已完成」桶：
|
||
|
||
1. **statusDots[] 新增第 5 类取值**：
|
||
```json
|
||
{ "status": "confirmed", "label": "已完成", "count": 1, "color": "blue" }
|
||
```
|
||
- 触发：该团需求 house_status=CONFIRMED（房务已最终回传）
|
||
- 整团（订单维度）覆盖其全部已确认配房行 → 该团所有住宿晚在日历显「已完成」蓝点
|
||
|
||
2. **summary 新增字段 `confirmed`**（月度摘要「已完成」团数）：
|
||
```json
|
||
"summary": { "totalNights": 12, "inProgress": 2, "inquiry": 1, "pending": 0, "exception": 0, "confirmed": 2 }
|
||
```
|
||
|
||
3. **status 筛选参数**支持 `confirmed`（与原 inProgress/inquiry/pending/exception 并列，逗号多选）。
|
||
|
||
## 【前端必看】
|
||
- 日历状态点渲染若是按 `status` 白名单硬编码的（只认 inProgress/inquiry/pending/exception），**请补 `confirmed` 一类**，否则 finalize 完成的团会从日历消失（比修复前更糟）。
|
||
- 推荐做法：直接用接口返回的 `label` + `color` 通用渲染（status 仅作筛选 key），后端已自描述。
|
||
- 颜色约定（与文档 §2.6 一致）：异常=red / 待配房=gray / 进行中=green / 询房中=yellow / **已完成=blue（新增）**。
|
||
|
||
## 口径对齐说明（无需前端处理，仅知悉）
|
||
- 「待最终确认」(PENDING_FINALIZE) 在日历仍归「进行中」绿点（wx 拍板保持现状，日历为天级概览，不单列该态）；详情/我的接单/工作台首页仍各自显「待最终确认」。
|
||
- 「询房中」(inquiry) 是日历专属细分态（assignment 级有 INQUIRING 行），系统其它视图按 house_status 显「配房中」——文档 §2.6 设计如此，非缺陷。
|
||
|
||
## 补充（PR #4657，2026-06-29 每日 CR 收口，无需前端处理）
|
||
- 后端已把 `DayTourItemVO.status` / `CalendarRespVO.StatusDot.status` 的 swagger `@ApiModelProperty` 枚举描述补上 `confirmed`（此前漏列仅 4 类）。看 knife4j 文档对接的前端现在能看到完整 5 类取值。纯文档/契约描述对齐，响应结构与行为不变，前端行动项同上「前端必看」不变。
|