chore: sync local project changes

Project/fonrey/UI_DESIGN/房源管理/房源详情_UI.md

@@ -0,0 +1,286 @@
+# 房源详情 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 文档）

Project/fonrey/UI_DESIGN/房源管理/新增房源_UI.md

@@ -0,0 +1,198 @@
+# 新增房源 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 文档）