diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL.md b/Project/fonrey/DATA_MODEL/DATA_MODEL.md index b03595c8..333528d8 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey 房产经纪管理系统 — DATA MODEL 设计文档 > **作者**: Backend Architect diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md index baab0cb4..9d3797e3 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — 客源管理数据模型（DATA_MODEL_CLIENT） > **所属系统**: Fonrey 房产经纪管理系统 diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_COMPLEX.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_COMPLEX.md index 0f0f06cc..74992e7e 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_COMPLEX.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_COMPLEX.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — 楼盘与区域数据模型（DATA_MODEL_COMPLEX） > **所属系统**: Fonrey 房产经纪管理系统 diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_ORG.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_ORG.md index 8219a4b6..48fe13d8 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_ORG.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_ORG.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — 组织人事数据模型（DATA_MODEL_ORG） > **所属系统**: Fonrey 房产经纪管理系统 diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_PERMISSION.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_PERMISSION.md index fcbcba6b..06c19e84 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_PERMISSION.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_PERMISSION.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — 权限管理数据模型（DATA_MODEL_PERMISSION） > **所属系统**: Fonrey 房产经纪管理系统 diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md index 1d7ac7e0..9f8512f6 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — 房源模块数据模型（DATA_MODEL_PROPERTY） > **权威定义**：本文件是房源模块所有表结构的唯一权威来源。 diff --git a/Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md b/Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md index 6082e199..2c6dd7ba 100644 --- a/Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md +++ b/Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey — Public Schema 数据模型 > **作者**: Backend Architect diff --git a/Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md b/Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md index e9d11846..1cf36df9 100644 --- a/Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md +++ b/Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md @@ -436,7 +436,7 @@ Response 200 (失败): │ └─ 用户查收邮件，获取用户名 → 返回登录 ``` - +![[找回用户名流程.png]] > **前端识别逻辑**：用户在「忘记用户名」页面输入邮箱提交后，服务端根据是否匹配到 Tenant Admin 账号决定处理路径，前端无需区分，统一展示「如该邮箱已绑定账号，您将收到邮件」。 **邮件模板（找回用户名）**： @@ -490,7 +490,7 @@ Response 200 (失败): → 清除该账号所有有效 Session（强制重新登录） → 跳转登录界面，提示「密码已重置，请重新登录」 ``` - +![[找回密码流程.png]] > **注意**：找回密码流程依赖员工账号绑定了邮箱。若员工未绑定邮箱，无法自助找回，需联系 Tenant Admin 在管理界面执行「重置密码」操作，将密码恢复为固定初始密码。 **邮件模板（重置密码）**： diff --git a/Project/fonrey/TECH_STACK/权限管理系统技术方案.md b/Project/fonrey/TECH_STACK/权限管理系统技术方案.md index e8568571..24ceedc8 100644 --- a/Project/fonrey/TECH_STACK/权限管理系统技术方案.md +++ b/Project/fonrey/TECH_STACK/权限管理系统技术方案.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey 权限管理系统技术方案建议 **版本**: 1.0 | **项目**: Fonrey 房产经纪管理系统 | **技术栈**: Django 4.x + HTMX + Alpine.js + PostgreSQL + Redis diff --git a/Project/fonrey/TECH_STACK/登录管理技术方案.md b/Project/fonrey/TECH_STACK/登录管理技术方案.md index 7678fa37..4e9c8cf1 100644 --- a/Project/fonrey/TECH_STACK/登录管理技术方案.md +++ b/Project/fonrey/TECH_STACK/登录管理技术方案.md @@ -1,3 +1,4 @@ +> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. # Fonrey 登录管理系统技术方案 **版本**: 1.0 | **项目**: Fonrey 房产经纪管理系统 | **技术栈**: Django 4.x + HTMX + Alpine.js + PostgreSQL + Redis + Celery diff --git a/Project/fonrey/prompt/Fonrey_PRD_提示词模板_v2.md b/Project/fonrey/prompt/Fonrey_PRD_提示词模板_v2.md new file mode 100644 index 00000000..12f9249d --- /dev/null +++ b/Project/fonrey/prompt/Fonrey_PRD_提示词模板_v2.md @@ -0,0 +1,347 @@ +# Fonrey PRD 需求文档生成提示词模板 + +> 本模板专注于**产品需求定义**：做什么、为谁做、怎么验收。 +> 技术实现细节（数据模型 DDL、API 路由、架构设计）由配套的 **TECH_STACK & DATA_MODEL 模板**负责，两份文档互不重复。 + +--- + +## ✅ 使用前检查清单 + +- [ ] 已填写本次设计的模块 / 功能名称 +- [ ] 已确认参考的已有 PRD 路径（可留空） +- [ ] 已准备好产品截图或草图（如有，直接附在消息中） +- [ ] 已明确本次功能的优先级范围（P0 / P1 / P2） +- [ ] TECH_STACK.md 已存在，可供 AI 读取技术约束 + +--- + +## 📋 完整提示词（复制后填写 `【...】` 再发送） + + +## 角色与背景 + +你是 **Billy**，一名拥有 10 年以上经验的资深产品经理，擅长 B2B SaaS 产品的全生命周期管理。 +核心方法论：先问问题再给答案，先定义问题再讨论方案，先看证据再拍板决策。 +你输出的每一份需求文档都必须包含清晰的用户故事、可量化的验收标准、明确的边界（Non-Goals）。 +你永远不写模糊需求，每条需求都可以被工程师直接实现、测试和验收。 + +**你的职责边界**： +- ✅ 负责：功能范围定义、用户故事、验收标准、字段规范、页面结构、权限要求、性能指标 +- ❌ 不负责：数据库 DDL、API 路由代码、系统架构设计——这些由配套技术文档承接 + +--- + +## 项目背景 + +**工作目录**：`~/Workspace/nexus` + +**项目概览**： +我正在开发 **Fonrey（房睿）**——一款面向房地产经纪公司的 B2B SaaS 平台。 +核心目标：解决房源 / 客源信息散乱、跟进缺失、重复录入等痛点，支撑 89,000+ 条数据量级下的高效匹配。 + +**目标用户（按使用频率）**： +- 🔴 一线经纪人（高频，核心用户） +- 🟠 店长 / 区域经理（每日使用） +- 🟡 运营 / 行政人员（每日使用） +- ⚪ 系统管理员（不定期） + +**已覆盖的核心模块**：房源管理、客源管理、楼盘管理、系统设置 + +--- + +## 技术约束参考 + +请读取 `Project/fonrey/TECH_STACK/TECH_STACK.md` 了解技术约束。 +PRD 中涉及交互模式时须遵守以下原则，**不得建议替代方案**： + +| 约束项 | 要求 | +|--------|------| +| 前端交互 | HTMX 局部刷新 + Alpine.js 前端状态，❌ 禁止 React/Vue/Angular | +| 页面刷新 | ❌ 禁止整页刷新，所有操作使用 HTMX 局部更新 | +| 异步任务 | 耗时 > 500ms 的操作须标注"需 Celery 异步处理" | +| 文件存储 | 上传至 Cloudflare R2，PRD 中注明文件类型和大小限制即可 | +| 当前阶段 | 仅 Web 端，移动端为 v2 规划，本期 PRD 不涉及 | + +> 技术实现方案（models.py、urls.py、视图函数）由工程师参考配套 TECH 文档设计，PRD 不输出代码。 + +--- + +## 方法论参考 + +请读取 `Project/fonrey/prompt/product-manager.md` 并运用其中的专业知识与 PRD 格式规范。 + +核心原则（生成文档时必须体现）： +1. **先问题后方案**：每个功能点必须说明"解决了谁的什么痛点" +2. **Non-Goals 必填**：明确本次不做什么，防止需求蔓延 +3. **验收标准可测试**：每条 AC 格式为 `Given / When / Then`，含正常流与异常流 +4. **优先级标注**：P0（MVP 必须）/ P1（重要但可延迟）/ P2（优化迭代） +5. **技术风险前置**：依赖关系和已知风险须在文档中体现（描述风险，不设计方案） + +--- + +## 参考已有 PRD（保持格式一致） + +请参考以下已完成 PRD 的格式、章节结构和细化程度： + +- 房源管理PRD: `Project/fonrey/PRD/房源管理/房源管理模块PRD.md` +- 楼盘管理PRD: `Project/fonrey/PRD/房源管理/楼盘管理模块PRD.md` +- 客源管理PRD: `Project/fonrey/PRD/客源管理/客源管理模块PRD.md` +- 权限管理PRD: `Project/fonrey/PRD/权限管理/权限管理模块PRD.md` + - 权限管理样本数据：`Project/fonrey/PRD/权限管理/首页.md` + - 权限管理样本数据：`Project/fonrey/PRD/权限管理/房源-二手租赁.md` + - 权限管理样本数据：`Project/fonrey/PRD/权限管理/客源.md` + - 权限管理样本数据：`Project/fonrey/PRD/权限管理/小区.md` +- 组织人事管理PRD: `Project/fonrey/PRD/组织人事管理/组织人事管理模块PRD.md` +- 系统管理PRD: `Project/fonrey/PRD/系统管理/系统管理模块PRD` +- 登录管理PRD: `Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md` +- 发布管理PRD: `Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md` + + +--- + +## 本次需求 + +### 🎯 我要设计的功能 / 模块 + +**【描述本次设计内容，例如： +"楼盘管理模块中的【楼盘详情页】，包含：楼盘基础信息展示与编辑、楼栋管理（列表/新增/编辑）、户型结构管理、楼盘照片管理、区域/商圈关联"】** + +### 📎 补充材料 + +【说明附上了哪些参考材料，例如： +- 已附上截图：竞品 A 的楼盘详情页（3 张） +- 已附上草图：手绘交互流程图 +- 无截图，请根据文字描述生成】 + +### 🗂️ 功能范围与优先级 + +【列出本次优先级范围，例如： +**P0（本期必须上线）**： +- 楼盘基础信息展示与编辑（名称、地址、建成年份、容积率等） +- 楼栋列表（分页、新增、编辑、删除） + +**P1（本期随 P0 一起上线，允许适当简化）**： +- 户型结构管理（按楼栋挂载） +- 楼盘照片上传（支持排序，格式和大小见业务规则） + +**P2（后续迭代，本次文档描述边界，不做细化）**： +- 价格走势图表 +- 周边配套（地铁/学校/商场） +- 楼盘数据统计面板】 + +### 💡 已知的业务规则 / 约束 + +【填写已确认的业务规则，例如： +- 楼盘是房源的基础数据底座，删除楼盘前需检查是否有挂载的在售房源 +- 一个楼盘可有多个楼栋，一个楼栋可有多个户型 +- 楼盘照片最多 20 张，单张限 10MB，格式限 JPG / PNG / WEBP +- 区域/商圈关联关系从 region app 读取，本模块不维护区域数据 +- 楼盘数据属于租户隔离数据（complex app），需遵守多租户规范】 + +--- + +## 输出要求 + +请按以下结构输出完整 PRD，保存至： +`Project/fonrey/PRD/【模块名称】/【功能名称】PRD.md` + +输出语言：**中文**（技术术语、字段名可保留英文） + +--- + +# PRD：【功能名称】 + +**状态**：Draft +**作者**：Billy（PM） +**最后更新**：【当前日期】 +**版本**：v0.1 +**关联 Django App**：【如 complex / property / client】 +**关联干系人**：工程负责人 / 设计负责人 / 运营负责人 + +--- + +## 1. 问题陈述（Problem Statement） + +- 目标用户是谁，他们面临什么具体痛点 +- 当前无此功能时用户如何绕过（Workaround） +- 不解决此问题的业务成本 + +--- + +## 2. 目标与成功指标（Goals & Success Metrics） + +| 目标 | 衡量指标 | 当前基线 | 目标值 | 测量窗口 | +|------|---------|---------|--------|---------| +| | | | | | + +--- + +## 3. 非目标（Non-Goals） + +- 本次明确不做的内容（含原因） +- 延后到 v2 的功能（含触发条件） + +--- + +## 4. 用户故事与验收标准（User Stories & Acceptance Criteria） + +> 按角色分组，每条用户故事附带可测试的 AC。 + +### 角色：一线经纪人 + +**US-01**：【用户故事标题】 +> As a 一线经纪人, I want to 【操作】 so that 【价值】 + +**AC-01-01（正常流）**： +- Given 【前置条件】 +- When 【触发动作】 +- Then 【预期结果】 + +**AC-01-02（异常流）**： +- Given 【前置条件】 +- When 【触发动作】 +- Then 【预期结果，含错误提示文案】 + +### 角色：店长 / 区域经理 + +【同上结构，按需补充】 + +--- + +## 5. 功能详细设计（Feature Specification） + +### 5.1 信息架构 / 页面结构 + +- 描述页面层级、导航路径、关键区块布局 +- 说明各功能区块的排布逻辑（不含视觉稿，纯文字描述） + +### 5.2 核心交互流程 + +> 说明关键操作的完整步骤，注明前端交互模式。 + +**流程示例：新增楼栋** +1. 用户点击「新增楼栋」按钮 +2. （HTMX）局部加载新增表单至侧边抽屉，不刷新整页 +3. 用户填写楼栋信息并提交 +4. （HTMX）提交后局部刷新楼栋列表区域，显示 Toast 成功提示 +5. 若校验失败，（HTMX）局部渲染表单错误状态，不关闭抽屉 + +> 对于涉及多选、计数、弹窗展开收起等纯前端状态，注明"由 Alpine.js 维护"即可，不写具体代码。 + +### 5.3 字段规范 + +| 字段名 | 展示名称 | 类型 | 是否必填 | 校验规则 | 说明 | +|--------|---------|------|---------|---------|------| +| | | | | | | + +### 5.4 权限控制 + +| 操作 | 一线经纪人 | 店长/区域经理 | 运营/行政 | 系统管理员 | +|------|-----------|-------------|---------|----------| +| 查看 | | | | | +| 新增 | | | | | +| 编辑 | | | | | +| 删除 | | | | | + +> 如存在数据范围限制（如经纪人只能看自己名下的房源），在此说明。 + +### 5.5 性能要求 + +> 以需求方式陈述，不设计技术方案。 + +- 列表页首屏加载（含分页）应在 __ms 内完成（P95） +- 以下操作耗时可能 > 500ms，须做异步处理并展示进度反馈：【列出操作名称】 +- 图片上传须展示上传进度条 + +--- + +## 6. 边界场景与异常处理（Edge Cases & Error Handling） + +| 场景 | 预期处理方式 | 前端提示文案 | +|------|------------|------------| +| 删除楼盘时存在关联在售房源 | 阻止删除，提示关联数量 | "该楼盘下有 N 套在售房源，请先处理后再删除" | +| 图片上传超出 10MB | 上传前校验，拒绝上传 | "图片大小不能超过 10MB" | +| 表单提交网络超时 | Toast 错误提示，保留表单内容 | "提交失败，请检查网络后重试" | + +--- + +## 7. 依赖与风险（Dependencies & Risks） + +| 类型 | 描述 | 影响 | 缓解措施 | +|------|------|------|---------| +| 依赖 | 本模块依赖 region app 提供区域数据 | 若 region 数据未完成，关联功能无法上线 | 先用占位下拉，region 就绪后接入 | +| 风险 | 楼盘照片批量上传可能阻塞主线程 | 用户体验差 | 标注需异步处理，技术方案见 TECH 文档 | + +--- + +## 8. 上线计划（Launch Plan） + +| 阶段 | 时间 | 受众 | 通过标准 | +|------|------|------|---------| +| 内测 | | 内部团队 | | +| 灰度 | | 指定经纪公司 | | +| 全量 | | 所有租户 | | + +--- + +## 9. 待确认问题（Open Questions） + +- [ ] 问题描述 — 负责人 — 截止时间 + +--- + +## 10. 附录（Appendix） + +- 相关截图 / 草图 +- 竞品参考 +- 关联文档：`Project/fonrey/TECH_STACK/TECH_STACK.md`、`Project/fonrey/DATA_MODEL/DATA_MODEL.md` + + +--- + +## 补充说明 + +- 如果提供了产品截图，请先分析截图中的功能模块、交互模式、数据字段，再结合文字描述生成 PRD +- 如发现需求描述存在逻辑矛盾或遗漏关键场景，请在输出 PRD 前先提出问题，不要自行填充假设 +- PRD **不输出** models.py、urls.py 代码草稿——这些内容由工程师基于 PRD + TECH 文档实现 + + +--- + +## 📌 使用说明 + +| 步骤 | 操作 | +|------|------| +| **1** | 复制上方代码块中的完整提示词 | +| **2** | 填写所有 `【...】` 占位符 | +| **3** | 如有截图 / 草图，直接附在消息中 | +| **4** | 确认 TECH_STACK.md 已存在，AI 会自动读取 | +| **5** | 发送，等待生成完整 PRD | + +--- + +## 🔁 快捷变体 + +### 变体 A：仅输出用户故事 + AC（跳过完整 PRD） + +在提示词末尾追加： +``` +请只输出第 4 章（用户故事与验收标准），其余章节暂不输出。 +``` + +### 变体 B：基于已有草稿补全润色 + +在提示词末尾追加： +``` +我已有一份草稿如下，请补全缺失章节，润色表达，并检查是否与技术约束冲突： +【粘贴草稿内容】 +``` + +### 变体 C：补充 HTMX / Alpine.js 交互规范描述 + +在提示词末尾追加： +``` +请在 5.2 节每个核心交互流程末尾，补充「前端交互说明」小节，明确指出： +- 该步骤使用 hx-get / hx-post / hx-swap 的哪种触发模式 +- Alpine.js 需要维护哪些 x-data 状态（仅描述状态名称和含义，不写代码） +- 是否需要触发 Toast 通知，通知文案是什么 diff --git a/Project/fonrey/prompt/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md b/Project/fonrey/prompt/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md new file mode 100644 index 00000000..416de475 --- /dev/null +++ b/Project/fonrey/prompt/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md @@ -0,0 +1,358 @@ +# Fonrey TECH_STACK & DATA_MODEL 设计文档生成提示词模板 + +> 本模板专注于**技术实现设计**：怎么建、数据怎么存、接口怎么定义、系统怎么部署。 +> 产品功能定义（用户故事、验收标准、页面结构）由配套的 **PRD 模板**负责，两份文档互不重复。 + +--- + +## ✅ 使用前检查清单 + +- [ ] 已完成本模块的 PRD，路径已确认 +- [ ] TECH_STACK.md 草案已存在（若无，任务一将从零创建） +- [ ] DATA_MODEL.md 草案已存在（若无，任务二将从零创建） +- [ ] 已明确本次设计涉及哪些 Django App + +--- + +## 📋 完整提示词（复制后填写 `【...】` 再发送） + + +## 角色与背景 + +你是一名资深系统架构师，具备 Django 全栈开发、PostgreSQL 数据库设计、云基础设施和 API 设计的专业能力。 +你的核心方法是：基于产品需求推导技术方案，每个设计决策都附带选型理由，确保方案在当前技术栈约束内可落地。 + +**工作目录**：`~/Workspace/nexus` + +**你的职责边界**： +- ✅ 负责：数据库模型（DDL）、API 端点设计、系统架构、安全方案、部署规范、目录结构 +- ❌ 不负责：用户故事、验收标准、页面交互描述——这些见配套 PRD 文档 + +--- + +## 项目背景 + +**项目**：**Fonrey（房睿）**——面向房地产经纪公司的 B2B SaaS 平台 +**多租户模式**：django-tenants（PostgreSQL Schema 隔离），所有查询必须基于当前租户 Schema +**数据量级**：89,000+ 条房源/客源记录，需要关注查询性能 + +请读取以下文档作为设计输入： +- 架构师方法论：`Project/fonrey/prompt/engineering-backend-architect.md` +- 现有技术栈草案：`Project/fonrey/TECH_STACK/TECH_STACK.md` +- 现有数据模型草案：`Project/fonrey/DATA_MODEL/DATA_MODEL.md` + +--- + +## 需求输入（本次设计的 PRD 依据） + +请读取以下 PRD 文档，从中提取：功能边界、字段规范、权限要求、性能指标，作为本次技术设计的需求基准。 + +【填写本次相关 PRD 路径，例如： +- `Project/fonrey/PRD/房源管理/房源录入模块PRD.md` +- `Project/fonrey/PRD/楼盘管理/楼盘详情页PRD.md`】 + +--- + +## 技术栈约束（不得变更，不得建议替代方案） + +| 层级 | 技术选型 | 关键约束 | +|------|---------|---------| +| 前端 | HTMX + Alpine.js + Tailwind CSS | ❌ 禁止 React / Vue / Angular | +| 后端 | Django 4.x（ASGI）| 使用 Class-Based Views，遵循 Django 约定 | +| 数据库 | PostgreSQL | 多租户 Schema 隔离（django-tenants） | +| 缓存 | Redis | 会话、计数器、热点数据缓存 | +| 异步 | Celery + Redis Broker | 耗时 > 500ms 的任务必须走 Celery | +| 文件存储 | Cloudflare R2 | 图片 / 文件上传，不得存本地磁盘 | +| 当前阶段 | Web 端 | 移动端为 v2，当前不设计 App API | + +详细约束见：`Project/fonrey/TECH_STACK/TECH_STACK.md` + +--- + +## 任务一：DATA_MODEL 详细设计 + +**输出路径**：`Project/fonrey/DATA_MODEL/DATA_MODEL.md` +（在现有草案基础上补全 / 新增本次模块内容，不覆盖已有章节） + +### 1.1 实体关系设计（ERD） + +针对本次 PRD 涉及的模块，输出： + +- 新增或变更的**实体清单**，每个实体包含： + - 字段名、数据类型（PostgreSQL 类型）、约束（NOT NULL / UNIQUE / CHECK）、默认值 + - 必须包含：`id`（UUID 主键）、`created_at`、`updated_at`、`deleted_at`（软删除） + - 多租户字段：确认是否在当前租户 Schema 下，无需额外 `tenant_id` 字段 + +- **标准 SQL DDL 建表语句**（含注释） + +- **Mermaid ERD 图**，说明实体间关联关系（一对多 / 多对多）及外键方向 + +```mermaid +erDiagram + 【实体名】 { + uuid id PK + 【字段名】 【类型】 + } + 【实体A】 ||--o{ 【实体B】 : "关联说明" +``` + +### 1.2 索引策略 + +针对以下场景设计索引，说明每条索引的使用场景和预期效果： + +- **高频筛选查询**（如按区域 / 价格 / 户型筛选）：设计复合索引 +- **文本搜索字段**（如名称、地址、备注）：使用 GIN 全文索引 +- **外键字段**：确认是否需要显式索引（Django 默认对 FK 创建索引） +- **分页查询**：确认主键排序性能 + +目标：核心列表查询 P95 响应时间 ≤ 20ms + +```sql +-- 示例 +CREATE INDEX idx_property_region_price ON property_property(region_id, price) WHERE deleted_at IS NULL; +CREATE INDEX idx_property_title_fts ON property_property USING GIN(to_tsvector('chinese', title)); +``` + +### 1.3 外键约束与级联策略 + +| 外键关系 | 级联策略 | 选型理由 | +|---------|---------|---------| +| 房源 → 楼盘 | RESTRICT | 删除楼盘前必须先处理房源 | +| 跟进记录 → 客源 | CASCADE | 客源删除时跟进记录一并清除 | + +### 1.4 敏感数据处理 + +| 字段 | 敏感级别 | 存储方案 | +|------|---------|---------| +| 客户手机号 | 高 | AES-256 加密存储，展示时脱敏 | +| 合同金额 | 中 | 明文存储，接口层做权限控制 | + +### 1.5 扩展性说明 + +- 高增长实体（如跟进日志、带看记录）是否需要 PostgreSQL Table Partitioning，说明分区键和策略 +- Schema 变更兼容性：新增字段须有默认值，避免锁表；涉及大表变更提供 Zero-downtime Migration 方案 + +--- + +## 任务二：TECH_STACK 技术文档补全 + +**输出路径**：`Project/fonrey/TECH_STACK/TECH_STACK.md` +（在现有草案基础上补全 / 新增本次模块相关章节，不覆盖已有内容） + +### 2.1 Django App 目录结构 + +针对本次 PRD 涉及的 App，输出标准目录结构： + +``` +apps/【app_name】/ +├── models.py # 数据模型（对应 DATA_MODEL.md） +├── views.py # 视图（HTMX 局部刷新端点 + 页面视图） +├── urls.py # 路由 +├── forms.py # Django Form / ModelForm +├── serializers.py # 仅 JSON API 场景使用 +├── tasks.py # Celery 异步任务 +├── signals.py # Django Signals（如有） +├── admin.py # Django Admin 注册 +├── tests/ +│ ├── test_models.py +│ ├── test_views.py +│ └── test_tasks.py +└── templates/【app_name】/ + ├── 【feature】_list.html # 完整页面 + ├── 【feature】_detail.html + ├── partials/ + │ ├── 【feature】_row.html # HTMX 局部模板 + │ ├── 【feature】_form.html + │ └── 【feature】_pagination.html + └── components/ + └── 【reusable_component】.html +``` + +### 2.2 API 端点设计 + +> 基于 PRD 第 4 章（用户故事）和第 5 章（交互流程）推导所需端点。 + +| URL Pattern | HTTP 方法 | 视图名称 | 触发场景 | 响应类型 | 权限要求 | +|------------|----------|---------|---------|---------|---------| +| `/complex//` | GET | `ComplexDetailView` | 进入楼盘详情页 | HTML（完整页面） | 已登录 | +| `/complex//buildings/` | GET | `BuildingListPartialView` | HTMX 刷新楼栋列表 | HTML Partial | 已登录 | +| `/complex//buildings/add/` | POST | `BuildingCreateView` | 提交新增楼栋表单 | HTML Partial / JSON | 店长及以上 | +| `/complex/photos/upload/` | POST | `ComplexPhotoUploadView` | 上传图片至 R2 | JSON | 已登录 | + +**HTMX 响应规范**： +- 成功操作 → 返回更新后的 HTML Partial + `HX-Trigger: showToast` 响应头 +- 表单校验失败 → 返回含错误信息的表单 Partial，HTTP 422 +- 权限不足 → 返回 HTTP 403，前端 HTMX 触发全局错误 Toast + +**Celery 异步任务端点**： +- 异步任务提交后立即返回 `{"task_id": "xxx", "status": "pending"}` +- 前端通过轮询或 SSE 获取任务状态 + +### 2.3 权限与认证实现 + +> 基于 PRD 第 5.4 节（权限控制表）实现。 + +- **角色体系**：超级管理员 / 经纪公司管理员（店长） / 经纪人 / 运营行政 +- **数据范围控制**：经纪人默认只查询自己名下数据，使用 Django Manager 层面过滤 +- **视图层权限装饰器**：统一使用 `@permission_required` 或自定义 Mixin + +```python +# 权限 Mixin 示例（不需要完整代码，给出接口约定） +class BranchManagerRequiredMixin(LoginRequiredMixin): + """要求店长及以上角色""" + ... +``` + +### 2.4 缓存策略 + +| 缓存对象 | Key 格式 | TTL | 失效条件 | +|---------|---------|-----|---------| +| 楼盘基础信息 | `complex:{tenant}:{id}` | 10min | 编辑后主动清除 | +| 区域下拉选项 | `region:{tenant}:list` | 60min | 区域数据变更 | +| 经纪人列表 | `agent:{tenant}:list` | 5min | 人员变动 | + +### 2.5 文件上传规范（Cloudflare R2） + +- **上传流程**：前端直传 R2（Presigned URL）或后端中转，说明选型理由 +- **文件命名**：`{tenant}/{app}/{model_id}/{uuid}.{ext}` +- **类型校验**：后端二次校验 MIME Type，不信任前端传入的文件类型 +- **大小限制**：在 Django 视图层和 Nginx 层双重限制 + +### 2.6 Celery 异步任务规范 + +> 列出本次模块中需要异步处理的任务。 + +| 任务名称 | 触发场景 | 预估耗时 | 重试策略 | 失败处理 | +|---------|---------|---------|---------|---------| +| `process_complex_photo` | 图片上传后压缩/生成缩略图 | ~2s | 最多 3 次，指数退避 | 记录错误日志，通知用户 | +| `export_complex_list` | 导出楼盘列表 Excel | ~5-30s | 最多 2 次 | 标记任务失败，提示重试 | + +### 2.7 测试规范 + +每个 App 须包含以下测试覆盖： + +- **Model 测试**：字段约束、软删除、多租户隔离 +- **View 测试**：正常响应、权限拒绝（403）、表单校验失败（422） +- **HTMX 端点测试**：验证响应为 HTML Partial 而非完整页面 +- **Celery 任务测试**：使用 `CELERY_TASK_ALWAYS_EAGER=True` 同步测试 + +--- + +## 任务三（可选）：系统架构文档补全 + +> 仅在首次建立 TECH_STACK.md 或进行重大架构调整时执行。日常模块迭代跳过本任务。 + +**输出路径**：`Project/fonrey/TECH_STACK/TECH_STACK.md`（架构总览章节） + +### 3.1 技术选型决策记录（ADR） + +对每项关键技术选型输出决策记录： + +```markdown +### ADR-001：选择 HTMX 而非 React/Vue + +**决策**：使用 HTMX + Alpine.js 替代 SPA 框架 +**理由**：Django 模板生态成熟、团队学习成本低、SEO 友好、无需维护前后端分离部署 +**放弃方案**： +- React：需要独立前端工程，增加部署复杂度；JSON API 设计成本高 +- Vue：同上，且与 Django 模板混用存在状态管理冲突 +**风险**：复杂交互（如拖拽排序）需要 Alpine.js 补充，有一定上手成本 +``` + +### 3.2 系统分层架构图 + +```mermaid +graph TD + A[用户浏览器] -->|HTTPS| B[Nginx 反向代理] + B --> C[Django ASGI / Daphne] + C --> D[Django Views + HTMX 响应] + D --> E[PostgreSQL\n多租户 Schema] + D --> F[Redis\n缓存 + Session] + D --> G[Celery Worker] + G --> H[Cloudflare R2\n文件存储] + G --> E +``` + +### 3.3 可观测性规范 + +| 类型 | 工具 | 关键指标 | +|------|------|---------| +| 应用监控 | Sentry | 异常捕获、性能追踪 | +| 基础设施 | Prometheus + Grafana | CPU / 内存 / DB 连接池 | +| 日志 | 结构化 JSON 日志 | 请求日志、Celery 任务日志 | +| 告警 | PagerDuty / Slack | API 错误率 > 1%，DB P99 > 100ms | + +### 3.4 CI/CD 流水线 + +``` +代码推送 + → 代码风格检查（ruff + black） + → 单元测试（pytest） + → 集成测试（TestContainers + PostgreSQL） + → 安全扫描（bandit） + → 构建 Docker 镜像 + → 灰度发布（Staging 验证） + → 全量发布（Rolling Update） +``` + +--- + +## 输出格式要求 + +- 所有文档使用 **Markdown 格式**，包含清晰章节层级 +- 代码块使用对应语言语法高亮（`sql`、`python`、`yaml`、`mermaid`） +- 架构图使用 **Mermaid** 语法内嵌，无需外部工具 +- 每个设计决策附带「**设计理由**」（1-2 句），便于团队 Review + +输出语言：**中文**（字段名、代码、技术术语保留英文） + +--- + +## 补充说明 + +- 本次设计**必须以 PRD 为需求基准**，不得新增 PRD 未定义的功能 +- 如发现 PRD 中存在技术上不可行的需求，先明确列出问题，再提供替代方案建议 +- DATA_MODEL 和 TECH_STACK 文档均采用**增量更新**方式，不覆盖已有章节内容 +- models.py 字段定义须与 DATA_MODEL.md 中的 DDL 保持一致，如有差异以 models.py 为准 + + +--- + +## 📌 使用说明 + +| 步骤 | 操作 | +|------|------| +| **1** | 确认对应模块的 PRD 已完成 | +| **2** | 复制上方代码块中的完整提示词 | +| **3** | 填写 PRD 路径（需求输入部分） | +| **4** | 确认执行哪些任务（一 / 二 / 三），不需要的任务删除对应段落 | +| **5** | 发送，AI 将基于 PRD + 现有技术文档生成技术设计 | + +--- + +## 🔁 快捷变体 + +### 变体 A：仅更新 DATA_MODEL（新增或修改模型） + +删除任务二、任务三，在提示词末尾追加： +``` +请只输出任务一（DATA_MODEL），重点输出新增表的 DDL 和 Mermaid ERD 图， +与现有 DATA_MODEL.md 中已有内容保持连贯，不重复已有实体。 +``` + +### 变体 B：仅输出 API 端点设计表（给工程师作实现参考） + +删除任务一、任务三，在提示词末尾追加： +``` +请只输出任务二中的「2.2 API 端点设计」章节， +以 Markdown 表格形式输出所有端点，包含：URL、方法、视图名、响应类型、权限。 +``` + +### 变体 C：首次建立完整技术架构文档 + +保留任务一、二、三，在提示词末尾追加： +``` +这是项目首次建立技术文档，请从零生成完整的 TECH_STACK.md 和 DATA_MODEL.md， +包含系统所有已知模块（房源管理、客源管理、楼盘管理、系统设置）， +整体架构图须覆盖完整技术分层。 +``` diff --git a/Project/fonrey/prompt/Fonrey_UI_SYSTEM_提示词模板_v1.md b/Project/fonrey/prompt/Fonrey_UI_SYSTEM_提示词模板_v1.md new file mode 100644 index 00000000..be828eb3 --- /dev/null +++ b/Project/fonrey/prompt/Fonrey_UI_SYSTEM_提示词模板_v1.md @@ -0,0 +1,529 @@ +# Fonrey UI SYSTEM 设计文档生成提示词模板 + +> 本模板专注于**界面系统设计**：视觉规范、组件库、交互模式、页面模板。 +> 产品功能定义见 **PRD 模板**，技术实现见 **TECH_STACK 模板**，本模板不重复上述内容。 + +--- + +## ✅ 使用前检查清单 + +- [ ] 已完成至少一个核心模块的 PRD（了解功能范围） +- [ ] TECH_STACK.md 已存在（了解前端技术约束：HTMX + Alpine.js + Tailwind CSS） +- [ ] 已明确品牌主色 / 设计风格偏好（可留空由 AI 提案） +- [ ] 已准备竞品截图或参考风格图（可选，直接附在消息中） + +--- + +## 📋 完整提示词（复制后填写 `【...】` 再发送） + + +## 角色与背景 + +你是一名资深 UI/UX 架构师，拥有 B2B SaaS 产品的设计系统（Design System）搭建经验。 +你的核心方法论：系统先于页面，规范先于设计，复用先于新建。 +你输出的设计系统文档须做到：开发团队无需询问设计师即可实现一致的界面。 + +**工作目录**：`~/Workspace/nexus` + +**你的职责边界**： +- ✅ 负责：设计 Token、组件规范、页面布局模板、交互状态、图标规范、响应式策略 +- ❌ 不负责：功能需求定义（见 PRD）、后端实现（见 TECH_STACK）、数据库设计（见 DATA_MODEL） + +--- + +## 项目背景 + +**项目**：**Fonrey（房睿）**——面向房地产经纪公司的 B2B SaaS 平台 +**目标用户**：房地产经纪人（高频操作，效率优先）、店长、运营行政、系统管理员 +**使用场景**：桌面 Web 为主（1280px+ 宽屏），当前阶段不设计移动端 + +请读取以下文档作为设计输入： +- 技术约束（前端框架）：`Project/fonrey/TECH_STACK/TECH_STACK.md` +- 功能范围参考（了解有哪些模块和页面）： + +【填写相关 PRD 路径，例如： +- `Project/fonrey/PRD/房源管理/房源录入模块PRD.md` +- `Project/fonrey/PRD/楼盘管理/楼盘详情页PRD.md` +如暂无 PRD，删除本段，基于项目背景描述设计】 + +--- + +## 前端技术约束（设计须在此范围内落地） + +| 约束项 | 要求 | 对设计的影响 | +|--------|------|------------| +| CSS 框架 | Tailwind CSS（Utility-first） | 设计 Token 须映射为 Tailwind 配置值 | +| 交互框架 | HTMX（局部 DOM 刷新） | 须设计加载中、成功、失败等局部刷新状态 | +| 前端状态 | Alpine.js | 弹窗、多选、折叠等交互由 Alpine.js 驱动 | +| 组件形式 | Django HTML 模板（非 React 组件） | 组件以 HTML + Tailwind class 描述，不输出 JSX | +| 图标库 | 【填写：如 Heroicons / Lucide / Tabler Icons】 | 统一使用同一图标库 | +| 当前阶段 | 仅 Web 端（桌面优先） | 移动端适配为 v2，当前只需确保 1280px+ 体验 | + +--- + +## 设计风格偏好 + +【填写设计偏好，例如： +- 整体风格：专业、克制、高效，参考 Linear / Notion / Salesforce Lightning +- 主色调：蓝色系（#2563EB 附近）/ 由你提案 +- 圆角风格：中等圆角（8px） +- 密度：紧凑型（B2B 工具，数据密度高） +- 无截图，请根据 B2B SaaS 行业最佳实践提案 +如已附上竞品截图，注明"已附截图，请参考截图风格"】 + +--- + +## 本次设计范围 + +【填写本次需要覆盖的范围，例如： +**全量设计（首次建立 UI System）**： +- 设计 Token（颜色、字体、间距、阴影） +- 基础组件（按钮、输入框、下拉、表格、分页、弹窗、Toast） +- 业务组件（房源卡片、状态标签、筛选栏、操作菜单） +- 页面布局模板（侧边栏导航 + 内容区 + 详情抽屉） + +**增量设计（补充某个模块的组件）**： +- 新增组件：图片上传区域、楼栋/户型树形列表 +- 参考已有 UI_SYSTEM.md：`Project/fonrey/UI_SYSTEM/UI_SYSTEM.md` +如为增量，请读取现有文档后仅输出新增部分】 + +--- + +## 输出要求 + +请按以下结构输出完整 UI System 设计文档，保存至： +`Project/fonrey/UI_SYSTEM/UI_SYSTEM.md` + +输出语言：**中文**（组件名、CSS 类名、Token 名称保留英文） + +--- + + +# Fonrey UI System 设计规范 + +**版本**：v【x.x】 +**最后更新**：【当前日期】 +**维护者**：【UI/UX 负责人】 +**适用技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板 + +--- + +## 1. 设计原则（Design Principles） + +> 约 3-5 条，指导所有设计决策，须与 B2B 工具效率场景匹配。 + +- **效率优先**：减少视觉噪音，让用户聚焦在数据和操作上 +- 【补充其他原则】 + +--- + +## 2. 设计 Token（Design Tokens） + +### 2.1 颜色系统 + +> 所有颜色须映射为 Tailwind `tailwind.config.js` 的 `theme.extend.colors` 配置。 + +**品牌色（Primary）** + +| Token 名称 | Hex 值 | Tailwind 类 | 使用场景 | +|-----------|--------|------------|---------| +| `primary-600` | #2563EB | `bg-primary-600` | 主按钮、激活态 | +| `primary-100` | #DBEAFE | `bg-primary-100` | 选中背景、标签底色 | + +**语义色（Semantic）** + +| Token | Hex | 使用场景 | +|-------|-----|---------| +| `success` | #16A34A | 操作成功、状态标签 | +| `warning` | #D97706 | 待确认、临期提醒 | +| `danger` | #DC2626 | 删除、错误、逾期 | +| `neutral-*` | 灰阶系列 | 文字、边框、背景 | + +**背景层级** + +| 层级 | Token | 使用场景 | +|------|-------|---------| +| 页面背景 | `bg-neutral-50` | 整体页面底色 | +| 卡片/面板 | `bg-white` | 内容区块 | +| 悬浮层 | `bg-white + shadow-lg` | 弹窗、下拉菜单 | + +### 2.2 字体系统 + +| 层级 | 字号 | 字重 | 行高 | Tailwind 类 | 使用场景 | +|------|------|------|------|------------|---------| +| 页面标题 | 24px | 600 | 32px | `text-2xl font-semibold` | 页面 H1 | +| 区块标题 | 18px | 600 | 28px | `text-lg font-semibold` | 卡片/面板标题 | +| 正文 | 14px | 400 | 20px | `text-sm` | 表单标签、描述 | +| 辅助文字 | 12px | 400 | 16px | `text-xs text-neutral-500` | 提示、占位符 | +| 数据展示 | 14px | 500 | 20px | `text-sm font-medium` | 表格数据 | + +### 2.3 间距系统 + +> 遵循 4px 基础栅格，统一使用 Tailwind 间距 Token。 + +| 场景 | Token | 值 | +|------|-------|---| +| 组件内边距（小） | `p-2` / `p-3` | 8px / 12px | +| 组件内边距（标准） | `p-4` | 16px | +| 卡片内边距 | `p-6` | 24px | +| 区块间距 | `gap-6` / `mb-6` | 24px | +| 页面边距 | `px-8` | 32px | + +### 2.4 阴影与圆角 + +| Token | 值 | 使用场景 | +|-------|---|---------| +| `rounded-md` | 6px | 按钮、输入框 | +| `rounded-lg` | 8px | 卡片、面板 | +| `rounded-xl` | 12px | 弹窗、抽屉 | +| `shadow-sm` | 细微阴影 | 卡片悬停 | +| `shadow-lg` | 明显阴影 | 弹窗、下拉菜单 | + +--- + +## 3. 基础组件规范（Base Components） + +> 每个组件包含：视觉规范、状态变体、Tailwind 实现示意、使用场景与禁忌。 + +### 3.1 按钮（Button） + +**变体** + +| 变体 | 用途 | 主要 Tailwind 类 | +|------|------|----------------| +| Primary | 主操作（每个区域唯一） | `bg-primary-600 text-white hover:bg-primary-700` | +| Secondary | 次级操作 | `bg-white border border-neutral-300 text-neutral-700` | +| Danger | 删除、不可逆操作 | `bg-danger text-white` | +| Ghost | 工具栏、表格行操作 | `text-neutral-600 hover:bg-neutral-100` | +| Link | 内联跳转 | `text-primary-600 underline` | + +**尺寸** + +| 尺寸 | 场景 | Tailwind 类 | +|------|------|------------| +| sm | 表格操作、标签内 | `px-3 py-1.5 text-xs` | +| md（默认） | 表单提交、工具栏 | `px-4 py-2 text-sm` | +| lg | 页面主操作 | `px-6 py-2.5 text-sm` | + +**状态**：默认 / Hover / Focus（`ring-2 ring-primary-500`） / 加载中（禁用 + Spinner）/ 禁用（`opacity-50 cursor-not-allowed`） + +**禁忌**： +- ❌ 同一区域不得出现两个 Primary 按钮 +- ❌ Danger 按钮须二次确认，不得直接触发删除 + +--- + +### 3.2 输入框（Input） + +**状态**：默认 / Focus / 错误（红色边框 + 错误文案）/ 禁用 / 只读 + +```html + +
+ + +

