Files
nexus/Project/fonrey/UI_DESIGN/ROUTES.md
2026-06-04 14:34:32 +08:00

25 KiB
Raw Blame History

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

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


1. 通用约定

  • URL 规范:资源复数形式 + 末尾斜杠(例如:/properties/)。
  • 多租户:业务端 URL 不携带租户 IDSchema 由 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 中的标准名称,统一双语形式 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

页面名称 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

页面名称 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

页面名称 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 列表页 同上 同上
私客列表(暂缓 TabP2 /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

页面名称 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

页面名称 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

页面名称 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

页面名称 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 §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