Files

Shen Wei d42bc16120 文档修改

2026-04-26 19:50:01 +08:00

14 KiB

Raw Blame History

任务：为房源列表生成模块 UI 设计文档

你的角色

你是 Fonrey 房产经纪管理系统的 UI/UX 架构师，负责根据竞品截图和 PRD 功能描述，产出一份标准化的模块级 UI 设计文档。该文档将直接交给 AI Engineer 用于编码实现，必须包含足够的细节，Engineer 无需再问任何问题。

注意
以下所有的文档或图片是基于文档库的相对路径。
文档库的根路径为：/mnt/d/Workspace/nexus

全局设计约束（必须严格遵守）

所有设计决策必须符合 Project/fonrey/UI_SYSTEM/UI_SYSTEM.md 中的设计规范。核心约束如下：

技术栈：Tailwind CSS + HTMX + Alpine.js + Django HTML 模板（非 React/Vue/JSX）
图标库：Heroicons v2（Outline 24px 默认，Solid 20px 强调，Mini 16px 极密场景）
主色：Teal #0F766E（primary-600），所有颜色引用 Token，禁止硬编码 Hex
圆角：rounded-lg（8px）为默认，表格行/小组件用 rounded-md（6px）
表格行高：56px（h-14）
字体：Inter + PingFang SC，正文 text-sm（14px）
焦点环：focus-visible:ring-2 focus-visible:ring-primary-600/40
桌面优先：≥1280px，不做移动端适配
禁止独立 CSS 文件或 CSS-in-JS：所有样式用 Tailwind utility class（少量例外如 Flatpickr 覆盖样式）
组件实现参考：Project/fonrey/UI_SYSTEM/组件规范设计.md（含 20 个特殊组件的完整 HTML + Alpine.js 实现）

本次任务输入

1. 目标模块

模块名称：房源列表
模块描述：房源列表

2. PRD 功能文档路径

{{PRD文件路径，如：Project/fonrey/PRD/房源管理/房源管理模块PRD.md}}

请读取该文件，理解每个功能点的业务逻辑和验收标准。

3. DATA_MODEL 数据模型文档路径

{{DATA_MODEL文件路径，如：Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md}}

请读取该文件，理解该模块的数据模型以及字段命名。

4. 竞品参考截图

请读取以下截图文件作为视觉参考（所有截图均在 Project/fonrey/screenshots/ 目录下）：

房源列表：
- Project/fonrey/screenshots/房源/房源列表.png
- Project/fonrey/screenshots/房源/全部房源.png

5. 参考已完成类似页面设计

请读取以下已完成和当前模块页面设计类似的文档和页面：

客源列表UI文档设计：Project/fonrey/UI_DESIGN/客源管理/客源列表_UI.md
客源泪飙UI静态原型：Project/fonrey/UI_DESIGN/客源管理/客源列表_UI.html

6. MVP 优先级参考

请参考 Project/fonrey/PRD/PRD_MVP.md，在设计文档中标注每个页面/功能的优先级（P0/P1/P2）。

输出格式要求

输出一份完整的 Markdown 文档，Project/fonrey/UI_DESIGN/房源列表_UI.md，结构如下：

# {{模块名称}} UI 设计文档

> **版本**：v1.0 · **日期**：{今日日期}
> **依赖规范**：UI_SYSTEM.md v1.1 · 组件规范设计.md v1.0
> **PRD 来源**：{PRD文件路径}
> **优先级**：P0 功能在本文档中用 🔴 标注，P1 用 🟡，P2 用 ⚫

---

## 目录

（列出本文档所有章节）

---

## 1. 模块概述

### 1.1 功能范围
（从 PRD 提取本模块包含的所有功能，按优先级分组列表）

### 1.2 页面清单
（列出本模块所有页面/视图，每行包含：页面名称 | URL 模式建议 | 优先级 | 对应 PRD 章节）

### 1.3 用户角色与权限差异
（说明不同角色（经纪人/店长/管理员）在本模块的视图差异，如哪些字段/按钮对特定角色隐藏）

---

## 2. 页面设计规范

> 每个页面单独一节，按以下子结构输出。

### 2.N {页面名称}（{优先级} 🔴/🟡/⚫）

#### 2.N.1 页面概述
- **URL**：`/模块/页面/`
- **访问入口**：（从哪里进入此页面）
- **页面职责**：（一句话）
- **竞品参考截图**：`{截图路径}`

#### 2.N.2 布局结构
（用文字描述页面整体布局，如：三栏布局、左侧边栏+右侧主内容区、全宽列表等）

┌──────────────────────────────────────────────────────────┐
│ 顶部区域（Breadcrumb / 页面标题 / 主操作按钮） │
├──────────────────────────────────────────────────────────┤
│ 筛选区域（可折叠） │
├──────────────────────────────────────────────────────────┤
│ 工具栏（批量操作 / 排序切换 / 列设置 / 导出） │
├──────────────────────────────────────────────────────────┤
│ 主内容区（表格 / 详情卡片 / 表单） │
├──────────────────────────────────────────────────────────┤
│ 分页栏 │
└──────────────────────────────────────────────────────────┘

