7d21b6516f
后端： 1. 启动层完成第一轮运行边界拆分，新增 `all / api / worker` 三种进程模式：`all` 保持原单体行为，`api` 只启动 Gin 与同步业务依赖，`worker` 只启动 outbox、Kafka consumer 与 memory worker。 2. 启动装配从单个入口拆成 runtime 依赖图，配置、DB、Redis、RAG、memory、DAO、Service、Handler、newAgent 依赖统一集中构造，再按进程角色选择启动 HTTP 或后台循环。 3. outbox 事件总线补齐 dispatch / consume 分离启动能力，支持后续 relay 与 consumer 独立进程化，同时保留原组合启动语义。 4. 核心 outbox handler 注册收口为公共接线入口，统一校验依赖并复用注册顺序，避免 api / worker / all 多入口复制事件注册逻辑。 迁移说明： 5. 本轮只迁运行边界，不拆业务服务边界；旧单体入口仍保留并默认走 `all` 兼容模式，当前切流点是 API 不再消费异步事件，worker 承担后台消费与 memory 任务。 6. 补充微服务四步迁移与第二阶段并行开发计划，明确先拆 API/Worker，再接主动调度与飞书通知，后续再拆 notification、active-scheduler、schedule/task。
558 lines
17 KiB
Markdown
558 lines
17 KiB
Markdown
# 微服务四步迁移与第二阶段并行开发计划
|
||
|
||
## 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 服务拆出去。
|