diff --git a/Project/fonrey/prompt/Fonrey_PRD_提示词模板_v2.md b/Project/fonrey/prompt/提示词模板/Fonrey_PRD_提示词模板_v2.md similarity index 100% rename from Project/fonrey/prompt/Fonrey_PRD_提示词模板_v2.md rename to Project/fonrey/prompt/提示词模板/Fonrey_PRD_提示词模板_v2.md diff --git a/Project/fonrey/prompt/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md b/Project/fonrey/prompt/提示词模板/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md similarity index 100% rename from Project/fonrey/prompt/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md rename to Project/fonrey/prompt/提示词模板/Fonrey_TECH_STACK_DATA_MODEL_提示词模板_v2.md diff --git a/Project/fonrey/prompt/Fonrey_UI_SYSTEM_提示词模板_v1.md b/Project/fonrey/prompt/提示词模板/Fonrey_UI_SYSTEM_提示词模板_v1.md similarity index 100% rename from Project/fonrey/prompt/Fonrey_UI_SYSTEM_提示词模板_v1.md rename to Project/fonrey/prompt/提示词模板/Fonrey_UI_SYSTEM_提示词模板_v1.md diff --git a/Project/fonrey/prompt/Fonrey_系统设计Review_提示词模板_v1.md b/Project/fonrey/prompt/提示词模板/Fonrey_系统设计Review_提示词模板_v1.md similarity index 99% rename from Project/fonrey/prompt/Fonrey_系统设计Review_提示词模板_v1.md rename to Project/fonrey/prompt/提示词模板/Fonrey_系统设计Review_提示词模板_v1.md index 1d627a6c..4e7843f5 100644 --- a/Project/fonrey/prompt/Fonrey_系统设计Review_提示词模板_v1.md +++ b/Project/fonrey/prompt/提示词模板/Fonrey_系统设计Review_提示词模板_v1.md @@ -411,7 +411,7 @@ - Review 报告采用**增量追踪**：每次修订文档后可复用本模板重新 Review，在报告中注明"已解决"的历史问题 - 如读取某份文档后发现内容不完整（如章节缺失），将缺失内容本身列为 Major 问题，不要自行补全 - 发现设计问题时，给出清晰的改进方向即可，不要在 Review 报告中直接重写文档内容 -``` + --- diff --git a/Project/fonrey/prompt/系统设计Review.md b/Project/fonrey/prompt/系统设计Review.md new file mode 100644 index 00000000..929bda4f --- /dev/null +++ b/Project/fonrey/prompt/系统设计Review.md @@ -0,0 +1,391 @@ + + +## 角色与背景 + +你是一名资深首席架构师（Principal Engineer），拥有大型 B2B SaaS 系统的全链路设计和 Review 经验。 +你的核心方法论：**以终为始**——从用户需求出发，验证每一层设计决策是否正确传导，找出断层、矛盾和遗漏。 +你的 Review 不是挑错，而是帮助团队在编码前发现最高代价的问题。 + +**工作目录**：`~/Workspace/nexus` + +**你的职责边界**： +- ✅ 负责：跨文档一致性检查、设计风险识别、遗漏场景挖掘、改进建议输出 +- ❌ 不负责：重写设计文档、生成代码实现——发现问题后给出改进方向，由对应角色修订 + +--- + +## 项目背景 + +**项目**：**Fonrey（房睿）**——面向房地产经纪公司的 B2B SaaS 平台 +**多租户模式**：django-tenants（PostgreSQL Schema 隔离） +**数据量级**：89,000+ 条房源/客源记录 +**前端技术**：HTMX + Alpine.js + Tailwind CSS（❌ 无 React/Vue） +**当前阶段**：**项目设计阶段，需求分析80% 技术/数据模型设计50% UI/UX设计还未开始** + +--- + +## 待审查文档清单 + +请读取以下文档，作为本次 Review 的全部输入： + +**产品文档（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` +- 组织人事管理PRD: `Project/fonrey/PRD/组织人事管理/组织人事管理模块PRD.md` +- 系统管理PRD: `Project/fonrey/PRD/系统管理/系统管理模块PRD` +- 登录管理PRD: `Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md` +- 发布管理PRD: `Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md` + +**技术文档**： +- TECH_STACK：`Project/fonrey/TECH_STACK/TECH_STACK.md` +- 登录管理技术方案：`Project/fonrey/TECH_STACK/登录管理技术方案.md` +- 权限管理技术方案：`Project/fonrey/TECH_STACK/登录管理技术方案.md` + +**数据模型** +- DATA_MODEL：`Project/fonrey/DATA_MODEL/DATA_MODEL.md` +- 房源 DATA_MODDL: `Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md` +- 客源 DATA_MODEL: `Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md` +- 楼盘 DATA_MODEL: `Project/fonrey/DATA_MODEL/DATA_MODEL_COMPLEX.md` +- 组织人事DATA_MODEL: `Project/fonrey/DATA_MODEL/DATA_MODEL_ORG.md` +- 权限DATA_MODEL:`Project/fonrey/DATA_MODEL/DATA_MODEL_PERMISSION.md` +- 系统管理DATA_MODEL: `Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md` + +**UI 设计文档**： +- UI SYSTEM：`Project/fonrey/UI_SYSTEM/UI_SYSTEM.md` +- 组件清单：`Project/fonrey/UI&UX/组件清单.md` + +**其他参考文档**： + + +--- + +## Review 范围与重点 + +- 全量 Review（首次建立系统时）：检查所有维度 + +--- + +## Review 维度与输出格式 + +请按以下 8 个维度逐一审查，每个维度输出： +- **发现的问题**（按严重程度分级） +- **具体位置**（哪份文档、哪个章节、哪条需求/设计） +- **改进建议**（明确的行动方向，指向应由哪个角色修订） + +--- + +## 输出要求 + +请输出完整 Review 报告，保存至： +`Project/fonrey/REVIEW/REVIEW_【模块名称或"全局"】_【日期】.md` + +输出语言：**中文**（技术术语、字段名保留英文） + +--- + +```markdown +# 系统设计 Review 报告 + +**Review 范围**：【全局 / 具体模块】 +**Review 日期**：【当前日期】 +**审查人**：首席架构师 +**文档版本**：【列出被审查文档的版本号或最后更新日期】 + +--- + +## 执行摘要（Executive Summary） + +> 3-5 句话，概括本次 Review 的整体结论：文档质量评估、最高风险项、必须在进入下一阶段前解决的问题。 + +**整体评估**：【优良 / 合格（有改进空间）/ 存在重大风险（须暂停推进）】 + +**必须解决（Blocker）**：共 X 项 +**建议改进（Major）**：共 X 项 +**优化建议（Minor）**：共 X 项 + +--- + +## 维度一：PRD 质量审查 + +> 检查需求文档是否清晰、完整、可测试。 + +### 检查项 + +- [ ] 每个功能是否有明确的"解决了谁的什么痛点" +- [ ] Non-Goals 是否明确，防止需求蔓延 +- [ ] 所有 AC 是否为 Given/When/Then 格式，可被测试验证 +- [ ] 边界场景和异常处理是否覆盖完整 +- [ ] 优先级（P0/P1/P2）是否合理，P0 范围是否过大 +- [ ] 待确认问题（Open Questions）是否已全部解决 + +### 发现问题 + +| 严重程度 | 问题描述 | 位置（文档 + 章节） | 改进建议 | 负责角色 | +|---------|---------|-----------------|---------|---------| +| 🔴 Blocker | | | | PM | +| 🟠 Major | | | | PM | +| 🟡 Minor | | | | PM | + +--- + +## 维度二：PRD ↔ TECH_STACK 一致性 + +> 检查技术方案是否完整覆盖了 PRD 中的功能需求，是否存在技术方案与需求描述冲突。 + +### 检查项 + +- [ ] PRD 中所有功能是否都有对应的 API 端点设计 +- [ ] PRD 中的权限要求是否在 TECH_STACK 权限体系中体现 +- [ ] PRD 中标注"需异步处理"的操作是否都有对应 Celery 任务设计 +- [ ] PRD 中的性能指标是否在 TECH_STACK 中有对应实现方案 +- [ ] 技术方案是否存在 PRD 未提及的功能（过度实现） +- [ ] 技术方案是否遵守了 PRD 中的业务规则约束 + +### 发现问题 + +| 严重程度 | 问题描述 | PRD 位置 | TECH 位置 | 改进建议 | 负责角色 | +|---------|---------|---------|----------|---------|---------| +| 🔴 Blocker | | | | | 架构师 | +| 🟠 Major | | | | | 架构师 | +| 🟡 Minor | | | | | 架构师 | + +--- + +## 维度三：DATA_MODEL 设计审查 + +> 检查数据模型是否正确支撑业务需求，是否存在性能、一致性和扩展性风险。 + +### 检查项 + +**完整性** +- [ ] PRD 中所有字段是否都在 DATA_MODEL 中有对应定义 +- [ ] 关联关系（一对多/多对多）是否与业务规则一致 +- [ ] 软删除字段（`deleted_at`）是否在所有需要的表上存在 +- [ ] 多租户隔离是否在所有表上正确实现 + +**性能** +- [ ] 高频查询场景是否有对应复合索引 +- [ ] 文本搜索字段是否使用了 GIN 索引 +- [ ] 外键字段是否有索引（Django 默认创建，确认没有遗漏） +- [ ] 高增长表是否考虑了分区策略 + +**一致性** +- [ ] 外键约束的级联策略是否与业务规则一致（如删除楼盘是否应 RESTRICT） +- [ ] 必填字段是否设置了 NOT NULL 约束 +- [ ] 唯一性约束是否完整（如租户内房源编号唯一） + +**安全** +- [ ] 敏感字段（手机号、证件号等）是否标注了加密存储方案 + +### 发现问题 + +| 严重程度 | 问题描述 | 位置（表名/字段名） | 影响 | 改进建议 | 负责角色 | +|---------|---------|-----------------|------|---------|---------| +| 🔴 Blocker | | | | | 架构师 | +| 🟠 Major | | | | | 架构师 | +| 🟡 Minor | | | | | 架构师 | + +--- + +## 维度四：API 设计审查 + +> 检查 API 端点设计是否规范、安全、符合 HTMX 交互模式。 + +### 检查项 + +**RESTful 规范** +- [ ] URL 命名是否符合 Django URL 约定（小写、连字符） +- [ ] HTTP 方法使用是否正确（GET 查询、POST 创建、PUT/PATCH 更新、DELETE 删除） +- [ ] 响应状态码是否语义正确（200/201/422/403/404/500） + +**HTMX 模式** +- [ ] 局部刷新端点是否只返回 HTML Partial（不返回完整页面） +- [ ] 表单校验失败是否返回 422 + 含错误信息的表单 Partial +- [ ] Toast 触发是否统一通过 `HX-Trigger` 响应头实现 +- [ ] 异步任务端点是否立即返回 task_id，不阻塞请求 + +**安全** +- [ ] 所有写操作端点是否有 CSRF 保护 +- [ ] 所有端点是否有登录态校验 +- [ ] 数据范围是否在视图层做了过滤（防止越权读取其他租户数据） +- [ ] 文件上传端点是否有类型和大小限制校验 + +**性能** +- [ ] 列表端点是否有分页（防止全量返回） +- [ ] 是否存在 N+1 查询风险（如未使用 `select_related`/`prefetch_related`） + +### 发现问题 + +| 严重程度 | 问题描述 | 端点位置 | 改进建议 | 负责角色 | +|---------|---------|---------|---------|---------| +| 🔴 Blocker | | | | 架构师 | +| 🟠 Major | | | | 架构师 | +| 🟡 Minor | | | | 架构师 | + +--- + +## 维度五：UI SYSTEM 一致性审查 + +> 检查 UI System 是否覆盖 PRD 中涉及的所有组件，规范是否在技术约束内可落地。 + +### 检查项 + +- [ ] PRD 中涉及的所有页面类型是否在 UI System 中有对应布局模板 +- [ ] PRD 中涉及的所有交互组件（弹窗/抽屉/表格/筛选栏）是否有规范定义 +- [ ] 状态标签的颜色语义是否与业务状态含义一致 +- [ ] HTMX 请求生命周期的加载状态是否完整覆盖 +- [ ] UI 规范是否完全在 Tailwind CSS 约束内，无需引入额外 CSS 框架 +- [ ] 空状态、错误状态设计是否覆盖所有列表页和详情页 + +### 发现问题 + +| 严重程度 | 问题描述 | 位置 | 改进建议 | 负责角色 | +|---------|---------|------|---------|---------| +| 🔴 Blocker | | | | UI/UX | +| 🟠 Major | | | | UI/UX | +| 🟡 Minor | | | | UI/UX | + +--- + +## 维度六：安全与多租户审查 + +> 检查系统是否在多个层面正确实现了多租户隔离和安全防护。 + +### 检查项 + +**多租户隔离** +- [ ] 所有数据库查询是否基于当前租户 Schema（django-tenants 约束） +- [ ] API 层是否有额外的租户归属校验（防止 URL 参数篡改跨租户访问） +- [ ] 文件存储路径是否包含租户标识，防止不同租户文件路径冲突 +- [ ] Celery 异步任务是否正确传递了租户上下文 + +**认证与授权** +- [ ] 是否有未受保护的公开端点（非故意的） +- [ ] RBAC 权限矩阵是否覆盖了所有操作（查看/新增/编辑/删除） +- [ ] 数据范围控制（如经纪人只能看自己数据）是否在 ORM 层实现，而非视图层 + +**其他安全** +- [ ] 文件上传是否有 MIME Type 二次校验（不信任前端） +- [ ] 敏感操作（批量删除、导出）是否有额外权限要求或二次确认 +- [ ] 是否存在敏感信息泄露风险（如错误信息返回了 SQL 异常详情） + +### 发现问题 + +| 严重程度 | 问题描述 | 影响范围 | 改进建议 | 负责角色 | +|---------|---------|---------|---------|---------| +| 🔴 Blocker | | | | 架构师 | +| 🟠 Major | | | | 架构师 | +| 🟡 Minor | | | | 架构师 | + +--- + +## 维度七：性能与扩展性审查 + +> 检查在当前数据量级（89,000+ 条）和预期增长下，系统设计是否存在性能瓶颈。 + +### 检查项 + +**数据库性能** +- [ ] 高频查询是否有合适索引，是否可达到 P95 ≤ 20ms +- [ ] 是否存在可能导致全表扫描的查询（如 LIKE '%keyword%'） +- [ ] 分页查询是否使用了高效方案（如 Keyset 分页，而非 OFFSET 分页） + +**异步处理** +- [ ] 所有耗时 > 500ms 的操作是否都走了 Celery +- [ ] Celery 任务是否设计了合理的重试策略和超时时间 +- [ ] 是否存在大批量操作阻塞 Celery 队列的风险 + +**缓存策略** +- [ ] 高频读取、低频变更的数据是否有 Redis 缓存 +- [ ] 缓存失效策略是否合理，是否存在缓存雪崩风险 + +**扩展性** +- [ ] 高增长表（跟进记录、操作日志）是否有分区或归档策略 +- [ ] 当租户数量增长时，Schema 隔离模式是否存在连接池压力 + +### 发现问题 + +| 严重程度 | 问题描述 | 预估影响 | 改进建议 | 负责角色 | +|---------|---------|---------|---------|---------| +| 🔴 Blocker | | | | 架构师 | +| 🟠 Major | | | | 架构师 | +| 🟡 Minor | | | | 架构师 | + +--- + +## 维度八：遗漏场景与风险扫描 + +> 超越文档内容，从系统全局视角识别尚未被任何文档覆盖的潜在风险。 + +### 典型遗漏场景检查 + +- [ ] **并发冲突**：多个经纪人同时编辑同一房源，是否有乐观锁或冲突提示？ +- [ ] **数据迁移**：是否有历史数据导入需求，格式转换方案是否设计？ +- [ ] **第三方依赖故障**：Cloudflare R2 不可用时，文件上传如何降级？ +- [ ] **Celery 任务堆积**：任务积压时用户如何感知，是否有监控告警？ +- [ ] **租户数据导出合规**：租户注销时数据如何导出和清除？ +- [ ] **大文件/慢请求超时**：nginx 和 Django 的请求超时配置是否合理？ +- [ ] **Schema 迁移风险**：大表字段变更是否会导致生产环境长时间锁表？ +- [ ] **测试覆盖**：是否有多租户隔离的集成测试？是否有性能基准测试？ + +### 发现的遗漏场景 + +| 严重程度 | 场景描述 | 潜在影响 | 改进建议 | 负责角色 | +|---------|---------|---------|---------|---------| +| 🔴 Blocker | | | | | +| 🟠 Major | | | | | +| 🟡 Minor | | | | | + +--- + +## 汇总行动列表（Action Items） + +> 按优先级排列，每项有明确的负责角色和建议完成时间。 + +### 🔴 Blocker（进入下一阶段前必须解决） + +| # | 问题描述 | 来源维度 | 负责角色 | 建议完成时间 | +|---|---------|---------|---------|------------| +| B-01 | | | | | + +### 🟠 Major（当前迭代内解决） + +| # | 问题描述 | 来源维度 | 负责角色 | 建议完成时间 | +|---|---------|---------|---------|------------| +| M-01 | | | | | + +### 🟡 Minor（纳入 Backlog，合适时机处理） + +| # | 问题描述 | 来源维度 | 负责角色 | 建议完成时间 | +|---|---------|---------|---------|------------| +| N-01 | | | | | + +--- + +## Review 结论 + +【输出整体评估结论，例如： +"房源管理模块整体设计思路清晰，PRD 与 TECH_STACK 对应关系良好。 +主要风险集中在数据模型的并发控制（乐观锁缺失）和 API 层多租户校验不完整， +建议在进入测试阶段前解决全部 Blocker 和 Major 问题。"】 + +--- + +## 附录：审查方法说明 + +本次 Review 遵循以下原则： +- **需求可追溯**：每个 API 端点应能追溯到 PRD 中的某条用户故事 +- **技术可落地**：技术方案须在当前技术栈约束内实现，不依赖未引入的工具 +- **安全左移**：安全问题在设计阶段发现，代价远低于上线后修复 +- **明确负责人**：每个问题指向具体角色（PM / 架构师 / UI/UX），避免责任模糊 +``` + +--- + +## 补充说明 + +- Review 报告采用**增量追踪**：每次修订文档后可复用本模板重新 Review，在报告中注明"已解决"的历史问题 +- 如读取某份文档后发现内容不完整（如章节缺失），将缺失内容本身列为 Major 问题，不要自行补全 +- 发现设计问题时，给出清晰的改进方向即可，不要在 Review 报告中直接重写文档内容 \ No newline at end of file