442 lines
30 KiB
Markdown
442 lines
30 KiB
Markdown
# Fonrey 全局系统设计 Review 报告
|
||
|
||
> **Review 类型**：全量 Review（PRD + DATA_MODEL + TECH_STACK + UI/UX 交叉验证）
|
||
> **Review 日期**：2026-04-25
|
||
> **Reviewer**：系统设计 Reviewer（AI 辅助）
|
||
> **当前阶段**：需求 80% / 数据模型 50% / UI 未开始
|
||
> **覆盖文档**：8 份 PRD、8 份 DATA_MODEL、3 份 TECH_STACK、2 份 UI/UX
|
||
> **问题分级**：🔴 Blocker（阻塞开发） / 🟠 Major（必须修复但不阻塞） / 🟡 Minor（建议优化）
|
||
|
||
---
|
||
|
||
## 〇、执行摘要（Executive Summary）
|
||
|
||
### 整体评价
|
||
|
||
Fonrey 文档体系**结构完整、深度足够**，DATA_MODEL 与 TECH_STACK 的颗粒度（手机号加密、稀疏权限存储、tsvector 全文检索、物化路径树、append-only 审计）已达"可直接进入编码阶段"的水平，远超一般 SaaS 项目设计文档。但作为**全局系统**，存在 **6 处文档间一致性裂缝**、**4 处多租户隔离的执行细节缺失**、**1 处性能落地空缺**，以及 UI 阶段尚未启动带来的 **5 处验收标准悬空**。
|
||
|
||
### 核心问题摘录（Top 8）
|
||
|
||
| # | 等级 | 问题 | 维度 |
|
||
|---|------|------|------|
|
||
| 1 | 🔴 | **权限 PRD v1.1 与 DATA_MODEL_PERMISSION 的数据范围档位不一致**（PRD 三档 vs 数据模型 5 档 SCOPE + 跨层级 DataScope 叠加） | PRD↔Data |
|
||
| 2 | 🔴 | **Keyset 分页未在任何正式设计文档落地**（仅 Review 提示词模板提及），89k 房源 + 200 万跟进日志使用 OFFSET 分页将在深翻页时崩溃 | TECH/Data |
|
||
| 3 | 🟠 | **R2 文件路径无租户隔离命名规范**，所有 `file_key` 字段说明均为"R2 存储路径"，未约束 `tenants/{schema_name}/...` 前缀 | TECH/合规 |
|
||
| 4 | 🟠 | **Celery 任务的 Schema 切换机制无统一规范**，`tenant_context()` 仅在 PERMISSION 文档某 signal 中出现一次，TECH_STACK.md 未规定异步任务的租户上下文传递契约 | TECH/多租户 |
|
||
| 5 | 🟠 | **PRD 性能目标（录入耗时 ≤ 30s、配房响应 < 3s）在 TECH_STACK 中无 SLI/SLO 落地**，缺索引清单与 N+1 查询治理策略 | PRD↔TECH |
|
||
| 6 | 🟠 | **UI 阶段尚未开始**，但 PRD 含 90+ 个"验收标准"涉及具体交互（侧边抽屉、Toast、面包屑、批量操作 Modal），目前组件清单仅覆盖核心列表/表单，缺 Drawer / Stepper / Permission Tree 等关键组件设计 | PRD↔UI |
|
||
| 7 | 🟠 | **租户注销→数据导出→清除**全链路在 PRD（系统管理 §) 与 DATA_MODEL_PUBLIC（export_tasks/backup_records）中存在职责边界模糊：导出包是否包含 R2 文件实体、清除时序与备份保留期的依赖关系 | PRD↔Data↔合规 |
|
||
| 8 | 🟠 | **房源并发编辑乐观锁 / 楼盘锁定（4 类锁）的 DDL/版本字段未见**，PRD 多处提到"楼盘锁定不可改商圈"但 `complexes` 表 DDL 未发现 `version` 或 `lock_type` 字段（待 DATA_MODEL_COMPLEX §三 详查） | PRD↔Data |
|
||
|
||
### 风险等级分布
|
||
|
||
- 🔴 Blocker: **2** 项
|
||
- 🟠 Major: **14** 项
|
||
- 🟡 Minor: **9** 项
|
||
|
||
---
|
||
|
||
## 一、PRD 一致性审查（PRD ↔ PRD）
|
||
|
||
### 1.1 数据范围/权限粒度——核心冲突
|
||
|
||
| 文档 | 表述 |
|
||
|------|------|
|
||
| `PRD/权限管理/权限管理模块PRD.md` v1.1 §3 非目标 | "数据范围控制以**本人 / 本部门 / 全公司**三档为主，本期不含行级权限" |
|
||
| `PRD/权限管理/权限管理模块PRD.md` v1.1 Story 3 §验收 | 范围型选项："**本人 / 本组 / 本门店 / 本区域 / 全公司**"——五档 |
|
||
| `DATA_MODEL_PERMISSION.md` §1.2 | SCOPE 五档 + `staff_data_scopes` 跨层级并集叠加（"本组 ∪ 门店B"） |
|
||
|
||
🔴 **Blocker P-01**：同一份 PRD 内 §3 与 Story 3 自相矛盾（三档 vs 五档），且 DATA_MODEL 实现的"跨层级 DataScope 叠加"已超出 PRD §3 非目标声明的范畴——**这本质上是行级/对象级权限的弱化形态**。
|
||
- **责任**：PM 必须先在 PRD v1.2 中：(a) 锁定档位数（推荐五档）；(b) 明确 `staff_data_scopes` 是否为本期范围（若是，§3 非目标第 1 条需改写）；(c) 给出"跨层级叠加"的业务用例与 UI 入口（当前 Story 1 操作列只有 "扩充范围"/"范围"，未说明能否选多个组织节点）。
|
||
|
||
### 1.2 模块边界
|
||
|
||
🟠 **Major P-02**：**"系统设置"职责分散**。`PRD/权限管理` §1 提到"关联模块：组织人事管理、房源管理、客源管理、**系统设置**"，但 PRD 列表中没有独立的"系统设置 PRD"，仅有 `PRD/系统配置/系统配置.md`（128 行）和 `PRD/系统管理/系统管理模块PRD.md`（594 行，平台运营视角）。`TECH_STACK.md` §1 又提到"本期聚焦首页设置与房源设置（字段标签、必填规则、自定义字段、标签管理）"——**租户级"系统设置"PRD 缺失**。
|
||
- **责任**：PM 补一份 `PRD/系统设置/租户级系统设置模块PRD.md`，覆盖 lookup_items / 字段标签 / 自定义字段 / 标签管理，否则数据模型中已存在的 `lookup_items`（客源活跃度阈值依赖）配置入口不明。
|
||
|
||
🟡 **Minor P-03**：登录 PRD v1.4 §5.5 已迁出数据模型，但**"业务规则"与"数据约束"的交叉**（如 5 次失败锁定 30min、密码历史保留 3 条）在 PRD/技术方案/DATA_MODEL_LOGIN 三处重复定义，未来变更存在三处同步风险。建议 PRD 改为"详见 DATA_MODEL_LOGIN.md §X"引用。
|
||
|
||
### 1.3 性能目标完整性
|
||
|
||
🟠 **Major P-04**：PRD 中性能目标分布零散且**不可观测**：
|
||
- 房源 PRD：录入耗时 ≤ 30s（验收无对应 SLI）
|
||
- 客源 PRD：智能配房响应 < 3s、跟进率 ≥ 60%
|
||
- 系统管理 PRD：RTO < 2h、灰度 ≤ 5%
|
||
- 登录 PRD：登录成功率指标缺失
|
||
- 发布 PRD：自动更新成功率 ≥ 98%
|
||
|
||
未见统一的"非功能性需求矩阵"，TECH_STACK 也未承接这些目标。
|
||
- **责任**：PM 在 `PRD/PRD_MVP.md` 中汇总 NFR 矩阵；架构师在 `TECH_STACK.md` 中映射为 SLI/SLO + 监控埋点。
|
||
|
||
### 1.4 状态机一致性
|
||
|
||
🟡 **Minor P-05**：房源 `properties.status` 8 态（出售/出租/租售/暂缓/他售/他租/成交/未挂牌）与 PRD 房源生命周期描述未做状态转换图（哪些状态可互转、转出条件），DATA_MODEL_PROPERTY §3 仅枚举值。建议补状态机图。
|
||
|
||
---
|
||
|
||
## 二、DATA_MODEL 完整性审查
|
||
|
||
### 2.1 表覆盖度
|
||
|
||
DATA_MODEL 已实施"按模块拆分"（v1.3 索引化），8 个子文档覆盖良好。已确认存在的关键设计：
|
||
- ✅ public schema 13 表（含 audit_logs 月度分区建议、唯一 current 版本约束）
|
||
- ✅ 房源 22 张表（含 `sensitive_view` 跟进不可删、`listing_histories` append-only）
|
||
- ✅ 客源（手机号加密+哈希索引、活跃度阈值由 `lookup_items` 配置）
|
||
- ✅ 楼盘（`complexes.search_vector` tsvector + GIN）
|
||
- ✅ 组织（物化路径 + `staff_transfer_logs` append-only）
|
||
- ✅ 权限 6 表（稀疏存储 + 优先级合并）
|
||
- ✅ 登录 4 表（90 天审计、3 条历史防重用）
|
||
|
||
### 2.2 跨文档一致性
|
||
|
||
🔴 **Blocker D-01**：**Keyset 分页缺位**。`prompt/Fonrey_系统设计Review_提示词模板_v1.md` Line 315 明确要求"分页查询是否使用了高效方案（如 Keyset 分页，而非 OFFSET 分页）"，但：
|
||
- `DATA_MODEL.md` §五 容量与分区规划仅给出表大小估算
|
||
- `DATA_MODEL_PROPERTY.md`、`DATA_MODEL_CLIENT.md` 的"查询模式参考"章节未见 Keyset 示例
|
||
- `TECH_STACK.md` 无任何分页规范
|
||
|
||
89,000 房源 + 200 万跟进日志使用 OFFSET 分页，第 100 页响应将达秒级。
|
||
- **责任**：架构师在 `TECH_STACK.md` 新增 §「分页规范」、在 `DATA_MODEL_PROPERTY.md` §6 查询模式参考补 Keyset SQL 模板（`WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT 21`）。
|
||
|
||
🟠 **Major D-02**：**乐观锁/写冲突字段缺失**。
|
||
- `properties` 主表 PRD 多处提到"维护完成度 ≥ 70% 才能上架"、多人协作场景，但 DATA_MODEL_PROPERTY.md `properties` 表 DDL 未见 `version` / `row_version` 字段。
|
||
- 楼盘 PRD §"楼盘锁定"提到 4 类锁（信息锁/坐标锁/楼栋锁/合并锁），DATA_MODEL_COMPLEX 是否实现待详查（grep 未在 §三 摘要中发现 `lock_*` 字段）。
|
||
- **责任**：架构师在 `properties`、`clients`、`complexes` 主表补 `version INTEGER DEFAULT 0`，配合 Django ORM `update(version=F('version')+1).filter(version=expected)` 模式。
|
||
|
||
🟠 **Major D-03**：**外键跨 schema 限制的隔离机制说明不足**。`DATA_MODEL_PERMISSION.md` §3.1 已明确 `permission_defs` 放租户 schema 是为了规避 django-tenants 跨 schema FK，但其他类似场景（如 `staff` 引用 `org_units`、`user_accounts.staff_id`）未统一说明。建议在 `DATA_MODEL.md` §一架构决策中补 "**所有 FK 必须在同一 schema 内**" 原则。
|
||
|
||
🟠 **Major D-04**：**审计/日志表的分区策略不一致**。
|
||
- `platform_audit_logs`：建议月度分区 ✅
|
||
- `permission_change_logs`：月度分区 + 6 个月归档 ✅
|
||
- `follow_logs`（200 万+）：DATA_MODEL.md §五已建议月度分区，但 DATA_MODEL_PROPERTY §4.5 表 DDL **未给出分区 DDL 或 PARTITION BY 子句**——开发期不分区，未来再分区将带来数据迁移成本。
|
||
- `login_attempts`（90 天保留）：DATA_MODEL_LOGIN 未给分区或 TTL 清理策略。
|
||
- **责任**：架构师在每张高写入表的 DDL 中给出 `CREATE TABLE ... PARTITION BY RANGE (created_at)` + `pg_partman` 自动维护方案。
|
||
|
||
🟡 **Minor D-05**：`UserAccount.username` 在 `user_accounts` 表的唯一性约束注释提到"在租户 Schema 维度生效"，但若员工跨租户（多平台账号 `StaffAccount` 已支持 Fonrey/58/安居客/网络经纪人），登录 PRD 的"账号体系"是否覆盖这一场景未明。
|
||
|
||
🟡 **Minor D-06**：DATA_MODEL.md §一 1.3 关键设计原则中"金额 NUMERIC(12,2) 万元精度"——12,2 表示最大 9999999999.99 万元，是否过度，建议改 NUMERIC(14,2) 元精度（与会计/合同模块对齐）或在文档中说明万元单位的统一约定。
|
||
|
||
### 2.3 缺失数据
|
||
|
||
🟠 **Major D-07**：以下 PRD 提及但 DATA_MODEL 未见的实体（待 PM/架构师确认是否本期范围）：
|
||
- 楼盘"价格走势"（PRD 楼盘 §)：DATA_MODEL_COMPLEX 是否含 `complex_price_history` 待查
|
||
- "市场报盘"（房源 PRD §)：DATA_MODEL_PROPERTY 22 表中无 `market_quotes`
|
||
- "公客转换"（客源 PRD：私客 → 公客自动转）：DATA_MODEL_CLIENT 是否含触发器/job 待查
|
||
- "学区关联距离"：DATA_MODEL_COMPLEX 已实现 `complex_schools` N:M 含距离 ✅
|
||
|
||
---
|
||
|
||
## 三、TECH_STACK 完整性审查
|
||
|
||
### 3.1 已覆盖
|
||
|
||
✅ HTMX + Alpine.js + Tailwind 禁用清单（Do NOT use 段）
|
||
✅ App 目录结构（`apps/property/models/` 文件级拆分）
|
||
✅ Celery + Redis + R2 + Sentry + Grafana
|
||
✅ Electron 客户端：electron-builder + electron-updater + EV 签名 + SHA256 校验
|
||
✅ 登录 `accounts` App 依赖关系图、Redis Key 命名规范
|
||
✅ 权限系统：自定义 Hybrid RBAC、Redis 缓存快照、Override 优先级
|
||
|
||
### 3.2 关键缺失
|
||
|
||
🟠 **Major T-01**：**Celery 多租户上下文规范缺失**。
|
||
- `TECH_STACK.md` §3 关键约定第 4 条仅说"耗时任务必须 Celery"，未规定**租户 ID 如何传入 Worker**。
|
||
- `DATA_MODEL_PERMISSION.md` 行 1075 出现 `tenant_context(instance)` 仅一例，其他模块（导出 89k 房源、智能配房、图片转码）的 schema 切换无统一约定。
|
||
- 风险：Worker 在错误 schema 下执行查询、跨租户数据污染。
|
||
- **责任**：架构师在 `TECH_STACK.md` 新增 §「异步任务规范」：(a) 所有 task 第一参数必须为 `tenant_schema_name`；(b) 强制使用装饰器 `@with_tenant_context`；(c) Sentry 上报必须包含 `tenant_schema` tag。
|
||
|
||
🟠 **Major T-02**：**R2 文件路径租户隔离命名规范缺失**。
|
||
- 所有 `file_key TEXT` 字段注释为 "R2 存储路径"，但 TECH_STACK 未约束 key 前缀。
|
||
- 当前若开发各自约定，可能出现 `photos/{uuid}.jpg`（无租户标识）的隐患——R2 bucket 是共享的。
|
||
- **责任**：架构师在 `TECH_STACK.md` 增加 R2 路径模板：
|
||
- 房源照片：`tenants/{schema_name}/property/{property_id}/photos/{uuid}.jpg`
|
||
- 跟进附件：`tenants/{schema_name}/follow_logs/{log_id}/attachments/{uuid}`
|
||
- 客户端发布：`releases/{platform}/{version}/{filename}`（共享）
|
||
- 备份/导出：`platform/backups/{tenant_schema}/{date}/...`、`platform/exports/{task_id}/...`
|
||
|
||
🟠 **Major T-03**：**索引清单与查询模式未集中化**。
|
||
- 各 DATA_MODEL 子文档都有零散索引 DDL，但缺一份"高频查询场景 → 索引"对应表。
|
||
- 例：客源活跃度筛选、房源多条件搜索（户型/面积/价格/标签/区域）、跟进日志按员工+时间范围——这些查询是否都有覆盖索引？
|
||
- **责任**：架构师补 `TECH_STACK/索引规范.md` 或在 `DATA_MODEL.md` §六 增加查询索引矩阵。
|
||
|
||
🟠 **Major T-04**：**前端构建与资产管线未定义**。
|
||
- `TECH_STACK.md` 只说 HTMX + Alpine + Tailwind，但未规定：Tailwind JIT 配置位置、CSS 变量加载顺序（UI_SYSTEM 要求 `:root` 中定义所有 token）、HTMX 扩展（`hx-boost`、`hx-ext="response-targets"`）启用清单、Alpine 插件（`x-intersect`、`x-mask`）。
|
||
- **责任**：架构师补 §「前端构建管线」。
|
||
|
||
🟡 **Minor T-05**：**降级方案缺失**（呼应 Review 提示词模板第 348 行）：
|
||
- R2 不可用时图片上传如何降级？
|
||
- Redis 不可用时权限/Session 如何降级？
|
||
- Celery 队列堆积时如何熔断？
|
||
- 当前文档无任何降级策略。
|
||
|
||
🟡 **Minor T-06**：登录技术方案 v2.0 §十 提到滑块 Token 3min Redis TTL，但未说明 Redis 不可用时是否降级到内存（多 worker 不一致）或拒绝登录。
|
||
|
||
🟡 **Minor T-07**：发布 PRD 提到 ARM64 按需支持，TECH_STACK 第 8 节同步——但未规定 ARM64 触发条件（用户量阈值？）。
|
||
|
||
---
|
||
|
||
## 四、UI/UX 完整性审查
|
||
|
||
### 4.1 已覆盖（UI_SYSTEM.md / 组件清单.md）
|
||
|
||
✅ Design Philosophy（4 条原则 + 9 条反模式，含 `禁 window.alert / 禁无限滚动 / 禁 Generic 错误`）
|
||
✅ Design Tokens（颜色/间距 4px 网格/圆角/阴影 CSS 变量化）
|
||
✅ Tailwind fallback 映射表
|
||
✅ 核心组件：Sortable Data Table、Column Visibility、Pagination、Toolbar、Toggle、Multi-select Tag
|
||
✅ 焦点环 / disabled / readonly 状态规范
|
||
|
||
### 4.2 缺失组件 vs PRD 验收标准
|
||
|
||
PRD 的 90+ 验收标准要求以下组件，但组件清单未覆盖：
|
||
|
||
🟠 **Major U-01**：**侧边抽屉（Drawer）缺失**。权限 PRD Story 4 明确要求"右侧滑出 Drawer 不覆盖左侧导航"，UI_SYSTEM 仅在 §一开头提及 `--radius-lg → 模态/抽屉/面板`，但组件清单无 Drawer 实现。
|
||
|
||
🟠 **Major U-02**：**权限树/复杂表单组件缺失**。权限 PRD 描述：14 个一级模块树 + 每模块多分组 + 分组内 Toggle/Select/Number——这是本期最复杂的页面，组件清单未给原型。
|
||
|
||
🟠 **Major U-03**：**Stepper/Wizard 缺失**。房源/客源录入 PRD 强调 ≤ 30s 完成，多 Tab 表单（基本信息/价格/联系人/标签/图片）需要 Stepper 或可折叠分组组件。
|
||
|
||
🟡 **Minor U-04**：Toast/Dialog/确认对话框组件未在清单中正式定义（Anti-pattern 中提到"禁 window.alert，使用 Dialog/Toast"）。
|
||
|
||
🟡 **Minor U-05**：树形选择器（用于 OrgUnit 选择、Permission Scope 选择）缺失。
|
||
|
||
### 4.3 流程缺失
|
||
|
||
🟠 **Major U-06**：**Wireframe / 信息架构未启动**。当前进度"UI 未开始"，但 PRD 中存在大量 UI 隐含决策：
|
||
- 房源列表 21 个核心字段 + 自定义列：默认显示哪些？密度？
|
||
- 89k 数据列表的视觉层级（卡片 vs 表格——UI_SYSTEM 反模式禁止两者混用）
|
||
- 多租户登录页面是否需要展示 tenant_logo？（DATA_MODEL_LOGIN 已有 `tenant_logo_url` 字段）
|
||
- **责任**：UI/UX 设计师在动手前，先输出"页面清单 + 信息架构 + 关键页面 wireframe"。
|
||
|
||
🟡 **Minor U-07**：UI_SYSTEM.md 未规定**国际化**策略（虽然本期中文为主，但 `to_tsvector('simple')` 而非 `'chinese'` 已暗示无中文分词，需在 PRD 中确认是否本期不做中文模糊检索）。
|
||
|
||
---
|
||
|
||
## 五、多租户隔离审查（横切）
|
||
|
||
| 隔离维度 | 现状 | 风险 |
|
||
|----------|------|------|
|
||
| DB Schema | ✅ django-tenants Schema 隔离，所有租户业务表均在 tenant schema | 已落实 |
|
||
| public ↔ tenant FK | ✅ 已在 PERMISSION 文档明确禁止跨 schema FK | 已落实 |
|
||
| 登录认证 | ✅ Tenant 验证在 public，UserAccount 在 tenant schema；username 仅 schema 内唯一 | 已落实 |
|
||
| Celery Worker schema 切换 | 🟠 仅一例，无统一规范 | T-01 |
|
||
| R2 文件路径 | 🟠 无租户前缀规范 | T-02 |
|
||
| Redis Key 命名 | 🟡 登录方案 §十 已包含 `{tenant_id}` 前缀；权限缓存方案 Redis Key 是否带 tenant 待查 | 待确认 |
|
||
| Sentry / 日志 | 🟡 登录方案提及 `tenant_id` tag，但全局未统一 | T-01 |
|
||
|
||
🟠 **Major X-01**：**Redis Key 命名跨模块未统一**。登录方案使用 `login_fail:{tenant_id}:{username}`、`tenant_verify_ip:{ip}`，权限方案使用"员工权限快照"——若不强制 `{tenant_schema_name}:` 前缀，多租户 Redis 共享时存在键冲突。
|
||
|
||
🟠 **Major X-02**：**租户注销→数据导出→清除全链路职责模糊**。
|
||
- PRD/系统管理 §"租户删除"提到：释放子域名、R2 存储桶、License 席位
|
||
- DATA_MODEL_PUBLIC `export_tasks` 含 24h 下载链接
|
||
- 缺失：(a) 导出包是否包含 R2 文件实体（PRD §232 提示"含 R2 文件实体"，但 export_tasks 字段是否落地待查）；(b) 清除时序：tenants.status `pending_delete → deleted` 的硬删除窗口（推荐 30 天宽限期，文档未明确）；(c) 备份保留期 vs 清除时序的一致性。
|
||
- **责任**：PM + 架构师 + 合规共同梳理租户注销 SOP，并在 `DATA_MODEL_PUBLIC.md` §2.4 增加 `tenant_deletion_workflow` 文档化流程图。
|
||
|
||
---
|
||
|
||
## 六、合规与安全审查
|
||
|
||
🟠 **Major S-01**：**手机号加密策略统一性已落实**（AES-256-GCM + SHA-256 哈希），但**密钥管理方案缺失**。
|
||
- TECH_STACK.md 无 KMS / Vault / 环境变量加密管理说明。
|
||
- `core.encryption` 仅作为模块名出现，密钥轮换流程未定义。
|
||
|
||
🟠 **Major S-02**：**敏感字段访问审计**已通过 `follow_logs.sensitive_view` + `is_deletable=FALSE` 实现，但：
|
||
- 客源 `phone_hash` 解密查看是否每次都写 `sensitive_view` 跟进？
|
||
- 业主联系人查看是否同样有"号码方审批"前置流程（PRD 提及 `number_holder_approvals`）？
|
||
- 这些"敏感数据访问审计"的触发链路在 TECH_STACK 未集中说明。
|
||
|
||
🟡 **Minor S-03**：登录失败锁定 30min 是 IP 维度还是账号维度？登录方案 §十 Key 为 `login_fail:{tenant_id}:{username}` 是账号维度，可能被恶意撞库锁定真实用户。建议补 IP 维度限流。
|
||
|
||
🟡 **Minor S-04**：MFA 仅强制平台管理员（`admin_mfa_devices`），租户内部 Tenant Admin / 高敏角色（系统管理员）是否需要 MFA 未提及。
|
||
|
||
🟡 **Minor S-05**：CORS / CSP / SameSite Cookie 等 Web 安全策略未在 TECH_STACK 中规定。
|
||
|
||
---
|
||
|
||
## 七、性能与容量审查
|
||
|
||
🔴 **Blocker** D-01（Keyset 分页缺失）已在 §二列出。
|
||
|
||
🟠 **Major P-08**：**89k 房源筛选的执行计划未验证**。房源 PRD 列表筛选含户型/面积/价格/区域/标签/属性——多条件 AND 查询：
|
||
- 是否有覆盖索引？（DATA_MODEL_PROPERTY §6 待详查）
|
||
- 标签筛选（`property_tag_relations` N:M）是否需要 GIN array 索引或物化视图？
|
||
- 排序字段（更新时间/价格）是否在索引中？
|
||
|
||
🟠 **Major P-09**：**`follow_logs` 200 万+/月增长但无分区 DDL**（D-04 已列）。
|
||
|
||
🟡 **Minor P-10**：`property_photos` 500 万+ 建议 HASH 分区（DATA_MODEL.md §五），但 DATA_MODEL_PROPERTY §4.14 表 DDL 未给分区子句。
|
||
|
||
🟡 **Minor P-11**：智能配房 PRD < 3s 响应，但匹配算法（`client_property_matches`）的索引/计算路径未设计文档。Celery 异步是离线计算还是实时？
|
||
|
||
---
|
||
|
||
## 八、可维护性与扩展性
|
||
|
||
🟡 **Minor M-01**：DATA_MODEL 8 文档 + TECH_STACK 3 文档 + PRD 8 文档版本号不统一（v1.0~v1.4 混用），缺一份 `CHANGELOG.md` 跟踪跨文档变更。
|
||
|
||
🟡 **Minor M-02**：`核心文档体系.md` 提到 "AI 指令手册 (`.cursorrules` / `AI_INSTRUCTIONS.md`)"——但仓库未见该文件。AI 协同开发约定缺位。
|
||
|
||
🟡 **Minor M-03**：单元测试 / 集成测试约定未在 TECH_STACK 中提及（pytest-django / factory_boy / django-tenants 测试 utility）。
|
||
|
||
🟡 **Minor M-04**：Migration 策略未定义。多租户场景下 schema migration 跨数百租户的执行顺序、回滚策略需明文（django-tenants `migrate_schemas` 命令）。
|
||
|
||
---
|
||
|
||
## 九、行动清单（按责任人 + 优先级）
|
||
|
||
### PM（产品经理）
|
||
|
||
| ID | 等级 | 任务 |
|
||
|----|------|------|
|
||
| PM-1 | 🔴 | **修订权限 PRD v1.2**：锁定数据范围档位（建议五档+DataScope），同步修改 §3 非目标声明，补 DataScope UI 入口 |
|
||
| PM-2 | 🟠 | 补充 `PRD/系统设置/租户级系统设置模块PRD.md`（lookup_items 配置、字段标签、自定义字段、标签管理） |
|
||
| PM-3 | 🟠 | 在 `PRD/PRD_MVP.md` 中汇总 NFR 矩阵（性能/可用性/安全/合规） |
|
||
| PM-4 | 🟠 | 与架构师 + 合规一起梳理租户注销 SOP（导出范围、宽限期、清除时序） |
|
||
| PM-5 | 🟡 | 房源 status 状态机图、客源公客转换规则文档化 |
|
||
| PM-6 | 🟡 | 确认是否本期支持中文模糊检索（影响 tsvector 配置） |
|
||
| PM-7 | 🟡 | MFA 是否扩展到租户内部高权限角色 |
|
||
|
||
### 架构师
|
||
|
||
| ID | 等级 | 任务 |
|
||
|----|------|------|
|
||
| ARCH-1 | 🔴 | **TECH_STACK 新增 §「分页规范」**，给出 Keyset 模板；DATA_MODEL_PROPERTY/CLIENT §6 补查询模式参考 |
|
||
| ARCH-2 | 🟠 | TECH_STACK 新增 §「异步任务规范」（tenant_schema 必传 + `@with_tenant_context` 装饰器 + Sentry tag） |
|
||
| ARCH-3 | 🟠 | TECH_STACK 新增 §「R2 路径规范」（每类资源的 key 模板，强制 `tenants/{schema_name}/...` 前缀） |
|
||
| ARCH-4 | 🟠 | DATA_MODEL 各高写入表（`follow_logs`, `property_photos`, `permission_change_logs`, `login_attempts`, `platform_audit_logs`）补 PARTITION DDL + pg_partman 自动维护脚本 |
|
||
| ARCH-5 | 🟠 | `properties` / `clients` / `complexes` 主表补 `version` 字段实现乐观锁；楼盘 4 类锁补 `lock_*` 字段 |
|
||
| ARCH-6 | 🟠 | DATA_MODEL.md §一架构决策补 "**所有 FK 必须同 schema**" 原则；TECH_STACK 补 "**Redis Key 必须 `{schema_name}:` 前缀**" 强制规范 |
|
||
| ARCH-7 | 🟠 | 补 `TECH_STACK/索引规范.md`（高频查询 → 索引矩阵）；补「前端构建管线」章节（Tailwind JIT/HTMX 扩展/Alpine 插件） |
|
||
| ARCH-8 | 🟠 | 密钥管理方案：KMS/Vault 选型、轮换 SOP、`core.encryption` 接口契约 |
|
||
| ARCH-9 | 🟡 | 降级方案：R2/Redis/Celery 不可用时的策略 |
|
||
| ARCH-10 | 🟡 | Migration 策略（跨 N 租户 migrate_schemas 顺序与回滚） |
|
||
| ARCH-11 | 🟡 | 测试规范（pytest-django + factory_boy + tenant 测试 utility） |
|
||
| ARCH-12 | 🟡 | CORS/CSP/SameSite 安全头规范 |
|
||
| ARCH-13 | 🟡 | 智能配房算法路径文档（实时 vs 异步） |
|
||
|
||
### UI/UX 设计师
|
||
|
||
| ID | 等级 | 任务 |
|
||
|----|------|------|
|
||
| UI-1 | 🟠 | **启动 Wireframe**：先输出页面清单 + 信息架构 + 高频页面（房源列表、房源录入、权限编辑、登录）线框 |
|
||
| UI-2 | 🟠 | 组件清单补 Drawer / Stepper / Permission Tree / Tree Select |
|
||
| UI-3 | 🟠 | 89k 列表的视觉密度方案（行高、字段优先级、列宽策略） |
|
||
| UI-4 | 🟡 | Toast / Dialog / Confirm 组件正式定义 |
|
||
| UI-5 | 🟡 | 多租户登录页是否展示 `tenant_logo_url` 的视觉规范 |
|
||
| UI-6 | 🟡 | 国际化策略（v1 是否仅中文） |
|
||
|
||
---
|
||
|
||
## 十、结论
|
||
|
||
### 是否可进入开发阶段
|
||
|
||
**部分可以，但需先解决 2 个 Blocker**：
|
||
|
||
1. **🔴 P-01 权限范围档位冲突**：必须先在 PRD 锁定，否则 `staff_data_scopes` 表是否生效不明，权限模块无法开工。
|
||
2. **🔴 D-01 Keyset 分页规范缺失**：必须在 TECH_STACK 落地，否则房源/客源/跟进列表的核心查询路径设计错误，后期返工成本高。
|
||
|
||
**可立即并行启动的部分**：
|
||
- 公共 Schema（`tenants`、`platform_admins`、`audit_logs`）开发——文档完整，无 Blocker
|
||
- 楼盘/区域/学校 CRUD——DATA_MODEL_COMPLEX 完整，主流程清晰
|
||
- Electron 客户端框架搭建——TECH_STACK §8 决策已封闭
|
||
- 登录模块（accounts App）——文档完整，仅需在编码前补 Redis Key 命名前缀规范
|
||
|
||
**必须延后的部分**：
|
||
- 权限模块编码（等待 PM-1 完成）
|
||
- 房源/客源高基数列表查询（等待 ARCH-1 完成）
|
||
- 全 UI 实现（等待 UI-1 Wireframe）
|
||
|
||
### 文档体系成熟度评分
|
||
|
||
| 维度 | 成熟度 | 说明 |
|
||
|------|--------|------|
|
||
| PRD 业务清晰度 | 8.5/10 | 用户故事和验收标准充分，仅权限档位有自相矛盾 |
|
||
| DATA_MODEL 落地深度 | 8/10 | 颗粒度高，但 Keyset/分区 DDL/乐观锁字段缺失 |
|
||
| TECH_STACK 完整性 | 6/10 | 选型已封闭，但异步/R2/索引/降级等横切规范缺位 |
|
||
| UI/UX 系统化 | 5/10 | Token/核心组件已成型，但 Wireframe 未启动且复杂组件缺失 |
|
||
| 跨文档一致性 | 6.5/10 | 整体高，但 6 处裂缝需要修复 |
|
||
| 多租户隔离严谨度 | 7.5/10 | DB 隔离扎实，但 Celery/R2/Redis 横切层规范不足 |
|
||
| **整体** | **7/10** | 已达"中等偏上"水平，远超普通 SaaS 项目；解决 Blocker 后可达 8.5+ |
|
||
|
||
---
|
||
|
||
## 附录 A：本次 Review 涵盖文档
|
||
|
||
### PRD（8 份）
|
||
- `PRD/房源管理/房源管理模块PRD.md` v2.1（1881 行）
|
||
- `PRD/房源管理/楼盘管理模块PRD.md` v1.0（704 行）
|
||
- `PRD/客源管理/客源管理模块PRD.md` v1.4（2050 行）
|
||
- `PRD/权限管理/权限管理模块PRD.md` v1.1（623 行）
|
||
- `PRD/组织人事管理/组织人事管理模块PRD.md` v1.2（512 行）
|
||
- `PRD/系统管理/系统管理模块PRD.md` v1.0（594 行）
|
||
- `PRD/登录管理/用户登录管理模块PRD.md` v1.4（648 行）
|
||
- `PRD/发布管理/客户端发布管理模块PRD.md` v1.0（407 行）
|
||
|
||
### DATA_MODEL（8 份）
|
||
- `DATA_MODEL/DATA_MODEL.md` v1.3（622 行，索引文档）
|
||
- `DATA_MODEL/DATA_MODEL_PUBLIC.md` v1.0（599 行）
|
||
- `DATA_MODEL/DATA_MODEL_ORG.md` v1.0（342 行）
|
||
- `DATA_MODEL/DATA_MODEL_COMPLEX.md` v1.0（548 行）
|
||
- `DATA_MODEL/DATA_MODEL_PROPERTY.md` v1.0（1169 行）
|
||
- `DATA_MODEL/DATA_MODEL_CLIENT.md` v1.0（575 行）
|
||
- `DATA_MODEL/DATA_MODEL_PERMISSION.md` v1.0（1363 行）
|
||
- `DATA_MODEL/DATA_MODEL_LOGIN.md` v1.0（470 行）
|
||
|
||
### TECH_STACK（3 份）
|
||
- `TECH_STACK/TECH_STACK.md`（154 行）
|
||
- `TECH_STACK/登录管理技术方案.md` v2.0（711 行）
|
||
- `TECH_STACK/权限管理系统技术方案.md` v1.0（677 行）
|
||
|
||
### UI/UX（2 份）
|
||
- `UI&UX/UI_SYSTEM.md`（987 行）
|
||
- `UI&UX/组件清单.md`（1264 行）
|
||
|
||
---
|
||
|
||
## 附录 B：问题汇总速查表
|
||
|
||
| ID | 等级 | 维度 | 责任人 | 简述 |
|
||
|----|------|------|--------|------|
|
||
| P-01 | 🔴 | PRD↔Data | PM | 权限数据范围档位冲突（3 vs 5+叠加） |
|
||
| D-01 | 🔴 | TECH/Data | 架构师 | Keyset 分页规范全局缺失 |
|
||
| P-02 | 🟠 | PRD | PM | 租户级系统设置 PRD 缺失 |
|
||
| P-04 | 🟠 | PRD↔TECH | PM+架构师 | 性能 NFR 矩阵未汇总 |
|
||
| D-02 | 🟠 | Data | 架构师 | 主表乐观锁/楼盘锁字段缺失 |
|
||
| D-03 | 🟠 | Data | 架构师 | 跨 schema FK 原则未统一 |
|
||
| D-04 | 🟠 | Data | 架构师 | 高写入表分区 DDL 未落地 |
|
||
| D-07 | 🟠 | Data | PM/架构师 | 楼盘价格走势/市场报盘等表缺失待确认 |
|
||
| T-01 | 🟠 | TECH | 架构师 | Celery 多租户 schema 切换规范缺失 |
|
||
| T-02 | 🟠 | TECH | 架构师 | R2 文件路径租户隔离规范缺失 |
|
||
| T-03 | 🟠 | TECH | 架构师 | 索引清单未集中化 |
|
||
| T-04 | 🟠 | TECH | 架构师 | 前端构建管线未定义 |
|
||
| U-01 | 🟠 | UI | UI/UX | Drawer 组件缺失 |
|
||
| U-02 | 🟠 | UI | UI/UX | 权限树/Permission Tree 复杂组件缺失 |
|
||
| U-03 | 🟠 | UI | UI/UX | Stepper/Wizard 缺失 |
|
||
| U-06 | 🟠 | UI | UI/UX | Wireframe 未启动 |
|
||
| X-01 | 🟠 | 多租户 | 架构师 | Redis Key 命名跨模块未统一带 tenant 前缀 |
|
||
| X-02 | 🟠 | 合规 | PM+架构师 | 租户注销→导出→清除链路职责模糊 |
|
||
| S-01 | 🟠 | 安全 | 架构师 | 加密密钥管理方案缺失 |
|
||
| S-02 | 🟠 | 安全 | 架构师 | 敏感字段访问审计触发链未集中说明 |
|
||
| P-08 | 🟠 | 性能 | 架构师 | 89k 房源筛选执行计划未验证 |
|
||
| P-03 | 🟡 | PRD | PM | 登录业务规则三处重复 |
|
||
| P-05 | 🟡 | PRD | PM | 房源 status 状态机图缺失 |
|
||
| D-05 | 🟡 | Data | PM | 跨平台账号 username 复用未明 |
|
||
| D-06 | 🟡 | Data | 架构师 | NUMERIC(12,2) 精度选型理由 |
|
||
| T-05 | 🟡 | TECH | 架构师 | 降级方案缺失 |
|
||
| T-06 | 🟡 | TECH | 架构师 | Redis 不可用时滑块 Token 行为未定 |
|
||
| T-07 | 🟡 | TECH | 架构师 | ARM64 触发条件未定 |
|
||
| U-04 | 🟡 | UI | UI/UX | Toast/Dialog 组件未正式定义 |
|
||
| U-05 | 🟡 | UI | UI/UX | Tree Select 组件缺失 |
|
||
| U-07 | 🟡 | UI | PM | 国际化策略未明 |
|
||
| S-03 | 🟡 | 安全 | 架构师 | 登录限流仅账号维度缺 IP 维度 |
|
||
| S-04 | 🟡 | 安全 | PM | 租户内 MFA 范围未明 |
|
||
| S-05 | 🟡 | 安全 | 架构师 | CORS/CSP/SameSite 未规定 |
|
||
| P-10 | 🟡 | 性能 | 架构师 | property_photos HASH 分区 DDL 缺 |
|
||
| P-11 | 🟡 | 性能 | 架构师 | 智能配房算法路径未文档化 |
|
||
| M-01~M-04 | 🟡 | 维护 | 架构师 | CHANGELOG/AI 指令/测试规范/Migration 策略 |
|
||
|
||
**合计**：🔴 2 / 🟠 19 / 🟡 17 = **38 项**
|
||
|
||
---
|
||
|
||
*Report Generated: 2026-04-25 by AI Reviewer*
|