# 微服务四步迁移与第二阶段并行开发计划

## 1. 文档目的

本文档回答两个问题：

1. 当前 Gin 单体如何平滑演进到“同仓库、多 Go module、分别启动”的微服务形态。
2. 第二阶段 `to5.1` 主动调度闭环应在什么时间点介入，才能与底座迁移并行推进，避免互相干扰。

本轮迁移的核心原则是：**先拆运行边界，再拆服务边界，最后再拆数据所有权**。

也就是说，第一轮不追求一步到位变成完整微服务，而是先把现在所有能力都挤在 `cmd.Start()` 里的问题解决掉，让 API、Worker、通知、主动调度后续可以各走各的启动链路。

---

## 2. 最终目标形态

项目保持一个 GitHub 仓库，但后端逐步演进为多个可独立构建、独立启动、独立部署的 Go module。

推荐最终目录形态如下：

```text
SmartFlow-Agent/
  frontend/
    package.json
    src/

  backend/
    apps/
      api/                         # Gin BFF / API Gateway
        go.mod
        cmd/
          api/
            main.go
        internal/

    services/
      notification/                # go-zero 通知服务，飞书优先落地
        go.mod
        cmd/
        internal/

      active-scheduler/            # 主动调度服务/worker
        go.mod
        cmd/
        internal/

      schedule/                    # 正式日程应用服务，后期拆
        go.mod
        cmd/
        internal/

      task/                        # 四象限任务服务，后期拆
        go.mod
        cmd/
        internal/

    workers/
      outbox-worker/               # outbox relay + Kafka consumer
        go.mod
        cmd/
        internal/

      agent-worker/                # 后续 agent 重计算/主动优化 worker
        go.mod
        cmd/
        internal/

    shared/
      proto/                       # RPC 契约
      events/                      # Kafka 事件契约、JSON 示例、版本说明
      packages/                    # 极少量稳定公共库

    deploy/
    docs/
```

但这只是最终形态，不是第一轮要直接改成这样。

迁移期建议先保持当前 `backend/go.mod`，只在现有模块内拆出多启动入口。等第一轮稳定后，再把 `notification` 作为第一个独立 Go module 放到 `backend/services/notification`。

---

## 3. 四步走总览

### 第一步：拆运行边界，但保持业务行为不变

目标：把现在的 Gin 单体拆成同 Go module 内的多启动入口。

建议目录：

```text
backend/
  go.mod
  cmd/
    api/
      main.go
    worker/
      main.go
    all/
      main.go
  internal/app/                    # 或 cmd/app，承载启动装配函数
```

启动角色：

```text
api
  启动 Gin、鉴权、SSE、查询接口、用户确认接口、事件发布能力。
  迁移第一阶段仍保留 API 所需的同步 service/dao，不是最终纯网关。

worker
  只启动 outbox relay、Kafka consumer、事件 handler、memory worker。

all
  保持当前单体行为，用于本地开发和迁移期兜底。
```

这一阶段必须保证：

1. `all` 模式行为与当前 `cmd.Start()` 一致。
2. `api` 进程保留现有同步业务依赖，但不注册业务消费者，不启动 `memoryModule.StartWorker()`。
3. `worker` 进程不注册 Gin 路由，不占用 HTTP 端口。
4. 所有现有 API 路径、响应格式、缓存策略、数据库写入语义不变。
5. 只改启动装配，不改主动调度业务逻辑。

这一阶段完成后，第二阶段新功能就可以优先挂到 worker 或事件链路，而不是继续塞进 Gin 主进程。

### 第二步：建立事件契约、主动调度闭环 MVP 与飞书触达

目标：让“四象限任务池 + 课表时间轴”进入同一个调度闭环，并通过飞书主动触达用户。

关键修正：

1. 主动调度不是等用户打开聊天后才触发，而是由后台 worker 定时/事件驱动触发。
2. 飞书不是后置锦上添花，而是本周期主动出击闭环的第一版触达渠道。
3. 第一版飞书只负责通知用户“系统发现问题并生成了建议”，不承载复杂调度判断，也不直接改正式日程。

主动调度闭环 MVP：

```text
后台监控/事件触发
  -> 读取四象限任务
  -> 读取课表/日程空闲时间
  -> 生成局部调整建议
  -> 附带 Reasoning
  -> 写入对比预览
  -> 发布 notification.feishu.requested
  -> 飞书提醒用户回到系统确认
  -> 用户按变更项确认
  -> 确认后应用
```

