# **🔬 分布式 Fan-out 指南 (v1.2) 破壁级审查与修订报告**

**审查人：** 资深架构师 & Node.js 底层专家

**审查对象：** 《分布式 Fan-out 任务模式开发指南 v1.2》

**审查深度：** V8 引擎内存栈、Postgres 底层驱动、pg-boss 命名空间

**核心结论：** 业务逻辑已彻底闭环！但在**JSON 字符串强截断、长期闲置连接保活、全局唯一键防重**这三个底层物理机制上，存在 3 个会直接导致进程崩溃或静默失效的高危隐患。

## **🚨 破壁级漏洞 1：NOTIFY 强截断导致的 JSON.parse 爆栈崩溃**

### **❌ 逐行审查发现的问题（位于 模式 6：SSE 跨实例广播）**

指南中为了防止超过 PostgreSQL 的 8000 bytes 限制，写了如下安全截断代码：

const payloadStr \= JSON.stringify({ taskId, type: 'log', data: logEntry });  
const safePayload \= payloadStr.length \> 7000  
  ? payloadStr.substring(0, 7000\) \+ '..."}'  // 👈 致命漏洞  
  : payloadStr;

**🔥 灾难时序爆发：**

1. 假设 logEntry 的内容包含大量报错栈，导致 payloadStr 长达 9000 字节。  
2. 代码直接在第 7000 个字符处一刀切，然后粗暴地拼上 ..."}。  
3. 如果第 7000 个字符刚好切在一个中文字符的中间（导致 Unicode 乱码），或者切在了 JSON 的某个 key 名字中间（如 {"ms），拼接后的字符串将变成**绝对非法的 JSON**。  
4. **爆炸点：** 在 API 接收端，代码是这样写的：const { taskId, type, data } \= JSON.parse(msg.payload);  
5. 当非法的 JSON 被 JSON.parse 解析时，Node.js 会抛出 SyntaxError: Unexpected token。由于 pgClient.on('notification') 内部没有写 try-catch，**这个异常会直接击穿 Event Loop，导致整个 API Pod 进程崩溃重启 (Crash)！**

### **✅ 架构师修正方案 (内部字段安全截断)**

**绝对不能对 JSON.stringify 后的字符串进行切片！必须切片原始对象内的长文本字段：**

// 发送端：在 Stringify 之前，截断真正导致超长的 message 字段  
if (logEntry.message && logEntry.message.length \> 3000\) {  
    logEntry.message \= logEntry.message.substring(0, 3000\) \+ '...\[Truncated\]';  
}  
const payloadStr \= JSON.stringify({ taskId, type: 'log', data: logEntry });  
await prisma.$executeRaw\`SELECT pg\_notify('sse\_channel', ${payloadStr})\`;

// 接收端：必须加上防御性 try-catch，防止毒数据炸毁整个实例  
pgClient.on('notification', (msg) \=\> {  
  try {  
    const { taskId, type, data } \= JSON.parse(msg.payload);  
    // ... 推送逻辑  
  } catch (error) {  
    logger.error('Failed to parse SSE notification payload', { payload: msg.payload });  
  }  
});

## **🚨 破壁级漏洞 2：LISTEN 监听器的“静默死亡” (Silent Connection Drop)**

### **❌ 逐行审查发现的问题（位于 模式 6：SSE 跨实例广播）**

指南中的 API 接收端初始化代码如下：

const pgClient \= new Client({ connectionString: DATABASE\_URL });  
await pgClient.connect();  
await pgClient.query('LISTEN sse\_channel');

**🔥 灾难时序爆发：**

1. 这是一个一直挂在后台的长期长连接（Long-lived Connection）。  
2. 在云端环境，由于底层网络波动、PgBouncer 代理的闲置超时掐断、或者数据库主备切换，这根 TCP 连接**一定会在几天内断开一次**。  
3. pg 原生库的设计是：**Client 连接断开后，不会自动重连！**  
4. **后果：** 没有任何报错，服务依然在跑，但这个 Pod **永远也收不到**任何 NOTIFY 消息了。前端 SSE 终端彻底变成一潭死水。

### **✅ 架构师修正方案 (加入心跳重连与错误监听)**

必须为这个裸 Client 加上底层的生命周期守护：

// 封装为健壮的监听器启动函数  
async function setupSSEListener() {  
  const pgClient \= new Client({ connectionString: DATABASE\_URL });  
    
  // 核心补丁：监听错误与断开，强制重启监听！  
  pgClient.on('error', (err) \=\> {  
    logger.error('PG Listen Client Error, reconnecting...', err);  
    pgClient.end().catch(console.error);  
    setTimeout(setupSSEListener, 5000); // 5 秒后自动重连  
  });  
    
  pgClient.on('end', () \=\> {  
    logger.warn('PG Listen Client Ended, reconnecting...');  
    setTimeout(setupSSEListener, 5000);  
  });

  await pgClient.connect();  
  await pgClient.query('LISTEN sse\_channel');  
  pgClient.on('notification', (msg) \=\> { /\* ... \*/ });  
}  
setupSSEListener();

## **🚨 破壁级漏洞 3：singletonKey 作用域跨界的“狸猫换太子”**

### **❌ 逐行审查发现的问题（位于 五、pg-boss 配置速查）**

指南中建议这样写防重复 Key：

await pgBoss.send('module\_task\_child', { taskId, itemId }, {  
  singletonKey: \`child-${itemId}\`,  // ← 派发防重  
});

**🔥 灾难时序爆发：**

1. 假设 itemId 指的是源数据的 ID（例如 PKB里的 Document A）。  
2. 医生张三在“项目 1”里提取了 Document A。pg-boss 生成了 singletonKey: child-DocA，正在缓慢处理。  
3. **同时**，医生李四在“项目 2”里，也碰巧勾选了同一个 Document A 进行提取任务。  
4. pg-boss 会发现 singletonKey: child-DocA 已经在队列里了。根据幂等性去重规则，**pg-boss 会直接丢弃（Ignored）李四的这个子任务！**  
5. **后果：** 李四的这个任务永远缺少了这一篇文献的进度，父任务 Last Child Wins 机制卡死，系统挂起！

### **✅ 架构师修正方案 (引入绝对隔离域)**

singletonKey 在 pg-boss 中是**全局数据库唯一**的！它绝不能仅仅绑定业务实体 ID，必须绑定\*\*“实体 \+ 本次任务实例”\*\*的联合主键。

如果 itemId 对应的是 AslExtractionResult.id（专属于某一次提取任务的单行 ID），那是安全的。但为了规范，指南必须明确指出：

// 核心补丁：singletonKey 必须携带父任务 ID 形成绝对隔离！  
await pgBoss.send('module\_task\_child', { taskId, itemId }, {  
  singletonKey: \`task-${taskId}-item-${itemId}\`,  // 必须绑定 Task 实例级别！  
});

## **🏁 最终判词与交付建议**

经过这次“贴脸”级别的底层审查，我们不仅防住了高并发的业务死锁，还防住了**网络断线、V8 JSON解析、全局哈希碰撞**这三个底层基建级别的灭顶之灾。

请将这 3 个补丁打入《分布式 Fan-out 任务模式开发指南 v1.2》中（升级为 v1.3 定稿版）。有了这套带底层防线的文档，您的团队在面对任何高并发、高可用挑战时，都能写出真正的“大厂级”工业代码！