nexus/Project/fonrey/UI_DESIGN/ROUTES.md

# Fonrey 路由与组件映射表 (ROUTES.md)

> **文档定位**：Fonrey MVP 全局路由与 UI 组件映射的权威来源。
> **适用对象**：Web 开发、前端工程、后端视图开发。
> **更新原则**：新增页面必须在此登记。URL 命名严格遵循 RESTful + Django 习惯。
> **对齐基线**：本表与 `UI_DESIGN/*/*.md` 各模块设计文档对齐。模块设计文档的页面清单是权威，本文为汇总入口。

---

## 1. 通用约定

- **URL 规范**：资源复数形式 + 末尾斜杠（例如：`/properties/`）。
- **多租户**：业务端 URL 不携带租户 ID（Schema 由 `django-tenants` 中间件按 subdomain 切换）；平台管理后台为 `public` schema 下独立子域，前缀 `/admin/`。
- **分页规范**：所有列表页强制使用 **Keyset 分页**。API 主参数统一为 `cursor`，禁止使用 `offset`。**过渡兼容**（MVP Phase 1 期，详见 `ADR-20260604-001`）：已有 page-based 示例的模块可保留页码 UI 表现（页码导航 + 跳页），但后端 API 必须以 `cursor` 为主参数；`page` 仅作过渡输入且不得用于 1000 条以上数据集。MVP GA 后 1 个版本内须清理所有 page-based 示例。
- **Tab 维度**：列表页的 Tab 切换统一以 query param `?tab=` 表达；切换走 HTMX 局刷，由后端根据 `tab` 返回对应数据。
- **HTMX Partial 路径**：业务页面的局部刷新走 `/<resource>/_partials/<purpose>/`；与某条记录强绑定的子区块走 `/<resource>/<uuid>/<sub>/partial`。
- **JSON-only API 端点**：对外暴露给前端 AJAX/HTMX 的纯数据端点统一前缀 `/api/`。
- **组件引用**：本表"复用组件"列必须严格引用 [`UI_SYSTEM/组件清单.md`](../UI_SYSTEM/组件清单.md) 中的标准名称，统一双语形式 `English（中文）`。新增组件必须先入组件清单再在此引用，禁止造词。
- **页面权威来源**：每个模块的路由细节、Tab/筛选、交互态以同模块下 `UI_DESIGN/<模块>/*_UI.md` 为准；本表仅做全局汇总。

---

## 2. 全局基础页面

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **仪表盘 (Dashboard)** | `/` | 统计页 | `Tab Navigation（标签页导航）`, `Collapsible Card Grid（折叠展开面板）` | **空**: 暂无统计数据(图表显示 0) / **加载**: Skeleton 占位 / **错误**: 全局 500 / **权限**: 重定向至登录 |
| **404 错误页** | `/404/` | 错误页 | 无 | **空**: 不适用 / **加载**: 不适用 / **错误**: 展示 404 图文 / **权限**: 公开 |
| **500 错误页** | `/500/` | 错误页 | 无 | **空**: 不适用 / **加载**: 不适用 / **错误**: 展示 500 图文 / **权限**: 公开 |
| **403 无权限页** | `/403/` | 错误页 | 无 | **空**: 不适用 / **加载**: 不适用 / **错误**: 展示 403 图文 / **权限**: 已登录但无权 |

---

## 3. 登录管理模块 (Account)