建议新增事件契约：

```text
active_schedule.triggered
schedule.preview.generated
schedule.apply.requested
schedule.apply.succeeded
schedule.apply.failed
notification.feishu.requested
```

这一阶段主动调度可以仍在 `backend` 模块内实现，但要按未来服务边界写：

1. API 只负责测试触发、查询预览、用户确认和正式应用入口。
2. Worker 负责后台监控、消费触发事件、生成建议、写预览、发布飞书通知事件。
3. 正式应用仍先复用当前强一致落库链路，不拆成远程服务。
4. 飞书第一版可以先在 `backend` worker 内实现 webhook/provider，后续再迁出到独立 notification 服务。

### 第三步：拆出第一个独立 Go module：notification

目标：把第二步里先落在 `backend` worker 内的飞书通知，演进为第一个真正服务化模块。

推荐目录：

```text
backend/
  services/
    notification/
      go.mod
      cmd/
        notification/
          main.go
      internal/
        consumer/
        domain/
        repo/
        provider/
          feishu/
```

推荐技术选型：

1. 使用 go-zero 作为服务工程框架。
2. 通过 Kafka 消费 `notification.feishu.requested`。
3. 若需要同步管理接口，再补 go-zero API 或 RPC。

通知服务必须有自己的投递模型，不能只依赖 outbox 的 `consumed` 状态。

建议新增通知记录表或等价存储：

```text
notification_records
  id
  user_id
  channel
  biz_type
  biz_id
  idempotency_key
  status
  retry_count
  last_error
  requested_at
  sent_at
```

飞书发送链路：

```text
notification.feishu.requested
  -> 写入/读取 notification_records
  -> 幂等判断
  -> 调用飞书 provider
  -> 记录 sent / failed / retry
```

这一阶段完成后，飞书挂了不会影响 Gin API，也不会影响主动调度生成预览。

> 说明：第二步允许先做简版飞书 webhook，是为了尽快跑通“后台主动发现 -> 飞书触达 -> 用户回系统确认”的产品闭环。第三步再把通知投递模型、失败补偿、幂等记录独立出来，避免第一轮就被完整 notification 平台拖慢。

### 第四步：逐步拆主动调度、日程、任务服务

目标：在业务边界稳定后，再拆核心服务。

推荐顺序：

```text
active-scheduler
  -> schedule
  -> task
```

拆 `active-scheduler` 的前提：

1. 主动调度输入输出 DTO 稳定。
2. Reasoning 结构稳定。
3. 预览生成和确认协议稳定。
4. 调度触发事件稳定。

拆 `schedule` 的前提：

1. 正式日程应用命令契约稳定。
2. 已明确 `schedule_events`、`schedules`、`task_items.embedded_time` 的一致性边界。
3. 有 apply id / idempotency key。
4. 有冲突失败回执和回滚策略。

拆 `task` 的前提：

1. 四象限任务池语义稳定。
2. DDL、完成状态、优先级平移规则稳定。
3. 任务表所有权明确。

在这些前提未满足之前，不建议把 `schedule` 和 `task` 强行拆成独立服务，否则容易变成分布式单体。

---

## 4. 第二阶段功能如何并行介入

第二阶段 `to5.1` 的业务目标是让四象限任务和课表联通，不再是两个孤岛。

建议按以下时间点介入。

### 介入点 A：第一步完成后，开始“后台主动调度 + 飞书触达”MVP

当 `api / worker / all` 三种启动角色跑通后，就可以开始主动调度 MVP。

这一版不要只做“用户打开聊天后触发”，而是要把后台触发作为主链路，把 API 测试接口作为调试入口。

此时你可以开发：

1. 主动调度后台触发器。
2. 主动调度 dry-run / trigger 测试接口。
3. `mock_now` 时间注入。
4. 任务未完成 / 用户反馈很累 / DDL 临近 的触发 payload。
5. 写入对比预览。
6. 发布 `notification.feishu.requested`。
7. 简版飞书 webhook/provider，通知用户回系统确认。

不建议此时开发：

1. 飞书内直接确认/改日程。
2. 飞书作为完整 agent 聊天入口。
3. DDL 全自动插空的复杂版本。
4. 大范围全局重排。
5. 独立 schedule/task 微服务。

原因：这一阶段的目标是验证“后台主动发现 -> 生成建议预览 -> 飞书触达 -> 用户回系统确认”的闭环，而不是一次性做完所有渠道与触发场景。

