代码架构优化顾问

结构优化方案

以下方案在不改变现有数据库主 Schema 与 REST v1 接口的前提下，明确模块边界，统一横切能力，建立事件驱动的解耦机制，优先化解“通知/计费侵入任务流”和“服务间环形依赖”两大问题。

• 目标模块划分与职责（面向领域，单向依赖）

  1. 身份与租户（Identity & Tenant）
     • 租户、用户、组织、RBAC 策略与角色绑定
     • 多租户隔离与鉴权上下文的解析/校验
  2. 项目与成员（Project & Membership）
     • 项目、迭代、项目成员关系与权限校验入口
     • 项目级配额入口（从计费读取只读能力）
  3. 工作域（Work）
     • 任务、子任务、评论、附件（文件元信息与预览指引）
     • @提及解析、状态流转、看板与甘特的领域规则
     • 域事件源头（TaskCreated/Updated, CommentAdded 等）
  4. 通知聚合器（Notifications）
     • 通道编排（邮件/站内/Webhook），模板选择与去重合并
     • 可靠投递与重试、节流/频率控制、用户偏好与免打扰
     • 对 Work/Billing 等领域事件的订阅者
  5. 计费订阅与配额（Billing）
     • 订阅生命周期（试用/激活/降级）、成员计量、特性开关
     • 配额与能力查询（只读能力提供者），写入只限计费自有表
     • 异步响应（降级、额度预警）通过事件与通知沟通
  6. 报表与分析（Reporting）
     • ES 查询与预计算（事件驱动的投影/物化视图）
     • 统计 API 只读，对上游完全无回写
  7. 集成与 Webhook（Integrations）
     • 出站 Webhook、第三方回调验签、退避与死信
     • 用统一事件订阅机制触发
  8. 平台层（Platform）- 横切能力收敛
     • 日志/审计、缓存、配置、限流、队列/事件总线、请求上下文
     • 认证鉴权中间件、幂等与去重、外部邮件客户端/ES/Redis 适配
     • 统一的错误与可观测性（Tracing/Metric）

• 分层与交互原则（自上而下单向）

  • Interface 层：现有 controllers 保持 REST v1，不直接触达 models
  • Application 层（每个领域模块内的编排服务）：组合用例、事务边界、发出领域事件；不得相互直接调用其他模块的 Application/Service
  • Domain 层：领域服务、实体规则、策略（尽量无基础设施依赖）
  • Infrastructure 层（每模块私有）：Repository（封装 Sequelize 模型）、外部适配器（ES/Redis/邮件/队列）
  • Platform 层：横切能力统一入口；业务模块不得直接使用 common 下的工具（逐步迁移）

• 领域事件与数据流（消除服务环、缩短调用链）

  • 事件总线：在单体内先用进程内发布/订阅，统一接口对接 Bull 队列以异步处理
  • 核心事件（示例）：ProjectCreated, IterationStarted, TaskCreated/Updated/Moved, CommentAdded, FileAttached, MentionDetected, SubscriptionActivated/Expired, QuotaThresholdReached, ReportMaterialized
  • 事件消费者：Notifications、Reporting、Integrations、Billing（仅用于自身状态转换，不回写他域）
  • 读多写少优化：读路径尽量走 ES/缓存/物化视图，写路径小事务化并异步联动

• DTO 与仓储（Repository）边界

  • DTO：每个模块对外定义输入/输出 DTO，严禁传出 ORM 模型实例
  • Repository：每模块拥有自己的仓储，外部不得直接访问其 models；Billing 不再直读写用户/项目模型，只能通过 Project & Membership 提供的只读查询接口或预计算视图（保持 Schema 不变的前提下可用视图/只读投影表）
  • Anti-Corruption Layer：将 common/utils/email 折叠进入 Notifications 的渠道适配器；其他模块通过 Notifications 的应用服务或事件交互，禁止直接发邮件

• 缓存/ES/队列的统一入口

  • CacheFacade：提供 Key 规范、TTL 策略、租户隔离；禁止业务模块直连 Redis
  • SearchFacade：Reporting 独占对 ES 的写入，其他模块只发事件
  • EventBus/Outbox：Application 层写业务数据与 outbox 同事务，确保至少一次投递

• 授权与配额的“只读能力”注入

  • CapabilityProvider（由 Billing 提供只读接口）：特性开关、成员配额、试用状态
  • 工作域/项目域在入站用例边界做“允许/拒绝”判定；不在用例内部做计费写入
  • 降级与变更通过事件驱动通知与渐进生效（避免写路径耦合）

