From 319751c781c851d9c3aa219501c63c1832668b38 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 28 Jun 2026 09:00:36 +0800
Subject: [PATCH] =?UTF-8?q?docs(house/calendar):=20=E6=88=BF=E5=8A=A1?=
 =?UTF-8?q?=E6=97=A5=E5=8E=86=20=E6=88=91=E7=9A=84/=E5=85=A8=E9=83=A8=20sc?=
 =?UTF-8?q?ope=20=E5=88=87=E6=8D=A2=E5=A5=91=E7=BA=A6(=E5=89=8D=E7=AB=AF?=
 =?UTF-8?q?=E5=AF=B9=E6=8E=A5,=20=E5=90=8E=E7=AB=AF=E6=97=A0=E6=94=B9?=
 =?UTF-8?q?=E5=8A=A8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...¥åŽ†æˆ‘的全部scope切æ�¢å¥‘约_å‰�端对接-管ç�†å�Žå�°.md | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 changelogs-v2/2026-06/34_房务日历我的全部scope切�契约_�端对接-管���.md

diff --git a/changelogs-v2/2026-06/34_房务日历我的全部scope切�契约_�端对接-管���.md b/changelogs-v2/2026-06/34_房务日历我的全部scope切�契约_�端对接-管���.md
new file mode 100644
index 0000000..95d8ec9
--- /dev/null
+++ b/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` ��。**