Files

weishen 3b6697df35 Sync: add workflow registry and review notes

2026-04-25 08:02:41 +08:00

30 KiB

Raw Blame History

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：

🔴 P-01 权限范围档位冲突：必须先在 PRD 锁定，否则 staff_data_scopes 表是否生效不明，权限模块无法开工。
🔴 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

30 KiB Raw Blame History Unescape Escape