Sync: add design and process improvement notes

2026-04-25 19:38:47 +08:00
parent 2613a74c73
commit 8c909c9c08
21 changed files with 1553 additions and 107 deletions
--- a/Project/fonrey/UI_DESIGN/客源详情_UI设计.md
+++ b/Project/fonrey/UI_DESIGN/客源详情_UI设计.md
@@ -0,0 +1,316 @@
+# 客源详情页 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）。