HaHafeng
dc6b292308
ASL Tool 3 Development Plan: - Architecture blueprint v1.5 (6 rounds of architecture review, 13 red lines) - M1/M2/M3 sprint checklists (Skeleton Pipeline / HITL Workbench / Dynamic Template Engine) - Code patterns cookbook (9 chapters: Fan-out, Prompt engineering, ACL, SSE dual-track, etc.) - Key patterns: Fan-out with Last Child Wins, Optimistic Locking, teamConcurrency throttling - PKB ACL integration (anti-corruption layer), MinerU Cache-Aside, NOTIFY/LISTEN cross-pod SSE - Data consistency snapshot for long-running extraction tasks Platform capability: - Add distributed Fan-out task pattern development guide (7 patterns + 10 anti-patterns) - Add system-level async architecture risk analysis blueprint - Add PDF table extraction engine design and usage guide (MinerU integration) - Add table extraction source code (TableExtractionManager + MinerU engine) Documentation updates: - Update ASL module status with Tool 3 V2.0 plan readiness - Update system status document (v6.2) with latest milestones - Add V2.0 product requirements, prototypes, and data dictionary specs - Add architecture review documents (4 rounds of review feedback) - Add test PDF files for extraction validation Co-authored-by: Cursor <cursoragent@cursor.com>
75 lines
5.3 KiB
Markdown
75 lines
5.3 KiB
Markdown
# **🎯 系统级异步架构风险剖析与演进技术蓝图 (V2.0 定稿版)**
|
||
|
||
**文档性质：** 架构决策与研发执行规范 **面向受众：** 架构师、技术负责人、中高级后端研发 **背景：** 随着 ASL 工具 3 等批量耗时任务的引入，系统正从“单体异步”转向“分布式扇出 (Fan-out)”架构。 **核心目标：** 解决多实例部署下的计数丢失、状态撕裂与事件孤岛风险，建立工业级的分布式任务处理标准。
|
||
|
||
## **💡 一、 问题的本质：架构的分水岭**
|
||
|
||
在分布式系统设计中，异步任务的复杂度随业务颗粒度呈指数级跃迁。我们必须将任务划分为两个完全不同的等级：
|
||
|
||
| 维度 | Level 1：单体任务 (现有标准) | Level 2：分布式扇出 (演进方向) |
|
||
| :---- | :---- | :---- |
|
||
| **典型案例** | 工具 C 解析 1 个 Excel | 工具 3 批量提取 100 篇文献 |
|
||
| **工作流** | 1 个触发 \-\> 1 个 Worker \-\> 结束 | 1 个触发 \-\> 1 个 Manager \-\> N 个子 Worker |
|
||
| **多实例安全性** | **高**。依靠 pg-boss 行锁。 | **低**。子任务跨机器，必须处理原子性聚合。 |
|
||
| **容错代价** | **小**。失败重跑 40 秒。 | **极大**。若无扇出，第 99 篇失败会导致前 98 篇全废。 |
|
||
| **系统影响** | 局部影响。 | 全系统级风险（API 熔断、数据库连接耗尽）。 |
|
||
|
||
## **🔍 二、 核心风险深度剖析 (The Risks)**
|
||
|
||
在多 SAE 实例（Multi-Pod）部署环境下，若不严格执行 V2.0 规范，将面临以下系统性崩溃风险：
|
||
|
||
### **1\. 统计数据的“幻影覆盖” (Race Condition)**
|
||
|
||
* **现象：** 当 100 个子任务在不同 Pod 同时完成时，如果采用 count \= count \+ 1 的读写逻辑，多个进程会读到相同的旧值并覆盖写入。
|
||
* **后果：** 进度条卡死、统计金额错误、任务永远无法触发“完成”回调。
|
||
|
||
### **2\. “最后一个人关灯”难题 (The Terminator Problem)**
|
||
|
||
* **现象：** 缺乏全局协调逻辑。Manager 派发完任务就结束了，子任务各自为政。
|
||
* **后果：** 系统不知道“这组任务”什么时候算真正结束，无法自动触发后续的报告生成或通知发送。
|
||
|
||
### **3\. SSE 实时日志的“物理隔绝” (Event Silos)**
|
||
|
||
* **现象：** 用户的浏览器连接在 Pod A，但执行任务的 Worker 运行在 Pod B。Pod B 产生的日志在 Pod A 的内存里完全不存在。
|
||
* **后果：** 页面显示“处理中”但日志区一片空白，用户因感知不到进度而频繁刷新，造成更大的后端冲击。
|
||
|
||
## **🛠️ 三、 全系统演进执行建议 (The Guidelines)**
|
||
|
||
为了消除上述风险，全平台所有异步模块必须强制对齐以下 4 项架构红线：
|
||
|
||
### **🚨 规范 1：强制执行数据库级原子操作**
|
||
|
||
禁止在异步代码中使用任何内存层面的数学运算来更新数据库。
|
||
|
||
* **错误写法：** data: { count: task.count \+ 1 }
|
||
* **正确标准 (Prisma)：** \`\`\`typescript await prisma.task.update({ where: { id: taskId }, data: { successCount: { increment: 1 } } });
|
||
|
||
### **🚨 规范 2：引入“Last Child Wins”收口机制**
|
||
|
||
在分布式环境下，必须由最后一个完成任务的进程负责“关灯（翻转父任务状态）”。
|
||
|
||
* **执行逻辑：** 每个子任务在执行完【原子递增】后，必须同步读取更新后的结果。
|
||
* **判定公式：** if (updatedTask.successCount \+ updatedTask.failedCount \=== updatedTask.totalCount)
|
||
* **后续：** 若条件成立，该实例负责将 Task.status 改为 completed 并触发 SSE 完成事件。
|
||
|
||
### **🚨 规范 3：从 EventEmitter 转向跨实例消息总线**
|
||
|
||
彻底封杀多实例环境下的单机 EventEmitter 实时推送。
|
||
|
||
* **Postgres-Only 方案：** 充分利用 PostgreSQL 的 LISTEN/NOTIFY 机制。
|
||
* **工作流：** 1\. Worker 发送 NOTIFY channel\_name, payload。 2\. 所有 API 节点在启动时 LISTEN 该频道。 3\. 收到通知的 API 节点检查本地内存，若存在对应 taskId 的 SSE 客户端，则执行推送。
|
||
|
||
### **🚨 规范 4：极端场景下的“背压限制”与超时阻断**
|
||
|
||
* **全局限流：** 针对昂贵的外部 API（如 MinerU），必须使用 pg-boss 的 teamConcurrency 进行数据库级全局限流，严禁使用单机 P-Queue。
|
||
* **超时阻断：** 所有跨网络请求必须强制设置 timeout（建议 ≤ 90s），防止外部接口假死扣住 pg-boss 队列名额，导致系统死锁。
|
||
|
||
## **📅 四、 路线图：如何平滑过渡？**
|
||
|
||
1. **实验场 (M1/M2)：** 以“ASL 工具 3”作为首个 V2.0 规范试点，沉淀出通用的 FanOutHelper 和 ListenNotifyService。
|
||
2. **基建化：** 将上述成功代码抽离，封装入 common/jobs 和 common/streaming 能力层。
|
||
3. **全量覆盖：** 发布《Postgres-Only 异步任务处理指南 v2.0》，要求后续所有涉及“批量处理”的模块（如 IIT Agent、批量报告生成）严格照此执行。
|
||
|
||
## **🏁 架构师寄语**
|
||
|
||
工具 3 的出现不是增加了复杂度，而是帮我们掀开了分布式环境下一直被掩盖的风险盖子。 **与其在上线后通过熬夜排查“幽灵 Bug”，不如现在多审核一次，在文档阶段就打好地基。** 请研发团队认真研读此蓝图，这套规范将让我们的系统从“能跑通”进化到“金身不坏”。 |