依赖关系图

• 当前主要环与越界访问（简化）

graph LR
  Controllers --> Services
  Services --> Models
  subgraph Current
    TaskService --> CommentService
    CommentService --> NotifyService
    NotifyService --> TaskService
    BillingService --> UserModel
    BillingService --> ProjectModel
    CommonEmail[(common/utils/email)]
    TaskService --> CommonEmail
    NotifyService --> CommonEmail
    BillingService --> CommonEmail
  end

• 目标依赖与模块边界（单向依赖、事件解耦）

graph LR
  subgraph Platform
    Platform[Platform: Log/Cache/Auth/EventBus/Outbox]
  end

  subgraph Interfaces
    Controllers[Controllers (REST v1)]
  end

  subgraph ProjectMembership
    PM_App[Project & Membership Application]
    PM_Domain[Domain]
    PM_Repo[Repository]
  end

  subgraph Work
    W_App[Work Application]
    W_Domain[Domain]
    W_Repo[Repository]
  end

  subgraph Notifications
    N_App[Notifications Application]
    N_Domain[Domain]
    N_Adapters[Channels (Email/Webhook/InApp)]
  end

  subgraph Billing
    B_App[Billing Application]
    B_Domain[Domain]
    B_Repo[Repository]
    B_Cap[Capability Provider (Read-Only)]
  end

  subgraph Reporting
    R_App[Reporting Application]
    R_Proj[Projections/Materialization]
  end

  Controllers --> W_App
  Controllers --> PM_App
  Controllers --> B_App
  Controllers --> R_App
  Controllers --> N_App

  W_App --> W_Domain --> W_Repo
  PM_App --> PM_Domain --> PM_Repo
  B_App --> B_Domain --> B_Repo
  N_App --> N_Domain --> N_Adapters
  R_App --> R_Proj

  W_App -. publish .-> Platform
  PM_App -. publish .-> Platform
  B_App -. publish .-> Platform

  Platform -. subscribe .-> N_App
  Platform -. subscribe .-> R_App
  Platform -. subscribe .-> B_App

  W_App --> B_Cap
  PM_App --> B_Cap

  W_App --> Platform
  PM_App --> Platform
  B_App --> Platform
  N_App --> Platform
  R_App --> Platform

• 关键事件流示例（打散环、缩短请求链）
  • CommentAdded（Work 发布）→ Notifications 订阅并发送消息（异步）→ Reporting 投影更新
  • TaskCreated（Work 发布）→ Reporting 更新看板/甘特预计算
  • QuotaThresholdReached（Billing 发布）→ Notifications 发送预警 → Controllers 显示限流提示（读 CapabilityProvider）
  • SubscriptionExpired（Billing 发布）→ Work/Project 仅在入站用例处读能力并拒绝新建，不在写路径回写

重构策略

围绕“三阶段低风险重构”，每次迭代不超过 15% 开发量，蓝绿/灰度发布、零停机，保持 REST v1 与主 Schema 稳定。

• 第一阶段（2–4 周）：事件总线与 DTO 边界，消除服务环

  • 目标
    • 循环依赖清零（尤其 task–comment–notify 环）
    • 引入统一 EventBus 接口与 Outbox，建立 10+ 核心领域事件
    • 模块间转为事件驱动或通过 CapabilityProvider 的只读调用
  • 步骤
    1. 建立 Platform 层骨架：EventBus/Outbox、CacheFacade、标准日志与请求上下文；将 common/utils/email 注册为 Notifications 的渠道适配器对外暴露统一入口
    2. DTO 与仓储边界：为 Work/Notifications/Billing 定义对外 DTO；禁止 ORM 实例外泄；为 Billing 增加 CapabilityProvider（只读）
    3. 打散环路
       • CommentAdded 由 Work 发布事件，不再同步调 NotifyService
       • Notify 改为订阅 CommentAdded/TaskUpdated 等事件
       • 去除 Notify → Task 回调，将需要的 Task 最小信息放入事件或由 Notifications 读只读查询
    4. 计费解耦
       • Billing 禁止直接访问 User/Project 模型；仅使用 Project & Membership 的只读查询接口或视图/物化表
       • 用例入口在 Controllers→Application 读取 CapabilityProvider 判定可执行性（配额/特性）
    5. 测试与护栏
       • 为事件契约与 DTO 建立合约测试；为 Work 与 Notifications 的应用服务补齐单测
       • 静态检查：模块间引用白名单（如使用目录与 Lint 规则）拦截跨域访问
  • 风险与控制
    • 事件重复消费：引入幂等键（事件 ID + 版本）；Outbox 重试有上限与死信
    • 语义回归：先影子发布（事件订阅方双写日志比对），再切流
  • 验收度量
    • 循环依赖 0；相关路径单测覆盖提升到 40%+；关键 API 延迟下降 10%（通知异步化）

