From 3b6697df357f8de71cd4fb9e06721b6678b0668d Mon Sep 17 00:00:00 2001 From: weishen Date: Sat, 25 Apr 2026 08:02:41 +0800 Subject: [PATCH] Sync: add workflow registry and review notes --- .../fonrey/REVIEW/REVIEW_全局_2026-04-25.md | 441 ++++++++++++++++++ wiki/concepts/Handoff-Contract.md | 39 ++ wiki/concepts/Observable-States.md | 30 ++ wiki/concepts/Workflow-Registry.md | 44 ++ wiki/concepts/Workflow-Tree-Spec.md | 45 ++ wiki/index.md | 6 +- wiki/log.md | 9 + wiki/overview.md | 1 + .../healthcare-marketing-compliance.md | 69 +++ .../sources/specialized-workflow-architect.md | 58 +++ 10 files changed, 741 insertions(+), 1 deletion(-) create mode 100644 Project/fonrey/REVIEW/REVIEW_全局_2026-04-25.md create mode 100644 wiki/concepts/Handoff-Contract.md create mode 100644 wiki/concepts/Observable-States.md create mode 100644 wiki/concepts/Workflow-Registry.md create mode 100644 wiki/concepts/Workflow-Tree-Spec.md create mode 100644 wiki/sources/healthcare-marketing-compliance.md create mode 100644 wiki/sources/specialized-workflow-architect.md diff --git a/Project/fonrey/REVIEW/REVIEW_全局_2026-04-25.md b/Project/fonrey/REVIEW/REVIEW_全局_2026-04-25.md new file mode 100644 index 00000000..6ee5084f --- /dev/null +++ b/Project/fonrey/REVIEW/REVIEW_全局_2026-04-25.md @@ -0,0 +1,441 @@ +# 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* diff --git a/wiki/concepts/Handoff-Contract.md b/wiki/concepts/Handoff-Contract.md new file mode 100644 index 00000000..6f05b242 --- /dev/null +++ b/wiki/concepts/Handoff-Contract.md @@ -0,0 +1,39 @@ +--- +title: "Handoff Contract" +type: concept +tags: [workflow, system-integration, contract, reliability] +last_updated: 2026-04-25 +--- + +## Definition +交接合同——两个系统、服务或 Agent 之间每次交接时必须明确定义的接口规范，确保交接的每个环节都有明确的成功/失败/超时约定，防止隐式假设导致级联故障。 + +## Contract Elements（合同要素） + +``` +HANDOFF: [From] -> [To] + PAYLOAD: { field: type, field: type, ... } + SUCCESS: { field: type, ... } + FAILURE: { error: string, code: string, retryable: bool } + TIMEOUT: Xs — treated as FAILURE + ON FAILURE: [recovery action] +``` + +### 字段说明 + +| 字段 | 说明 | +|------|------| +| `PAYLOAD` | 交接时传递的数据结构，必须包含类型注解 | +| `SUCCESS` | 成功时的返回数据结构 | +| `FAILURE` | 失败时的标准错误格式（含错误码和可重试标识）| +| `TIMEOUT` | 超时阈值，超时视为失败 | +| `ON FAILURE` | 失败后的恢复动作（重试、清理、escalation）| + +## Why It Matters +没有显式交接合同的工作流边界是最常见的故障来源： +- 服务 A 假设服务 B 总是返回某个字段，但 B 偶尔不返回 → 静默故障 +- 超时值未约定，一方认为 5s 合理，另一方认为 30s 才够 → 不匹配 +- 失败后未约定恢复动作，部分场景重试有效，部分场景重试造成数据重复 + +## Source +- [[specialized-workflow-architect]]（Workflow Architect Agent） diff --git a/wiki/concepts/Observable-States.md b/wiki/concepts/Observable-States.md new file mode 100644 index 00000000..34455d37 --- /dev/null +++ b/wiki/concepts/Observable-States.md @@ -0,0 +1,30 @@ +--- +title: "Observable States" +type: concept +tags: [workflow, observability, system-modeling] +last_updated: 2026-04-25 +--- + +## Definition +可观察状态——每个工作流状态（快乐路径中的每一步 + 每个失败模式）必须同时从四个视角描述系统当前状态，确保客户、运维、数据库和日志各方都能准确感知系统发生了什么。 + +## Four Dimensions（四维度） + +| 维度 | 描述 | 示例 | +|------|------|------| +| **Customer View** | 当前客户在 UI 上看到什么 | 加载中 / "处理中..." / 空白 / 错误提示 | +| **Operator View** | 运维/管理员在管理面板看到什么 | 实体处于"处理中"状态 / 任务步骤显示 "step_3_running" | +| **Database View** | 数据库中数据当前状态 | `job.status = "running"`, `job.current_step = "step_1"` | +| **Log View** | 系统日志当前记录了什么 | `[order-service] step 1 started entity_id=abc123` | + +## Why Four Dimensions? +单一视角不足以支撑调试和运维： +- **只有 Customer View**：运维无法知道后台发生了什么 +- **只有 Database View**：客户不知道自己看到了什么 +- **只有 Log View**：没有结构化数据支撑告警和审计 +- **只有 Operator View**：缺乏原始数据记录 + +四个维度必须同步更新、互相印证，构成完整的可观测性闭环。 + +## Source +- [[specialized-workflow-architect]]（Workflow Architect Agent） diff --git a/wiki/concepts/Workflow-Registry.md b/wiki/concepts/Workflow-Registry.md new file mode 100644 index 00000000..0530b203 --- /dev/null +++ b/wiki/concepts/Workflow-Registry.md @@ -0,0 +1,44 @@ +--- +title: "Workflow Registry" +type: concept +tags: [workflow, documentation, system-modeling] +last_updated: 2026-04-25 +--- + +## Definition +工作流注册表——系统所有工作流的权威参考指南，以四个交叉索引视角组织，确保任何角色（工程师、运维、产品负责人、AI Agent）都能从任意角度快速查找所需工作流。 + +## Four Views（四视角） + +### View 1: By Workflow（按工作流，主列表） +| 字段 | 说明 | +|------|------| +| Workflow | 工作流名称 | +| Spec file | 规范文件名 | +| Status | Approved / Review / Draft / **Missing** / Deprecated | +| Trigger | 触发条件 | +| Primary actor | 主要执行者 | +| Last reviewed | 最近审查日期 | + +> **Missing** = 代码中存在但无规范，红色警报，立即暴露。 + +### View 2: By Component（按组件） +每个代码组件映射到其参与的所有工作流。工程师查看任意文件时，可立即知道哪些工作流涉及该文件。 + +### View 3: By User Journey（按用户旅程） +每条用户旅程映射到其背后的底层工作流，含客户旅程/运营旅程/系统间旅程。 + +### View 4: By State（按状态） +每个实体状态映射到能转入或转出的工作流。 + +## Maintenance Rules +- 每发现或规范一个新工作流必须更新注册表（强制） +- Missing 状态的工作流视为红色警报，需在下一轮审查中处理 +- 四个视角必须交叉引用一致 +- Draft 升为 Approved 时必须同步更新注册表 +- 永不删除行——使用 Deprecated 而非删除以保留历史 + +## Related +- [[Workflow-Tree-Spec]]（规范格式） +- [[Discovery-Audit]]（发现隐式工作流的方法） +- [[Observable-States]]（每个工作流状态的可见性） diff --git a/wiki/concepts/Workflow-Tree-Spec.md b/wiki/concepts/Workflow-Tree-Spec.md new file mode 100644 index 00000000..10942ef2 --- /dev/null +++ b/wiki/concepts/Workflow-Tree-Spec.md @@ -0,0 +1,45 @@ +--- +title: "Workflow Tree Spec" +type: concept +tags: [workflow, specification, documentation, quality-assurance] +last_updated: 2026-04-25 +--- + +## Definition +工作流树规范格式——为每个工作流生成的结构化规范文档，工程师可直接依据实现，QA 可直接导出测试用例，运维可理解系统行为，产品负责人可验证需求是否满足。 + +## Required Sections（必须章节） + +1. **Overview**：2-3 句话描述工作流目标、触发者和产出 +2. **Actors**：参与此工作流的所有角色（人/系统/Agent） +3. **Prerequisites**：工作流启动前必须满足的条件 +4. **Trigger**：触发来源（用户操作/API调用/定时任务/事件） +5. **Workflow Tree**：每步的 Actor/Action/Timeout/Input/Output on SUCCESS/Output on FAILURE + Observable States +6. **ABORT_CLEANUP**：失败清理流程（含触发条件、清理动作顺序、客户视图、运维视图） +7. **State Transitions**：状态机转换图 +8. **Handoff Contracts**：每个系统边界的交接合同 +9. **Cleanup Inventory**：工作流创建的所有资源及其销毁方法 +10. **Reality Checker Findings**：规范与代码对照验证结果 +11. **Test Cases**：每个分支对应一个测试用例 +12. **Assumptions**：所有未经代码验证的假设 +13. **Open Questions**：待确认事项 + +## Branch Coverage（分支覆盖要求） +每个工作流规范必须覆盖 **7 类分支**： +1. 快乐路径（所有步骤成功，所有输入有效） +2. 输入验证失败（具体错误信息 + 客户看到什么） +3. 超时失败（每个步骤的超时值 + 超时后行为） +4. 瞬态失败（网络抖动/限流，可重试并退避） +5. 永久失败（无效输入/配额超限，立即失败并清理） +6. 部分失败（步骤7/12失败，已创建资源必须销毁） +7. 并发冲突（同一资源同时被创建/修改） + +## Status Lifecycle +``` +Draft → Review → Approved + ↑ + Reality Checker 验证（必须，不可跳过） +``` + +## Source +- [[specialized-workflow-architect]]（Workflow Architect Agent） diff --git a/wiki/index.md b/wiki/index.md index 7c339890..4a4195ff 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,6 +4,7 @@ - [Overview](overview.md) — living synthesis ## Sources +- [2026-04-24] [Workflow Architect Agent Personality](sources/specialized-workflow-architect.md) - [2026-04-24] [Government Digital Presales Consultant](sources/government-digital-presales-consultant.md) - [2026-04-24] [Agentic Identity & Trust Architect](sources/agentic-identity-trust.md) - [2026-04-24] [Document Generator Agent](sources/specialized-document-generator.md) @@ -412,7 +413,6 @@ - [2026-04-20] [specialized-cultural-intelligence-strategist](sources/specialized-cultural-intelligence-strategist.md) — (expected: wiki/sources/specialized-cultural-intelligence-strategist.md — source missing) - [2026-04-20] [healthcare-marketing-compliance](sources/healthcare-marketing-compliance.md) — (expected: wiki/sources/healthcare-marketing-compliance.md — source missing) - [2026-04-20] [llm-wiki](sources/llm-wiki.md) — (expected: wiki/sources/llm-wiki.md — source missing) -- [2026-04-20] [specialized-workflow-architect](sources/specialized-workflow-architect.md) — (expected: wiki/sources/specialized-workflow-architect.md — source missing) - [2026-04-20] [baoyu-skills](sources/baoyu-skills.md) — (expected: wiki/sources/baoyu-skills.md — source missing) - [Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog](sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md) — (expected: wiki/sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md — source missing) - [Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend](sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md) — (expected: wiki/sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md — source missing) @@ -1017,6 +1017,7 @@ - [GPG-密钥验证](concepts/GPG-密钥验证.md) - [Green-Computing](concepts/Green-Computing.md) - [Hand-Tracking](concepts/Hand-Tracking.md) +- [Handoff-Contract](concepts/Handoff-Contract.md) - [HCX](concepts/HCX.md) - [Headless-服务器](concepts/Headless-服务器.md) - [Heartbeat-Monitoring](concepts/Heartbeat-Monitoring.md) @@ -1117,6 +1118,7 @@ - [Nitro-System](concepts/Nitro-System.md) - [Normal-Change](concepts/Normal-Change.md) - [NVMe硬盘分区](concepts/NVMe硬盘分区.md) +- [Observable-States](concepts/Observable-States.md) - [Obsidian-Agent-Client](concepts/Obsidian-Agent-Client.md) - [Obsidian-Bases](concepts/Obsidian-Bases.md) - [Obsidian-CLI](concepts/Obsidian-CLI.md) @@ -1320,6 +1322,8 @@ - [What-If-Simulation](concepts/What-If-Simulation.md) - [WinThemes](concepts/WinThemes.md) - [Workflow-Engineering](concepts/Workflow-Engineering.md) +- [Workflow-Registry](concepts/Workflow-Registry.md) +- [Workflow-Tree-Spec](concepts/Workflow-Tree-Spec.md) - [Workspace](concepts/Workspace.md) - [X11](concepts/X11.md) - [Xinchuang](concepts/Xinchuang.md) diff --git a/wiki/log.md b/wiki/log.md index 3a11e86e..be57ffda 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,3 +1,12 @@ +## [2026-04-25] ingest | Workflow Architect Agent Personality +- Source file: Agent/agency-agents/specialized/specialized-workflow-architect.md +- Status: ✅ 成功摄入 +- Summary: Workflow Architect——The Agency Specialized 部门的工作流设计专家 Agent，负责在代码编写前穷举建模系统所有路径。核心交付物：四视角工作流注册表（按工作流/按组件/按用户旅程/按状态）+ 工作流树规范格式（覆盖快乐路径+七类失败分支）+ 交接合同（Handoff Contract）+ 清理清单（Cleanup Inventory）。关键原则：不只为快乐路径设计，每个系统边界定义显式交接合同，Reality Checker 验证是 Draft 升为 Approved 的前置条件。Agent 协作协议：Reality Checker 验证→Backend Architect 实现→API Tester 生成测试用例→DevOps Automator 验证清理顺序。与 [[Designing-for-Agentic-AI]] 存在潜在冲突（确定性要求 vs LLM 概率性），已在 Contradictions 中记录。 +- Concepts created: [[Workflow-Registry]]（四视角工作流注册表）、[[Observable-States]]（四维度可观察状态）、[[Handoff-Contract]]（系统边界交接合同）、[[Workflow-Tree-Spec]]（结构化工作流树规范格式） +- Entities created: （Backend Architect/Reality Checker/API Tester/DevOps Automator/Security Engineer 在当前 sources 中出现次数均 < 2，暂不创建 Entity 页面） +- Source page: wiki/sources/specialized-workflow-architect.md +- Notes: index.md 中原有 "source missing" 条目，本次摄入后已更新为完整条目并修正日期。overview.md Specialized 部门新增 Workflow Architect 条目。Concept 页面创建前已做去重检查，Workflow-Engineering（已存在，定义侧重 AI 执行流程 vs 本文档侧重工作流规范格式）保留原页面，新增页面侧重建模规范维度。 + ## [2026-04-25] ingest | Agentic Identity & Trust Architect（补充摄入） - Source file: Agent/agency-agents/specialized/agentic-identity-trust.md - Status: ✅ 补充摄入（source page 已存在，本次补充 Concept 页面） diff --git a/wiki/overview.md b/wiki/overview.md index f71e11bb..f7e11a6d 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -687,6 +687,7 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]] **[[government-digital-presales-consultant]]**（Government Digital Presales Consultant）：The Agency Specialized 部门的政府数字化售前专家——面向中国ToG（政府）市场，专注于数字政府、智慧城市、一网统管、城市大脑等主流方向的全生命周期售前支持。核心能力：政策解读（数字中国/国家数据局政策信号提取：区分"鼓励探索"与"全面实施"的政策成熟度判断）、合规架构（等保2.0三级/商用密码评估/信创适配）、招投标全流程（需求调研→方案设计→POC验证→标书撰写→述标答辩→中标交接）。五步工作流配合技术方案模板、等保合规矩阵、投标检查清单、机会评估模板等交付物。关键原则：**技术方案必须以业务场景驱动**（"市民服务处理速度提升80%"而非"微服务架构"）；**等保/密评/信创是强制项而非加分项**；方案至少经过三轮迭代打磨。成功指标：中标率>40%、零废标、售前到交付偏差<10%。与 [[sales-engineer]]（通用售前）互补——后者覆盖企业级B2B市场，前者专精中国政府ToG市场特有的政策合规与采购流程；与 [[Digital-Government]]（数字政府）和 [[Smart-City]]（智慧城市）构成完整的政府信息化知识体系。属 The Agency Specialized 部门的垂直行业方向。 +|**[[specialized-workflow-architect]]**（Workflow Architect）：工作流设计专家 Agent——The Agency Specialized 部门的工作流设计与系统建模专家，在代码编写前对系统所有路径进行穷举建模。核心职责：**工作流发现**（扫描 route/worker/migration/IaC/cron 文件找出隐式工作流）+ **工作流注册表维护**（四视角：按工作流/按组件/按用户旅程/按状态）。核心交付物：**工作流树规范格式**（含 Actor/Prerequisites/Trigger/Step 树/ABORT_CLEANUP/State Transitions/Cleanup Inventory/Test Cases/Assumptions），覆盖快乐路径+七类失败分支（输入验证/超时/瞬态/永久/部分失败/并发冲突）。关键原则：**不只为快乐路径设计**、**每个系统边界定义显式 Handoff Contract**（payload schema + 成功/失败响应 + 超时值 + 恢复动作）、**Reality Checker 验证是 Draft 升为 Approved 的前置条件**。Agent 协作协议：Reality Checker 验证规范→Backend Architect 实现代码→API Tester 生成测试用例→DevOps Automator 验证清理顺序。属 The Agency Specialized 部门的质量保障基础设施，与 [[specialized-civil-engineer]]（基础设施工程）同属 Specialized 专业 Agent 系列。 ## Conflict Areas 1. **Kanban vs Event Sourcing**: Kanban emphasizes visual team collaboration; Event Sourcing emphasizes auto-tracking and context preservation. **[[Project State Management]]**（事件驱动看板替代方案）vs 传统 PM 工具。核心差异：手动拖拽 vs 自然语言输入；静态快照 vs 全历史保留；无上下文 vs 完整决策链。**[[Event Sourcing]]** 在此上下文中指将项目变更存储为事件序列，每次 progress/blocker/decision/pivot 均持久化，保留完整决策上下文。 diff --git a/wiki/sources/healthcare-marketing-compliance.md b/wiki/sources/healthcare-marketing-compliance.md new file mode 100644 index 00000000..41b6d69a --- /dev/null +++ b/wiki/sources/healthcare-marketing-compliance.md @@ -0,0 +1,69 @@ +--- +title: "Healthcare Marketing Compliance Specialist" +type: source +tags: [] +date: 2026-04-20 +--- + +## Source File +- [[Agent/agency-agents/specialized/healthcare-marketing-compliance.md]] + +## Summary（用中文描述） +- 核心主题：医疗营销合规专家 Agent，覆盖中国医疗健康领域（药品/医疗器械/医美/保健食品/互联网医疗）全品类营销合规 +- 问题域：医疗健康企业在品牌推广、内容营销、学术推广中的合规边界；平台内容审核规则；患者隐私保护 +- 方法/机制：以《广告法》《医疗广告管理办法》《互联网广告管理办法》为核心监管框架，建立"三级审查机制"（法务初审→合规复审→终审发布）；风险分级矩阵（Critical/High/Medium/Low）；违规应急响应流程（2小时下架→24小时报告→72小时审计） +- 结论/价值：合规不是"堵营销"，而是"保护品牌"——一次违规处罚的代价远高于合规投入 + +## Key Claims（用中文描述） +- 医疗广告必须经省级卫生行政部门审查并取得《医疗广告审查证明》，否则不得发布——这是行政出发乃至刑事追责的底线 +- 处方药严禁在大众媒体（电视/广播/报纸/互联网）发布广告——任何隐性推广均面临严厉处罚 +- 保健食品不得声称具有治疗功能——这是行业内处罚最高频的违规原因 +- 医美广告不得制造"容貌焦虑"——2021年起市场监管总局执法力度显著加强 +- 患者健康数据属于《个人信息保护法》认定的"敏感个人信息"——违规最高罚款5000万元或上年度营收5% + +## Key Quotes +> "医疗广告必须审查后方可发布——这是行政处罚乃至刑事追责的底线。" — 广告法第46条核心要求 +> "保健食品不得声称治病功能，必须标注'保健食品不是药物，不能替代药物治疗疾病'。" — 蓝帽子标识管理制度核心声明 +> "合规不是'堵营销'，而是'保护品牌'。一次违规处罚的代价远高于合规投入。" — Agent 核心合规文化理念 +> "医美日记类内容无论是否由用户'自愿'分享，平台和诊所均可被追究连带责任。" — 小红书医美合规红线 + +## Key Concepts +- [[Healthcare-Marketing-Compliance]]：医疗健康营销全品类（药品/器械/医美/保健食品/互联网医疗）合规框架 +- [[Medical-Advertisement-Review]]：《医疗广告审查证明》制度——广告发布前必须获得省级卫生行政部门审查 +- [[Three-Tier-Review-Mechanism]]：企业内部三级审查机制（法务初审→合规复审→终审发布） +- [[OTC-Drug-Marketing]]：非处方药大众媒体广告规则——必须包含"请按照药品说明书或药师指导下使用"等咨询语句 +- [[Prescription-Drug-Restrictions]]：处方药大众媒体广告禁令——仅限在医药专业期刊发布 +- [[Medical-Device-Classification]]：医疗器械三类分级管理制度（I类备案/II类注册/III类严格审批） +- [[Blue-Hat-Logo]]：保健食品"蓝帽子"注册标志——合法保健食品必须取得并展示 +- [[Appearance-Anxiety]]：容貌焦虑——医美广告2021年起明确禁止制造焦虑情绪的表述 +- [[Internet-Diagnosis-Treatment]]：互联网诊疗规范——初诊必须线下面诊，复诊限常见病/慢性病 +- [[Patient-Privacy-PIPL]]：《个人信息保护法》将个人健康医疗信息认定为敏感信息，须单独授权 +- [[Academic-Detailing]]：学术推广合规——医疗代表备案、会议赞助标准、医师讲课费规范 +- [[Platform-Content-Review]]：平台内容审核机制——抖音/小红书/微信各有行业准入标准和内容红线 +- [[Compliance-Risk-Matrix]]：医疗营销合规风险分级矩阵（Critical/High/Medium/Low + 处置建议） + +## Key Entities +- [[NMPA]]（国家药品监督管理局）：负责药品/医疗器械注册审批及广告批准文号管理 +- [[SAMR]]（国家市场监督管理总局）：2021年发布《医疗美容广告执法指南》，主导医美合规整治 +- [[Haodf]]（好大夫在线）：互联网医疗平台——医师入驻资质审核、患者评价管理、图文/视频问诊标准 +- [[DXY]]（丁香园）：医师专业社区——健康科普内容专业审核机制、医师认证体系、商业合作与编辑独立性分离 +- [[WeDoctor]]（微医）：互联网医院牌照、在线处方流转、医保接入合规 +- [[JD-Health]]（京东健康）：在线售药资质、处方药审核流程、物流配送合规 +- [[Douyin]]（抖音）：医疗行业准入（须提交医疗机构执业许可证或药械资质）、认证医师标识、直播带货限制 +- [[Xiaohongshu]]（小红书）：2021年起大规模清理医美内容、白名单管理制度、蒲公英品牌合作平台合规要求 +- [[WeChat]]（视频号）：医疗机构公众号认证、朋友圈广告投放规范、小程序在线问诊/售药资质要求 + +## Connections +- [[Healthcare-Marketing-Compliance]] ← extends ← [[The-Agency]]（Specialized 部门） +- [[Healthcare-Marketing-Compliance]] ← depends_on ← [[NMPA]]（监管机构） +- [[Healthcare-Marketing-Compliance]] ← depends_on ← [[SAMR]]（执法机构） +- [[Platform-Content-Review]] ← extends ← [[Healthcare-Marketing-Compliance]] +- [[Patient-Privacy-PIPL]] ← depends_on ← [[Healthcare-Marketing-Compliance]] +- [[Academic-Detailing]] ← extends ← [[Healthcare-Marketing-Compliance]] + +## Contradictions +- 与 [[legal-compliance-checker]] 潜在冲突： + - 冲突点：通用法律合规 Agent 与医疗专项合规 Agent 的职责边界 + - 当前观点：医疗营销合规具有高度专业化特征（广告法/药械注册/平台规则），通用法律合规工具无法覆盖 + - 对方观点：合规 Agent 应具备跨行业通用合规框架，无需细分至医疗领域 + - 解决方向：通用合规 Agent 负责数据隐私/合同合规等横向能力，医疗营销合规 Agent 专注垂直领域规则差异 diff --git a/wiki/sources/specialized-workflow-architect.md b/wiki/sources/specialized-workflow-architect.md new file mode 100644 index 00000000..f71207e3 --- /dev/null +++ b/wiki/sources/specialized-workflow-architect.md @@ -0,0 +1,58 @@ +--- +title: "Workflow Architect Agent Personality" +type: source +tags: [] +date: 2026-04-25 +--- + +## Source File +- [[Agent/agency-agents/specialized/specialized-workflow-architect.md]] + +## Summary（用中文描述） +- 核心主题：Workflow Architect——工作流设计专家 Agent，负责在代码编写前对系统所有路径进行穷举建模与规范输出。 +- 问题域：隐式工作流（代码中存在但无规范）、分支缺失、故障恢复路径未定义、系统边界交接合同模糊、代码与规范漂移。 +- 方法/机制：工作流注册表（四视角）、工作流树规范格式（覆盖快乐路径+所有失败分支+清理清单）、交接合同规范、发现审计清单、Reality Checker 交叉验证、Agent 协作协议。 +- 结论/价值：工程师可依据规范实现、QA 可直接生成测试用例、运维可理解系统行为、成功指标为零孤岛资源/假设表持续缩减。 + +## Key Claims（用中文描述） +- 代码中存在但无规范的工作流是隐患——它会在无人了解其全貌时被修改并导致故障。 +- 每一个系统边界（system boundary）必须定义显式 payload schema、成功响应、失败响应（含错误码）、超时值、故障恢复动作。 +- 每个工作流必须覆盖七类分支：快乐路径、输入验证失败、超时失败、瞬态失败、永久失败、部分失败、并发冲突。 +- 工作流状态必须同时回答四个维度：客户看到什么、运维看到什么、数据库中有什么、日志中有什么。 +- Reality Checker 验证是规范从 Draft 升为 Approved 的前置条件，不可跳过。 + +## Key Quotes +> "I do not design for the happy path only." — Workflow Architect 核心原则 + +> "A workflow that exists in code but not in a spec is a liability. It will be modified without understanding its full shape, and it will break." — 发现即记录，不问是否被要求 + +> "Every step that depends on something else being already done is a potential race condition." — 命名时序假设 + +## Key Concepts +- [[Workflow-Registry]]：四视角交叉索引工作流注册表（按工作流/按组件/按用户旅程/按状态），维护所有工作流状态（Approved/Review/Draft/Missing/Deprecated） +- [[Observable-States]]：每个工作流状态必须同时描述客户视图、运维视图、数据库视图、日志视图 +- [[Handoff-Contract]]：系统边界交接合同——定义显式 payload schema、成功/失败响应、超时值、恢复动作 +- [[Workflow-Tree-Spec]]：结构化工序树规范格式，含 Actor/Prerequisites/Trigger/Step 树/ABORT_CLEANUP/State Transitions/Cleanup Inventory/Test Cases/Assumptions +- [[Cleanup-Inventory]]：完整资源销毁清单，每项资源必须有对应清理动作 +- [[Discovery-Audit]]：发现审计清单——扫描所有 route/worker/migration/IaC/cron/event-listener/webhook 文件找出隐式工作流 +- [[Reality-Checker]]：规范验证流程，由 Reality Checker Agent 将规范与实际代码对照，报告差距 + +## Key Entities +- [[Backend-Architect]]：工作流规范依赖 Backend Architect 实现具体代码；工作流揭示实现缺陷时向其发起修复协作 +- [[Reality-Checker]]：每次 draft 完成后、标记 Review 前必须执行的代码验证 Agent；报告 Reality Checker Findings +- [[API-Tester]]：规范 Approved 后接收工作流规范，生成全部测试用例 +- [[DevOps-Automator]]：工作流揭示基础设施销毁顺序需求时协作；验证 IaC 销毁顺序是否符合规范 +- [[Security-Engineer]]：工作流涉及凭证/密钥/认证/外部 API 调用时必须发起安全审查 + +## Connections +- [[Reality-Checker]] ← verifies ← [[Workflow-Tree-Spec]]（规范 vs 代码差距验证） +- [[Backend-Architect]] ← implements ← [[Workflow-Tree-Spec]]（实现具体代码） +- [[API-Tester]] ← generates test cases from ← [[Workflow-Tree-Spec]]（从规范导出测试用例） +- [[DevOps-Automator]] ← maintains ← [[Cleanup-Inventory]]（验证销毁顺序） +- [[Security-Engineer]] ← reviews ← [[Handoff-Contract]]（凭证传递安全性审查） + +## Contradictions +- 与 [[Designing-for-Agentic-AI]] 潜在冲突： + - 冲突点：工作流规范要求确定性（每个分支必须精确描述），而 LLM 本质为概率性模型 + - 当前观点：LLM 相关行为（如自然语言理解）通过概率模型处理；工作流规范聚焦于确定性的业务流程与系统边界，而非 LLM 推理过程 + - 对方观点：[[Designing-for-Agentic-AI]] 强调 LLM 的概率性和不确定性