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` 即可。**