# 新增房源 UI 设计文档

> **版本**：v1.0 · **日期**：2026-04-28  
> **依赖规范**：`UI_SYSTEM/UI_SYSTEM.md v1.2`、`UI_SYSTEM/UI_SYSTEM文档要求.md`  
> **PRD 来源**：`PRD/房源管理/房源管理模块PRD.md` §5.3（新增房源）+ §5.3.1 / §5.3.2（类型差异）  
> **TASK 来源**：`PRD/TASK.md` · `US-PROPERTY-001`  
> **数据模型来源**：`DATA_MODEL/DATA_MODEL_PROPERTY.md`

---

## 1. 模块概述

### 1.1 设计目标

本任务对应 `UI_设计任务总表.md` 任务 02（P0-A）与 `US-PROPERTY-001`：

- 支持经纪人录入二手房源核心信息，并完成必填校验
- 以「新增住宅」为 P0 主链路
- 同页支持切换房源类型并展示差异字段（便于评审与后续迭代）
- 保存成功后给出“保存成功”反馈并进入详情页（静态原型中为模拟跳转）

### 1.2 页面清单

| 页面 | 文件 | 优先级 | 说明 |
|---|---|---|---|
| 新增房源页 | `UI_DESIGN/新增房源_UI.html` | P0 🔴 | 主表单页，含类型切换、锚点导航、校验与保存反馈 |

---

## 2. 信息架构与布局

### 2.1 页面骨架

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

Sidebar（固定左侧 240px，位于 Top Bar 下方）
└─ 房源管理二级导航（全部房源/我的房源/公海池/成交房源/已删房源）

