docs(house/calendar): 房务日历 我的/全部 scope 切换契约(前端对接, 后端无改动)

changelogs-v2/2026-06/34_房务日历我的全部scope切换契约_前端对接-管理后台.md

@@ -0,0 +1,73 @@
+# 房务日历「我的 / 全部」切换契约（前端对接）
+
+> 模块：房务管家 · 日历视图（管理后台）
+> 类型：**前端对接说明（后端无改动，能力早已具备）**
+> 日期：2026-06-28
+> 背景：房务日历需要能看到「全部订单」，当前默认只看本人（我的）。后端 `GET /admin/house/calendar` **早已支持 `scope=all` 返回全部、且无任何角色门控**，前端把「全部」Tab 接到 `scope=all` 即可，无需后端改动。
+
+---
+
+## 一、端点与参数（不变）
+
+`GET /admin/house/calendar`
+
+| 参数 | 必填 | 取值 | 说明 |
+|------|------|------|------|
+| `month` | 是 | `YYYY-MM`（如 `2026-06`） | 月份 |
+| `scope` | 否 | `mine`（**默认**）/ `all` | **「我的」=`mine`，「全部」=`all`** |
+| `status` | 否 | `inProgress,inquiry,pending,exception` 多选逗号分隔，不填=全部 | 状态点筛选 |
+
+## 二、「我的 / 全部」怎么切换（核心）
+
+**同一个端点，切换 Tab 只改 `scope` 参数值、重新请求即可**，其余参数（month/status）不变：
+
+- 点「我的」→ 请求 `?month=2026-06&scope=mine`
+- 点「全部」→ 请求 `?month=2026-06&scope=all`
+
+两个 scope 的差异（后端口径）：
+
+| | `scope=mine`（我的） | `scope=all`（全部） |
+|---|---|---|
+| 数据范围 | **仅当前登录房务作为认领人（claimer）的订单** | **所有订单**，不按认领人过滤 |
+| 角色门控 | 无 | **无**（普通房务 / admin / 组长都能看全部，不需要组长权限） |
+| 待配房桶（pending，无归属房务） | **恒为空**（待配房还没认领人，不属于"我的"） | 正常返回本月全部待配房 |
+| summary 各计数 / days 各天团数 | 按"我的"口径 | 按"全部"口径 |
+
+> 即：要让日历"看到全部订单"，前端在「全部」Tab 下传 `scope=all` 即可。**建议日历默认进入时用 `scope=all`（一眼看全团），保留「我的」Tab 让房务切回 `scope=mine` 只看自己。** 是否默认全部由前端定，后端两种都支持。
+
+## 三、出参结构（随 scope 变化，结构不变）
+
+```
+{
+  "month": "2026-06",
+  "summary": { "totalNights": 64, "inProgress": 32, "pending": 0, "inquiry": 0, "exception": 0 },
+  "days": [
+    {
+      "date": "2026-06-28",
+      "isCurrentMonth": true,
+      "isToday": true,
+      "tourCount": 24,                       // 该日团数(DISTINCT order_id)
+      "statusDots": [                        // 右下角圆点
+        { "status": "inProgress", "label": "进行中", "count": 14, "color": "green" },
+        { "status": "inquiry",    "label": "询房中", "count": 8,  "color": "orange" },
+        { "status": "exception",  "label": "异常",   "count": 2,  "color": "red" }
+      ]
+    }
+    // ... 完整周排版 28~42 天, isCurrentMonth=false 的为补位的上/下月日期(灰显)
+  ]
+}
+```
+
+- `summary` 与 `days` 都随 `scope` 变；`scope=mine` 且当前房务名下无认领时全为 0（`totalNights=0`、days 无点）。
+- 状态点 `status` 取值：`inProgress`(进行中) / `inquiry`(询房中) / `pending`(待配房) / `exception`(异常)。
+
+## 四、测试服实测（已通过，证明能力具备）
+
+同一 admin 账号、同月 `2026-06`：
+
+| scope | 实测结果 | 说明 |
+|-------|----------|------|
+| `mine` | `totalNights=0`、0 团 | 该账号名下无认领订单 → 我的为空 |
+| `all` | `totalNights=64`、`inProgress=32` 团 | **全部订单正常返回**，无门控 |
+
+接口 HTTP 200，结构如上。**后端无需任何改动，前端按本说明把「全部」Tab 接到 `scope=all` 即可。**