317 lines
12 KiB
Markdown
317 lines
12 KiB
Markdown
# 客源详情页 UI 设计文档
|
||
|
||
> **版本**：v1.1 · **日期**：2026-04-25
|
||
> **依赖规范**：`Project/fonrey/UI_SYSTEM/UI_SYSTEM.md` v1.2、`Project/fonrey/UI_SYSTEM/组件规范设计.md`
|
||
> **视觉参考**：`Project/fonrey/UI_SYSTEM/preview.html`（页面骨架、卡片层级、工具栏密度）
|
||
> **PRD 来源**：`Project/fonrey/PRD/客源管理/客源管理模块PRD.md` §5.7 私客详情页
|
||
|
||
---
|
||
|
||
## 1. 模块概述
|
||
|
||
### 1.1 页面目标
|
||
|
||
- 在一个页面内完成私客详情查看、跟进、带看、状态流转、联系人管理、相关员工查看。
|
||
- 桌面优先（`>=1280px`），不做移动端适配。
|
||
- 技术栈固定：Tailwind CSS + HTMX + Alpine.js + Django Template。
|
||
|
||
### 1.2 本版关键改动（相对 v1.0）
|
||
|
||
- 左侧主内容区**取消 Tab 切换**，改为**全量 Section 连续展示**。
|
||
- 顶部 Section 导航仅用于锚点跳转（`#section-*`），不隐藏任何内容。
|
||
- 页面布局、间距、层级、色彩、焦点环严格对齐 `UI_SYSTEM.md` 与 `preview.html`。
|
||
|
||
### 1.3 URL 与入口
|
||
|
||
- 详情页主路由：`/clients/<client_id>/`
|
||
- 入口：客源列表点击姓名或详情操作。
|
||
- 所有左侧 Section 默认随页面 SSR 输出，首屏即可看到首个 Section，向下滚动查看其余 Section。
|
||
|
||
---
|
||
|
||
## 2. 设计基线（必须遵守）
|
||
|
||
### 2.1 视觉与 Token
|
||
|
||
- 主色：`primary-600`，禁用硬编码 Hex。
|
||
- 页面底色：`bg-neutral-50`，内容卡片：`bg-white border border-neutral-200 rounded-lg`。
|
||
- 正文字号：`text-sm`；辅助：`text-xs text-neutral-500`；关键数字加 `tabular-nums`。
|
||
- 圆角：卡片 `rounded-lg`，输入/按钮 `rounded-md`，标签 `rounded`。
|
||
- 焦点环统一：`focus-visible:ring-2 focus-visible:ring-primary-600/40`。
|
||
|
||
### 2.2 组件与图标
|
||
|
||
- 图标库：Heroicons v2。
|
||
- 默认：Outline 24px（`w-5 h-5`）
|
||
- 强调：Solid 20px（`w-5 h-5`）
|
||
- 高密：Mini 16px（`w-4 h-4`）
|
||
- 禁止独立 CSS 文件；样式全部使用 Tailwind utility class。
|
||
|
||
### 2.3 页面骨架对齐 preview 模板
|
||
|
||
- Topbar：`h-14 sticky top-0 z-20 bg-white border-b border-neutral-200`
|
||
- Sidebar：展开 `w-60`，内容区偏移 `ml-60`
|
||
- 主内容区：`px-6 py-4`
|
||
- 区块垂直节奏：`space-y-6`
|
||
|
||
---
|
||
|
||
## 3. 页面信息架构
|
||
|
||
## 3.1 整体结构
|
||
|
||
```
|
||
Topbar (56)
|
||
-> Sidebar (240)
|
||
-> Content Area (bg-neutral-50)
|
||
-> Breadcrumb + Header Actions
|
||
-> Main Grid (12 cols)
|
||
- Left Content: 8 cols
|
||
- Sticky Section Anchor Nav (非 Tab)
|
||
- Section 1: 需求信息
|
||
- Section 2: 跟进记录
|
||
- Section 3: 带看记录
|
||
- Section 4: 客源解读（P1）
|
||
- Section 5: 二手配房（P1）
|
||
- Right Sidebar: 4 cols
|
||
- 客源信息概览
|
||
- 联系人
|
||
- 相关员工
|
||
- 其他操作
|
||
```
|
||
|
||
### 3.2 主体布局规范
|
||
|
||
```html
|
||
<main class="ml-60 min-h-[calc(100vh-56px)] bg-neutral-50 px-6 py-4">
|
||
<div class="mx-auto max-w-[1600px] space-y-4">
|
||
<!-- 面包屑 + 页头 -->
|
||
|
||
<div class="grid grid-cols-12 gap-6 items-start">
|
||
<section class="col-span-8 min-w-0 space-y-6" id="client-detail-main">
|
||
<!-- Anchor Nav -->
|
||
<!-- All sections rendered below -->
|
||
</section>
|
||
|
||
<aside class="col-span-4 min-w-0 space-y-3 sticky top-20" id="client-detail-side">
|
||
<!-- right panels -->
|
||
</aside>
|
||
</div>
|
||
</div>
|
||
</main>
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 左侧主内容区（全量 Section + 锚点导航）
|
||
|
||
### 4.1 Section 导航（替代 Tab）
|
||
|
||
### 4.1.1 交互定义
|
||
|
||
- 导航仅用于锚点跳转，不切换内容，不销毁 DOM。
|
||
- 点击导航项：`href="#section-xxx"`，平滑滚动到目标 Section。
|
||
- 当前高亮：通过 IntersectionObserver + Alpine 更新 `activeSection`。
|
||
- 导航条 sticky：滚动时固定在左栏顶部，便于快速定位。
|
||
|
||
### 4.1.2 导航样式
|
||
|
||
- 容器：`bg-white border border-neutral-200 rounded-lg px-3 py-2 sticky top-20 z-30`
|
||
- 项默认：`text-sm text-neutral-600 hover:text-neutral-800 hover:bg-neutral-100 rounded-md`
|
||
- 项激活：`bg-primary-50 text-primary-700 font-medium`
|
||
|
||
### 4.1.3 代码骨架
|
||
|
||
```html
|
||
<div x-data="sectionNav()" class="bg-white border border-neutral-200 rounded-lg px-3 py-2 sticky top-20 z-30">
|
||
<nav class="flex items-center gap-1 overflow-x-auto whitespace-nowrap" aria-label="详情分区导航">
|
||
<a href="#section-requirements" @click="jump('section-requirements')"
|
||
:class="active==='section-requirements' ? 'bg-primary-50 text-primary-700 font-medium' : 'text-neutral-600 hover:bg-neutral-100 hover:text-neutral-800'"
|
||
class="px-3 py-1.5 text-sm rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-600/40">需求信息</a>
|
||
<a href="#section-follow" @click="jump('section-follow')" class="px-3 py-1.5 text-sm rounded-md">跟进记录</a>
|
||
<a href="#section-viewings" @click="jump('section-viewings')" class="px-3 py-1.5 text-sm rounded-md">带看记录</a>
|
||
<a href="#section-insights" @click="jump('section-insights')" class="px-3 py-1.5 text-sm rounded-md">客源解读</a>
|
||
<a href="#section-matches" @click="jump('section-matches')" class="px-3 py-1.5 text-sm rounded-md">二手配房</a>
|
||
</nav>
|
||
</div>
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 Section 1：需求信息（P0）
|
||
|
||
- Section ID：`section-requirements`
|
||
- 卡片结构：标题行（含编辑按钮）+ 三列字段网格 + 备注跨列。
|
||
- 容器：`bg-white rounded-lg border border-neutral-200 p-4 space-y-4`
|
||
|
||
字段：总价、面积、居室、装修、朝向、楼层、楼龄、意向商圈、意向小区、交通情况、备注。空值统一 `-`。
|
||
|
||
```html
|
||
<section id="section-requirements" class="scroll-mt-24 bg-white rounded-lg border border-neutral-200 p-4 space-y-4">
|
||
<header class="flex items-center justify-between">
|
||
<h2 class="text-base font-semibold text-neutral-800">需求信息</h2>
|
||
<button class="text-sm text-primary-600 hover:text-primary-700 hover:underline underline-offset-2">编辑</button>
|
||
</header>
|
||
<dl class="grid grid-cols-3 gap-x-6 gap-y-4">
|
||
<!-- field items -->
|
||
</dl>
|
||
</section>
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 Section 2：跟进记录（P0）
|
||
|
||
- Section ID：`section-follow`
|
||
- 不再以 Tab 切页；在同一 Section 内使用筛选条 + 时间线。
|
||
- Header 右侧固定主操作：`写跟进`（Primary）。
|
||
|
||
结构：
|
||
- 筛选工具栏（跟进类型、日期范围、有录音/有图片）
|
||
- 时间线列表（日期分组）
|
||
- 加载更多
|
||
|
||
样式要点：
|
||
- 条目卡片 `rounded-md border border-neutral-200 p-3`
|
||
- 敏感信息记录 `bg-warning-50 border-warning-600/20`
|
||
|
||
---
|
||
|
||
### 4.4 Section 3：带看记录（P0）
|
||
|
||
- Section ID：`section-viewings`
|
||
- Header 右侧操作：`新增带看`（Secondary）+ `新增预约`（Secondary）。
|
||
- 筛选：日期范围、归属人带看、其他人带看。
|
||
- 内容：时间线卡片，显示带看情况、房源链接、带看次数标签、详情链接。
|
||
|
||
---
|
||
|
||
### 4.5 Section 4：客源解读（P1）
|
||
|
||
- Section ID：`section-insights`
|
||
- 默认展示占位/空态，接口就绪后替换数据。
|
||
- 布局：2 列卡片 + 偏好摘要 + 图表占位（可先文本百分比）。
|
||
|
||
---
|
||
|
||
### 4.6 Section 5：二手配房（P1）
|
||
|
||
- Section ID：`section-matches`
|
||
- Header：更新时间 + `批量分享`。
|
||
- 内容：按分组展示房源卡片列表（优质户型/降价/热门/新上）。
|
||
- 卡片内操作：`分享房源`、`反馈`。
|
||
|
||
---
|
||
|
||
## 5. 右侧信息面板
|
||
|
||
### 5.1 客源信息概览（P0）
|
||
|
||
- 顶部标识区使用主色：`bg-primary-600 text-white rounded-t-lg`。
|
||
- 标签行：私客、带看进度、等级。
|
||
- 字段列表：最近跟进、客户编号、委托日期、需求类型、用途、来源、购房目的、付款方式、名下房产、贷款记录、证件信息、意向学校、入学时间。
|
||
- 展开收起：默认展示 8 行，点击 `展开全部` 展示完整。
|
||
|
||
### 5.2 快捷操作区（P0）
|
||
|
||
- 三主按钮：打电话、写跟进、报备/常看。
|
||
- 两列操作网格：收藏、置顶、改等级、改状态、转公客、转成交、转无效、编辑客源。
|
||
- 禁用态统一：`disabled:opacity-50 disabled:cursor-not-allowed`。
|
||
|
||
### 5.3 联系人面板（P0）
|
||
|
||
- Header 操作：`查看号码`、`新增联系人`。
|
||
- 手机号默认脱敏；点击查看明文需后端留痕并返回片段更新。
|
||
|
||
### 5.4 相关员工面板（P0）
|
||
|
||
- 展示首录人、归属人、参与时间。
|
||
- 店长/管理员显示 `编辑` 入口。
|
||
|
||
---
|
||
|
||
## 6. 弹窗与抽屉（与右侧操作对应）
|
||
|
||
### 6.1 统一规范
|
||
|
||
- Modal：遵循 `UI_SYSTEM.md` §3.6，默认 `max-w-sm/max-w-md/max-w-lg`。
|
||
- Drawer：右侧 `w-[480px]`，用于写跟进等字段较多场景。
|
||
- Footer：右对齐，`取消` + `确认`。
|
||
|
||
### 6.2 P0 弹窗清单
|
||
|
||
- 改等级（Modal, `max-w-sm`）
|
||
- 改状态（Modal, `max-w-md`）
|
||
- 转成交（Modal, `max-w-lg`）
|
||
- 选择成交房源（Modal, `max-w-5xl`，内含表格+分页）
|
||
- 写跟进（Drawer, `w-[480px]`）
|
||
|
||
---
|
||
|
||
## 7. HTMX 交互规范（锚点版）
|
||
|
||
### 7.1 关键变化
|
||
|
||
- 删除「左侧 Tab 切换请求」。
|
||
- 详情页首次渲染直接返回完整 Sections。
|
||
- 每个 Section 内部独立筛选和分页请求，仅刷新本 Section 容器。
|
||
|
||
### 7.2 请求映射
|
||
|
||
| 操作 | URL | Target | Swap |
|
||
|---|---|---|---|
|
||
| 跟进筛选 | `/clients/{id}/follow-logs/partial` | `#follow-section-body` | `innerHTML` |
|
||
| 跟进加载更多 | `/clients/{id}/follow-logs/partial?page=N` | `#follow-timeline-list` | `beforeend` |
|
||
| 带看筛选 | `/clients/{id}/viewings/partial` | `#viewings-section-body` | `innerHTML` |
|
||
| 客源解读时段切换 | `/clients/{id}/insights/partial?period=7d` | `#insights-section-body` | `innerHTML` |
|
||
| 配房筛选/分页 | `/clients/{id}/matches/partial` | `#matches-section-body` | `innerHTML` |
|
||
| 查看号码 | `/clients/{id}/contacts/{cid}/reveal-phone/` | `#phone-{cid}` | `innerHTML` |
|
||
|
||
---
|
||
|
||
## 8. 状态与可用性规范
|
||
|
||
### 8.1 Loading
|
||
|
||
- 每个 Section 内独立 `htmx-indicator` 骨架。
|
||
- 按钮提交中显示 Spinner + 进行时文案（如 `保存中...`）。
|
||
|
||
### 8.2 Empty
|
||
|
||
- 跟进为空：`暂无跟进`。
|
||
- 带看为空：`暂无带看记录` + `新增带看`。
|
||
- 配房为空：`暂无匹配房源`。
|
||
|
||
### 8.3 Error
|
||
|
||
- `htmx:responseError` 保留旧内容 + 右下角 Error Toast。
|
||
|
||
### 8.4 A11y
|
||
|
||
- 可点击项支持键盘 Tab 聚焦。
|
||
- 所有交互控件保留 `focus-visible` 样式。
|
||
- 锚点导航项增加 `aria-current="true"`（当前 Section）。
|
||
|
||
---
|
||
|
||
## 9. 工程落地清单（给 AI Engineer）
|
||
|
||
1. 以 `UI_SYSTEM.md` 页面框架替换客源详情页现有容器尺寸（Topbar/Sidebar/Content offset）。
|
||
2. 删除左侧 Tab 状态机（`activeTab`）及对应 `hx-get` Tab 切换逻辑。
|
||
3. 新增 `Section Anchor Nav`，实现锚点滚动与激活高亮。
|
||
4. 将需求信息、跟进记录、带看记录、客源解读、二手配房改为同页连续 Sections。
|
||
5. 每个 Section 设置独立 HTMX target，避免全页刷新。
|
||
6. 右侧信息面板保持 sticky（`top-20`）并拆分为 4 个卡片区块。
|
||
7. 弹窗/抽屉入口统一走 HTMX 拉取片段，提交后定向刷新对应 Section 或右侧卡片。
|
||
8. 全量检查 class 是否符合 token（尤其颜色、圆角、焦点环、表格密度）。
|
||
|
||
---
|
||
|
||
## 10. 验收标准
|
||
|
||
- 左侧主区无 Tab 切换行为，所有内容可连续滚动查看。
|
||
- 点击 Section 导航仅发生锚点滚动，不触发内容隐藏/显示。
|
||
- 页面视觉与 `preview.html` 一致：层级、卡片密度、按钮和输入风格一致。
|
||
- 颜色、字号、圆角、焦点环全部使用系统 token 与规范类名。
|
||
- 关键路径（写跟进、改状态、查看号码）可在单页完成并有明确反馈（loading/toast/error）。
|