### 介入点 B：飞书触达可用后，预埋飞书聊天链路

当飞书 webhook 通知可用后，可以提前预埋下周期“飞书接入 agent 聊天链路”的边界。

下周期目标类似“飞书内直接和 agent 对话”，但本周期只埋以下能力：

1. `channel` 字段：区分 `web`、`feishu`、未来移动端等入口。
2. `external_user_id` / `open_id` 映射：把飞书用户身份映射到系统用户。
3. `external_conversation_id` 映射：把飞书会话映射到系统 `conversation_id`。
4. 入站消息 DTO：把飞书消息统一转换成 `AgentInboundMessage`。
5. 出站消息 DTO：把 agent 回复统一转换成 `AgentOutboundMessage`。
6. 幂等键：飞书 message id 需要映射为入站消息幂等键，避免重复回调导致重复对话。

本周期不做：

1. 飞书内完整多轮 Agent Chat。
2. 飞书内复杂确认卡片。
3. 飞书内直接应用日程。
4. 移动端替代方案。

推荐预埋事件：

```text
agent.channel.message.received
agent.channel.reply.requested
```

飞书主动通知仍然走：

```text
notification.feishu.requested
```

也就是说，**通知通道** 和 **聊天通道** 从事件名和 DTO 上就要分开，避免下周期把飞书消息接入时污染 notification 逻辑。

### 介入点 C：主动调度 MVP 稳定后，扩充更多主动触发源

此时可以扩展：

1. DDL 临近插入课表空余时间。
2. 任务未完成监控。
3. 用户反馈很累后的局部微调。
4. 提前完成后的碎片任务建议。
5. 休息/发呆选项。

所有触发源都应该进入同一个主动调度入口：

```text
active_schedule.triggered
```

不要每个触发源各写一套调度逻辑。

### 介入点 D：飞书通知模型稳定后，拆 notification 独立 module

当飞书通知从“能发 webhook”升级为“有幂等、有记录、有失败补偿”后，再把它从 `backend` 中迁到：

```text
backend/services/notification
```

迁移时要保持：

1. 主动调度 worker 只发布 `notification.feishu.requested`，不直接依赖飞书 SDK 或 webhook 细节。
2. notification 服务负责通知记录、幂等、重试、provider 调用。
3. 飞书聊天链路如果下周期启动，应单独走 `agent.channel.*` 事件，不混入 notification 投递模型。

### 介入点 E：主动调度协议稳定后，再拆 active-scheduler 独立 module

当主动调度闭环稳定后，再把它从 `backend` 中迁到：

```text
backend/services/active-scheduler
```

迁移时要保持：

1. API 仍只发布事件和查询预览。
2. active-scheduler 只负责建议生成和预览。
3. 正式日程应用仍通过稳定命令或事件进入 schedule 域。

---

## 4.1 为下周期飞书 Agent 聊天链路预埋

如果后续暂缓移动端开发，把飞书作为轻量移动入口，那么本周期接飞书时要提前避免两个误区：

1. 不要把飞书通知写成只会发送固定文案的死逻辑。
2. 不要把飞书聊天直接塞进 notification handler。

建议从本周期就区分三层：

```text
notification
  负责主动通知，例如“我发现你的今晚安排可能过载，已生成一版建议”。

channel adapter
  负责不同渠道的入站/出站消息适配，例如 web、feishu、未来移动端。

agent conversation
  负责真正的 agent 多轮对话、上下文、工具调用、确认卡片。
```

飞书作为聊天入口时，推荐链路是：

```text
飞书回调
  -> feishu channel adapter
  -> 校验签名/解密/去重
  -> 映射系统 user_id 与 conversation_id
  -> 发布 agent.channel.message.received
  -> agent worker / agent service 处理
  -> 发布 agent.channel.reply.requested
  -> feishu channel adapter 发送回复
```

本周期最小预埋：

1. 配置层预留 `feishu.enabled`、`feishu.webhook`、`feishu.appID`、`feishu.appSecret` 等字段位置。
2. DTO 层预留 `Channel`、`ExternalUserID`、`ExternalConversationID`、`MessageID`、`IdempotencyKey`。
3. 事件层预留 `agent.channel.message.received` 和 `agent.channel.reply.requested`。
4. 数据层先不强行建全量飞书会话表；若需要，只建轻量映射表或先通过 Redis/配置映射过渡。

这样下周期即使做“飞书内直接聊 agent”，也不会推翻本周期的飞书通知实现。

---

## 5. 并行开发分工建议