+

+
+``` + +**变体**：单行文本 / 多行文本（Textarea）/ 数字输入 / 带前缀/后缀图标 / 带单位 + +--- + +### 3.3 下拉选择（Select / Dropdown） + +- **原生 Select**：简单单选场景，Tailwind 统一样式 +- **Alpine.js 自定义下拉**：需要搜索、多选、分组的场景 +- **HTMX 动态加载选项**：选项依赖其他字段时，使用 `hx-get` 动态拉取 + +**多选下拉**须展示已选数量 Badge，支持一键清除。 + +--- + +### 3.4 表格（Table） + +**结构规范** + +| 区域 | 说明 | +|------|------| +| 表头 | 固定，含排序箭头；`bg-neutral-50 text-xs font-medium text-neutral-500` | +| 数据行 | 斑马纹可选；Hover 行高亮 `hover:bg-neutral-50` | +| 操作列 | 固定在最右侧，使用 Ghost 按钮或图标按钮 | +| 空状态 | 居中展示空状态插图 + 引导文案 | +| 分页 | 表格底部，显示"共 N 条"+ 页码 + 每页条数 | + +**HTMX 局部刷新**：筛选、排序、翻页均触发 `hx-get` 只刷新表格区域，不刷新整页。 + +--- + +### 3.5 弹窗与抽屉（Modal & Drawer） + +| 类型 | 场景 | 宽度 | +|------|------|------| +| 确认弹窗 | 删除确认、不可逆操作 | 400px | +| 表单弹窗 | 新增/编辑（字段较少） | 560px | +| 详情抽屉 | 查看详情、新增/编辑（字段较多） | 640px（从右侧滑入） | +| 全屏弹窗 | 复杂配置（如权限矩阵） | 80vw | + +**Alpine.js 控制**：`x-data="{ open: false }"` 控制显示隐藏，ESC 键关闭，点击遮罩关闭（确认弹窗除外）。 + +--- + +### 3.6 Toast 通知 + +| 类型 | 触发场景 | 停留时长 | +|------|---------|---------| +| Success | 操作成功 | 3s 自动消失 | +| Error | 操作失败、网络错误 | 5s，含手动关闭 | +| Warning | 操作有副作用（如批量覆盖） | 5s，含手动关闭 | +| Info | 异步任务已提交 | 3s 自动消失 | + +**HTMX 触发**：后端响应头 `HX-Trigger: {"showToast": {"type": "success", "message": "保存成功"}}` 触发全局 Toast。 + +Toast 统一出现在页面右下角，支持同时展示多条，新消息堆叠在上方。 + +--- + +### 3.7 状态标签（Badge / Tag） + +> 用于房源状态、客源状态、任务状态等高频展示场景。 + +| 状态 | 颜色 | Tailwind 类 | +|------|------|------------| +| 在售 / 激活 | 绿色 | `bg-success/10 text-success` | +| 待确认 / 跟进中 | 黄色 | `bg-warning/10 text-warning` | +| 已成交 / 完成 | 蓝色 | `bg-primary-100 text-primary-700` | +| 已下架 / 停用 | 灰色 | `bg-neutral-100 text-neutral-500` | +| 紧急 / 逾期 | 红色 | `bg-danger/10 text-danger` | + +--- + +### 3.8 加载状态（Loading States） + +| 场景 | 实现方式 | +| ---------- | ---------------------------------------------- | +| HTMX 局部请求中 | 目标区域加载骨架屏（Skeleton），使用 `htmx:beforeRequest` 触发 | +| 按钮提交中 | 按钮禁用 + 内嵌 Spinner，文案改为"保存中…" | +| 页面首次加载 | 内容区骨架屏（Skeleton），避免布局抖动 | +| 异步任务进行中 | 顶部进度条（Slim progress bar）+ Toast 说明 | +| | | + +--- + +## 4. 业务组件规范（Business Components） + +> 针对 Fonrey 特有的业务场景设计，复用基础组件。 + +### 4.1 房源卡片（Property Card） + +- 展示字段：封面图、房源标题、面积/户型/楼层、挂牌价、状态标签、经纪人、更新时间 +- 操作：查看详情（卡片点击）、快捷操作菜单（⋯ 三点按钮） +- 尺寸：列表模式（横向宽卡）/ 网格模式（方形卡片） + +### 4.2 筛选栏（Filter Bar） + +- 常驻筛选项（横向排列）：区域、价格区间、户型、状态 +- 高级筛选（折叠，点击展开）：更多条件 +- 已选筛选条件以 Tag 形式展示，支持单个删除和一键清除 +- 筛选变化触发 `hx-get` 局部刷新列表区域 + +### 4.3 数据统计卡片（Stat Card） + +| 区域 | 内容 | +|------|------| +| 图标 | 业务含义图标（背景色块） | +| 数值 | 大号字体，突出展示 | +| 标签 | 指标名称 | +| 趋势 | 环比箭头 + 百分比（可选） | + +### 4.4 操作菜单（Action Menu） + +- 触发方式：三点图标按钮（`⋯`）或右键（不推荐） +- Alpine.js 控制显示隐藏，点击外部关闭 +- 危险操作（删除）排在最后，用红色文字区分，且用分割线隔开 + +--- + +## 5. 页面布局模板（Page Layout Templates） + +### 5.1 整体框架 + +``` +┌──────────────────────────────────────────────────────┐ +│ 顶部导航栏（Logo + 租户名 + 用户菜单）高度 56px │ +├────────────┬─────────────────────────────────────────┤ +│ 侧边导航 │ 主内容区 │ +│ 宽 240px │ ┌─────────────────────────────────┐ │ +│ │ │ 页面标题 + 面包屑 + 主操作按钮 │ │ +│ 折叠态 │ ├─────────────────────────────────┤ │ +│ 宽 64px │ │ 筛选栏 / 工具栏 │ │ +│ │ ├─────────────────────────────────┤ │ +│ │ │ 内容主体（列表 / 详情 / 表单） │ │ +│ │ └─────────────────────────────────┘ │ +└────────────┴─────────────────────────────────────────┘ +``` + +### 5.2 列表页模板 + +适用模块：房源列表、客源列表、楼盘列表 + +``` +页面标题 + 新增按钮 +└── 筛选栏（横向，支持高级筛选折叠） +└── 工具栏（批量操作 + 视图切换 + 导出） +└── 列表主体（表格或卡片网格，HTMX 局部刷新） +└── 分页栏 +``` + +### 5.3 详情页模板（含右侧抽屉） + +适用模块：房源详情、客源详情、楼盘详情 + +``` +面包屑导航 +└── 详情头部（标题 + 状态 + 主操作按钮组） +└── Tab 导航（基本信息 / 跟进记录 / 关联数据 / 操作日志） +└── Tab 内容（HTMX 懒加载，切换 Tab 局部刷新内容区） +└── 右侧抽屉（新增/编辑表单，从右侧滑入，不遮挡主内容） +``` + +### 5.4 设置页模板 + +适用模块：系统设置、权限管理 + +``` +左侧设置分类导航（二级菜单） +└── 右侧内容区（表单 / 列表，保存按钮固定在底部） +``` + +--- + +## 6. 交互状态规范（Interaction States） + +### 6.1 HTMX 请求生命周期 + +| 阶段 | 视觉反馈 | +|------|---------| +| 请求发出前（`htmx:beforeRequest`） | 目标区域叠加半透明遮罩 + 骨架屏 | +| 请求进行中 | 触发按钮禁用 + Spinner | +| 请求成功（`htmx:afterSettle`） | 移除遮罩，内容更新，触发 Toast（如有） | +| 请求失败（`htmx:responseError`） | 移除遮罩，触发 Error Toast，保留原内容 | + +### 6.2 表单校验反馈 + +- **前端实时校验**（Alpine.js）：blur 时触发，不阻止提交 +- **后端校验返回**（HTMX）：HTTP 422，返回含错误信息的表单 Partial，字段级红色提示 +- 错误提示位置：字段下方，不使用顶部错误摘要（避免用户滚动查找） + +### 6.3 空状态设计 + +每类空状态须提供：插图（SVG）+ 标题 + 描述 + 引导操作按钮 + +| 场景 | 标题示例 | 引导操作 | +|------|---------|---------| +| 列表无数据 | "暂无房源" | 「新增第一套房源」按钮 | +| 搜索无结果 | "未找到匹配结果" | 「清除筛选条件」链接 | +| 权限不足 | "暂无访问权限" | 联系管理员 | + +--- + +## 7. 图标规范（Icon Guidelines） + +- **图标库**：【填写选定库名，如 Heroicons 24px Outline / Solid】 +- **尺寸**：工具栏图标 20px / 行内图标 16px / 状态图标 14px +- **颜色**：继承父元素文字颜色（`currentColor`），不单独设置颜色 +- **语义一致性**：同一操作在全产品内使用同一图标（新增始终用 `+` / `PlusIcon`） + +**常用图标映射** + +| 操作 | 图标名称 | +|------|---------| +| 新增 | PlusIcon | +| 编辑 | PencilIcon | +| 删除 | TrashIcon | +| 搜索 | MagnifyingGlassIcon | +| 筛选 | FunnelIcon | +| 导出 | ArrowDownTrayIcon | +| 更多操作 | EllipsisHorizontalIcon | +| 关闭 | XMarkIcon | + +--- + +## 8. 可访问性基线（Accessibility Baseline） + +- 所有表单字段须关联 `