> 权威来源：[`UI_DESIGN/登录管理/登录_UI.md`](./登录管理/登录_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **Tenant 识别页** | `/account/tenant/verify/` | 基础页 | 无 | **空**: 不适用 / **加载**: 提交按钮 Loading / **错误**: 租户未识别/网络错误内联提示 / **权限**: 公开 |
| **登录页（密码 Tab）** | `/account/login/` | 基础页 | `Tab Navigation（标签页导航）` | **空**: 不适用 / **加载**: 提交按钮 Loading / **错误**: 凭证错误 / 锁定 / 禁用 / 会话过期 字段级提示 / **权限**: 公开 |
| **登录页（验证码 Tab）** | `/account/login/?tab=otp` | 基础页 | `Tab Navigation（标签页导航）` | **空**: 不适用 / **加载**: OTP 发送 / 倒计时态 / **错误**: OTP 错误 / 过期 内联提示 / **权限**: 公开 |
| **设置新密码页** | `/account/password/reset/` | 基础页 | 无 | **空**: 不适用 / **加载**: 强度校验态 + 提交 Loading / **错误**: 两次不一致/校验失败 内联提示 / **权限**: 仅通过 OTP 校验的合法 Token |
| **退出登录** | `/account/logout/` | 处理页 | 无 | **空**: 不适用 / **加载**: 渐进式遮罩 / **错误**: Toast 提示 / **权限**: 仅登录用户 |
| **(Partial) 租户识别** | `POST /api/auth/tenant/verify/` | API | — | **错误**: JSON 错误码 + 字段级提示 / **权限**: 公开 |
| **(Partial) 密码登录** | `POST /api/auth/login/` | API | — | **错误**: JSON 错误码（凭证/锁定/禁用） / **权限**: 公开 |
| **(Partial) OTP 发送** | `POST /api/auth/login/phone/` | API | — | **错误**: 频率限制/号码非法 / **权限**: 公开 |
| **(Partial) 找回密码-请求** | `POST /api/auth/recover/password/request/` | API | — | **错误**: 账号不存在/限流 / **权限**: 公开 |
| **(Partial) 找回密码-校验** | `POST /api/auth/recover/password/verify/` | API | — | **错误**: OTP 错误/过期 / **权限**: 公开 |
| **(Partial) 找回密码-重置** | `POST /api/auth/recover/password/reset/` | API | — | **错误**: Token 过期/校验失败 / **权限**: 持有有效重置 Token |

---

## 4. 房源管理模块 (Property)

> 权威来源：[`UI_DESIGN/房源管理/房源列表_UI.md`](./房源管理/房源列表_UI.md) / [`房源详情_UI.md`](./房源管理/房源详情_UI.md) / [`新增房源_UI.md`](./房源管理/新增房源_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **房源列表（全部）** | `/properties/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）`, `Toolbar（操作工具栏）`, `Export Button（导出按钮）`, `Smart Sort（智能排序）`, `Tab Navigation（标签页导航）` | **空**: 暂无房源(引导图 + 新增 CTA) / **加载**: 表格 Skeleton / **错误**: 列表刷新失败 Toast / **权限**: 403 遮罩 |
| **房源列表（出售 Tab）** | `/properties/?tab=for_sale` | 列表页 | 同上 | 同上 |
| **房源列表（出租 Tab）** | `/properties/?tab=for_rent` | 列表页 | 同上 | 同上 |
| **房源列表（未挂牌 Tab）** | `/properties/?tab=unlisted` | 列表页 | 同上 | 同上 |
| **房源列表（成交 Tab）** | `/properties/?tab=sold` | 列表页 | 同上 | 同上 |
| **重复房源** | `/properties/duplicates/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无重复 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员/店长 |
| **嫌疑号码** | `/properties/suspect-numbers/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无嫌疑号 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员/店长 |
| **新增房源** | `/properties/create/` | 编辑页(独立) | `Tab Navigation（标签页导航）`, `Multi-select Tag Input（多选标签选择器）`, `Tree Select / Cascading Dropdown（树形下拉选择器）` | **空**: 字段默认值 / **加载**: 表单骨架屏 / **错误**: 422 字段级 / 500 Toast / **权限**: 仅有权经纪人 |
| **房源详情** | `/properties/<uuid>/` | 详情页 | `Tab Navigation（标签页导航）`, `Accordion Progress Panel（可折叠进度检查面板）`, `Collapsible Card Grid（折叠展开面板）`, `Image Lightbox View（全屏图片灯箱预览器）` | **空**: 房源不存在(404) / **加载**: 模块化局部 Skeleton / **错误**: 详情加载失败 Toast / **权限**: 403 页面 |
| **房源全量编辑** | `/properties/<uuid>/edit/` | 编辑页(独立) | `Tab Navigation（标签页导航）`, `Inline Edit Mode（页面级读写切换）`, `Multi-select Tag Input（多选标签选择器）` | **空**: 不适用 / **加载**: 表单骨架屏 / **错误**: 提交失败(422/500) / **权限**: 仅维护人/管理员 |
| **挂牌历史** | `/properties/<uuid>/history/` | 子详情页 | `Collapsible Card Grid（折叠展开面板）` | **空**: 暂无挂牌记录 / **加载**: 列表 Skeleton / **错误**: Toast / **权限**: 403 遮罩 |
| **(Partial) 写跟进** | `/properties/<uuid>/_partials/followup/` | Drawer | `Drawer / Slide-over Panel（右侧抽屉面板）`, `Tab Navigation（标签页导航）` | **加载**: Drawer 内 Loading / **错误**: 提交失败 Toast / **权限**: 仅参与经纪人 |
| **(Partial) 相册管理** | `/properties/<uuid>/_partials/gallery/` | Modal | `Photo Gallery Manager（相册管理器）`, `Sortable Table with Drag Handle（带拖拽手柄的可排序表格）` | **空**: 暂无照片 / **加载**: 缩略图 Skeleton / **错误**: 上传失败 Toast / **权限**: 仅维护人/管理员 |

---

## 5. 客源管理模块 (Client)

> 权威来源：[`UI_DESIGN/客源管理/客源列表_UI.md`](./客源管理/客源列表_UI.md) / [`客源详情_UI.md`](./客源管理/客源详情_UI.md) / [`新增客源_UI.md`](./客源管理/新增客源_UI.md) / [`编辑客源_UI.md`](./客源管理/编辑客源_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **私客列表（全部）** | `/clients/private/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）`, `Toolbar（操作工具栏）`, `Tab Navigation（标签页导航）` | **空**: 暂无客源(引导录入) / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 403 遮罩 |
| **私客列表（求购 Tab）** | `/clients/private/?tab=buying` | 列表页 | 同上 | 同上 |
| **私客列表（求租 Tab）** | `/clients/private/?tab=renting` | 列表页 | 同上 | 同上 |
| **私客列表（暂缓 Tab，P2）** | `/clients/private/?tab=suspended` | 列表页 | 同上 | 同上 |
| **公客列表（P2）** | `/clients/public/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无公客 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅店长/管理员 |
| **成交客列表（P2）** | `/clients/transacted/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无成交客 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员 |
| **重复客源** | `/clients/duplicates/?tab=transacted\|public` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）`, `Tab Navigation（标签页导航）` | **空**: 暂无重复 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员（成交/公客子集见 `ADR-20260604-002`） |
| **客源回收站** | `/clients/deleted/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无回收 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员 |
| **录入客源** | `/clients/create/` | 编辑页(独立) | `Tree Select / Cascading Dropdown（树形下拉选择器）`, `Multi-select Tag Input（多选标签选择器）` | **空**: 字段默认值 / **加载**: 表单 Loading / **错误**: 字段级 422 / 500 Toast / **权限**: 仅有权经纪人 |
| **客源详情** | `/clients/<uuid>/` | 详情页 | `Tab Navigation（标签页导航）`, `Collapsible Card Grid（折叠展开面板）` | **空**: 客源不存在 / **加载**: 局部 Skeleton / **错误**: Toast / **权限**: 403 页面 |
| **编辑客源** | `/clients/<uuid>/edit/` | 编辑页(独立) | `Tab Navigation（标签页导航）`, `Inline Edit Mode（页面级读写切换）`, `Tree Select / Cascading Dropdown（树形下拉选择器）` | **空**: 不适用 / **加载**: 表单 Loading / **错误**: 字段级 422 / **权限**: 仅归属人/首录人/管理员（其他重定向至详情 + Toast） |
| **(Partial) 电话重复检测** | `POST /clients/check-duplicate-phone/` | API | — | **错误**: 返回橙色警告 Partial / **权限**: 仅有权经纪人 |
| **(Partial) 跟进日志筛选/分页** | `/clients/<uuid>/follow-logs/partial/` | Partial | `Tab Navigation（标签页导航）` | **空**: 暂无跟进 / **错误**: Toast / **权限**: 仅参与经纪人 |
| **(Partial) 带看记录筛选** | `/clients/<uuid>/viewings/partial/` | Partial | — | **空**: 暂无带看 / **错误**: Toast / **权限**: 仅参与经纪人 |
| **(Partial) 客源解读刷新** | `/clients/<uuid>/insights/partial/` | Partial | — | **空**: 暂无洞察 / **错误**: Toast / **权限**: 仅参与经纪人 |
| **(Partial) 配房筛选/分页** | `/clients/<uuid>/matches/partial/` | Partial | `Pagination（分页组件）` | **空**: 暂无匹配 / **错误**: Toast / **权限**: 仅参与经纪人 |
| **(Partial) 查看号码** | `/clients/<uuid>/contacts/<cid>/reveal-phone/` | API | — | **错误**: 频次超限/无权 Toast / **权限**: 仅归属人/上级 |
| **(Partial) 标记号码无效** | `PATCH /api/clients/<uuid>/contacts/<cid>/mark-invalid/` | API | — | **错误**: 422 / 500 Toast / **权限**: 仅归属人/管理员 |
| **(Partial) 编辑基础信息弹窗** | `PATCH /api/clients/<uuid>/basic-info/` | Modal | `Modal Dialog（模态对话框）` | **错误**: 字段级 422 / **权限**: 仅归属人/管理员 |

---

## 6. 楼盘/区域管理模块 (Complex / Region)

> 权威来源：[`UI_DESIGN/楼盘管理/楼盘列表_UI.md`](./楼盘管理/楼盘列表_UI.md) / [`楼盘详情_UI.md`](./楼盘管理/楼盘详情_UI.md) / [`区域管理_UI.md`](./楼盘管理/区域管理_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **楼盘列表** | `/complexes/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）`, `Toolbar（操作工具栏）` | **空**: 暂无楼盘 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 全员可见/不可改 |
| **楼盘详情** | `/complexes/<uuid>/` | 详情页 | `Tab Navigation（标签页导航）`, `Collapsible Card Grid（折叠展开面板）` | **空**: 楼盘不存在 / **加载**: 局部 Skeleton / **错误**: Toast / **权限**: 全员可见 |
| **区域/商圈管理** | `/regions/` | 设置页 | `Tree Select / Cascading Dropdown（树形下拉选择器）`, `Dynamic Form Table（动态可增删行表格）` | **空**: 暂无配置 / **加载**: 树形 Skeleton / **错误**: 保存失败 Toast / **权限**: 仅系统管理员 |

---

## 7. 组织人事模块 (Org / Staff)

> 权威来源：[`UI_DESIGN/组织人事管理/组织人事_UI.md`](./组织人事管理/组织人事_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **组织架构** | `/org/` | 树形页 | `Tree Select / Cascading Dropdown（树形下拉选择器）`, `Drawer / Slide-over Panel（右侧抽屉面板）` | **空**: 暂无门店 / **加载**: 树形 Skeleton / **错误**: Toast / **权限**: 仅管理员 |
| **人员列表** | `/staff/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）`, `Toolbar（操作工具栏）` | **空**: 暂无员工 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅管理员/店长 |
| **人员详情** | `/staff/<uuid>/` | 详情页 | `Inline Edit Mode（页面级读写切换）`, `Collapsible Card Grid（折叠展开面板）` | **空**: 人员不存在 / **加载**: 局部 Skeleton / **错误**: Toast / **权限**: 仅本人/上级/管理员 |

---

## 8. 权限管理模块 (Permission)

> 权威来源：[`UI_DESIGN/权限管理/权限管理_UI.md`](./权限管理/权限管理_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **角色权限配置** | `/permissions/roles/` | 设置页 | `Tab Navigation（标签页导航）`, `Dynamic Form Table（动态可增删行表格）`, `Drawer / Slide-over Panel（右侧抽屉面板）` | **空**: 暂无角色 / **加载**: 列表 Loading / **错误**: 配置失败 Toast / **权限**: 仅系统管理员 |
| **人员权限分配** | `/permissions/assignments/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Tree Select / Cascading Dropdown（树形下拉选择器）` | **空**: 暂无分配 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅系统管理员 |

---

## 9. 系统配置模块 (Setting)

> 权威来源：[`UI_DESIGN/系统配置/系统配置_UI.md`](./系统配置/系统配置_UI.md) / [`首页设置_UI.md`](./系统配置/首页设置_UI.md)

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **全局参数配置** | `/settings/params/` | 设置页 | `Inline Edit Mode（页面级读写切换）`, `Dynamic Form Table（动态可增删行表格）`, `Multi-Table Independent Pagination（同页多表格独立分页）` | **空**: 暂无参数 / **加载**: 局部 Skeleton / **错误**: 保存失败 Toast / **权限**: 仅系统管理员 |
| **首页设置** | `/settings/homepage/` | 设置页 | `Inline Edit Mode（页面级读写切换）`, `Collapsible Card Grid（折叠展开面板）` | **空**: 默认模板 / **加载**: 局部 Skeleton / **错误**: 保存失败 Toast / **权限**: 仅系统管理员 |
| **关注楼盘** | `/settings/watch-complexes/` | 设置页 | `Tree Select / Cascading Dropdown（树形下拉选择器）`, `Multi-select Tag Input（多选标签选择器）` | **空**: 暂未关注 / **加载**: Tree Skeleton / **错误**: 保存失败 Toast / **权限**: 仅本人/管理员 |
| **(Partial) 字段自定义** | `/settings/_partials/fields/` | Drawer | `Drawer / Slide-over Panel（右侧抽屉面板）`, `Sortable Table with Drag Handle（带拖拽手柄的可排序表格）` | **加载**: Drawer Loading / **错误**: 422 Toast / **权限**: 仅系统管理员 |

---

## 10. 平台管理后台 (Platform Admin)

> 仅由平台超级管理员在 Public Schema 下访问，独立子域，统一前缀 `/admin/`。
> 权威来源：[`UI_DESIGN/平台管理后台/平台管理后台_UI.md`](./平台管理后台/平台管理后台_UI.md) §3.1。

| 页面名称 | URL 路径 | 页面类型 | 复用组件 | 空/加载/错误/权限状态描述 |
| :--- | :--- | :--- | :--- | :--- |
| **平台管理员登录** | `/admin/login/` | 基础页 | 无 | **空**: 不适用 / **加载**: 提交按钮 Loading / **错误**: 凭证错误内联提示 / **权限**: 公开 |
| **平台仪表盘** | `/admin/` | 统计页 | `Collapsible Card Grid（折叠展开面板）` | **空**: 暂无数据 / **加载**: Skeleton / **错误**: Toast / **权限**: 仅平台管理员 |
| **租户列表** | `/admin/tenants/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）`, `Toolbar（操作工具栏）` | **空**: 暂无租户 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **新建租户** | `/admin/tenants/new/` | 编辑页(独立) | `Tab Navigation（标签页导航）`, `Multi-select Tag Input（多选标签选择器）` | **空**: 字段默认值 / **加载**: 表单 Loading / **错误**: 422 字段级 / **权限**: 仅平台超管 |
| **租户详情 - 基本信息** | `/admin/tenants/<id>/` | 详情页 | `Tab Navigation（标签页导航）`, `Collapsible Card Grid（折叠展开面板）`, `Inline Edit Mode（页面级读写切换）` | **空**: 租户不存在 / **加载**: 局部 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **租户详情 - 用户管理** | `/admin/tenants/<id>/users/` | 子列表 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无用户 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **租户详情 - 套餐信息** | `/admin/tenants/<id>/plan/` | 子设置页 | `Inline Edit Mode（页面级读写切换）`, `Modal Dialog（模态对话框）` | **空**: 默认套餐 / **加载**: 局部 Skeleton / **错误**: 422 字段级 / **权限**: 仅平台超管 |
| **租户详情 - 监控** | `/admin/tenants/<id>/monitoring/` | 子统计页 | `Collapsible Card Grid（折叠展开面板）` | **空**: 暂无指标 / **加载**: 图表 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **租户详情 - 备份记录** | `/admin/tenants/<id>/backups/` | 子列表 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无备份 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **租户详情 - 操作历史** | `/admin/tenants/<id>/history/` | 子列表 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无记录 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营/审计 |
| **系统版本管理** | `/admin/system/versions/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）`, `Drawer / Slide-over Panel（右侧抽屉面板）` | **空**: 暂无版本 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管 |
| **系统备份管理** | `/admin/system/backups/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）` | **空**: 暂无备份 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **监控与告警** | `/admin/monitoring/` | 统计页 | `Collapsible Card Grid（折叠展开面板）`, `Tab Navigation（标签页导航）` | **空**: 暂无告警 / **加载**: 图表 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营 |
| **客户端版本管理** | `/admin/client-releases/` | 列表页 | `Data Table（数据表格）`, `Pagination（分页组件）`, `Drawer / Slide-over Panel（右侧抽屉面板）` | **空**: 暂无发布 / **加载**: 列表 Skeleton / **错误**: 发布失败 Toast / **权限**: 仅平台超管 |
| **审计日志** | `/admin/audit-logs/` | 列表页 | `Data Table（数据表格）`, `Column Visibility Panel（自定义列显示）`, `Pagination（分页组件）` | **空**: 暂无日志 / **加载**: 表格 Skeleton / **错误**: Toast / **权限**: 仅平台超管/运营/审计 |
| **管理员设置** | `/admin/settings/admins/` | 列表+设置 | `Data Table（数据表格）`, `Drawer / Slide-over Panel（右侧抽屉面板）`, `Inline Edit Mode（页面级读写切换）` | **空**: 暂无管理员 / **加载**: 表格 Skeleton / **错误**: 422 字段级 / **权限**: 仅平台超管 |

---

## X. 非 MVP 占位 (v2 规划)

- **移动端适配页**：`/m/` 起始的所有路由。
- **合同管理**：`/contracts/`。
- **财务结算**：`/finance/`。
- **营销/三网发布**：`/marketing/`。
- **新房模块**：`/new-houses/`。

---

## 附录 A: 页面状态定义 (Page States)

- **空 (Empty)**: 使用 `Empty State` 设计，包含图标、说明文案及主要行动点 (CTA)。
- **加载 (Loading)**: 优先使用 `Skeleton` 骨架屏（针对表格、详情块）；按钮操作使用 `Spinner` 及禁用态。
- **错误 (Error)**:
  - 页面级：404/500 全屏错误页。
  - 异步/局部：通过 `HX-Trigger` 弹出 `fonrey:toast` 提示。
  - 表单：422 返回包含错误信息的 Partial，红色文字定位到字段。
- **权限 (Permission)**:
  - 无权访问页面：重定向至 403 页面。
  - 无权操作按钮：不渲染该按钮或置灰。

---

## 附录 B: 页面类型定义 (Page Types)

- **列表页 (List)**: 主体为数据表格，含筛选、分页。
- **详情页 (Detail)**: 多维展示单一资源，多为 Tab 布局。
- **编辑页(独立) (Edit Page)**: 独立 URL 的全量表单页（非 Drawer/Modal）。
- **设置页 (Setting)**: 多为左侧导航 + 右侧表单/列表，含读写切换。
- **基础页 (Base)**: 独立布局，如登录、错误页。
- **统计页 (Stats)**: 以指标卡 + 图表为主。
- **子详情页 / 子列表 / 子设置页**: 嵌于某条记录上下文下的二级页面。
- **Partial**: 供 HTMX 调用的局部 HTML 片段。
- **API**: 仅返回 JSON / 局部 HTML 的端点，无独立页面。

---

## 附录 C: 与 UI_DESIGN 模块文档的对齐索引

| 模块 | 权威 UI 设计文档 |
| :--- | :--- |
| 登录 | [`UI_DESIGN/登录管理/登录_UI.md`](./登录管理/登录_UI.md) |
| 房源 | [`房源列表_UI.md`](./房源管理/房源列表_UI.md) / [`房源详情_UI.md`](./房源管理/房源详情_UI.md) / [`新增房源_UI.md`](./房源管理/新增房源_UI.md) |
| 客源 | [`客源列表_UI.md`](./客源管理/客源列表_UI.md) / [`客源详情_UI.md`](./客源管理/客源详情_UI.md) / [`新增客源_UI.md`](./客源管理/新增客源_UI.md) / [`编辑客源_UI.md`](./客源管理/编辑客源_UI.md) |
| 楼盘/区域 | [`楼盘列表_UI.md`](./楼盘管理/楼盘列表_UI.md) / [`楼盘详情_UI.md`](./楼盘管理/楼盘详情_UI.md) / [`区域管理_UI.md`](./楼盘管理/区域管理_UI.md) |
| 组织人事 | [`组织人事_UI.md`](./组织人事管理/组织人事_UI.md) |
| 权限 | [`权限管理_UI.md`](./权限管理/权限管理_UI.md) |
| 系统配置 | [`系统配置_UI.md`](./系统配置/系统配置_UI.md) / [`首页设置_UI.md`](./系统配置/首页设置_UI.md) |
| 平台管理后台 | [`平台管理后台_UI.md`](./平台管理后台/平台管理后台_UI.md) |