diff --git a/Project/fonrey/客源详情_静态原型.html b/Project/fonrey/UI_DESIGN/客源详情_UI设计.html similarity index 100% rename from Project/fonrey/客源详情_静态原型.html rename to Project/fonrey/UI_DESIGN/客源详情_UI设计.html diff --git a/Project/fonrey/prompt/为 客源详情页生成模块 UI 设计文档.md b/Project/fonrey/prompt/为 客源详情页生成模块 UI 设计文档.md index 311e1ad8..65bae1df 100644 --- a/Project/fonrey/prompt/为 客源详情页生成模块 UI 设计文档.md +++ b/Project/fonrey/prompt/为 客源详情页生成模块 UI 设计文档.md @@ -19,8 +19,8 @@ ## 本次任务输入 ### 1. 目标模块 -**模块名称**:客源列表 -**模块描述**:客源列表 +**模块名称**:客源详情页 +**模块描述**:客源详情页 ### 2. PRD 功能文档路径 ``` 客源列表:`Project/fonrey/PRD/客源管理/客源管理模块PRD.md` 章节5.7 私客详情页 @@ -56,20 +56,14 @@ - 客源详情页Section6:客源信息概览 - `Project/fonrey/screenshots/客源/客源信息概览.png` - `Project/fonrey/screenshots/客源/编辑基础信息.png` - - `Project/fonrey/screenshots/客源/选择私客收藏夹.png` - - `Project/fonrey/screenshots/客源/创建私客收藏夹.png` - `Project/fonrey/screenshots/客源/改等级.png` - `Project/fonrey/screenshots/客源/改状态.png` - `Project/fonrey/screenshots/客源/转成交.png` - `Project/fonrey/screenshots/客源/选择成交房源.png` - - `Project/fonrey/screenshots/客源/转公客.png` - - `Project/fonrey/screenshots/客源/转无效.png` - 客源详情页Section7:联系人 - `Project/fonrey/screenshots/客源/联系人.png` - - `Project/fonrey/screenshots/客源/编辑联系人.png` - 客源详情页Section8:相关员工 - `Project/fonrey/screenshots/客源/相关员工.png` - - `Project/fonrey/screenshots/客源/编辑相关员工.png` ### 5. MVP 优先级参考 请参考 `Project/fonrey/PRD/PRD_MVP.md`,在设计文档中标注每个页面/功能的优先级(P0/P1/P2)。 diff --git a/Project/fonrey/客源详情_UI设计.md b/Project/fonrey/客源详情_UI设计.md deleted file mode 100644 index d9f9706d..00000000 --- a/Project/fonrey/客源详情_UI设计.md +++ /dev/null @@ -1,1743 +0,0 @@ -# 客源详情页 UI 设计文档 - -> **版本**:v1.0 · **日期**:2026-04-25 -> **依赖规范**:UI_SYSTEM.md v1.2 · 组件规范设计.md v1.0 -> **PRD 来源**:`Project/fonrey/PRD/客源管理/客源管理模块PRD.md` §5.7 私客详情页 -> **优先级**:P0 功能用 🔴 标注,P1 用 🟡,P2 用 ⚫ - ---- - -## 目录 - -1. [模块概述](#1-模块概述) - - 1.1 功能范围 - - 1.2 页面清单 - - 1.3 用户角色与权限差异 -2. [页面设计规范](#2-页面设计规范) - - 2.1 私客详情页 — 整体框架 - - 2.2 Section 左侧:需求信息 Tab - - 2.3 Section 左侧:跟进记录 Tab - - 2.4 Section 左侧:带看 Tab - - 2.5 Section 左侧:客源解读 Tab - - 2.6 Section 左侧:二手配房 Tab - - 2.7 Section 右侧:客源信息概览面板 - - 2.8 Section 右侧:联系人面板 - - 2.9 Section 右侧:相关员工面板 -3. [弹窗/抽屉设计规范](#3-弹窗抽屉设计规范) - - 3.1 编辑基础信息(Modal) - - 3.2 改等级(Modal) - - 3.3 改状态(Modal) - - 3.4 转成交(Modal) - - 3.5 选择成交房源(Modal 宽型) - - 3.6 写入跟进(Drawer) - - 3.7 新增带看(全页表单) - - 3.8 新增预约带看(全页表单) -4. [交互状态规范](#4-交互状态规范) - - 4.1 客源状态机 - - 4.2 权限控制矩阵 - - 4.3 HTMX 请求规范 -5. [关键数据字段说明](#5-关键数据字段说明) -6. [竞品截图对应关系](#6-竞品截图对应关系) -7. [实现优先级与工期估算](#7-实现优先级与工期估算) -8. [开放问题(待决策)](#8-开放问题待决策) - ---- - -## 1. 模块概述 - -### 1.1 功能范围 - -**P0 功能 🔴** -- 私客详情页整体框架(左右双栏布局 + Tab 导航) -- 需求信息查看与编辑 -- 跟进记录(全部/写入跟进/敏感信息跟进/修改跟进/其他跟进) -- 带看记录(预约带看 + 实际带看) -- 联系人查看与新增 -- 客源状态变更:改等级、改状态 -- 转公客 / 转成交 / 转无效 -- 右侧客源信息概览面板(基础字段展示 + 快捷操作) -- 相关员工查看 - -**P1 功能 🟡** -- 客源解读(AI 行为分析) -- 二手配房(录客配房 + 系统配房) -- 收藏功能 -- 待办提醒模块 -- 编辑基础信息(完整表单) - -**P2 功能 ⚫** -- 编辑信息来源 -- 查看操作日志 -- 名下房产修改 - ---- - -### 1.2 页面清单 - -| 页面名称 | URL 模式建议 | 优先级 | 对应 PRD 章节 | -|---|---|---|---| -| 私客详情页(主框架) | `/clients//` | P0 🔴 | §5.7.1 | -| 需求信息 Tab | `/clients//requirements/` (HTMX partial) | P0 🔴 | §5.7.2 | -| 跟进记录 Tab | `/clients//follow-logs/` (HTMX partial) | P0 🔴 | §5.7.2 | -| 带看 Tab | `/clients//viewings/` (HTMX partial) | P0 🔴 | §5.7.2 | -| 客源解读 Tab | `/clients//insights/` (HTMX partial) | P1 🟡 | §5.7.2 | -| 二手配房 Tab | `/clients//property-matches/` (HTMX partial) | P1 🟡 | §5.7.2 | -| 右侧信息面板 | `/clients//sidebar/` (HTMX partial) | P0 🔴 | §5.7.3 | -| 新增带看(全页) | `/clients//viewings/create/` | P0 🔴 | §5.7.2 | -| 新增预约带看(全页) | `/clients//viewings/appointment/create/` | P0 🔴 | §5.7.2 | - ---- - -### 1.3 用户角色与权限差异 - -| 功能/视图元素 | 经纪人(本人) | 经纪人(他人客源) | 店长 | 管理员 | -|---|---|---|---|---| -| 查看详情页 | ✅ | 受限(需权限) | ✅ | ✅ | -| 查看联系人号码明文 | ✅(有操作留痕) | ❌ | ✅ | ✅ | -| 写入跟进记录 | ✅ | ❌ | ✅ | ✅ | -| 编辑需求信息 | ✅ | ❌ | ✅ | ✅ | -| 改等级/改状态 | ✅ | ❌ | ✅ | ✅ | -| 转公客/转成交/转无效 | ✅ | ❌ | ✅ | ✅ | -| 编辑相关员工 | ❌ | ❌ | ✅ | ✅ | -| 查看操作日志 | 部分 | ❌ | ✅ | ✅ | -| 敏感信息跟进查看 | ✅(本人) | ❌ | ✅ | ✅ | -| 转公客后操作 | ❌ | ❌ | ✅ | ✅ | - -> 注:联系人号码查看必须留痕(自动写入 `log_type='sensitive_view'` 的 `client_follow_logs` 记录)。 - ---- - -## 2. 页面设计规范 - -### 2.1 私客详情页 — 整体框架(P0 🔴) - -#### 2.1.1 页面概述 - -- **URL**:`/clients//` -- **访问入口**:客源列表点击任意行 → 跳转详情页;面包屑返回列表 -- **页面职责**:集中展示私客的全量信息,提供跟进、带看、状态变更等核心操作入口 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/私客详情.png` - -#### 2.1.2 布局结构 - -``` -┌────────────────────────────────────────────────────────────────────────┐ -│ 顶部导航栏(全局,来自 base.html,高度 48px) │ -├────────────────────────────────────────────────────────────────────────┤ -│ 面包屑导航(客源 / 客源管理 / {客源标题}) │ -├──────────────────────────────────────┬─────────────────────────────────┤ -│ │ │ -│ 左侧主内容区(约 68% 宽度) │ 右侧信息面板(约 32% 宽度) │ -│ ───────────────────────────── │ ───────────────────────── │ -│ [Tab 导航栏] │ [客源标题 Banner(橙色)] │ -│ 需求信息 | 跟进记录 | 带看 | │ [状态标签行] │ -│ 客源解读 | 智能配房 │ [基础字段列表] │ -│ │ [展开全部 链接] │ -│ [Tab 内容区(HTMX 动态加载)] │ [快捷操作按钮组] │ -│ │ [状态变更操作网格] │ -│ │ [待办提醒区块] │ -│ │ [联系人区块] │ -│ │ [相关员工区块] │ -│ │ │ -└──────────────────────────────────────┴─────────────────────────────────┘ -``` - -#### 2.1.3 区域详细规范 - -**[面包屑导航区]** - -| 属性 | 说明 | -|---|---| -| 组件 | 原生 HTML `` + Heroicons `chevron-right` 16px | -| 内容 | 客源 / 客源管理 / {client.title} | -| 样式 | `flex items-center gap-1 text-sm text-neutral-500 px-6 py-3` | -| 最后一项 | `text-neutral-700 font-medium`(不可点击) | - -**[双栏主布局]** - -```html - - - - - - - - - - -``` - -> 右侧面板使用 `sticky top-4` 实现滚动时固定,最大高度 `max-h-[calc(100vh-5rem)] overflow-y-auto` - -**[Tab 导航栏]** - -| 属性 | 说明 | -|---|---| -| 组件 | §10 Tab Navigation | -| Tab 列表 | 需求信息 / 跟进记录 / 带看 / 客源解读 / 智能配房 | -| 默认激活 | 需求信息 | -| 激活样式 | `text-primary-600 font-medium border-b-2 border-primary-600 -mb-px` | -| 未激活样式 | `text-neutral-500 hover:text-neutral-700` | -| Alpine 管理 | `x-data="{ activeTab: 'requirements' }"` | -| HTMX 行为 | 点击 Tab 时 `hx-get` 对应 partial URL,`hx-target="#tab-content"`, `hx-swap="innerHTML"` | -| 懒加载 | 非默认 Tab 内容通过 `hx-trigger="click"` 首次点击时加载 | - -```html - - - - - 需求信息 - - - - - - - - -``` - -#### 2.1.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | 自定义说明 | -|---|---|---|---| -| Tab Navigation | §10 Tab Navigation | 左侧五个功能 Tab 切换 | 不做懒加载 `intersect`,改为 `click` 首次触发 | - -#### 2.1.5 空状态设计 - -不适用(详情页框架本身无空状态,各 Tab 内容各自定义) - -#### 2.1.6 Loading 状态 - -Tab 切换时,`#tab-content` 区域显示骨架屏: - -```html - - - - - - -``` - ---- - -### 2.2 Section 左侧:需求信息 Tab(P0 🔴) - -#### 2.2.1 页面概述 - -- **URL**:`/clients//requirements/`(HTMX partial) -- **访问入口**:详情页默认激活 Tab -- **页面职责**:展示客户购房/租房需求的全量字段,支持内联编辑 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/需求信息.png` - -#### 2.2.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ [标题区] 需求信息 [编辑] 链接 │ -├──────────────────────────────────────────────────────────┤ -│ [字段网格] 3列布局,字段名(灰色)/ 字段值(深色) │ -│ 总价 | 面积 | 居室 │ -│ 装修 | 朝向 | 楼层 │ -│ 楼龄 | 意向商圈 | 意向小区 │ -│ 交通情况 | 备注(跨列) │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 2.2.3 区域详细规范 - -**[需求信息字段网格]** - -| 字段名 | 数据字段 | 展示类型 | 特殊渲染 | -|---|---|---|---| -| 总价 | `requirement.price_min` / `price_max` | 文本范围 | `{min}-{max}万元`,空时显示 `-` | -| 面积 | `requirement.area_min` / `area_max` | 文本范围 | `{min}㎡-{max}㎡` | -| 居室 | `requirement.rooms` | 文本 | 如 `2居` | -| 装修 | `requirement.decoration` | 文本 | 空时 `-` | -| 朝向 | `requirement.orientation` | 文本 | 多选逗号分隔 | -| 楼层 | `requirement.floor_preference` | 文本 | 多选,如 `中楼层、低楼层` | -| 楼龄 | `requirement.building_age` | 文本 | 空时 `-` | -| 意向商圈 | `requirement.preferred_districts` | 多标签 | 逗号分隔文本,空时 `-` | -| 意向小区 | `requirement.preferred_communities` | 多标签 | 逗号分隔,空时 `-` | -| 交通情况 | `requirement.transport_preference` | 文本 | 空时 `-` | -| 备注 | `requirement.notes` | 多行文本 | 跨越全行 `col-span-3`,空时 `-` | - -**字段渲染 HTML 结构:** - -```html - - - 总价 - {{ req.price_min }}-{{ req.price_max }}万元 - - - -``` - -**[编辑按钮]** - -| 属性 | 说明 | -|---|---| -| 样式 | `text-sm text-info-600 hover:text-blue-700 font-medium` | -| 触发 | 点击打开编辑需求信息 Drawer(§3.1) | -| 权限 | 仅归属人/管理员/店长可见 | - -#### 2.2.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | 自定义说明 | -|---|---|---|---| -| Inline Edit Mode | §15 | 字段网格切换编辑态 | 本模块改为 Drawer 编辑,不用内联编辑模式 | - -#### 2.2.5 空状态设计 - -若需求信息尚未录入(所有字段均为空),在内容区中部显示: - -```html - - - 暂未填写需求信息 - 立即编辑 - -``` - -#### 2.2.6 Loading 状态 - -由父页面 Tab 切换骨架屏覆盖(见 §2.1.6),内容区自身不额外处理。 - ---- - -### 2.3 Section 左侧:跟进记录 Tab(P0 🔴) - -#### 2.3.1 页面概述 - -- **URL**:`/clients//follow-logs/`(HTMX partial) -- **访问入口**:点击"跟进记录" Tab -- **页面职责**:按时间线展示所有跟进记录,支持筛选、写入新跟进 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/跟进记录-全部.png`、`跟进记录-写入跟进.png` 等 - -#### 2.3.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ [子 Tab 行] 全部 | 写入跟进 | 敏感信息跟进 | 修改跟进 | 其他跟进 │ -├──────────────────────────────────────────────────────────┤ -│ [筛选区(写入跟进 Tab 展开更多筛选)] │ -│ 日期范围选择器 [有录音] [有图片] 复选框 │ -│ 跟进目的:多选复选框(展开/收起) │ -│ 跟进标签:多选复选框(展开/收起) │ -├──────────────────────────────────────────────────────────┤ -│ [时间线内容区] │ -│ ● 2026-04-19 ────────────────────────────────── │ -│ [跟进记录条目 1] │ -│ [跟进记录条目 2] │ -│ ● 2026-04-18 ────────────────────────────────── │ -│ [跟进记录条目 ...] │ -│ [加载更多 按钮] │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 2.3.3 区域详细规范 - -**[子 Tab 导航栏]** - -| 属性 | 说明 | -|---|---| -| 组件 | §10 Tab Navigation(嵌套,风格改为 pill 式) | -| Tab 列表 | 全部 / 写入跟进 / 敏感信息跟进 / 修改跟进 / 其他跟进 | -| 映射 log_type | `all` / `written` / `sensitive_view` / `modified` / `other` | -| 样式 | `bg-neutral-100 rounded-full px-3 py-1 text-xs`;激活 `bg-primary-600 text-white` | -| Alpine | `x-data="{ logTab: 'all' }"` | -| HTMX | 切换时 `hx-get="/clients/{id}/follow-logs/?type={logTab}"` `hx-target="#log-list"` `hx-swap="innerHTML"` | - -**[筛选区]** - -| 字段 | 组件类型 | 说明 | -|---|---|---| -| 日期范围 | §9 Date Range Picker | `开始时间 → 结束时间`;`hx-trigger="change"` | -| 有录音 / 有图片 | Checkbox | `hx-trigger="change"` 触发重筛 | -| 跟进目的 | 多选 Checkbox 网格 | 仅在"写入跟进"Tab 下展开显示;默认折叠,"展开 ∨" 链接切换;竞品中约 25 个选项 | -| 跟进标签 | 多选 Checkbox | 同上,与跟进目的共用展开/收起逻辑 | - -```html - - - - 筛选: - - - 有录音 - - - - 有图片 - - - - - - - 跟进目的: - - - - - - - - - - - -``` - -**[时间线内容区]** - -采用 §10.3 内嵌 Timeline 子组件规范: - -| 元素 | 规格 | -|---|---| -| 外容器 | `relative pl-6 space-y-1` | -| 竖线 | `absolute left-2.5 top-0 bottom-0 w-px bg-neutral-200` | -| 日期分组标题 | `flex items-center gap-2 text-xs font-semibold text-neutral-500 uppercase py-2`;圆点 `w-3 h-3 rounded-full border-2 border-primary-600 bg-white absolute -left-[14px]` | -| 记录条目卡片 | `ml-2 bg-white border border-neutral-100 rounded-md p-3 space-y-1` | - -**跟进记录条目卡片规范:** - -``` -┌────────────────────────────────────────────────────────┐ -│ [类型标签 Badge] 【电话】 [时间戳] 11:25 [⋯ 更多] │ -│ [内容文本] 433弄5楼65.85平想置换... │ -│ [底部元信息] 都市港湾店一组 雷威 · 2026-04-19 │ -│ [已开放] [隐藏] 操作链接(灰色小字) │ -└────────────────────────────────────────────────────────┘ -``` - -| 元素 | 规格 | -|---|---| -| 类型标签 | `text-xs font-medium px-2 py-0.5 rounded-full bg-blue-100 text-blue-700` | -| 时间戳 | `text-xs text-neutral-400 tabular-nums` | -| 内容文本 | `text-sm text-neutral-700 leading-relaxed` | -| 元信息 | `text-xs text-neutral-400` | -| 操作链接 | `text-xs text-info-600 hover:underline`("ℹ️ 已开放" / "隐藏") | -| 更多菜单 | Heroicons `ellipsis-horizontal` 16px,点击展开 Dropdown(修改/删除选项) | -| 敏感信息标记 | `log_type === 'sensitive_view'`:条目背景 `bg-amber-50 border-amber-200`,不可删除 | - -**[加载更多]** - -```html - - - 查看全部跟进 - - - -``` - -#### 2.3.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | 自定义说明 | -|---|---|---|---| -| Tab Navigation | §10 | 跟进类型子 Tab | 改为 pill 风格,而非下划线风格 | -| Timeline 子组件 | §10.3 | 时间线记录展示 | 增加日期分组标题,圆点用 `border-primary-600` | -| Date Range Picker | §9 | 跟进记录日期筛选 | 标准实现,`hx-trigger="change"` 自动触发筛选 | - -#### 2.3.5 空状态设计 - -```html - - - 暂无跟进 - -``` - -#### 2.3.6 Loading 状态 - -```html - - - - - - - - -``` - ---- - -### 2.4 Section 左侧:带看 Tab(P0 🔴) - -#### 2.4.1 页面概述 - -- **URL**:`/clients//viewings/`(HTMX partial) -- **访问入口**:点击"带看" Tab -- **页面职责**:展示该客源的预约带看和实际带看记录,提供新增入口 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/带看.png` - -#### 2.4.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ [子 Tab] 预约 | 带看(active) [日期范围选择器] │ -├──────────────────────────────────────────────────────────┤ -│ [筛选复选框] □ 归属人带看 □ 其他人带看 │ -├──────────────────────────────────────────────────────────┤ -│ [时间线带看记录列表] │ -│ ● 2026-04-17 20:30 │ -│ 带看情况: 客户继续维护 │ -│ 房源: 金沙丽晶苑一期-001-1201 [一看] 带看: 雷威 │ -│ [详情 ›] │ -│ [加载更多] │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 2.4.3 区域详细规范 - -**[子 Tab 导航]** - -| 属性 | 说明 | -|---|---| -| Tab 列表 | 预约 / 带看 | -| Alpine | `x-data="{ viewingTab: 'viewing' }"` | -| HTMX | `hx-get="/clients/{id}/viewings/?type={viewingTab}"` `hx-target="#viewing-list"` | - -**[筛选行]** - -| 字段 | 说明 | -|---|---| -| 归属人带看 | `hx-trigger="change"` 筛选重载 | -| 其他人带看 | 同上 | -| 日期范围 | §9 Date Range Picker,`hx-trigger="change"` | - -**[带看记录条目]** - -``` -┌─────────────────────────────────────────────────────────┐ -│ ● 2026-04-17 20:30 │ -│ 带看情况: 客户继续维护 │ -│ [房源链接] 金沙丽晶苑一期-001-1201 │ -│ [带看次数 Badge: 一看 橙色] 带看: 雷威 │ -│ [详情 › 链接] │ -└─────────────────────────────────────────────────────────┘ -``` - -| 元素 | 规格 | -|---|---| -| 带看次数 Badge | `text-xs font-medium px-2 py-0.5 rounded-full bg-primary-50 text-primary-700 border border-primary-200` | -| 房源链接 | `text-sm text-info-600 hover:underline` | -| 带看情况 | `text-sm text-neutral-700` | -| 带看人 | `text-xs text-neutral-500` | -| 详情链接 | `text-xs text-info-600 hover:underline ml-auto` | - -#### 2.4.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | 自定义说明 | -|---|---|---|---| -| Tab Navigation | §10 | 预约/带看子 Tab | pill 风格 | -| Timeline 子组件 | §10.3 | 带看记录时间线 | 圆点时间戳展示带看时刻 | -| Date Range Picker | §9 | 带看日期筛选 | 标准实现 | - -#### 2.4.5 空状态设计 - -```html - - - 暂无带看记录 - 新增带看 - -``` - -#### 2.4.6 Loading 状态 - -与 §2.3.6 相同的骨架屏方案。 - ---- - -### 2.5 Section 左侧:客源解读 Tab(P1 🟡) - -#### 2.5.1 页面概述 - -- **URL**:`/clients//insights/`(HTMX partial) -- **访问入口**:点击"客源解读" Tab -- **页面职责**:展示 AI 分析的客户找房行为数据:活跃时间、购房偏好、区域偏好 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/客源解读.png` - -#### 2.5.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ [说明文字] + 使用指南链接 [数据更新时间戳] │ -├──────────────────────────────────────────────────────────┤ -│ [活跃行为卡片] [活跃时间卡片: 工作日 | 周末] │ -├──────────────────────────────────────────────────────────┤ -│ 购房偏好 [时段筛选: 近7日 | 近30日 | 近90日] │ -│ [偏好摘要网格: 价格/户型/面积/商圈/小区] │ -│ [类型占比行] │ -│ [偏好子 Tab: 二手偏好 | 新房偏好] │ -│ [三个甜甜圈图: 价格偏好 / 户型偏好 / 面积偏好] │ -│ [区域-商圈偏好] [小区偏好] │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 2.5.3 区域详细规范 - -**[活跃行为卡片]** - -| 属性 | 说明 | -|---|---| -| 样式 | `bg-white border border-neutral-200 rounded-lg p-4` | -| 内容 | 标题"活跃行为"+ 数值(如"7 天内")用 `text-2xl font-bold text-neutral-800` | -| 副标题 | `text-sm text-neutral-500` 描述说明 | - -**[购房偏好摘要网格]** - -| 字段 | 规格 | -|---|---| -| 价格 | `text-sm font-semibold text-neutral-800` 展示范围 | -| 户型 | 同上 | -| 面积 | 同上 | -| 商圈 / 小区 | 空时显示 `-` | - -**[甜甜圈图]** - -> MVP 阶段可用简单的百分比 `text-4xl font-bold text-primary-600` 替代 Chart.js 图表,配合 `text-sm text-neutral-500` 标签文字。P1 阶段再引入图表库。 - -**[时段筛选 Pill]** - -```html - - - - - - - -``` - -#### 2.5.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | 自定义说明 | -|---|---|---|---| -| Tab Navigation | §10 | 二手偏好/新房偏好子 Tab | pill 风格 | - -#### 2.5.5 空状态设计 - -```html - - - 暂无找房行为数据 - 数据由系统每日凌晨更新 - -``` - -#### 2.5.6 Loading 状态 - -骨架屏三个卡片占位块,`animate-pulse` 处理。 - ---- - -### 2.6 Section 左侧:二手配房 Tab(P1 🟡) - -#### 2.6.1 页面概述 - -- **URL**:`/clients//property-matches/`(HTMX partial) -- **访问入口**:点击"智能配房" Tab -- **页面职责**:展示系统根据客户需求匹配的二手房源,按分组展示推荐卡片 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/二手配房.png` - -#### 2.6.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ 二手配房 [更新时间] ℹ️ [批量分享 按钮] │ -│ [子 Tab] 录客配房(active) | 系统配房 │ -├──────────────────────────────────────────────────────────┤ -│ [分组标题: 优质户型] │ -│ [房源卡片] [房源卡片] [房源卡片] │ -│ [分组标题: 降价] │ -│ [房源卡片] [房源卡片] │ -│ [分组标题: 热门] │ -│ [房源卡片] ... │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 2.6.3 区域详细规范 - -**[房源卡片]** - -``` -┌─────────────────────────────────────────────┐ -│ [缩略图 80×60] [房源名称(蓝色链接)] │ -│ [规格] 2/2/1 · 101.17㎡ │ -│ [区域] 嘉定 丰庄 │ -│ [特征标签组](橙/蓝 pills) │ -│ [价格] 620万 [跌价信息] 已跌20万 │ -│ [单价] 61283元/㎡ │ -│ [分享房源] [反馈 ∨](action 链接) │ -└─────────────────────────────────────────────┘ -``` - -| 元素 | 规格 | -|---|---| -| 缩略图 | `w-20 h-15 rounded-md object-cover flex-shrink-0` | -| 房源名称 | `text-sm font-medium text-info-600 hover:underline` | -| 规格文字 | `text-xs text-neutral-500` | -| 特征标签 | `text-xs px-1.5 py-0.5 rounded bg-orange-50 text-orange-700` 或 `bg-blue-50 text-blue-700` | -| 价格 | `text-base font-bold text-neutral-900` | -| 跌价标注 | `text-xs text-neutral-400` | -| 分组标题 | `text-sm font-semibold text-neutral-700 py-2 border-b border-neutral-200 mb-3` | -| 批量分享 | `btn-secondary text-xs` 灰色描边按钮 | -| 反馈 ∨ | Dropdown,选项:满意/不满意/已跟进 | - -**卡片网格布局:** - -```html - - - - 优质户型 - - - - - -``` - -#### 2.6.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Tab Navigation | §10 | 录客配房/系统配房子 Tab | - -#### 2.6.5 空状态设计 - -```html - - - 暂无匹配房源 - -``` - -#### 2.6.6 Loading 状态 - -卡片骨架屏,每张卡片用 `animate-pulse` 占位块。 - ---- - -### 2.7 Section 右侧:客源信息概览面板(P0/P1) - -#### 2.7.1 页面概述 - -- **URL**:`/clients//sidebar/`(HTMX partial,初始 SSR) -- **访问入口**:详情页右侧固定面板(持续可见) -- **页面职责**:集中展示客源核心标识信息 + 快捷操作入口 -- **竞品参考截图**:`Project/fonrey/screenshots/客源/客源信息概览.png` - -#### 2.7.2 布局结构 - -``` -┌──────────────────────────────────────────────┐ -│ [橙色 Banner] │ -│ 求购 叶阿姨买一房(上门) 女士 │ -├──────────────────────────────────────────────┤ -│ [状态标签行] 私客 · 一看 · C(一般) │ -├──────────────────────────────────────────────┤ -│ [基础字段列表(只读)] │ -│ 最近跟进 / 客户编号 / 委托日期 ... │ -│ [展开全部 ∨ 链接] │ -├──────────────────────────────────────────────┤ -│ [三个主操作按钮](P0) │ -│ [打电话] [写跟进] [报备/常看] │ -├──────────────────────────────────────────────┤ -│ [状态变更操作网格](P0) │ -│ ☆ 收藏 · 不置顶 │ -│ 改等级 · 改状态 │ -│ 转公客 · 转成交 │ -│ 转无效 · 编辑客源 │ -└──────────────────────────────────────────────┘ -``` - -#### 2.7.3 区域详细规范 - -**[橙色 Banner]** - -```html - - - 求购 - - - {{ client.title }} - - {{ client.primary_contact.name }} {{ client.primary_contact.gender_display }} - - - -``` - -> 注:竞品用橙色 `#f5774a`;本系统采用 Teal `primary-600 (#0F766E)` 替代,保持品牌一致性。 - -**[状态标签行]** - -| 标签 | 样式 | -|---|---| -| 私客(client_type) | `text-xs px-2 py-0.5 rounded-full bg-neutral-100 text-neutral-600` | -| 带看次数(如"一看") | `text-xs px-2 py-0.5 rounded-full bg-blue-100 text-blue-700` | -| 等级(C/一般) | `text-xs px-2 py-0.5 rounded-full`;A 级 `bg-red-100 text-red-700`;B 级 `bg-orange-100 text-orange-700`;C 级 `bg-yellow-100 text-yellow-700`;D/E `bg-neutral-100 text-neutral-500` | - -**[基础字段列表]** - -| 字段名 | 数据来源 | 空值展示 | -|---|---|---| -| 最近跟进 | `client.last_follow_at` | `-` | -| 客户编号 | `client.client_no` | — | -| 委托日期 | `client.created_at` date | — | -| 需求类型 | `client.requirement_type_display` | — | -| 房源用途 | `client.property_usage_display` | — | -| 客户来源 | `client.source_display` | — | -| 购房目的 | `client.purchase_purpose` | `-` | -| 付款方式 | `client.payment_method` | `-` | -| 名下房产 | `client.owned_properties` | `未填写` | -| 贷款记录 | `client.loan_record` | `-` | -| 证件类型 | `client.id_type` | `-` | -| 证件号码 | `client.id_number`(脱敏) | `-` | -| 意向学校 | `client.preferred_school` | `-` | -| 入学时间 | `client.school_start_year` | `-` | - -**字段行渲染:** - -```html - - - 最近跟进 - {{ client.last_follow_at|date:"Y-m-d"|default:"-" }} - - - -``` - -**[展开全部链接]** - -```html - - - - -``` - -**[三个主操作按钮(P0)]** - -```html - - - - 打电话 - - - - 写跟进 - - - - 报备/常看 - - -``` - -**[状态变更操作网格(P0)]** - -```html - - - - - 收藏 - - - - - 不置顶 - - - - - 改等级 - - - - - 改状态 - - - - - 转公客 - - - - - 转成交 - - - - - 转无效 - - - - - 编辑客源 - - -``` - -**[待办提醒区块(P1)]** - -```html - - - 待办提醒 ({{ todo_count }}) - 写办 - - 系统会在设置的时间点发送跟进通知 - -``` - -#### 2.7.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 改等级/改状态/转成交/编辑客源 弹窗容器 | - -#### 2.7.5 空状态设计 - -不适用(面板始终显示) - -#### 2.7.6 Loading 状态 - -右侧面板初始 SSR 渲染,HTMX 更新时对应区域显示 `opacity-50 pointer-events-none` 禁用态。 - ---- - -### 2.8 Section 右侧:联系人面板(P0 🔴) - -#### 2.8.1 页面概述 - -- **竞品参考截图**:`Project/fonrey/screenshots/客源/联系人.png` - -#### 2.8.2 布局结构 - -``` -┌─────────────────────────────────────────────┐ -│ 联系人 [查看号码] [新增联系人] 操作链接 │ -├─────────────────────────────────────────────┤ -│ [联系人条目] │ -│ 姓名 · 称呼 │ -│ 电话1: +86 137****8888 [默认拨打] [接通N次] │ -│ 微信: - QQ: - 备注: - │ -└─────────────────────────────────────────────┘ -``` - -#### 2.8.3 区域详细规范 - -**[面板 Header]** - -| 元素 | 规格 | -|---|---| -| 标题 | `text-sm font-semibold text-neutral-800` | -| 查看号码 | `text-xs text-info-600 hover:underline`;点击触发 HTMX POST 到 `/clients/{id}/reveal-phone/`,响应返回明文号码,同时后端写入 sensitive_view 日志 | -| 新增联系人 | `text-xs text-info-600 hover:underline`;触发 Drawer | - -**[联系人条目]** - -```html - - - - - {{ contact.name }} {{ contact.gender_display }} - - - - 电话1: - - {{ contact.phone_masked }} - - 默认拨打 - 接通{{ contact.call_success_count }}次 - 拨打{{ contact.call_total_count }}次 - - 微信: {{ contact.wechat|default:"-" }} - - - - - - -``` - -**查看号码交互:** - -```html - - 查看号码 - -``` - -#### 2.8.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 新增联系人表单 | - -#### 2.8.5 空状态设计 - -联系人列表为空时显示 `text-xs text-neutral-400` 提示 "暂无联系人"。 - ---- - -### 2.9 Section 右侧:相关员工面板(P0 🔴) - -#### 2.9.1 页面概述 - -- **竞品参考截图**:`Project/fonrey/screenshots/客源/相关员工.png` - -#### 2.9.2 布局结构 - -``` -┌─────────────────────────────────────────────┐ -│ 相关员工 [编辑] │ -├─────────────────────────────────────────────┤ -│ 【首录人】 ☎ 电话图标 │ -│ 都市港湾店一组 雷威 │ -│ 参与时间: 2026-04-17 19:21 │ -│ 【归属人】 ☎ 电话图标 │ -│ 都市港湾店一组 雷威 │ -│ 参与时间: 2026-04-17 19:21 │ -└─────────────────────────────────────────────┘ -``` - -#### 2.9.3 区域详细规范 - -```html - - - 相关员工 - {% if can_edit_staff %} - 编辑 - {% endif %} - - - {% for staff in related_staff %} - - - 【{{ staff.role_display }}】 - {{ staff.department }} {{ staff.name }} - 参与时间: {{ staff.joined_at|date:"Y-m-d H:i" }} - - - - - - {% endfor %} - - -``` - -| 元素 | 权限控制 | -|---|---| -| 编辑按钮 | 仅管理员/店长可见(`{% if can_edit_staff %}`) | -| 电话图标 | 拨打员工内部电话,无需权限控制 | - ---- - -## 3. 弹窗/抽屉设计规范 - -### 3.1 编辑基础信息(P1 🟡) - -#### 3.1.1 触发方式 - -- **触发位置**:右侧客源信息概览面板 → "编辑客源" 按钮 -- **组件类型**:Modal Dialog(内容字段多,但不足以需要 Drawer 宽度) -- **尺寸**:`max-w-2xl`(宽型)+ 最大高度 `max-h-[80vh]` 内部滚动 -- **竞品截图**:`Project/fonrey/screenshots/客源/编辑基础信息.png` - -#### 3.1.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值/预填值 | -|---|---|---|---|---| -| 需求类型 | Checkbox(二手/新房) | 是 | 至少选一 | 预填当前值 | -| 用途 | Select | 是 | 必选 | 预填当前值 | -| 来源 | Select | 是 | 必选 | 预填当前值 | -| 购房目的 | 多选 Checkbox | 否 | — | 预填当前值 | -| 付款方式 | Select | 否 | — | 预填 | -| 名下房产 | Select | 否 | — | 预填 | -| 贷款记录 | Radio(有/无) | 否 | — | 预填 | -| 证件类型 | Select | 否 | — | 预填 | -| 证件号码 | Text Input | 否 | 身份证 18 位格式校验 | 预填 | -| 意向学校 | 动态 Text Input(可多行) | 否 | — | 预填 | -| 入学时间 | Select(年份) | 否 | — | 预填 | - -#### 3.1.3 提交行为 - -- **提交方式**:`hx-patch="/clients/{{ id }}/edit-basic/"` -- **成功响应**:关闭 Modal + Toast "保存成功" + `hx-get` 刷新右侧面板 -- **失败响应(422)**:字段级 `` 错误提示 -- **HTMX 属性**: - -```html - -``` - -#### 3.1.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 弹窗容器 | -| Multi-select Tag Input | §17 | 购房目的多选 | - ---- - -### 3.2 改等级(P0 🔴) - -#### 3.2.1 触发方式 - -- **触发位置**:右侧面板 → "改等级" 按钮 -- **组件类型**:Modal Dialog(内容极简) -- **尺寸**:`max-w-sm` -- **竞品截图**:`Project/fonrey/screenshots/客源/改等级.png` - -#### 3.2.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 原等级 | 只读文本 | — | — | `client.grade_display` | -| 新等级 | Select | 是 | 必选;不能与原等级相同 | 无 | - -**新等级选项**:A_urgent(A+紧急)/ A / B / C(默认)/ D / E - -#### 3.2.3 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/change-grade/"` -- **成功**:关闭 Modal + Toast "等级已更新" + 刷新右侧状态标签行 -- **失败(422)**:Select 下方显示错误文字 -- **HTMX 属性**: - -```html - -``` - -#### 3.2.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 弹窗容器 | - ---- - -### 3.3 改状态(P0 🔴) - -#### 3.3.1 触发方式 - -- **触发位置**:右侧面板 → "改状态" 按钮 -- **组件类型**:Modal Dialog -- **尺寸**:`max-w-md` -- **竞品截图**:`Project/fonrey/screenshots/客源/改状态.png` - -#### 3.3.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 原状态 | 只读文本 | — | — | `client.status_display`(如"求购") | -| 新状态 | Select | 是 | 必选;受状态机约束(见 §4.1) | 无 | -| 等级 | Select | 否 | — | 当前等级预填 | -| 更改理由 | Textarea | 是 | 非空 | 无 | - -**新状态可选项(根据当前状态动态过滤,后端控制)**: -- 当前 `buying`/`renting` → 可选:`suspended`(暂缓)、`public`(转公)、`bought`/`rented_done`(成交)、`invalid`(无效) - -#### 3.3.3 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/change-status/"` -- **成功**:关闭 Modal + Toast "状态已更新" + 刷新整个右侧面板 -- **失败(422)**:字段级错误 -- **HTMX 属性**: - -```html - -``` - -#### 3.3.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 弹窗容器 | - ---- - -### 3.4 转成交(P0 🔴) - -#### 3.4.1 触发方式 - -- **触发位置**:右侧面板 → "转成交" 按钮 -- **组件类型**:Modal Dialog -- **尺寸**:`max-w-lg` -- **竞品截图**:`Project/fonrey/screenshots/客源/转成交.png` - -#### 3.4.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 状态 | Radio(我购/我租) | 是 | 必选 | 我购 | -| 房源类型 | Radio(二手/新房) | 是 | 必选 | 二手 | -| 成交房源 | 触发选择房源 Modal 的链接 | 是 | 必选 | 无 | -| 成交日期 | Date Picker | 是 | 不能早于委托日期 | 今日 | -| 成交价格 | Number Input | 是 | 正数,单位万元 | 无 | -| 成交方 | 员工标签(可删除,可搜索添加) | 是 | 至少一人 | 当前归属人 | - -**成交房源选择:** - -```html - - - + 选择成交房源 - - - - - - -``` - -#### 3.4.3 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/convert-deal/"` -- **成功**:关闭 Modal + Toast "已成功转为成交客" + 页面跳转至成交客详情 -- **失败(422)**:字段级错误 -- **特殊**:成功后客源状态不可逆(`bought`/`rented_done`),需在提交前显示 `hx-confirm` 二次确认 - -```html - -``` - -#### 3.4.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 弹窗容器 | -| Date Range Picker | §9 | 成交日期选择(单日模式) | - ---- - -### 3.5 选择成交房源(P0 🔴) - -#### 3.5.1 触发方式 - -- **触发位置**:转成交 Modal → "选择成交房源" 链接 -- **组件类型**:Modal Dialog(宽型,含搜索表格) -- **尺寸**:`max-w-5xl`(全宽搜索表) -- **竞品截图**:`Project/fonrey/screenshots/客源/选择成交房源.png` - -#### 3.5.2 表单字段规范 - -**[搜索筛选区]** - -| 字段 | 组件类型 | 说明 | -|---|---|---| -| 关键词 | Text Input | 房源编号/楼盘地址/业主姓名/电话 | -| 楼栋 / 单元 / 房号 | 三个联动 Text Input | 精确定位 | -| 区域 | Select | 城区筛选 | -| 状态 | Select | 房源状态 | -| 相关方 | Select + 员工搜索 | 归属人筛选 | - -**[结果表格]** - -| 列名 | 宽度 | 说明 | -|---|---|---| -| 选择(Radio) | 48px | 单选 | -| 房源名称 | auto | 含楼栋单元房号 | -| 交易类型 | 80px | 买卖/租赁 | -| 状态 | 80px | Badge 展示 | -| 用途 | 60px | 住宅/商业 | -| 城区商圈 | 100px | 文本 | -| 房型 | 80px | X/X/X | -| 楼层 | 80px | X/X | -| 面积(㎡) | 80px | `tabular-nums` | - -**分页**:`共N条 | ‹ 1 2 3 … ›`(§2 Pagination 组件) - -#### 3.5.3 提交行为 - -- **提交方式**:点击"确定"将选中房源 ID 写入父 Modal 的隐藏字段 -- **HTMX 属性**:搜索按钮 `hx-get` 刷新结果表 -- **Alpine 管理**:`selectedPropertyId` 状态,选中后激活"确定"按钮 - -```html - - - - - - 已选 (/1) - - - 确定 - - - -``` - -#### 3.5.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Modal Dialog | §7 | 宽型容器 `max-w-5xl` | -| Data Table | §1 | 房源选择结果表 | -| Pagination | §2 | 表格分页 | - ---- - -### 3.6 写入跟进(P0 🔴) - -#### 3.6.1 触发方式 - -- **触发位置**:右侧面板 → "写跟进" 按钮;或跟进记录 Tab 内"写入跟进"按钮 -- **组件类型**:Drawer(右侧抽屉,字段较多但无需全页) -- **尺寸**:`w-[480px]` -- **竞品截图**:`Project/fonrey/screenshots/客源/跟进记录-写入跟进.png` - -#### 3.6.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 跟进方式 | Select / Radio Pills | 是 | 必选 | 电话 | -| 跟进目的 | 多选 Checkbox | 否 | — | 无 | -| 跟进内容 | Textarea | 是 | ≥ 6 字 | 无 | -| 跟进标签 | §17 Multi-select Tag Input | 否 | — | 无 | -| 跟进时间 | DateTime Picker | 是 | 不能超过当前时间 | 当前时间 | -| 附件 | 文件上传 | 否 | 最多 20MB,格式 bmp/jpg/png/gif | 无 | -| 是否开放 | Toggle | 否 | — | 开放(`true`) | - -> **注**:跟进方式选项(含图标):电话 / 上门 / 短信 / 微信 / 其他 - -#### 3.6.3 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/follow-logs/create/"` -- **成功**:关闭 Drawer + Toast "跟进记录已保存" + `hx-trigger` 刷新跟进记录 Tab 列表 -- **失败(422)**:字段级错误 -- **HTMX 属性**: - -```html - -``` - -#### 3.6.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Drawer | §16 | 抽屉容器 | -| Multi-select Tag Input | §17 | 跟进标签选择 | -| Date Range Picker | §9 | 跟进时间(单时间模式) | - ---- - -### 3.7 新增带看(P0 🔴) - -#### 3.7.1 触发方式 - -- **触发位置**:右侧面板 → "报备/常看" 按钮;或带看 Tab → 空状态"新增带看" -- **组件类型**:全页表单(字段多、含文件上传、含房源关联) -- **URL**:`/clients//viewings/create/` -- **竞品截图**:`Project/fonrey/screenshots/客源/新增带看.png` - -#### 3.7.2 布局结构 - -``` -┌──────────────────────────────────────────────────────────┐ -│ 面包屑: 客源 / 客源管理 / 新增带看 │ -│ 页面标题: 新增带看 │ -├──────────────────────────────────────────────────────────┤ -│ [带看信息卡片] │ -│ 业务类型(只读) | 带看客户(只读+查看详情链接) │ -│ 经纪人(只读) │ -│ 带看时间(日期+时间段)* │ -│ 陪看人(最多5位)+ 合作带看人(最多5位) │ -│ 带看情况(Textarea)* │ -│ 附件上传 │ -├──────────────────────────────────────────────────────────┤ -│ [带看房源卡片] │ -│ 添加房源(至少1套,最多10套)* │ -│ 每套房源选择客户意向程度 │ -├──────────────────────────────────────────────────────────┤ -│ [操作按钮] 提交(primary) 保存(secondary) 取消 │ -└──────────────────────────────────────────────────────────┘ -``` - -#### 3.7.3 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 业务类型 | 只读文本 | — | — | 二手 | -| 带看客户 | 只读文本 + 链接 | — | — | 当前客源 | -| 经纪人 | 只读文本 | — | — | 当前登录人 | -| 带看时间 | Date Picker + Time Range | 是 | 开始时间 < 结束时间 | 无 | -| 陪看人 | 员工多选搜索 | 否 | ≤ 5 人 | 无 | -| 合作带看人 | 员工多选搜索 | 否 | ≤ 5 人 | 无 | -| 带看情况 | Textarea | 是 | ≥ 6 字 | 无 | -| 附件 | 文件上传 | 否 | 每张 ≤ 20MB,bmp/jpg/png/gif | 无 | -| 带看房源 | 动态房源选择列表 | 是 | 1-10 套 | 无 | -| 每套意向程度 | Select | 是(每套) | 必选 | 无 | - -#### 3.7.4 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/viewings/create/"` `hx-encoding="multipart/form-data"` -- **成功**:跳转至带看详情页 + Toast "带看记录已提交" -- **失败(422)**:字段级错误,保留已填内容 -- **"保存"按钮**:`hx-post="...?draft=true"`,保存草稿,不跳转 - -#### 3.7.5 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Date Range Picker | §9 | 带看时间段选择 | -| Dynamic Form Table | §18 | 带看房源动态增删列表 | -| Photo Gallery Manager | §12 | 附件上传管理 | - ---- - -### 3.8 新增预约带看(P0 🔴) - -#### 3.8.1 触发方式 - -- **触发位置**:带看 Tab → 预约子 Tab → 空状态 or "新增预约" 按钮 -- **组件类型**:全页表单 -- **URL**:`/clients//viewings/appointment/create/` -- **竞品截图**:`Project/fonrey/screenshots/客源/新增预约带看.png` - -#### 3.8.2 表单字段规范 - -| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 | -|---|---|---|---|---| -| 业务类型 | 只读文本 | — | — | 二手 | -| 预约客户 | 只读文本 + 链接 | — | — | 当前客源 | -| 预约人 | 只读文本 | — | — | 当前登录人 | -| 预约时间(日期) | Date Picker | 是 | 不早于今日 | 无 | -| 预约时间(时刻) | Time Picker | 是 | — | 无 | -| 陪看人 | 员工多选 | 否 | ≤ 5 人 | 无 | -| 合作带看人 | 员工多选 | 否 | ≤ 5 人 | 无 | -| 预约房源 | 动态房源选择列表 | 是 | 1-10 套 | 无 | - -#### 3.8.3 提交行为 - -- **提交方式**:`hx-post="/clients/{{ id }}/viewings/appointment/create/"` -- **成功**:跳转带看 Tab(预约子 Tab)+ Toast "预约带看已创建" -- **失败(422)**:字段级错误 - -#### 3.8.4 使用的特殊组件 - -| 组件名 | 来源 | 用途 | -|---|---|---| -| Date Range Picker | §9 | 预约日期+时刻 | -| Dynamic Form Table | §18 | 预约房源动态列表 | - ---- - -## 4. 交互状态规范 - -### 4.1 全局状态机 - -客源状态流转(`clients.status` 字段): - -``` - ┌──────────────────────────────┐ - │ buying │ - │ (求购,可逆态) │ - └──────────────────────────────┘ - │ │ - ┌──────┘ └──────┐ - ▼ ▼ - suspended(暂缓) public(转公) - (可逆 → 回到 buying) (不可逆) - │ - └──────────────────────────────────┐ - ▼ - bought(成交)(不可逆) - invalid(无效)(不可逆) -``` - -``` - ┌──────────────────────────────┐ - │ renting │ - │ (求租,可逆态) │ - └──────────────────────────────┘ - │ │ - ┌──────┘ └──────┐ - ▼ ▼ - suspended(暂缓) public(转公) - │ - └──────────────────────────────────┐ - ▼ - rented_done(成交)(不可逆) - invalid(无效)(不可逆) -``` - -**UI 控制规则:** -- 右侧面板"转公客"/"转成交"/"转无效"按钮在状态已为不可逆态时 `disabled` + `opacity-40 cursor-not-allowed` -- "改状态" Modal 中新状态 Select 选项由后端根据当前状态动态过滤 - ---- - -### 4.2 权限控制矩阵 - -| 操作 | 经纪人(本人) | 经纪人(他人) | 店长 | 管理员 | -|---|---|---|---|---| -| 查看需求信息 | ✅ | 受限 | ✅ | ✅ | -| 编辑需求信息 | ✅ | ❌ | ✅ | ✅ | -| 写入跟进 | ✅ | ❌ | ✅ | ✅ | -| 查看跟进记录 | ✅ | ❌(敏感不可见) | ✅ | ✅ | -| 查看联系人明文号码 | ✅(留痕) | ❌ | ✅(留痕) | ✅(留痕) | -| 新增联系人 | ✅ | ❌ | ✅ | ✅ | -| 改等级 | ✅ | ❌ | ✅ | ✅ | -| 改状态 | ✅ | ❌ | ✅ | ✅ | -| 转公客 | ✅ | ❌ | ✅ | ✅ | -| 转成交 | ✅ | ❌ | ✅ | ✅ | -| 转无效 | ✅ | ❌ | ✅ | ✅ | -| 新增带看 | ✅ | ❌ | ✅ | ✅ | -| 编辑相关员工 | ❌ | ❌ | ✅ | ✅ | -| 查看操作日志 | 部分 | ❌ | ✅ | ✅ | -| 删除跟进记录 | ✅(非敏感) | ❌ | ✅(非敏感) | ✅(非敏感) | - ---- - -### 4.3 HTMX 请求规范 - -| 操作 | hx-trigger | hx-method + URL | hx-target | hx-swap | Loading 行为 | -|---|---|---|---|---|---| -| Tab 切换(需求信息) | click | GET `/clients/{id}/requirements/` | `#tab-content` | innerHTML | `htmx-indicator` 骨架屏 | -| Tab 切换(跟进记录) | click | GET `/clients/{id}/follow-logs/` | `#tab-content` | innerHTML | 骨架屏 | -| Tab 切换(带看) | click | GET `/clients/{id}/viewings/` | `#tab-content` | innerHTML | 骨架屏 | -| Tab 切换(客源解读) | click | GET `/clients/{id}/insights/` | `#tab-content` | innerHTML | 骨架屏 | -| Tab 切换(智能配房) | click | GET `/clients/{id}/property-matches/` | `#tab-content` | innerHTML | 骨架屏 | -| 跟进子 Tab 切换 | click | GET `/clients/{id}/follow-logs/?type=written` | `#log-list` | innerHTML | 列表 spinner | -| 跟进记录日期筛选 | change | GET `/clients/{id}/follow-logs/` | `#log-list` | innerHTML | 列表 spinner | -| 跟进记录加载更多 | click | GET `/clients/{id}/follow-logs/?page=N` | `#log-list` | beforeend | 按钮 spinner | -| 带看子 Tab 切换 | click | GET `/clients/{id}/viewings/?type=appointment` | `#viewing-list` | innerHTML | 列表 spinner | -| 查看联系人号码 | click | POST `/clients/{id}/contacts/{cid}/reveal-phone/` | `#phone-display-{cid}` | innerHTML | 行内 spinner | -| 打开改等级 Modal | click | GET `/clients/{id}/change-grade/` | `#modal-container` | innerHTML | 无(预加载) | -| 提交改等级 | submit | POST `/clients/{id}/change-grade/` | `#status-badge-row` | outerHTML | 按钮 loading | -| 打开改状态 Modal | click | GET `/clients/{id}/change-status/` | `#modal-container` | innerHTML | 无 | -| 提交改状态 | submit | POST `/clients/{id}/change-status/` | `#sidebar-panel` | outerHTML | 按钮 loading | -| 打开转成交 Modal | click | GET `/clients/{id}/convert-deal/` | `#modal-container` | innerHTML | 无 | -| 提交转成交 | submit | POST `/clients/{id}/convert-deal/` | body | — | 按钮 loading | -| 选择成交房源搜索 | click | GET `/properties/select-modal/?q=...` | `#property-table-body` | innerHTML | 表格 spinner | -| 打开写跟进 Drawer | click | GET `/clients/{id}/follow-logs/create/` | `#drawer-container` | innerHTML | 无 | -| 提交写跟进 | submit | POST `/clients/{id}/follow-logs/create/` | `#log-list` | afterbegin | 按钮 loading | -| 编辑基础信息提交 | submit | PATCH `/clients/{id}/edit-basic/` | `#sidebar-panel` | outerHTML | 按钮 loading | -| 客源解读时段切换 | click | GET `/clients/{id}/insights/?period=7d` | `#insight-content` | innerHTML | 内容区 spinner | - ---- - -## 5. 关键数据字段说明 - -| 字段名(英文) | 显示名 | 数据类型 | 说明 | -|---|---|---|---| -| `client.id` | 客源 ID | UUID | 路由参数 | -| `client.client_no` | 客户编号 | string | 格式 `{日期}{类型}{随机}` | -| `client.title` | 需求标题 | string | 如"姚叔叔置换电梯两房(上门)" | -| `client.status` | 状态 | enum | buying/renting/suspended/public/bought/rented_done/invalid | -| `client.grade` | 等级 | enum | A_urgent/A/B/C/D/E | -| `client.client_type` | 客源类型 | enum | private(私客)/public(公客)/deal(成交客) | -| `client.source` | 客户来源 | string | 如"线下·门店接待" | -| `client.requirement_type` | 需求类型 | enum | second_hand/new/rent | -| `client.property_usage` | 房源用途 | enum | residential/commercial/... | -| `client.purchase_purpose` | 购房目的 | multi-enum | 刚需/投资/学区/改善 | -| `client.payment_method` | 付款方式 | enum | full/loan/... | -| `client.owned_properties` | 名下房产 | string | 自由文本 | -| `client.loan_record` | 贷款记录 | boolean | 有/无 | -| `client.id_type` | 证件类型 | enum | id_card/passport/... | -| `client.id_number` | 证件号码 | string(加密) | AES 加密,展示时脱敏 | -| `client.preferred_school` | 意向学校 | string list | 可多条 | -| `client.school_start_year` | 入学时间 | year | — | -| `client.last_follow_at` | 最近跟进时间 | datetime | — | -| `client.created_at` | 委托日期 | datetime | — | -| `client.activity_level` | 活跃度 | int | Celery 每日计算 | -| `client_contacts.name` | 联系人姓名 | string | — | -| `client_contacts.phone_hash` | 手机号 Hash | string | SHA-256,用于重复检测 | -| `client_contacts.phone_encrypted` | 手机号密文 | string | AES 加密,展示时解密脱敏 | -| `client_contacts.gender` | 性别 | enum | male/female | -| `client_contacts.wechat` | 微信号 | string | — | -| `client_requirements.price_min/max` | 总价范围 | decimal | 万元 | -| `client_requirements.area_min/max` | 面积范围 | decimal | ㎡ | -| `client_requirements.rooms` | 居室 | string | — | -| `client_requirements.floor_preference` | 楼层偏好 | multi-enum | — | -| `client_requirements.preferred_districts` | 意向商圈 | string list | — | -| `client_follow_logs.log_type` | 跟进类型 | enum | written/modified/sensitive_view/other/system | -| `client_follow_logs.follow_method` | 跟进方式 | enum | phone/door/sms/wechat/other | -| `client_follow_logs.content` | 跟进内容 | text | — | -| `client_follow_logs.is_open` | 是否开放 | boolean | — | -| `client_viewings.viewing_time` | 带看时间 | datetime | — | -| `client_viewings.situation` | 带看情况 | text | — | -| `client_viewings.viewing_count` | 带看次数 label | string | 一看/二看/... | -| `client_property_matches.match_type` | 配房类型 | enum | recorded/system | -| `client_property_matches.group_label` | 分组标签 | string | 优质户型/降价/热门/新上 | -| `related_staff.role` | 员工角色 | enum | first_recorder(首录人)/owner(归属人) | -| `related_staff.joined_at` | 参与时间 | datetime | — | - ---- - -## 6. 竞品截图对应关系 - -| 截图路径 | 对应功能 | 对应文档章节 | 采纳的设计要点 | -|---|---|---|---| -| `私客详情.png` | 详情页整体框架 | §2.1 | 左右双栏布局;右侧 Banner 使用品牌主色(竞品橙色改为 Teal);Tab 导航在左侧内容区顶部 | -| `需求信息.png` | 需求信息 Tab 内容 | §2.2 | 3 列字段网格;右上角蓝色"编辑"链接;空字段显示 `-` | -| `跟进记录-全部.png` | 跟进记录时间线 | §2.3 | 日期分组橙色圆点;条目卡片带类型 Badge;"已开放"/"隐藏"小字操作链接 | -| `跟进记录-写入跟进.png` | 跟进子 Tab + 扩展筛选 | §2.3 | 跟进目的多选展开/收起;pill 式子 Tab 导航 | -| `跟进记录-敏感信息跟进.png` | 敏感信息跟进空状态 | §2.3.5 | 空状态文案"暂无跟进" | -| `跟进记录-修改跟进.png` | 修改跟进空状态 | §2.3.5 | 同上 | -| `跟进记录-其他跟进.png` | 其他跟进(系统日志) | §2.3 | 【新增私客】等系统类型条目,无操作按钮 | -| `带看.png` | 带看 Tab 内容 | §2.4 | 预约/带看子 Tab;带看次数橙色 Badge;"详情 ›" 链接 | -| `新增带看.png` | 新增带看全页表单 | §3.7 | 分两个卡片区域(带看信息 + 带看房源);三个操作按钮(提交/保存/取消) | -| `新增预约带看.png` | 新增预约带看全页表单 | §3.8 | 日期+时刻分两个选择器;不含"保存"按钮(预约只有提交/取消) | -| `客源解读.png` | 客源解读 Tab | §2.5 | 时段筛选 Pill;活跃行为卡片;三个甜甜圈图(MVP 用百分比文字代替) | -| `二手配房.png` | 二手配房 Tab | §2.6 | 分组标题 + 房源卡片列表;录客/系统配房子 Tab;"批量分享"次要按钮 | -| `客源信息概览.png` | 右侧客源信息面板 | §2.7 | 字段列表 + 三主按钮 + 2列操作网格;"展开全部"收起切换 | -| `编辑基础信息.png` | 编辑基础信息 Modal | §3.1 | 宽型 Modal;多字段含联动(证件类型 → 证件号);意向学校可动态添加 | -| `改等级.png` | 改等级 Modal | §3.2 | 极简 2 字段;`max-w-sm` | -| `改状态.png` | 改状态 Modal | §3.3 | 4 字段含 Textarea;状态选项后端动态控制 | -| `转成交.png` | 转成交 Modal | §3.4 | Radio 选购/租、二手/新房;成交方员工标签组件 | -| `选择成交房源.png` | 选择成交房源宽型 Modal | §3.5 | 搜索 + 表格 + 分页;Radio 单选;"已选(0/1)"状态控制确定按钮 | -| `联系人.png` | 联系人面板 | §2.8 | 号码脱敏;"查看号码"留痕确认;接通/拨打次数展示 | -| `相关员工.png` | 相关员工面板 | §2.9 | 首录人/归属人标签;右侧电话图标;"编辑"仅管理员可见 | - ---- - -## 7. 实现优先级与工期估算 - -| 页面/功能 | 优先级 | 特殊组件复杂度 | 工期估算(前端) | -|---|---|---|---| -| 详情页整体框架(双栏 + Tab) | P0 🔴 | ⭐ Tab Navigation | 1 天 | -| 需求信息 Tab(只读 + 编辑链接) | P0 🔴 | ⭐ | 0.5 天 | -| 右侧信息概览面板(字段 + 操作网格) | P0 🔴 | ⭐ | 1 天 | -| 跟进记录 Tab(时间线 + 子 Tab + 筛选) | P0 🔴 | ⭐⭐ Timeline + Date Range Picker | 2 天 | -| 写入跟进 Drawer | P0 🔴 | ⭐⭐ Drawer + Multi-select Tag | 1.5 天 | -| 带看 Tab(时间线) | P0 🔴 | ⭐ | 1 天 | -| 新增带看(全页表单) | P0 🔴 | ⭐⭐ Dynamic Form Table + 文件上传 | 2 天 | -| 新增预约带看(全页表单) | P0 🔴 | ⭐ Date Picker | 1 天 | -| 改等级 Modal | P0 🔴 | ⭐ | 0.5 天 | -| 改状态 Modal | P0 🔴 | ⭐ | 0.5 天 | -| 转成交 Modal | P0 🔴 | ⭐⭐ | 1 天 | -| 选择成交房源 Modal(搜索表格) | P0 🔴 | ⭐⭐ Data Table + Pagination | 1.5 天 | -| 联系人面板(含查看号码留痕) | P0 🔴 | ⭐ | 0.5 天 | -| 相关员工面板 | P0 🔴 | ⭐ | 0.5 天 | -| 编辑基础信息 Modal(完整表单) | P1 🟡 | ⭐⭐ Multi-select | 1.5 天 | -| 客源解读 Tab(数据图表) | P1 🟡 | ⭐⭐ 图表组件 | 2 天 | -| 二手配房 Tab(房源卡片网格) | P1 🟡 | ⭐⭐ | 1.5 天 | -| 待办提醒区块 | P1 🟡 | ⭐ | 0.5 天 | -| 收藏功能 | P1 🟡 | ⭐ | 0.5 天 | -| 查看操作日志 | P2 ⚫ | ⭐ | 0.5 天 | -| **合计 P0** | — | — | **~14.5 天** | -| **合计 P1** | — | — | **~6 天** | -| **合计 P2** | — | — | **~0.5 天** | - ---- - -## 8. 开放问题(待决策) - -| # | 问题 | 影响范围 | 待确认方 | -|---|---|---|---| -| 1 | 竞品 Banner 颜色为橙色 `#f5774a`,本系统使用 Teal `primary-600`。确认是否在客源详情页 Banner 引入橙色辅助色,还是统一用 Teal? | §2.7 右侧面板 Banner | 产品/设计 | -| 2 | 跟进目的选项约 25 个,竞品截图可见,是否与 PRD 中枚举完全一致?需后端确认字段枚举值。 | §2.3 跟进筛选 | 后端 | -| 3 | "报备/常看" 按钮的业务逻辑:是打开带看表单还是单独的"报备"功能?竞品未见明确说明。 | §2.7 快捷操作 | 产品 | -| 4 | 联系人"查看号码"是否需要每次查看都弹出确认对话框(`hx-confirm`),还是首次查看确认即可(本 session 内缓存权限)? | §2.8 | 产品/法务 | -| 5 | 带看房源"意向程度"的选项枚举值是什么?竞品未完整显示。 | §3.7 新增带看 | 后端 | -| 6 | "转公客"操作是否需要理由 Textarea(竞品未显示此 Modal)?直接 POST 还是需要二次确认弹窗? | §2.7 状态变更 | 产品 | -| 7 | 客源解读 Tab 数据是否 MVP 就需要真实 AI 接口,还是 P1 阶段可先用静态假数据 + 占位图? | §2.5 | 产品/后端 | -| 8 | 右侧面板"展开全部"默认折叠后显示几个字段?竞品显示约 10 个,全部展开约 14 个,需确认默认展示数量。 | §2.7 基础字段列表 | 产品 | -| 9 | 二手配房"批量分享"的分享目标是什么渠道(微信/短信/链接复制)?需确认 P1 实现范围。 | §2.6 | 产品 | -| 10 | `client_status_logs` 是否需要在详情页"查看操作日志"入口展示?竞品有此链接但 PRD 未详细说明展示方式(独立页 or Drawer)。 | P2 操作日志 | 产品 |
暂未填写需求信息
暂无跟进
暂无带看记录
暂无找房行为数据
数据由系统每日凌晨更新
暂无匹配房源
{{ client.primary_contact.name }} {{ client.primary_contact.gender_display }}
系统会在设置的时间点发送跟进通知
- {{ contact.name }} {{ contact.gender_display }} -
- 电话1: - - {{ contact.phone_masked }} - - 默认拨打 - 接通{{ contact.call_success_count }}次 - 拨打{{ contact.call_total_count }}次 -
微信: {{ contact.wechat|default:"-" }}
【{{ staff.role_display }}】
{{ staff.department }} {{ staff.name }}
参与时间: {{ staff.joined_at|date:"Y-m-d H:i" }}
` 错误提示 -- **HTMX 属性**: - -```html -