### Codex 优先负责

1. 拆 `cmd.Start()`，抽启动装配层。
2. 新增 `api / worker / all` 启动入口。
3. 把 outbox relay、Kafka consumer、memory worker 从 API 入口移走。
4. 为 notification 服务预留事件契约和目录位置。
5. 补迁移文档和启动说明。

### 业务开发优先负责

1. 定义主动调度 MVP 的产品语义。
2. 明确 Reasoning 展示格式。
3. 明确用户确认粒度。
4. 设计后台触发、dry-run、trigger 测试场景。
5. 梳理哪些任务可被退回任务池，哪些必须保护。
6. 明确飞书通知文案与“回系统确认”的跳转语义。

### 双方交汇点

交汇点只放在事件契约和 DTO 上。

建议先稳定以下结构：

```text
ActiveScheduleTrigger
ActiveScheduleSuggestion
ActiveScheduleChangeItem
ActiveScheduleReasoning
SchedulePreviewVersion
NotificationRequested
AgentInboundMessage
AgentOutboundMessage
```

只要这些结构稳定，底层是否已经拆成独立 module，不影响你继续开发业务。

---

## 6. 每一步的验收标准

### 第一步验收：启动边界

1. `all` 模式与当前单体行为一致。
2. `api` 模式能启动 Gin，并能访问现有接口。
3. `worker` 模式能启动 outbox 和 memory worker，不启动 HTTP。
4. API 进程发布的 outbox 消息能被 worker 消费。
5. 停掉 worker 时，API 仍可启动，只是异步能力延迟执行。

### 第二步验收：主动调度 MVP

1. worker 能后台触发主动调度。
2. 测试接口能触发同一条主动调度链路。
3. 能传入 `mock_now`。
4. 能读取四象限任务和课表空余时间。
5. 能生成调整建议。
6. 每个建议都有 Reasoning。
7. 结果写入对比预览，不直接落库。
8. 能发布并发送飞书通知，提醒用户回系统确认。

### 第三步验收：飞书通知服务

1. `notification.feishu.requested` 能被独立服务消费。
2. 有通知幂等键。
3. 有通知发送记录。
4. 飞书失败可重试。
5. 飞书服务停止不影响 API 和主动调度预览生成。

### 第四步验收：核心服务化

1. active-scheduler 可独立启动。
2. schedule/task 的数据所有权逐步明确。
3. API 不再直接承担核心调度重计算。
4. 服务间通信只通过 RPC / Kafka / 明确契约完成。

---

## 7. 风险与回退策略

### 风险 1：启动拆分后本地开发变复杂

回退策略：

1. 保留 `all` 模式。
2. 本地默认仍可一键启动。
3. 只有联调 worker / 飞书时才分进程启动。

### 风险 2：API 不启动消费者后 outbox 堆积

回退策略：

1. 本地使用 `all` 模式。
2. 联调环境明确启动 worker。
3. 增加 outbox 堆积观测或临时查询 SQL。

### 风险 3：多个 worker 重复投递

回退策略：

1. 第一阶段只启动一个 worker。
2. 后续再补 outbox claim / processing 状态。
3. 外部通知必须有业务幂等键。

### 风险 4：过早拆 schedule/task 导致分布式单体

回退策略：

1. 第一阶段不拆正式日程落库。
2. 第二阶段只拆主动建议生成。
3. schedule/task 等数据所有权稳定后再拆。

---

## 8. 推荐近期执行顺序

近期建议按以下顺序推进：

1. Codex 先完成启动边界拆分：`api / worker / all`。
2. 业务侧同步定义主动调度 MVP 的 DTO 与 Reasoning 格式。
3. 在 `backend` worker 内实现后台主动触发器，并保留 dry-run / trigger 测试接口。
4. 主动调度结果先写现有对比预览。
5. 增加 `notification.feishu.requested` 事件，并实现简版飞书 webhook/provider。
6. 预留 `agent.channel.*` 事件和 channel DTO，为下周期飞书聊天链路做准备。
7. 飞书通知模型稳定后，新建 `backend/services/notification`，使用 go-zero 落地独立通知服务。
8. 主动调度稳定后，再考虑拆 `active-scheduler`。

一句话总结：

> 先让项目从“所有能力绑在一个 Gin 单体进程”变成“API 与 Worker 分开跑”；再让第二阶段主动调度闭环挂到 Worker 与事件契约上；最后把飞书通知作为第一个独立 Go module 服务拆出去。