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

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

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