（根据实际页面调整此 ASCII 图）

#### 2.N.3 区域详细规范

> 每个区域独立描述，包含：组件类型、字段/按钮清单、交互逻辑

**[区域名称，如：搜索筛选区]**

| 属性 | 说明 |
|---|---|
| 组件 | （引用组件规范设计.md 中的组件名，如：Date Range Picker） |
| 展开/收起 | （是否支持折叠，默认状态） |
| 筛选字段 | （列出所有筛选字段及输入类型） |
| 联动逻辑 | （字段间的联动关系） |
| HTMX 行为 | （如：`hx-get="/api/xxx/" hx-trigger="change" hx-target="#table-body"`） |

**[区域名称，如：数据表格]**

| 列名 | 数据类型 | 宽度 | 排序 | 特殊渲染 |
|---|---|---|---|---|
| （列名） | （string/number/date/badge/...） | （fixed px 或 auto） | （是/否） | （如：Tag、趋势箭头、行内按钮） |

（补充表格交互说明：行点击跳转、批量选择、列固定等）

#### 2.N.4 使用的特殊组件

| 组件名 | 来源（组件规范设计.md 章节） | 用途 | 自定义说明 |
|---|---|---|---|
| （组件名） | （如：§1 Data Table） | （用于展示xxx列表） | （如果有与标准实现不同的地方，详细说明） |

#### 2.N.5 空状态设计
（描述列表/表格无数据时的展示方式，参考 UI_SYSTEM.md §6.3 空状态设计）

#### 2.N.6 Loading 状态
（描述数据加载中的骨架屏或加载指示方案）

---

## 3. 弹窗/抽屉设计规范

> 每个弹窗/抽屉独立一节，按以下结构输出。

### 3.N {弹窗/抽屉名称}（{触发入口}）

#### 3.N.1 触发方式
- **触发位置**：（如：房源详情页-调价链接）
- **组件类型**：Modal Dialog / Drawer（选一个，说明选择理由）
- **尺寸**：（Modal: max-w-sm/md/lg/xl/2xl；Drawer: w-[480px]/w-[640px]）
- **竞品截图**：`{截图路径}`

#### 3.N.2 表单字段规范

| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值/预填值 |
|---|---|---|---|---|
| （字段名） | （Input/Select/Textarea/DatePicker/Toggle/TreeSelect/MultiTag/...） | （是/否） | （规则描述） | （如有） |

#### 3.N.3 提交行为
- **提交方式**：HTMX `hx-post` / `hx-put` / `hx-patch`
- **成功响应**：（如：关闭弹窗 + Toast "保存成功" + 刷新目标区域）
- **失败响应（422）**：（字段级错误提示）
- **HTMX 属性**：（完整写出 hx-post/hx-target/hx-swap/hx-on 等）

#### 3.N.4 使用的特殊组件

| 组件名 | 来源 | 用途 |
|---|---|---|

---

## 4. 交互状态规范

### 4.1 全局状态机（如有）
（如房源状态机：在售 → 暂缓 → 成交 → 下架，用状态流转图描述）

### 4.2 权限控制矩阵
（描述不同角色对本模块各操作的权限，如：删除只有管理员可见）

| 操作 | 经纪人 | 店长 | 管理员 |
|---|---|---|---|

### 4.3 HTMX 请求规范
（列出本模块所有 HTMX 请求，包含：触发事件、URL、target、swap 方式、Loading 行为）

| 操作 | hx-trigger | hx-get/post/... | hx-target | hx-swap | Loading |
|---|---|---|---|---|---|

---

## 5. 关键数据字段说明

（列出本模块所有需要后端支持的数据字段，便于 Engineer 与后端联调）

| 字段名（英文） | 显示名 | 数据类型 | 说明 |
|---|---|---|---|

---

## 6. 竞品截图对应关系

（将本模块所有参考截图按功能分类整理，说明截图对应设计文档的哪个章节）

| 截图路径 | 对应功能 | 对应文档章节 | 采纳的设计要点 |
|---|---|---|---|

---

## 7. 实现优先级与工期估算

| 页面/功能 | 优先级 | 特殊组件复杂度 | 工期估算（前端） |
|---|---|---|---|

---

## 8. 开放问题（待决策）

（列出设计过程中发现的、需要产品/后端确认的问题）

| # | 问题 | 影响范围 | 待确认方 |
|---|---|---|---|

额外要求

