5.1 KiB
5.1 KiB
楼盘列表 UI 设计文档
任务编号：04（P0-B）
覆盖范围：US-COMPLEX-002（经纪人查看楼盘列表与详情入口）
输出文件：UI_DESIGN/楼盘列表_UI.html
设计基线：UI_SYSTEM/UI_SYSTEM.md（列表页模板、Top Bar + Sidebar 壳层、分页规范）
1. 目标与范围
1.1 页面目标
楼盘列表页用于经纪人和运营人员进行楼盘检索与筛选，并作为楼盘详情页的统一入口。
核心目标：
- 支持关键词搜索（楼盘名称 / 别名 / 概要地址）
- 支持区域、用途等维度筛选
- 支持分页（默认 20 条/页 + 跳页）
- 列表中楼盘名称可点击进入楼盘详情
- 提供完整度统计面板与批量操作入口位（P0 原型占位）
1.2 本任务边界
本任务只交付“楼盘列表页”的静态高保真原型，不实现真实后端查询。
- ✅ 包含：筛选交互、分页演示、详情跳转入口位
- ⛔ 不包含：真实接口联动、真实批量操作执行、真实权限校验
2. 信息架构
2.1 壳层结构（与新增客源/房源详情一致）
- Top Bar（固定 56px）：品牌 + 一级导航 + 用户区
- Sidebar（固定 240px）：房源管理二级导航
- Main Content（
ml-60 pt-[72px]）：- 面包屑 + 页面标题
- 模块 Tab（楼盘 / 区域管理 / 学校管理 / 应用标准数据）
- 完整度统计面板
- 搜索筛选区
- 批量操作条
- 列表表格
- 分页条
2.2 楼盘列表表格字段
| 列字段 | 说明 |
|---|---|
| 勾选 | 批量操作选择 |
| 楼盘名称 | 蓝色可点击，进入详情页 |
| 楼盘类型 | 住宅 / 别墅 / 商住 / 商业 / 写字楼 / 其他 |
| 详细地址 | 城市 + 街道 / 弄号 |
| 城区商圈 | 形如「嘉定-江桥新城」 |
| 当月挂牌均价(元/㎡) | 数值，支持排序入口位 |
| 楼栋数 | 数值 |
| 产品数 | 数值 |
| 房源数 | 出售N / 出租N / 共N |
| 操作 | 编辑 / 删除 |
3. 交互设计
3.1 搜索与筛选
3.1.1 关键词搜索
- 输入框占位：
楼盘名/别名/拼音/详细地址 - 点击「查询」执行前端过滤演示
- 点击「清除」重置全部条件
3.1.2 快捷筛选
- 区域：不限、静安、闵行、普陀、松江、长宁、嘉定
- 用途：不限、住宅、别墅、商住、商业、写字楼、其他
3.1.3 下拉筛选（占位）
- 固定情况
- 完善情况
- 楼盘类型
- 有无房源
- 楼栋类型
- 权属关系
- 有无坐标
以上下拉项在本原型为可见控件，不做真实复杂筛选逻辑。
3.2 批量操作
按钮区：
-
- 新增楼盘（主 CTA）
- 批量新增楼栋
- 批改区域商圈
- 删除
- 合并楼盘
规则（原型态）：
- 当未选择行时，批量按钮显示禁用态
- 选中 1 条及以上时，禁用态解除（仅视觉）
3.3 列表与跳转
- 点击楼盘名称：跳转
#/complex/{id}（原型 hash）并 Toast 提示“进入楼盘详情（原型）” - 点击编辑 / 删除：仅触发提示，不执行真实动作
3.4 分页
- 默认每页 20 条
- 支持上一页 / 下一页
- 支持输入页码跳转（超范围自动纠正）
- 展示
共 X 条+ 当前页码
4. 状态矩阵
| 状态 | 触发 | 页面反馈 |
|---|---|---|
| 默认 | 首次加载 | 展示全部 mock 数据第一页 |
| 搜索结果 | 输入关键词并查询 | 表格按关键词过滤 |
| 空结果 | 条件过严 | 空状态（暂无匹配楼盘）+ 清除筛选 |
| 行选中 | 勾选一行或全选 | 批量按钮解除禁用 |
| 分页切换 | 点击页码/上一页/下一页 | 列表刷新为对应页 |
| 页面主题 | 统一浅色管理后台主题 | 不在页面内提供 Light/Dark 切换控件 |
5. 数据模型映射（DATA_MODEL_COMPLEX）
| UI 字段 | 数据模型字段 |
|---|---|
| 楼盘名称 | complexes.name |
| 详细地址 | complexes.address |
| 概要地址（搜索） | complexes.address_summary |
| 城区 | complexes.district_id -> districts.name |
| 主商圈 | complex_business_areas.is_primary -> business_areas.name |
| 楼栋数 | COUNT(buildings.id) |
| 出售/出租数量 | properties.status 聚合 |
| 搜索向量 | complexes.search_vector |
6. 可访问性与规范
- 表头使用语义化
<th scope="col"> - 纯图标按钮添加
aria-label - 所有输入项含可见 label 或占位 + 分组标题
- 焦点态统一
focus-visible:ring-2 - 空状态提供主动作按钮（清除筛选）
7. 验收清单
- 壳层结构：Top Bar + Sidebar + Main
- 楼盘列表页模块 Tab 完整
- 统计面板、筛选区、批量区、表格区、分页区完整
- 默认 20 条/页的分页演示
- 楼盘名称可点击触发“进入详情”原型行为
- 页面内不包含主题切换控件（遵循统一后台视觉）
- 控制台 0 报错（本地预览验证阶段）
8. 后续衔接
- 本页评审通过后，进入任务05：楼盘详情/维护（
US-COMPLEX-001） - 任务05将复用本页的详情入口与模块 Tab 风格，保证楼盘模块前后页体验一致