Main Content（ml-60 + pt-[72px]）
├─ 页面头卡（面包屑 + 页面标题 + Theme Toggle + 返回列表）
├─ 房源类型选择器（住宅/别墅/商住/商铺/写字楼/其他）
├─ 表单锚点导航（房源核心信息 / 业主联系人 / 基础信息 / 交易信息 / 相关方）
├─ 五个纵向区块卡片（按锚点顺序）
└─ 底部操作条（取消 / 保存并继续新增 / 保存）
```

### 2.2 设计说明

- 页面壳层**对齐 `UI_DESIGN/新增客源_UI.html`**：同款 top bar + left sidebar + content 区域栅格
- 表单采用“分区块竖向布局 + 顶部锚点”方案，对齐 PRD §5.3
- 锚点导航 `sticky`，滚动时高亮当前区块
- 必填未填时：字段红框 + 错误文案 + 自动滚动到首个错误字段

---

## 3. 字段设计（通用）

## 3.1 房源核心信息

| 字段 | 控件 | 必填 | 规则 / 说明 | 数据模型映射 |
|---|---|---|---|---|
| 状态 | Radio | 是 | 出售 / 出租 / 租售 / 暂缓 | `properties.status` |
| 房源属性 | Radio | 是 | 公盘 / 私盘 | `properties.attribute` |
| 用途 | Radio | 否 | 选项随房源类型变化 | `properties.usage_type` |
| 小区名称 | 搜索输入 | 是 | 支持联想，原型中为文本输入 | `properties.complex_id`（落地后） |
| 户室号 | 3 段输入 | 否 | 栋/幢/弄/胡同 + 单元/号 + 门牌/室号 | `block_no/unit_no/room_no` |
| 所在楼层 | 数字输入×2 | 是 | 当前楼层 ≤ 总楼层 | `floor/total_floors` |
| 户型 | 室厅卫厨阳台 | 条件必填 | 商铺/写字楼不显示 | `bedroom_count...balcony_count` |
| 建筑面积 | 数字输入 | 是 | 单位 m² | `area` |
| 售价 | 数字输入 | 条件必填 | 状态含出售/租售时显示 | `sale_price` |
| 租价 | 数字输入 | 条件必填 | 状态含出租/租售时显示 | `rent_price` |
| 开间 | 数字输入 | 条件必填 | 仅商铺显示，单位米 | `shop_frontage` |
| 进深 | 数字输入 | 条件必填 | 仅商铺显示，单位米 | `shop_depth` |
| 层高 | 数字输入 | 条件必填 | 仅商铺显示，单位米 | `shop_height` |
| 位置 | Radio | 条件必填 | 仅商铺：临街/商场/小区/底商/商业综合体 | `shop_location` |

## 3.2 业主/联系人

| 字段 | 控件 | 必填 | 规则 | 数据模型映射 |
|---|---|---|---|---|
| 姓名 | Input | 是 | 联系人1必填 | `property_contacts.name` |
| 性别 | Radio | 是 | 先生 / 女士，默认先生 | `property_contacts.gender` |
| 身份 | Select | 是 | 默认业主 | `property_contacts.identity` |
| 电话1 | Input | 否 | 手机/座机格式提示 | `phone_enc/phone_hash`（后端加密） |
| 电话2 | Input | 否 | 备用号码 | `phone2_enc/phone2_hash` |

交互：支持“+ 添加联系人”，第 1 个联系人不可删除。

## 3.3 基础信息

| 字段 | 控件 | 必填 | 规则 | 数据模型映射 |
|---|---|---|---|---|
| 朝向 | Radio | 是 | 10个枚举值 | `properties.orientation` |
| 装修 | Radio | 是 | 毛坯~豪装 | `properties.decoration` |

## 3.4 交易信息

| 字段 | 控件 | 必填 | 规则 | 数据模型映射 |
|---|---|---|---|---|
| 房本年限 | 双下拉 | 是（显示时） | 左侧年限 + 右侧补充 | `ownership_years / ownership_years_detail` |

显示规则：
- 住宅 / 别墅 / 其他：显示完整交易信息入口（本版先落地房本年限）
- 商住：仅显示房本年限
- 商铺 / 写字楼：不显示该区块

## 3.5 相关方

| 字段 | 控件 | 必填 | 规则 | 数据模型映射 |
|---|---|---|---|---|
| 首录方 | 只读输入 | 自动 | 默认当前登录人 | `first_recorder_id` |
| 号码方 | 员工选择 | 是 | 默认当前登录人，可清除重选 | `number_holder_id` |
| 出售方 | 员工选择 | 是 | 默认当前登录人，可清除重选 | `seller_agent_id` |

---

## 4. 房源类型差异（对齐 PRD §5.3.1）

| 类型 | 区块结构 | 与住宅差异 |
|---|---|---|
| 住宅（P0） | 5区块完整 | 用途：普通住宅/花园洋房 |
| 别墅（P1） | 5区块完整 | 用途：联排/独栋/双拼/叠加 |
| 商住（P2） | 5区块 | 用途字段保留但无选项；交易信息仅房本年限 |
| 商铺（P2） | 4区块（无交易信息） | 无户型；新增开间/进深/层高/位置 |
| 写字楼（P2） | 4区块（无交易信息） | 无户型；其余与住宅主干一致 |
| 其他（P2） | 5区块完整 | 用途为10项杂类 |

> 说明：根据 PRD，P2 类型在 v1 为“即将上线”。原型保留展示与交互，提交时给出“即将上线”提示，避免与开发范围冲突。

---

## 5. 关键交互与状态

## 5.1 联动规则

1. **状态-价格联动**
   - 出售：仅显示售价
   - 出租：仅显示租价
   - 租售：售价+租价均显示
   - 暂缓：隐藏售价/租价并给出提示文案

2. **类型-字段联动**
   - 商铺/写字楼：隐藏户型
   - 商铺：显示开间/进深/层高/位置
   - 商铺/写字楼：隐藏交易信息

3. **校验失败定位**
   - 点击保存后，自动滚动到首个错误字段
   - 字段红框 + 错误文案

## 5.2 页面状态

| 状态 | 触发 | 反馈 |
|---|---|---|
| 默认 | 首次进入 | 住宅类型 + 空白表单 |
| 编辑中 | 任意字段修改 | 页面 `dirty` 标记 |
| 保存中 | 点击保存 | 按钮 loading + 禁用 |
| 保存成功 | 校验通过 | Success Toast：保存成功，正在跳转 |
| 保存失败 | 校验不通过 | 错误提示 + 自动定位 |
| 类型未开放 | 提交 P2 类型 | Warning Toast：该类型即将上线 |

## 5.3 离开确认

- 页面有未保存更改时，离开触发浏览器确认
- 对齐 PRD“离开页面需提示是否放弃填写内容”

---

## 6. 主题与可访问性

## 6.1 主题（本任务新增）

页面内置 Theme Toggle：`Light / Dark / System`

- 存储键：`fonrey_theme`
- `system` 跟随 `prefers-color-scheme`
- 颜色通过 CSS 变量驱动，避免硬编码

## 6.2 可访问性

- 所有输入项均有可见 Label
- 错误提示与字段 `aria-describedby` 关联
- 锚点导航和按钮均支持键盘焦点态
- 颜色之外辅以文字提示（如必填、错误、状态文案）

---

## 7. 实现与评审清单

- [x] 产出 `UI_DESIGN/房源管理/新增房源_UI.md`
- [x] 产出 `UI_DESIGN/新增房源_UI.html`
- [x] 覆盖 `US-PROPERTY-001` 的主流程与验收关键点
- [x] 包含 Light / Dark / System 主题切换
- [ ] 待你评审后按反馈迭代（先改 HTML，再回写本 UI 文档）