522 lines
34 KiB
Markdown
522 lines
34 KiB
Markdown
# Fonrey 全局系统设计 Review 报告
|
||
|
||
> **Review 类型**：全量 Review（PRD + DATA_MODEL + TECH_STACK + UI/UX + TASK 交叉验证）
|
||
> **Review 模式**：聚焦 Top 风险 + 与 `REVIEW_全局_2026-04-25.md` 增量对比
|
||
> **Review 日期**：2026-04-26
|
||
> **Reviewer**：首席系统设计 Reviewer（AI 辅助）
|
||
> **当前阶段**：需求 ~85% / 数据模型 ~70% / UI 设计 ~30%（HTML 原型已启动）/ TECH 横切规范 ~50%
|
||
> **覆盖文档**：8 份 PRD（含 7 份模块 PRD + TASK.md）、8 份 DATA_MODEL、4 份 TECH_STACK、3 份 UI_SYSTEM、UI_DESIGN（10 份原型/设计稿）
|
||
> **问题分级**：🔴 Blocker（阻塞开发） / 🟠 Major（必须修复但不阻塞） / 🟡 Minor（建议优化）
|
||
|
||
---
|
||
|
||
## 〇、执行摘要（Executive Summary）
|
||
|
||
### 整体评价
|
||
|
||
相较 2026-04-25 版本，文档体系出现 **3 项实质性进展**：
|
||
1. **UI_DESIGN 原型已启动**（昨日 U-06 已修复）：客源列表/详情/新增/编辑、房源列表 5 类核心页面均已产出 HTML + Markdown 双版本，规范深度足够。
|
||
2. **租户注销 SOP 已落地**（昨日 X-02 已修复）：`PRD/系统管理` 已含导出范围、30 天宽限期、清除时序的完整生命周期。
|
||
3. **楼盘 4 类锁字段已实现**（昨日 D-02 部分修复）：`complexes.lock_building/lock_room/lock_info/lock_standard_room` DDL 已写入。
|
||
|
||
但本次审查也暴露出**昨日 Review 未触及的新一类系统性风险——枚举一致性塌方**：客源状态、客源等级、房源状态、操作日志类型等核心枚举在 PRD ↔ DATA_MODEL ↔ TASK AC 三方均无权威源，且互相矛盾。这是一类比"Keyset 分页缺失"更隐蔽、修复成本更高的债务。
|
||
|
||
同时，**昨日列出的 2 个 Blocker（P-01 权限档位 / D-01 Keyset 分页）均未修复**，新增 1 个 Blocker（系统配置 PRD 仍为空骨架但被 9 条 P0/P1 任务引用为权威），共 **3 个 Blocker**，必须在编码启动前清零。
|
||
|
||
### 核心问题摘录（Top 10）
|
||
|
||
| # | 等级 | 编号 | 问题 | 维度 | 状态 |
|
||
|---|------|------|------|------|------|
|
||
| 1 | 🔴 | **B-01** | 系统配置 PRD（`PRD/系统配置/系统配置.md`）仍为 128 行空骨架，但 TASK.md 排期 9 条 P0/P1 任务（US-SETTING-001/010~012/020~023）以其为权威；`lookup_items` 入口、字段必填、活跃度阈值（30 天）等无配置出口 | PRD↔TASK | 🆕 新增 |
|
||
| 2 | 🔴 | **B-02** | **核心枚举三方不一致**：客源状态（PRD"求购/求租/租购"vs DDL `buying/renting/buy_or_rent`）、等级（PRD A~E vs DDL A_urgent/A/B/C/D）、房源 status（DDL 未含 `sold/unlisted/paused`，但 TASK AC 与查询语句均使用） | PRD↔Data↔TASK | 🆕 新增 |
|
||
| 3 | 🔴 | **B-03** | 权限 PRD §3 非目标声明"三档"与 §5.6 / Story 3 验收"五档" + DATA_MODEL_PERMISSION 的"DataScope 跨层级叠加"实质性冲突 | PRD↔Data | ⚠️ 昨日 P-01 部分修复，仍 Blocker |
|
||
| 4 | 🔴 | **B-04** | Keyset 分页规范在 TECH_STACK / DATA_MODEL / 测试规范中**完全缺位**，89k 房源 + 200 万跟进日志的列表查询设计错误 | TECH/Data | ⚠️ 昨日 D-01 未修复 |
|
||
| 5 | 🟠 | **M-01** | 测试规范 v1.0 与 django-tenants 多租户工作模式冲突：`LocMemCache`/`FileSystemStorage`/`CELERY_TASK_ALWAYS_EAGER=True` 使权限 Redis 快照失效、跨租户隔离、Celery 异步导出三类场景无法验证；`TenantClient`/`tenant fixture` 仅在 §11.2 Prompt 模板中被引用但无实现 | TECH/测试 | 🆕 新增 |
|
||
| 6 | 🟠 | **M-02** | 主表乐观锁字段缺失：`properties` / `clients` 仍无 `version`；`complexes` 4 类锁已建字段但无解锁权限/过期规则 PRD | Data↔PRD | ⚠️ 昨日 D-02 部分修复 |
|
||
| 7 | 🟠 | **M-03** | 高写入表分区 DDL 仍未落地：`follow_logs` / `property_photos` / `permission_change_logs` / `login_attempts` / `platform_audit_logs` 均仅文字"建议月度分区"，无 `PARTITION BY` 子句 | Data | ⚠️ 昨日 D-04 未修复 |
|
||
| 8 | 🟠 | **M-04** | TECH_STACK 三大横切规范仍未补：Celery 多租户 schema 切换（昨 T-01）、R2 文件路径前缀（昨 T-02）、查询索引矩阵（昨 T-03） | TECH/多租户 | ⚠️ 昨日均未修复 |
|
||
| 9 | 🟠 | **M-05** | 89k 数据 < 2 秒列表查询是 TASK AC 中的硬性 NFR（US-PROPERTY-002 / US-CLIENT-002），但 TECH_STACK + 测试规范无 p95/EXPLAIN/性能基准对应任务，AC 不可测 | NFR↔TECH↔测试 | 🆕 新增 |
|
||
| 10 | 🟠 | **M-06** | 客户端发布无签名校验/防降级机制：`/api/client/updates/latest/` 与 `download_url` 公开 URL，仅 SHA256 完整性校验，可被中间人投递降级版本 | 安全 | 🆕 新增 |
|
||
|
||
### 风险等级分布
|
||
|
||
| 等级 | 本次（2026-04-26） | 昨日（2026-04-25） | 净变化 |
|
||
|------|---|---|---|
|
||
| 🔴 Blocker | **3** | 2 | +1（系统配置空骨架升级） |
|
||
| 🟠 Major | **12** | 19 | -7（含 6 项已修复 + 1 项降级） |
|
||
| 🟡 Minor | **6** | 17 | -11（聚焦 Top 风险，未列入本期） |
|
||
| 合计 | **21** | 38 | — |
|
||
|
||
### 增量对比一览（昨日 P0/P1 → 今日状态）
|
||
|
||
| 昨日编号 | 简述 | 状态 | 今日处置 |
|
||
|----------|------|------|----------|
|
||
| P-01 | 权限范围档位冲突 | 🟡 部分修复 | 升 B-03 仍 Blocker |
|
||
| D-01 | Keyset 分页缺失 | 🔴 未修复 | 转 B-04 |
|
||
| P-02 | 系统配置 PRD 缺失 | 🔴 仍空骨架 | 升 B-01 |
|
||
| D-02 | 主表乐观锁/楼盘锁 | 🟡 部分修复 | 转 M-02 |
|
||
| D-04 | 高写入表分区 | 🔴 未修复 | 转 M-03 |
|
||
| D-07 | 楼盘价格走势/市场报盘 | 🟡 部分修复 | M-08（降级） |
|
||
| T-01/T-02/T-03 | Celery/R2/索引规范 | 🔴 均未修复 | 合并 M-04 |
|
||
| U-01/U-02/U-03/U-06 | UI 组件 + Wireframe | 🟡 U-06 已修复，复杂组件仍缺 | 转 M-09 |
|
||
| X-01 | Redis Key tenant 前缀 | 🟡 部分修复 | M-10（降级） |
|
||
| X-02 | 租户注销 SOP | ✅ 已修复 | 关闭 |
|
||
| S-01 | 加密密钥管理 | 🔴 未修复 | M-11 |
|
||
|
||
---
|
||
|
||
## 一、PRD 一致性审查（PRD ↔ PRD ↔ TASK）
|
||
|
||
### 🔴 B-01 系统配置 PRD 空骨架阻塞 9 条 P0/P1 任务
|
||
|
||
**文档**：`PRD/系统配置/系统配置.md:1-128`（仅章节标题，无内容）；`PRD/TASK.md:59, 86-88, 107-110`
|
||
|
||
**事实**：
|
||
- 系统配置 PRD 仅 128 行骨架，无任何字段定义、规则说明、UI 描述。
|
||
- TASK.md 在 Phase 1/2/3 共排期 9 条 Story，全部以"参考 PRD：系统配置.md"为权威：
|
||
- P0：US-SETTING-001（房源相关设置-字段必填/自定义字段/标签）
|
||
- P1：US-SETTING-010/011/012（首页/相关方/客源参数）
|
||
- P2：US-SETTING-020~023（人事 OA/交易/财务/合同模板）
|
||
- 客源 PRD `DATA_MODEL_CLIENT.md:31` 提到"活跃度新配偶 30 天"阈值由 lookup_items 配置，但配置入口 PRD 不存在。
|
||
- 房源 PRD 多处提到"字段标签可配置"、"自定义字段"、"标签管理"，全部指向系统配置 PRD。
|
||
|
||
**影响**：
|
||
- US-SETTING-001 是 Phase 1 P0，无 PRD 即无法启动开发。
|
||
- 所有"可配置"行为（活跃度阈值、自动转公阈值、字段标签）的运营管理入口断链。
|
||
- DATA_MODEL_PUBLIC `lookup_items` 表已建好，但其管理 UI 与权限设计无规格。
|
||
|
||
**责任**：PM 必须在编码 Phase 1 启动前完成 `PRD/系统配置/系统配置.md` 至少 P0 范围（US-SETTING-001 内容），否则 TASK.md 应将 US-SETTING-001 暂时移出 Phase 1。
|
||
|
||
---
|
||
|
||
### 🔴 B-02 核心枚举三方不一致（PRD ↔ DDL ↔ TASK AC）
|
||
|
||
**文档**：多处（见下表）
|
||
|
||
| 字段 | PRD 表述 | DATA_MODEL CHECK | TASK AC | 冲突类型 |
|
||
|------|----------|------------------|---------|----------|
|
||
| 客源 status | `PRD/客源管理/客源管理模块PRD.md:465,504,1757,1786`：求购/求租/租购/我购/我租/成交/暂缓/无效/公 | `DATA_MODEL_CLIENT.md:471,511`：`buying / renting / buy_or_rent`（仅 3 值，无暂缓/无效/我购/我租/成交/公） | `TASK.md` US-CLIENT-002/010/011/012/013 均按 PRD 中文 | 三方均不同 |
|
||
| 客源 grade | PRD `1634`：A~E 五级 | `DATA_MODEL_PROPERTY.md:266`（注：客源 grade 字段实际位置待确认）：`A_urgent/A/B/C/D` 5 项无 E | `TASK.md:308` US-CLIENT-009：A 急迫/B 较强/C 一般/D 较弱/E 暂不关注 五级 | DDL 缺 E，混用 `A_urgent` |
|
||
| 房源 status | PRD 8 态：出售/出租/租售/暂缓/他售/他租/成交/未挂牌 | `DATA_MODEL_PROPERTY.md:197`：`for_sale/for_rent/for_sale_rent/...` | `TASK.md:232` US-PROPERTY-008：在售→暂缓/成交/下架；`TASK.md:1121` 隐式查询 `status NOT IN ('sold','unlisted')` | DDL CHECK 全集未冻结，"sold/unlisted/paused" 出现在查询但未确认在 CHECK 中 |
|
||
| 操作日志 type | 客源 PRD `668`：明文"系统实际枚举值更多" | DATA_MODEL_CLIENT 未给 CHECK 完整列表 | `TASK.md:578-581` US-CLIENT-024 AC："按操作类型筛选" | 全集未冻结 |
|
||
| 二级 Tab "暂缓" | 客源 PRD `713-717` Tab：求购/求租/暂缓/全部私客 | `DATA_MODEL_CLIENT.md:471,511` 状态枚举无 `paused/on_hold` | `US-CLIENT-002` AC 含暂缓 Tab | DDL 缺值 |
|
||
| `tenants.status` | `DATA_MODEL_PUBLIC.md:96`：6 值含 `failed` | 同文件 `488-494` 状态机图：仅 5 态，未含 `failed` | — | 同一文档内自相矛盾 |
|
||
|
||
**影响**：
|
||
- 迁移脚本将凭主观翻译，开发期会出现"经纪人在 PRD 看到的中文"与"DDL CHECK 拒绝的英文"不一致的运行时报错。
|
||
- 状态机断链导致 transition 校验逻辑（如"暂缓→在售"）无权威实现。
|
||
- 测试 factory 不知如何取样；form choices 与 query filter 各自定义。
|
||
|
||
**责任**：PM + 架构师共同冻结一份《Fonrey 枚举字典 v1.0》（建议放入 `DATA_MODEL/ENUMS.md`），所有 PRD/DDL/TASK 引用统一锚点。
|
||
|
||
---
|
||
|
||
### 🔴 B-03 权限数据范围档位冲突仍为 Blocker（昨日 P-01 部分修复）
|
||
|
||
**文档**：`PRD/权限管理/权限管理模块PRD.md:46`（§3 非目标）vs `:492-499`（§5.6 五档）vs `DATA_MODEL/DATA_MODEL_PERMISSION.md:24,31`（DataScope 跨层级叠加）
|
||
|
||
**事实**：
|
||
- §3 非目标仍写"数据范围控制以**本人 / 本部门 / 全公司**三档为主，本期不含行级权限"。
|
||
- §5.6 已扩为五档（本人/本组/本门店/本区域/全公司）。
|
||
- DATA_MODEL_PERMISSION `staff_data_scopes` 已实现"跨层级叠加"（"本组 ∪ 门店B"），实质上为对象级权限的弱化形态，已超出 §3 非目标边界。
|
||
|
||
**影响**：
|
||
- 同一 PRD 内 §3 与 §5.6 自相矛盾，开发无权威依据。
|
||
- `staff_data_scopes` 是否本期落地不明，权限模块（US-PERMISSION-001~005）无法启动。
|
||
|
||
**责任**：PM 在 PRD v1.2 中锁定五档 + 删除 §3 三档表述 + 明确 DataScope 跨层级叠加是否本期范围。
|
||
|
||
---
|
||
|
||
### 🟠 M-07 楼盘合并/申请流程仅占位
|
||
|
||
**文档**：`PRD/房源管理/楼盘管理模块PRD.md:117`
|
||
|
||
**事实**：PRD 仅写"小区名称/地址只读 — 合并/申请流程"占位，未定义触发条件、审批人、合并规则、对历史房源/客源的影响。`DATA_MODEL_COMPLEX` 无对应表/工作流。
|
||
|
||
**影响**：US-COMPLEX-001 录入与维护流程不闭环；楼盘合并将在生产环境出现"合并后历史房源 complex_id 漂移"问题。
|
||
|
||
---
|
||
|
||
### 🟠 M-08 客源新房/租房 Tab 字段未冻结
|
||
|
||
**文档**：`PRD/客源管理/客源管理模块PRD.md:1663`（明文"字段待截图补充确认"）
|
||
|
||
**事实**：US-CLIENT-014（编辑客源 Tab 三：二手/新房/租房）AC 不可测，DATA_MODEL_CLIENT 需求字段 schema 不可冻结。
|
||
|
||
---
|
||
|
||
## 二、DATA_MODEL 完整性审查
|
||
|
||
### 🔴 B-04 Keyset 分页规范全局缺位（昨日 D-01 未修复）
|
||
|
||
**文档**：`TECH_STACK/TECH_STACK.md`（全文未现 keyset/分页规范）；`DATA_MODEL_PROPERTY.md:1083` §6 / `DATA_MODEL_CLIENT.md:453` §五 查询模式参考章节均未给 Keyset SQL 模板
|
||
|
||
**事实**：
|
||
- 89k 房源 + 200 万/年跟进日志使用 OFFSET 分页，第 100 页响应将达秒级。
|
||
- TASK.md US-PROPERTY-002 / US-CLIENT-002 的 AC 均要求"<2 秒"。
|
||
- 测试规范无性能基准任务覆盖。
|
||
|
||
**责任**：架构师在 `TECH_STACK.md` 新增 §「分页规范」，并在 `DATA_MODEL_PROPERTY.md` §6 / `DATA_MODEL_CLIENT.md` §五 给出 Keyset SQL 模板（`WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT 21`）。
|
||
|
||
---
|
||
|
||
### 🟠 M-02 主表乐观锁/楼盘锁规则缺失
|
||
|
||
**文档**：`DATA_MODEL_COMPLEX.md:194-197`（楼盘 4 类锁字段已建）；`DATA_MODEL_PROPERTY.md` / `DATA_MODEL_CLIENT.md` / `DATA_MODEL_COMPLEX.md` 主表均无 `version` 字段；`PRD/房源管理/楼盘管理模块PRD.md:82` 列出 4 类锁但无解锁/过期规则
|
||
|
||
**事实**：
|
||
- 楼盘 `lock_building/lock_room/lock_info/lock_standard_room` 字段已落库 ✅
|
||
- 但 PRD 未规定每类锁的解锁权限、自动/手动解锁规则、锁过期机制。
|
||
- US-COMPLEX-001/002 AC 不含锁状态变更流程。
|
||
- `properties.version` / `clients.version` 仍未补，多人协作场景的写冲突无防护。
|
||
|
||
**责任**：架构师补 `version` 字段；PM 补 4 类锁的业务规则。
|
||
|
||
---
|
||
|
||
### 🟠 M-03 高写入表分区 DDL 仍未落地（昨日 D-04 未修复）
|
||
|
||
**文档**：`DATA_MODEL_PROPERTY.md:523`（follow_logs）/ `:801`（property_photos）；`DATA_MODEL.md:596-604`（仅文字描述）
|
||
|
||
**事实**：
|
||
- `follow_logs`（200 万+/年）、`property_photos`（500 万+）、`permission_change_logs`、`login_attempts`、`platform_audit_logs` 的 DDL 中均无 `PARTITION BY` 子句，仅在文字描述/分区策略表中"建议按月 RANGE 分区"。
|
||
- 开发期不分区，未来再分区将带来全表数据迁移成本。
|
||
|
||
**责任**：架构师在每张高写入表的 DDL 中给出 `PARTITION BY RANGE (created_at)` + `pg_partman` 自动维护脚本。
|
||
|
||
---
|
||
|
||
### 🟠 M-08 楼盘价格走势已建，市场报盘仍缺（昨日 D-07 部分修复）
|
||
|
||
**文档**：`DATA_MODEL_COMPLEX.md:376` `complex_price_trends` ✅；`DATA_MODEL_CLIENT.md:505` §5.4 私客自动转公（仅 SQL 查询示例，非完整 job）；`market_quotes` 表全表缺失
|
||
|
||
**事实**：
|
||
- 楼盘价格走势 ✅ 已建。
|
||
- "市场报盘"（房源 PRD §）仍无 `market_quotes` 表。
|
||
- 私客→公客自动转换仅给查询 SQL 示例，无完整 Celery beat 调度任务定义、无幂等保证、无并发控制。
|
||
|
||
**影响**：US-CLIENT-016（系统自动将超时无跟进的私客转为公客）AC 无法实现。
|
||
|
||
---
|
||
|
||
## 三、TECH_STACK 完整性审查
|
||
|
||
### 🟠 M-04 三大横切规范全部仍未补（昨日 T-01/T-02/T-03 未修复）
|
||
|
||
**文档**：`TECH_STACK/TECH_STACK.md`（全文）
|
||
|
||
| 子项 | 现状 | 影响 |
|
||
|------|------|------|
|
||
| Celery 多租户 schema 切换 | TECH_STACK.md L30/44/80/90/165 仅零散提及 Celery，无统一规范 | Worker 在错误 schema 下查询、跨租户数据污染 |
|
||
| R2 文件路径前缀 | TECH_STACK.md L31/105/119/166 仅提及 bucket 名 | 共享 bucket 下 `file_key` 无租户标识，存在隐患 |
|
||
| 查询索引矩阵 | TECH_STACK/ 目录无"索引规范.md"；DATA_MODEL.md §六 实为 Redis 缓存策略 | 89k 房源多条件筛选无覆盖索引验证依据 |
|
||
|
||
**责任**：架构师补 §「异步任务规范」、§「R2 路径规范」、`TECH_STACK/索引规范.md` 三份内容。
|
||
|
||
---
|
||
|
||
### 🟠 M-01 测试规范与 django-tenants 多租户工作模式冲突
|
||
|
||
**文档**：`TECH_STACK/测试规范.md:393-413`（settings_test）/`570-575`（引用未实现的 TenantClient）/`594`（禁用真实外部服务）
|
||
|
||
**事实**：
|
||
- `LocMemCache`（402-406）：django-tenants 需要 `tenant-cache-key` 前缀化的 Redis 行为；权限快照走 Redis（TASK L617 AC "Redis 权限快照失效重载"），切到 LocMem 后跨进程/跨租户隔离测试失效。
|
||
- `FileSystemStorage`（411-413）：替换 R2 用于测试本身合理，但与 §594 "禁止测试直接调用真实外部服务"叠加后，`tenants/{schema_name}/...` 路径前缀策略（M-04 R2）无 mock 验证手段。
|
||
- `CELERY_TASK_ALWAYS_EAGER=True`（398-399）：US-CLIENT-003 等要求"Celery 异步处理"的 AC 无法在 EAGER 模式下验证异步语义。
|
||
- `DATABASES "由环境变量注入"`（393-395）：未约定 `ENGINE=django_tenants.postgresql_backend`，可能落到错误的 backend 上。
|
||
- `TenantClient` / 多租户 fixture：仅在 §11.2 Prompt 模板中被引用，无实现，§12 又"禁止使用 Django 原生 Client()"，造成所有 integration 测试无统一基类。
|
||
|
||
**影响**：
|
||
- 权限模块 Redis 快照失效场景、跨租户隔离场景的自动化测试不可信。
|
||
- US-PERMISSION-* / US-CLIENT-003 / US-CLIENT-016 等核心场景的覆盖率指标存在水分。
|
||
|
||
**责任**：架构师与测试负责人协同：(a) `tests/conftest.py` 提供 `TenantClient` 与 `tenant_factory` 实现；(b) Redis 改用 fakeredis 而非 LocMemCache；(c) 异步场景使用 `pytest-celery` 的 `celery_app` fixture，区分 EAGER 单元测试与真实 broker 集成测试。
|
||
|
||
---
|
||
|
||
### 🟠 M-05 性能 NFR 无 SLI/SLO 落地（昨日 P-04 未修复）
|
||
|
||
**文档**：`TASK.md:189, 252` US-PROPERTY-002 / US-CLIENT-002 AC 写"89000 条数据下查询 < 2 秒"；`PRD/客源管理/客源管理模块PRD.md:1958-1960` 仅泛述"分页加载"；TECH_STACK 与测试规范无 p95/索引/EXPLAIN 验收
|
||
|
||
**事实**：
|
||
- 性能 AC 散布于 PRD/TASK 多处（录入耗时 ≤ 30s、配房 < 3s、登录成功率、自动更新 ≥ 98%、RTO < 2h），无统一的 NFR 矩阵。
|
||
- TECH_STACK 未承接为 SLI/SLO；测试规范无性能基准任务（如 pytest-benchmark + EXPLAIN ANALYZE 校验）。
|
||
|
||
**影响**：所有性能 AC 不可测，验收阶段将沦为主观判断。
|
||
|
||
---
|
||
|
||
### 🟠 M-11 加密密钥管理方案缺失（昨日 S-01 未修复）
|
||
|
||
**文档**：`TECH_STACK/TECH_STACK.md:96` 仅一句"禁止硬编码密钥"
|
||
|
||
**事实**：
|
||
- 全文未给出 KMS / Vault / 环境变量加密管理说明。
|
||
- `core.encryption` 仅作为模块名出现，密钥轮换流程未定义。
|
||
- 手机号、身份证、银行卡号、产证号等多处使用 AES-256-GCM 加密，密钥泄露后批量解密风险高。
|
||
|
||
**责任**：架构师补 KMS/Vault 选型 + 轮换 SOP + `core.encryption` 接口契约。
|
||
|
||
---
|
||
|
||
## 四、UI/UX 完整性审查
|
||
|
||
### ✅ U-06 已修复：UI_DESIGN 原型已启动
|
||
|
||
**证据**：`UI_DESIGN/preview.html`、`UI_DESIGN/客源列表_UI.html`（81KB）、`客源详情_UI.html`、`房源列表_UI.html`、`新增客源_UI.html`、`编辑客源_UI.html`；`UI_DESIGN/客源管理/`（4 份 md，60KB+/40KB+）；`UI_DESIGN/房源管理/房源列表_UI.md`（69KB）
|
||
|
||
**事实**：HTML 原型与对应 Markdown 设计稿均已启动，规范深度足够（含功能范围/页面规范/Data Table/HTMX/权限矩阵）。
|
||
|
||
---
|
||
|
||
### 🟠 M-09 复杂组件原型仍缺 + 楼盘/客源原型不完整（昨日 U-01/U-02/U-03 未修复）
|
||
|
||
**文档**：`UI_SYSTEM/UI_SYSTEM.md`（1742 行）；`UI_SYSTEM/组件清单.md:186`（仅在评论中提到 TreeSelect "建议手写 80~120 行 JS"）；`UI_DESIGN/房源管理/` 仅 1 个文件；`UI_DESIGN/客源管理/` 缺关键浮层
|
||
|
||
**事实**：
|
||
- 组件清单仍缺 4 类关键复杂组件：
|
||
1. **Stepper / Wizard**（多步表单）：录入私客、转成交浮层
|
||
2. **PermissionTree**（14 个一级模块树 + 多分组 + Toggle/Select/Number）：US-PERMISSION-001/004 最复杂页面
|
||
3. **智能配房比对器**（4 分组卡片）：US-CLIENT-020 录客配房
|
||
4. **审批前置弹层**：US-CLIENT-015 跨团队需店长权限、号码方审批
|
||
- UI_DESIGN/房源管理/ 仅 `房源列表_UI.md`，TASK.md L152/160 引用 `楼盘列表_UI.md` / `楼盘详情_UI.md` 不存在。
|
||
- UI_DESIGN/客源管理/ 缺 US-CLIENT-007（带看）/011（转公客）/012（转成交）/015（相关员工）/020（智能配房）独立原型，全部压缩进 `客源详情_UI.md` 单文件，颗粒度不足。
|
||
|
||
**责任**：UI/UX 设计师补 4 类复杂组件 + 楼盘 2 份原型 + 客源 5 份关键浮层独立原型。
|
||
|
||
---
|
||
|
||
## 五、多租户隔离审查（横切）
|
||
|
||
### 🟠 M-10 Redis Key 命名跨模块未统一（昨日 X-01 部分修复）
|
||
|
||
**文档**：`TECH_STACK/登录管理技术方案.md:553-562`（§九 Redis Key 规范，使用 `{tenant_id}:` 前缀）；`TECH_STACK.md` / `权限管理系统技术方案.md` 未见统一规范引用
|
||
|
||
**事实**：
|
||
- 登录方案已落地 Redis Key 规范表 ✅，但前缀使用 `{tenant_id}:` 而非昨日 Review 建议的 `{tenant_schema_name}:`。
|
||
- TECH_STACK.md 总纲未引用此规范；权限技术方案未明确 Redis Key 是否带 tenant 前缀。
|
||
- 跨模块（登录/权限/缓存）若不统一，多租户 Redis 共享时存在键冲突风险。
|
||
|
||
**责任**：架构师在 `TECH_STACK.md` 新增 §「Redis Key 规范」，统一 `{tenant_schema_name}:` 前缀（schema_name 比 tenant_id 在日志/调试时更直观），并在登录/权限技术方案中显式引用。
|
||
|
||
---
|
||
|
||
## 六、合规与安全审查
|
||
|
||
### 🟠 M-06 客户端发布无防降级/重放校验
|
||
|
||
**文档**：`PRD/发布管理/客户端发布管理模块PRD.md:58`（明文非目标"客户端代码混淆/反逆向"）；`DATA_MODEL_PUBLIC.md:413-416, 419-421`
|
||
|
||
**事实**：
|
||
- `/api/client/updates/latest/` 响应未要求服务端签名。
|
||
- `client_releases.download_url` 为 R2 公开 URL，无签名/有效期，旧客户端可继续拉取旧版本绕过强制升级。
|
||
- `min_required_version` 由"应用层比较 SemVer"，未定义服务端签名/客户端公钥校验。
|
||
- US-RELEASE-011 SHA256 仅校验完整性，不防替换（中间人可投递降级版本）。
|
||
|
||
**影响**：中间人攻击可投递已撤销的旧版本（含已修复漏洞的版本），合规与安全双重风险。
|
||
|
||
**责任**：架构师与发布团队补：(a) 更新元数据签名（Ed25519/RSA-PSS）；(b) `download_url` 改用签名 URL（短有效期）；(c) 客户端内置公钥校验。
|
||
|
||
---
|
||
|
||
### 🟠 M-12 RPO 数值缺失，备份计划与 SLA 断链
|
||
|
||
**文档**：`PRD/系统管理/系统管理模块PRD.md:58`（仅 RTO < 2h）；`DATA_MODEL_PUBLIC.md:265-280` `backup_schedules` 默认 daily 02:00、retention 10
|
||
|
||
**事实**：
|
||
- daily 频率隐含 RPO ≈ 24h 但 PRD 未声明。
|
||
- 与"全局/租户级覆盖"组合下，SLA 不可承诺。
|
||
- `tenants.status` 含 `failed`（DDL）但状态机图（同文 488-494）仅 5 态未含 `failed`，故障租户无 SLA 出口。
|
||
|
||
**责任**：PM 补 RPO 数值；架构师补 `failed` 状态的退出路径。
|
||
|
||
---
|
||
|
||
## 七、性能与容量审查
|
||
|
||
### 🟠 M-05 89k 数据 < 2 秒 AC 不可测（已在 §三列出）
|
||
|
||
### 🟠 M-13 智能配房算法路径仍未文档化
|
||
|
||
**文档**：客源 PRD §5 智能配房；TECH_STACK 与 DATA_MODEL 未有"实时 vs 异步""匹配算法 SQL"说明
|
||
|
||
**事实**：
|
||
- 客源 PRD 要求智能配房响应 < 3s。
|
||
- 匹配字段（户型/面积/价格/区域）跨 properties/clients 两表的 4-6 维筛选，是否使用物化视图/PostgreSQL 多列 GiST 未定。
|
||
- `client_property_matches` 表是否本期建（TASK Phase 3 才有 US-CLIENT-020）？若 Phase 1 不需要，PRD 提及的 < 3s 应明确不在 Phase 1 范围。
|
||
|
||
---
|
||
|
||
## 八、可维护性与扩展性
|
||
|
||
### 🟠 M-14 TASK.md PRD 锚点链接断链
|
||
|
||
**文档**：`TASK.md:124, 132, 139, 150, 158, 167` 等
|
||
|
||
**事实**：TASK.md 大量"参考 PRD：xxx#锚点"形式的链接，但所引锚点（如 `登录管理/用户登录管理模块PRD.md - 账号密码登录` / `楼盘管理模块PRD.md - 楼盘信息管理`）在对应 PRD 中作为标题不存在，开发无法直接跳转。
|
||
|
||
**影响**：TASK.md 作为开发入口的"可执行性"打折扣。
|
||
|
||
---
|
||
|
||
## 九、行动清单（按责任人 + 优先级）
|
||
|
||
### PM（产品经理）
|
||
|
||
| ID | 等级 | 任务 | 关联编号 |
|
||
|----|------|------|----------|
|
||
| PM-1 | 🔴 | **补齐 `PRD/系统配置/系统配置.md` P0 范围**（US-SETTING-001：字段必填/自定义字段/标签管理；lookup_items 配置入口；活跃度/转公阈值配置） | B-01 |
|
||
| PM-2 | 🔴 | 与架构师协同冻结《Fonrey 枚举字典 v1.0》（建议 `DATA_MODEL/ENUMS.md`），覆盖客源 status/grade、房源 status、操作日志 type、`tenants.status` 等核心枚举 | B-02 |
|
||
| PM-3 | 🔴 | 修订权限 PRD v1.2：删除 §3 三档表述，锁定五档 + DataScope 跨层级叠加是否本期范围 | B-03 |
|
||
| PM-4 | 🟠 | 楼盘合并/申请流程详述（触发/审批/对历史房源影响） | M-07 |
|
||
| PM-5 | 🟠 | 客源新房/租房 Tab 字段冻结 | M-08 |
|
||
| PM-6 | 🟠 | 在 `PRD_MVP.md` 中汇总 NFR 矩阵（性能/可用性/安全/合规），含 RPO 数值 | M-05, M-12 |
|
||
| PM-7 | 🟠 | 修复 TASK.md 内所有 PRD 锚点断链 | M-14 |
|
||
|
||
### 架构师
|
||
|
||
| ID | 等级 | 任务 | 关联编号 |
|
||
|----|------|------|----------|
|
||
| ARCH-1 | 🔴 | TECH_STACK 新增 §「分页规范」+ Keyset SQL 模板；DATA_MODEL_PROPERTY/CLIENT §查询模式补 Keyset 示例 | B-04 |
|
||
| ARCH-2 | 🟠 | 修复测试规范多租户冲突：补 `TenantClient` 实现、`tenant_factory` fixture；Redis 改用 fakeredis；区分 EAGER/真实 broker | M-01 |
|
||
| ARCH-3 | 🟠 | `properties` / `clients` 主表补 `version`；楼盘 4 类锁补解锁/过期机制（与 PM 协同） | M-02 |
|
||
| ARCH-4 | 🟠 | 高写入表（follow_logs/property_photos/permission_change_logs/login_attempts/platform_audit_logs）补 `PARTITION BY RANGE` DDL + pg_partman 脚本 | M-03 |
|
||
| ARCH-5 | 🟠 | TECH_STACK 三大横切规范补：异步任务（Celery tenant_schema 必传 + `@with_tenant_context`）/R2 路径前缀（`tenants/{schema_name}/...`）/查询索引矩阵 | M-04 |
|
||
| ARCH-6 | 🟠 | TECH_STACK 性能 NFR → SLI/SLO 映射 + 测试规范补 pytest-benchmark/EXPLAIN ANALYZE | M-05 |
|
||
| ARCH-7 | 🟠 | 客户端发布签名机制：服务端签发 Ed25519/RSA-PSS、客户端内置公钥、`download_url` 改签名 URL | M-06 |
|
||
| ARCH-8 | 🟠 | `market_quotes` 表 + 私客自动转公完整 Celery beat 任务（含幂等/并发控制） | M-08 |
|
||
| ARCH-9 | 🟠 | TECH_STACK 新增 §「Redis Key 规范」，统一 `{tenant_schema_name}:` 前缀 | M-10 |
|
||
| ARCH-10 | 🟠 | 加密密钥管理方案：KMS/Vault 选型、轮换 SOP、`core.encryption` 接口契约 | M-11 |
|
||
| ARCH-11 | 🟠 | `tenants.status='failed'` 状态机出口补全 | M-12 |
|
||
| ARCH-12 | 🟠 | 智能配房算法路径文档（实时 vs 异步、索引/物化视图选型） | M-13 |
|
||
|
||
### UI/UX 设计师
|
||
|
||
| ID | 等级 | 任务 | 关联编号 |
|
||
|----|------|------|----------|
|
||
| UI-1 | 🟠 | 补 4 类复杂组件原型：Stepper/Wizard、PermissionTree、智能配房比对器、审批前置弹层 | M-09 |
|
||
| UI-2 | 🟠 | 补 UI_DESIGN/房源管理/楼盘列表_UI.md / 楼盘详情_UI.md（修复 TASK 引用） | M-09 |
|
||
| UI-3 | 🟠 | 客源关键浮层独立原型：US-CLIENT-007/011/012/015/020 | M-09 |
|
||
|
||
---
|
||
|
||
## 十、结论
|
||
|
||
### 是否可进入开发阶段
|
||
|
||
**否，必须先解决 4 个 Blocker**：
|
||
|
||
| 编号 | Blocker | 影响范围 |
|
||
|------|---------|----------|
|
||
| B-01 | 系统配置 PRD 空骨架 | 阻塞 9 条 P0/P1 任务（US-SETTING-001/010~012/020~023） |
|
||
| B-02 | 核心枚举三方不一致 | 阻塞客源/房源全部 CRUD 模块（US-CLIENT-* / US-PROPERTY-*） |
|
||
| B-03 | 权限档位冲突 | 阻塞权限模块（US-PERMISSION-001~005） |
|
||
| B-04 | Keyset 分页缺失 | 阻塞高基数列表查询（US-PROPERTY-002 / US-CLIENT-002） |
|
||
|
||
**可立即并行启动的部分**：
|
||
- 公共 Schema（`tenants`、`platform_admins`、`audit_logs`）开发——文档完整，无 Blocker。
|
||
- 楼盘/区域/学校 CRUD——DATA_MODEL_COMPLEX 完整、4 类锁字段已建，主流程清晰（解锁规则可后置补充）。
|
||
- Electron 客户端框架搭建——TECH_STACK §8 决策已封闭（但发布签名机制 M-06 需在 RC 前补齐）。
|
||
- 登录模块（accounts App）——文档完整（含 Redis Key 规范），仅需在多租户场景下补 fakeredis 测试基线。
|
||
- UI 静态原型实施——核心 5 页已有 HTML 原型可直接转 HTMX 模板。
|
||
|
||
**必须延后的部分**：
|
||
- 系统配置模块（B-01 解除前）。
|
||
- 权限模块（B-03 解除前）。
|
||
- 房源/客源高基数列表查询（B-04 解除前；可先实施 OFFSET 分页，但需排期重构）。
|
||
- 89k 性能 AC 验收（M-05 解除前，AC 不可测）。
|
||
|
||
### 文档体系成熟度评分（与昨日对比）
|
||
|
||
| 维度 | 今日 | 昨日 | 变化 | 说明 |
|
||
|------|------|------|------|------|
|
||
| PRD 业务清晰度 | 7.5/10 | 8.5/10 | ↓ | 新发现枚举塌方 + 系统配置空骨架 |
|
||
| DATA_MODEL 落地深度 | 8.5/10 | 8/10 | ↑ | 楼盘锁字段、价格走势、租户注销已落地 |
|
||
| TECH_STACK 完整性 | 6/10 | 6/10 | — | 三大横切规范仍未补 |
|
||
| UI/UX 系统化 | 7/10 | 5/10 | ↑↑ | UI_DESIGN 原型显著启动 |
|
||
| 跨文档一致性 | 5.5/10 | 6.5/10 | ↓ | 枚举塌方拉低评分 |
|
||
| 多租户隔离严谨度 | 7.5/10 | 7.5/10 | — | Redis Key 部分修复但未统一 |
|
||
| 测试可执行性 | 5/10 | (未评估) | 🆕 | 测试规范与 django-tenants 工作模式冲突 |
|
||
| **整体** | **6.8/10** | **7/10** | ↓ 0.2 | 新发现风险大于已修复风险，但绝对水平仍属"中等偏上" |
|
||
|
||
**结论**：本次 Review 的实质性进展（UI 启动、租户注销 SOP、楼盘锁字段）值得肯定，但**枚举塌方**和**测试规范多租户冲突**是新发现的系统性风险，必须在编码启动前优先治理。在 4 个 Blocker 解除 + 6 项核心 Major 修复后，整体成熟度可重回 8.0+。
|
||
|
||
---
|
||
|
||
## 附录 A：本次 Review 涵盖文档
|
||
|
||
### PRD（8 份）
|
||
- `PRD/PRD_MVP.md` v1.0
|
||
- `PRD/TASK.md`（834 行）
|
||
- `PRD/房源管理/房源管理模块PRD.md` v2.1（1881 行）
|
||
- `PRD/房源管理/楼盘管理模块PRD.md`
|
||
- `PRD/客源管理/客源管理模块PRD.md` v1.4（2050 行）
|
||
- `PRD/权限管理/权限管理模块PRD.md` v1.1
|
||
- `PRD/组织人事管理/组织人事管理模块PRD.md` v1.2
|
||
- `PRD/系统管理/系统管理模块PRD.md` v1.0
|
||
- `PRD/登录管理/用户登录管理模块PRD.md` v1.4
|
||
- `PRD/发布管理/客户端发布管理模块PRD.md` v1.0
|
||
- `PRD/系统配置/系统配置.md`（128 行骨架）
|
||
|
||
### DATA_MODEL（8 份）
|
||
- `DATA_MODEL/DATA_MODEL.md` v1.3、`DATA_MODEL_PUBLIC.md`、`DATA_MODEL_ORG.md`、`DATA_MODEL_COMPLEX.md`、`DATA_MODEL_PROPERTY.md`、`DATA_MODEL_CLIENT.md`、`DATA_MODEL_PERMISSION.md`、`DATA_MODEL_LOGIN.md`
|
||
|
||
### TECH_STACK（4 份）
|
||
- `TECH_STACK/TECH_STACK.md` v2.0
|
||
- `TECH_STACK/登录管理技术方案.md` v2.0
|
||
- `TECH_STACK/权限管理系统技术方案.md` v1.0
|
||
- `TECH_STACK/测试规范.md` v1.0
|
||
|
||
### UI_SYSTEM（3 份）
|
||
- `UI_SYSTEM/UI_SYSTEM.md` v1.2（1742 行）
|
||
- `UI_SYSTEM/组件清单.md`
|
||
- `UI_SYSTEM/组件规范设计.md`
|
||
|
||
### UI_DESIGN（10 份原型/设计稿）
|
||
- `UI_DESIGN/preview.html`、`客源列表_UI.html`、`客源详情_UI.html`、`房源列表_UI.html`、`新增客源_UI.html`、`编辑客源_UI.html`
|
||
- `UI_DESIGN/客源管理/客源列表_UI.md`、`客源详情_UI.md`、`新增客源_UI.md`、`编辑客源_UI.md`
|
||
- `UI_DESIGN/房源管理/房源列表_UI.md`
|
||
|
||
---
|
||
|
||
## 附录 B：问题汇总速查表
|
||
|
||
| ID | 等级 | 维度 | 责任人 | 简述 | vs 昨日 |
|
||
|----|------|------|--------|------|---------|
|
||
| B-01 | 🔴 | PRD↔TASK | PM | 系统配置 PRD 空骨架 | ⚠️ P-02 升级 |
|
||
| B-02 | 🔴 | PRD↔Data↔TASK | PM+架构师 | 核心枚举三方不一致 | 🆕 新增 |
|
||
| B-03 | 🔴 | PRD↔Data | PM | 权限档位三档/五档冲突 | ⚠️ P-01 部分修复 |
|
||
| B-04 | 🔴 | TECH/Data | 架构师 | Keyset 分页规范缺失 | ⚠️ D-01 未修复 |
|
||
| M-01 | 🟠 | TECH/测试 | 架构师 | 测试规范与 django-tenants 冲突 | 🆕 新增 |
|
||
| M-02 | 🟠 | Data↔PRD | 架构师+PM | 主表乐观锁/楼盘锁规则缺失 | ⚠️ D-02 部分修复 |
|
||
| M-03 | 🟠 | Data | 架构师 | 高写入表分区 DDL 未落地 | ⚠️ D-04 未修复 |
|
||
| M-04 | 🟠 | TECH/多租户 | 架构师 | Celery/R2/索引矩阵三大横切规范 | ⚠️ T-01/T-02/T-03 未修复 |
|
||
| M-05 | 🟠 | NFR↔TECH↔测试 | PM+架构师 | 89k <2 秒 AC 不可测 | 🆕 新增（含昨 P-04） |
|
||
| M-06 | 🟠 | 安全 | 架构师 | 客户端发布无防降级/签名 | 🆕 新增 |
|
||
| M-07 | 🟠 | PRD | PM | 楼盘合并/申请流程占位 | 🆕 新增 |
|
||
| M-08 | 🟠 | PRD/Data | PM+架构师 | 客源新房/租房字段未冻结 + market_quotes 缺 + 转公 job 不完整 | 部分新增 |
|
||
| M-09 | 🟠 | UI | UI/UX | 复杂组件 + 楼盘/客源浮层原型缺 | ⚠️ U-01/U-02/U-03 未修复 |
|
||
| M-10 | 🟠 | 多租户 | 架构师 | Redis Key 跨模块未统一前缀 | ⚠️ X-01 部分修复 |
|
||
| M-11 | 🟠 | 安全 | 架构师 | 加密密钥管理方案缺失 | ⚠️ S-01 未修复 |
|
||
| M-12 | 🟠 | 合规 | PM+架构师 | RPO 缺 + tenants.status=failed 状态机断链 | 🆕 新增 |
|
||
| M-13 | 🟠 | 性能 | 架构师 | 智能配房算法路径未文档化 | ⚠️ P-11 未修复（升级） |
|
||
| M-14 | 🟠 | 维护 | PM | TASK.md PRD 锚点断链 | 🆕 新增 |
|
||
|
||
**合计**：🔴 4 / 🟠 14 = **18 项 Top 风险**（聚焦 Top 模式，未列入 Minor）
|
||
|
||
### 已关闭项（昨日 → 今日）
|
||
|
||
| 昨日编号 | 简述 | 关闭依据 |
|
||
| --------------- | ----------------------------------------- | ------------------------------------------------- |
|
||
| X-02 | 租户注销→导出→清除链路 | `PRD/系统管理` §189-227, §552-553 已落地完整生命周期 |
|
||
| U-06 | Wireframe 未启动 | UI_DESIGN/ 已产出 5 页 HTML + 5 份 md 设计稿 |
|
||
| 楼盘 4 类锁字段 | DATA_MODEL_COMPLEX 缺 lock_* 字段 | `DATA_MODEL_COMPLEX.md:194-197` 已建（业务规则待补，转 M-02） |
|
||
| 楼盘价格走势表 | DATA_MODEL_COMPLEX 缺 complex_price_trends | `DATA_MODEL_COMPLEX.md:376` 已建 |
|
||
| 登录 Redis Key 规范 | 跨模块未统一 | 登录方案 §九已建 ✅；统一 schema 前缀仍待办（转 M-10） |
|
||
|
||
---
|
||
|
||
*Report Generated: 2026-04-26 by AI Reviewer*
|
||
*基线版本：REVIEW_全局_2026-04-25.md*
|