• 第二阶段（2–4 周）：收敛 common 与横切关注到 Platform，稳定读写路径

  • 目标
    • 横切能力统一（日志、缓存、鉴权、速率限制、审计）
    • 读路径性能与一致性改进，降低跨模块同步调用
  • 步骤
    1. 将 common 分解：日志/审计、配置、缓存、外部客户端（邮件/ES/Redis/队列）迁入 Platform；业务侧通过 Facade 使用
    2. Cache 策略标准化：Key 命名与 TTL 规范；热路径（任务详情、评论计数、项目成员列表）挂缓存；由事件驱动失效
    3. Reporting 投影化：对看板/甘特/统计建立事件投影作业，减少在线聚合；ES 写入仅通过 Reporting
    4. 审计与可观测：为跨模块用例统一埋点（Trace/Metric/Log），新增“模块边界跨越计数”与“事件滞留时间”监控
    5. 测试体系：为 Platform Facade 增加契约测试；集成测试替换部分真实 DB 场景为“仓储层”级别测试
  • 风险与控制
    • 缓存一致性：事件驱动失效优先；关键数据使用短 TTL + 读修复
    • 可观测开销：采样率控制，灰度验证
  • 验收度量
    • 单测覆盖 50%+（核心模块）；P95 降低至目标的 15% 改善；边界跨越计数下降

• 第三阶段（4–8 周，按波次）：渐进拆出通知与计费为独立包/服务

  • 拆分准则
    • API 稳定、事件契约稳定、依赖指向单向（仅订阅事件与只读提供能力）
    • 数据主权明确（Billing/Notifications 各自持有写入表；对他域只读）
  • 路线
    1. 先“内部分包”：将 Notifications 与 Billing 各自收敛为独立 npm 包（工作区），对外仅暴露应用服务与事件订阅入口
    2. 外部化适配：对邮件服务/Webhook/支付网关的外部客户端适配层下沉到各自包
    3. 可选“进程外化”：在保持 REST v1 不变的前提下，内部调用改为事件/HTTP 私有接口；通过 Outbox/Bull 做可靠通信；灰度影子流量对比
    4. 运维与回滚：蓝绿部署，开关化回切到“进程内包”实现
  • 风险与控制
    • 网络分布式带来的时序问题：事件版本化、幂等、防重入锁
    • 计费一致性：重要状态变更采用事务+Outbox，所有副作用通过事件
  • 验收度量
    • 发布回滚 < 5 分钟（开关 + 蓝绿），P95 再降 5%+（通知完全异步），业务迭代与发布风险显著降低

总结

• 边界清晰化

  • 将系统划分为 Identity/Tenant、Project & Membership、Work、Notifications、Billing、Reporting、Integrations 与 Platform 八大模块；以 Application→Domain→Repository 的分层实现单向依赖。
  • 禁止服务间直接互调，以“领域事件 + 只读能力提供者”解耦跨域协作。

• 消除关键耦合

  • 用 CommentAdded 等事件替代 task–comment–notify 的同步调用链，打散循环依赖。
  • 将计费变更从任务流写路径中剥离，转为入站能力判定 + 异步通知/降级。

• 横切能力收敛

  • 将日志、缓存、鉴权、队列、外部客户端统一至 Platform；废弃对 common 的直接依赖，改走 Facade。

• 可落地的三阶段路线

  • 阶段一：上事件总线与 DTO，清零循环依赖，通知异步化。
  • 阶段二：平台化横切能力，缓存与投影稳态读路径，覆盖率 50%+。
  • 阶段三：按工作区→进程外化路径拆出通知与计费，确保零停机与快速回滚。

• 预期收益

  • 可维护性：模块边界清晰、依赖图简化、测试更聚焦；循环依赖清零。
  • 可扩展性：事件驱动 + 投影，支撑读多写少场景；通知/计费独立演进。
  • 性能与稳定性：请求链缩短、异步化副作用、缓存与 ES 投影提升读性能；P95 延迟目标下降 20% 可达。