# 楼盘列表 UI 设计文档

> **任务编号**：04（P0-B）  
> **覆盖范围**：`US-COMPLEX-002`（经纪人查看楼盘列表与详情入口）  
> **输出文件**：`UI_DESIGN/楼盘列表_UI.html`  
> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（列表页模板、Top Bar + Sidebar 壳层、分页规范）

---

## 1. 目标与范围

### 1.1 页面目标

楼盘列表页用于经纪人和运营人员进行楼盘检索与筛选，并作为楼盘详情页的统一入口。

核心目标：

1. 支持关键词搜索（楼盘名称 / 别名 / 概要地址）
2. 支持区域、用途等维度筛选
3. 支持分页（默认 20 条/页 + 跳页）
4. 列表中楼盘名称可点击进入楼盘详情
5. 提供完整度统计面板与批量操作入口位（P0 原型占位）

### 1.2 本任务边界

本任务只交付“楼盘列表页”的静态高保真原型，不实现真实后端查询。

- ✅ 包含：筛选交互、分页演示、详情跳转入口位
- ⛔ 不包含：真实接口联动、真实批量操作执行、真实权限校验

---

## 2. 信息架构

## 2.1 壳层结构（与新增客源/房源详情一致）

- **Top Bar（固定 56px）**：品牌 + 一级导航 + 用户区
- **Sidebar（固定 240px）**：房源管理二级导航
- **Main Content（`ml-60 pt-[72px]`）**：
  1. 面包屑 + 页面标题
  2. 模块 Tab（楼盘 / 区域管理 / 学校管理 / 应用标准数据）
  3. 完整度统计面板
  4. 搜索筛选区
  5. 批量操作条
  6. 列表表格
  7. 分页条

## 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. 验收清单

- [x] 壳层结构：Top Bar + Sidebar + Main
- [x] 楼盘列表页模块 Tab 完整
- [x] 统计面板、筛选区、批量区、表格区、分页区完整
- [x] 默认 20 条/页的分页演示
- [x] 楼盘名称可点击触发“进入详情”原型行为
- [x] 页面内不包含主题切换控件（遵循统一后台视觉）
- [x] 控制台 0 报错（本地预览验证阶段）

---

## 8. 后续衔接

- 本页评审通过后，进入任务05：楼盘详情/维护（`US-COMPLEX-001`）
- 任务05将复用本页的详情入口与模块 Tab 风格，保证楼盘模块前后页体验一致