Files

weishen 8c909c9c08 Sync: add design and process improvement notes

2026-04-25 19:38:47 +08:00

12 KiB

Raw Blame History

客源详情页 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 主体布局规范

<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 代码骨架

<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

字段：总价、面积、居室、装修、朝向、楼层、楼龄、意向商圈、意向小区、交通情况、备注。空值统一 -。

<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。

可点击项支持键盘 Tab 聚焦。
所有交互控件保留 focus-visible 样式。
锚点导航项增加 aria-current="true"（当前 Section）。

9. 工程落地清单（给 AI Engineer）

以 UI_SYSTEM.md 页面框架替换客源详情页现有容器尺寸（Topbar/Sidebar/Content offset）。
删除左侧 Tab 状态机（activeTab）及对应 hx-get Tab 切换逻辑。
新增 Section Anchor Nav，实现锚点滚动与激活高亮。
将需求信息、跟进记录、带看记录、客源解读、二手配房改为同页连续 Sections。
每个 Section 设置独立 HTMX target，避免全页刷新。
右侧信息面板保持 sticky（top-20）并拆分为 4 个卡片区块。
弹窗/抽屉入口统一走 HTMX 拉取片段，提交后定向刷新对应 Section 或右侧卡片。
全量检查 class 是否符合 token（尤其颜色、圆角、焦点环、表格密度）。

10. 验收标准

左侧主区无 Tab 切换行为，所有内容可连续滚动查看。
点击 Section 导航仅发生锚点滚动，不触发内容隐藏/显示。
页面视觉与 preview.html 一致：层级、卡片密度、按钮和输入风格一致。
颜色、字号、圆角、焦点环全部使用系统 token 与规范类名。
关键路径（写跟进、改状态、查看号码）可在单页完成并有明确反馈（loading/toast/error）。

12 KiB Raw Blame History Unescape Escape

客源详情页 UI 设计文档

1. 模块概述

1.1 页面目标

1.2 本版关键改动（相对 v1.0）

1.3 URL 与入口

2. 设计基线（必须遵守）

2.1 视觉与 Token

2.2 组件与图标

2.3 页面骨架对齐 preview 模板

3. 页面信息架构

3.1 整体结构

3.2 主体布局规范

4. 左侧主内容区（全量 Section + 锚点导航）

4.1 Section 导航（替代 Tab）

4.1.1 交互定义

4.1.2 导航样式

4.1.3 代码骨架

4.2 Section 1：需求信息（P0）

4.3 Section 2：跟进记录（P0）

4.4 Section 3：带看记录（P0）

4.5 Section 4：客源解读（P1）

4.6 Section 5：二手配房（P1）

5. 右侧信息面板

5.1 客源信息概览（P0）

5.2 快捷操作区（P0）

5.3 联系人面板（P0）

5.4 相关员工面板（P0）

6. 弹窗与抽屉（与右侧操作对应）

6.1 统一规范

6.2 P0 弹窗清单

7. HTMX 交互规范（锚点版）

7.1 关键变化

7.2 请求映射

8. 状态与可用性规范

8.1 Loading

8.2 Empty

8.3 Error

8.4 A11y

9. 工程落地清单（给 AI Engineer）

10. 验收标准

12 KiB

Raw Blame History