# 房源详情 UI 设计文档

> **版本**：v1.0 · **日期**：2026-04-28  
> **依赖规范**：`UI_SYSTEM/UI_SYSTEM.md v1.2`、`UI_SYSTEM/UI_SYSTEM文档要求.md`  
> **PRD 来源**：`PRD/房源管理/房源管理模块PRD.md` §5.2（房源详情）+ Story 3~8  
> **TASK 来源**：`PRD/TASK.md` · `US-PROPERTY-003 ~ US-PROPERTY-008`  
> **数据模型来源**：`DATA_MODEL/DATA_MODEL_PROPERTY.md`

---

## 1. 模块概述

### 1.1 页面目标

本任务对应任务03（P0-A），目标是交付可评审的房源详情主页面原型，覆盖以下关键能力：

- 完整展示房源详情信息，按分区连续展示并通过二级锚点导航定位（US-PROPERTY-003）
- 在详情页内支持写入/筛选跟进日志（US-PROPERTY-004）
- 支持房源状态变更（改状态）弹层入口（US-PROPERTY-008）
- 支持写跟进弹层入口（US-PROPERTY-004）
- 提供图片与附件管理入口结构（US-PROPERTY-005）
- 提供业主联系人与相关员工信息区（US-PROPERTY-006）
- 提供调价/调级/改属性等快捷编辑入口位（US-PROPERTY-007）

### 1.2 页面清单

| 页面 | 文件 | 优先级 | 说明 |
|---|---|---|---|
| 房源详情页 | `UI_DESIGN/房源详情_UI.html` | P0 🔴 | 主详情壳层 + 二级锚点导航 + 跟进子Tab + 右侧信息面板 + 关键弹层 |

---

## 2. 信息架构与页面骨架

### 2.1 壳层结构（与新增客源页对齐）

```
Top Bar（固定 56px，bg-primary-800）
├─ 左：品牌区（Fonrey）
├─ 中：主导航（工作台/房源/客源/营销/交易/数据/人事/系统）
└─ 右：消息 + 用户

Sidebar（固定左侧 240px，位于 top-14 下）
└─ 房源管理导航（全部房源 / 我的房源 / 公盘池 / 成交房源 / 已删房源）

Main Content（ml-60 + pt-[72px]）
├─ 面包屑 + 标题区 + 顶部操作区
├─ 二级锚点导航（8个分区）
└─ 双栏布局
   ├─ 左侧：分区主内容（连续展示）
   └─ 右侧：固定信息面板（业主联系人 / 维护完成度 / 房源动态）
```

### 2.2 二级锚点分区定义（PRD §5.2 对齐）

1. 核心信息
2. 跟进日志
3. 业务信息
4. 房源信息
5. 营销信息
6. 相关员工
7. 相册信息
8. 附件信息

---

## 3. 核心区块设计

### 3.1 顶部标题操作区

- 标题：`交易标签 + 房源名称`（例：出售 · 都市港湾055-0301）
- 快捷操作：
  - `改状态`（弹层）
  - `编辑房源`（入口）
  - `分享`（入口）
  - `写跟进`（弹层）
  - `更多`（下拉入口位）

### 3.2 核心信息分区

由三层信息组成：

1. **价格与图片层**：主图、总价、单价、近30天变化、调价入口
2. **房源概要层**：户型、面积、楼层、电梯、装修、朝向
3. **详情字段层**：基础信息 + 交易信息（键值对）

快捷编辑入口位（文本链）：

- 调价
- 改等级
- 改属性
- 改用途
- 看房时间
- 挂牌历史

### 3.3 跟进日志分区

#### 3.3.1 子Tab结构

- 全部
- 写入跟进
- 敏感信息跟进
- 敏感信息查看
- 修改跟进
- 其他跟进

#### 3.3.2 筛选区

- 日期范围（开始/结束）
- 复选项：有录音 / 有附件 / 仅看我的
- 关键字输入（记录内容检索）

#### 3.3.3 时间线

每条记录包含：

- 类型标签（颜色区分）
- 内容摘要
- 操作人 + 门店组别
- 时间戳
- 公开/隐藏状态位

### 3.4 业务信息分区

卡片化展示三个模块：

- 钥匙管理（新增钥匙 / 钥匙在他司）
- 委托管理（新增委托 / 查看全部）
- 实勘管理（新增实勘）

### 3.5 房源信息分区

四块可编辑信息：

- 基本信息
- 产证信息
- 房屋介绍
- 楼盘信息

每块右上角保留 `编辑` 入口。

### 3.6 相关员工分区

以列表卡片展示角色与归属：

- 首录方
- 号码方
- 出售方
- 实买方

### 3.7 相册信息分区

