199 lines
7.8 KiB
Markdown
199 lines
7.8 KiB
Markdown
# 新增房源 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 文档）
|