# 房务日历「我的 / 全部」切换契约（前端对接）

> 模块：房务管家 · 日历视图（管理后台）
> 类型：**前端对接说明（后端无改动，能力早已具备）**
> 日期：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` 即可。**