- 分类 Tab（全部/封面/客厅/卧室/卫生间/厨房…）
- 操作行（上传图片/批量改类/批量删除/批量下载）
- 图片网格（封面标记 + 分类 + 时间）

### 3.8 附件信息分区

- 分类 Tab（全部/身份证/房产证/委托书/其他）
- 操作行（上传附件/批量改类/批量下载）
- 空状态（暂无附件）

---

## 4. 右侧固定信息面板

> 布局：`w-80`，`sticky top-16`

### 4.1 业主联系人

字段与交互：

- 姓名 + 身份
- 电话（默认打码）
- `查看号码`（示例交互）
- `新增联系人`（入口位）
- `更多`（入口位）

### 4.2 房源维护完成度

- 总分（0~100）
- 分项进度（重点信息/附件/实勘/VR/钥匙/委托）
- 视觉：进度条 + 百分比

### 4.3 房源动态（近30天）

指标卡：

- 带看次数
- 复看次数
- 面访次数
- 收藏人数
- 分享次数

---

## 5. 关键弹层与交互

### 5.1 改状态弹层（US-PROPERTY-008）

字段：

- 原状态（只读）
- 原交易类型（只读）
- 新状态（必填）
- 更改理由（必填，≤50字）

交互规则：

- 未选新状态或理由为空不可提交
- 提交成功后提示“状态已更新（原型模拟）”

### 5.2 写跟进弹层（US-PROPERTY-004）

字段：

- 跟进目的（必填）
- 跟进内容（必填，6~500字）
- 附件上传入口（原型位）

交互规则：

- 内容不足 6 字时给出错误提示
- 提交后关闭弹层并提示“跟进已写入（原型模拟）”

---

## 6. 数据模型映射（关键字段）

| UI字段 | 数据模型字段 | 备注 |
|---|---|---|
| 房源状态 | `properties.status` | 支持状态流转 |
| 房源属性 | `properties.attribute` | 公盘/私盘 |
| 售价 | `properties.sale_price` | 调价入口 |
| 租价 | `properties.rent_price` | 状态联动显示 |
| 单价 | `properties.sale_unit_price`（计算） | 展示字段 |
| 户型（室厅卫厨阳） | `bedroom_count/living_room_count/bathroom_count/kitchen_count/balcony_count` | 概要展示 |
| 建筑面积 | `properties.area` | m² |
| 房本年限 | `properties.ownership_years` | 交易信息 |
| 等级 | `properties.grade` | 改等级入口 |
| 看房时间 | `properties.viewing_time` | 改看房时间入口 |
| 最后跟进时间 | `properties.last_followed_at` | 动态区可关联 |
| 联系人姓名/身份 | `property_contacts.name/identity` | 右侧面板 |
| 联系人号码 | `property_contacts.phone_enc/phone_hash` | 默认打码展示 |
| 跟进记录 | `follow_logs` | 跟进子Tab来源 |
| 跟进附件 | `follow_log_attachments` | 有附件筛选 |
| 调价记录 | `price_changes` | 历史追踪 |
| 相册 | `property_photos` | 分类、封面、排序 |
| 附件 | `property_attachments` | 分类、批量下载 |

---

## 7. 状态矩阵

| 状态 | 触发 | UI反馈 |
|---|---|---|
| 默认 | 首次进入 | 页面滚动到“核心信息”分区，右侧面板可见，锚点高亮同步 |
| 分区导航点击 | 点击二级锚点 | 平滑滚动至对应分区并更新高亮 |
| 跟进子Tab切换 | 点击跟进类型子Tab | 时间线按类型过滤 |
| 改状态弹层打开 | 点击改状态 | Modal 打开 |
| 写跟进弹层打开 | 点击写跟进 | Modal 打开 |
| 校验失败 | 必填未填/字数不达标 | 字段下方错误文案 |
| 提交成功（模拟） | 校验通过 | Toast 成功提示 |

---

## 8. 可访问性

### 8.1 可访问性

- 所有按钮具备可见文本或 `aria-label`
- Modal 支持 ESC 关闭
- 关键操作保留焦点态（focus ring）

---

## 9. 验收清单

- [x] 产出 `UI_DESIGN/房源管理/房源详情_UI.md`
- [x] 产出 `UI_DESIGN/房源详情_UI.html`
- [x] 覆盖 `US-PROPERTY-003 ~ US-PROPERTY-008` 的 UI 入口与结构
- [x] 二级锚点分区导航 + 跟进子Tab + 时间线结构齐备
- [x] 右侧信息面板（业主联系人/维护完成度/房源动态）齐备
- [x] 改状态 / 写跟进 弹层原型齐备
- [x] 页面内不包含 Light/Dark/System 主题切换控件
- [ ] 待你评审后迭代（先改 HTML，再回写本 UI 文档）