类似页面UI设计有限：如有已完成的类似页面设计，请作为主要参考，设计页面布局，内容布局等。
PRD优先：有截图的功能，以截图呈现的 UI 为补充说明，以PRD 文字为主要参考；截图和 PRD 有冲突时，以PRD为准，并在文档中注明差异。
组件引用：每次使用特殊组件（如 Data Table、Tree Select、Drawer 等），必须在"使用的特殊组件"表格中引用组件规范设计.md 的对应章节编号，并说明如有差异的自定义部分。
HTMX 落地：每个需要异步更新的交互（筛选、分页、弹窗提交）必须写出完整的 HTMX 属性，Engineer 可以直接复制使用。
Alpine.js 分工：说明哪些状态由 Alpine.js 管理（弹窗开关、选中状态、表单联动），哪些交互走 HTMX（数据加载、表单提交）。
禁止设计移动端：所有布局仅针对 ≥1280px 桌面端。
优先级标注：P0 功能用 🔴，P1 用 🟡，P2 用 ⚫，确保 Engineer 知道实现顺序。
不要遗漏边界状态：每个列表页必须包含空状态设计；每个表单必须包含校验失败状态；每个异步操作必须包含 Loading 状态。

任务：为房源列表生成模块 UI 静态原型

你的角色

注意以下所有的文档或图片是基于文档库的相对路径。文档库的根路径为：/mnt/d/Workspace/nexus

全局设计约束（必须严格遵守）

所有设计决策必须符合 Project/fonrey/UI_SYSTEM/UI_SYSTEM.md 中的设计规范。核心约束如下：

技术栈：Tailwind CSS + HTMX + Alpine.js + Django HTML 模板（非 React/Vue/JSX）
图标库：Heroicons v2（Outline 24px 默认，Solid 20px 强调，Mini 16px 极密场景）
主色：Teal #0F766E（primary-600），所有颜色引用 Token，禁止硬编码 Hex
圆角：rounded-lg（8px）为默认，表格行/小组件用 rounded-md（6px）
表格行高：56px（h-14）
字体：Inter + PingFang SC，正文 text-sm（14px）
焦点环：focus-visible:ring-2 focus-visible:ring-primary-600/40
桌面优先：≥1280px，不做移动端适配
禁止独立 CSS 文件或 CSS-in-JS：所有样式用 Tailwind utility class（少量例外如 Flatpickr 覆盖样式）
组件实现参考：Project/fonrey/UI_SYSTEM/组件规范设计.md（含 20 个特殊组件的完整 HTML + Alpine.js 实现）

输入文件

【UI_SYSTEM】全局UI设计规范文档 Project/fonrey/UI_SYSTEM/UI_SYSTEM.md
【现有原型页面】已完成的HTML页面（作为视觉和代码参考基准）
- Project/fonrey/UI_SYSTEM/preview.html
- Project/fonrey/UI_DESIGN/客源列表_UI.html
【本次模块UI设计文档】本次需要实现的模块设计说明
- Project/fonrey/UI_DESIGN/房源列表_UI.md 输出文件

【本次模块UI输出静态原型文件】
- Project/fonrey/UI_DESIGN/房源列表_UI.html

强制约束（不可违反）

一致性约束

颜色、字体、字号、圆角、阴影、间距等视觉变量，必须与 UI_SYSTEM 保持完全一致，不得自行创造新的变量
公共组件（导航栏、侧边栏、顶部栏、按钮、表单、卡片、标签等）的样式和结构，必须与现有原型页面中的实现保持一致
如果现有页面使用了 CSS 变量或特定 class 命名规范，本次输出必须沿用相同的规范

布局约束

整体页面框架（如侧边栏宽度、顶栏高度、内容区边距）必须与现有原型页面保持一致
响应式断点策略（如有）需与已有页面对齐

代码约束

输出单一 HTML 文件，CSS 写在 <style> 标签内，JS 写在 <script> 标签内
不引入任何外部依赖，除非现有原型页面已经使用了该依赖
类名、变量名的命名风格与现有代码保持一致

执行步骤（按顺序执行）

通读所有输入材料，识别 UI_SYSTEM 中的核心设计 token
分析现有原型页面，提取公共组件的 HTML 结构和 CSS 实现
阅读本次模块设计文档，理解页面结构、交互状态和内容层级
以现有页面为外壳，将本次模块内容填入正确的内容区域
对照设计文档逐项检查还原度，确认无遗漏后输出

输出要求

直接输出完整可运行的 HTML 文件内容
页面中需要数据的地方使用合理的占位内容（不要留空）
交互状态（hover、active、selected、disabled）需在 CSS 中体现
输出完成后，列出你在本次实现中做出的所有设计假设或补充决策

注意事项

如果设计文档与 UI_SYSTEM 存在冲突，以 UI_SYSTEM 为准，并告知我冲突点
如果设计文档描述不清晰，不要自行猜测，先列出疑问再继续

14 KiB Raw Blame History Unescape Escape

任务：为房源列表 生成模块 UI 设计文档

你的角色

全局设计约束（必须严格遵守）

本次任务输入

1. 目标模块

2. PRD 功能文档路径

3. DATA_MODEL 数据模型文档路径

4. 竞品参考截图

5. 参考已完成类似页面设计

6. MVP 优先级参考

输出格式要求

额外要求

任务：为房源列表生成模块 UI 静态原型

你的角色

全局设计约束（必须严格遵守）

强制约束（不可违反）

一致性约束

布局约束

代码约束

执行步骤（按顺序执行）

输出要求

注意事项

14 KiB

Raw Blame History

任务：为房源列表生成模块 UI 设计文档