产品团队沟通这件事，看起来只是把消息从一个屏幕传到另一个屏幕，真正落地之后才会发现，难点根本不在于传输，而在于信息过载、上下文丢失和结论难追溯。产品经理关心版本节奏，设计师关心方案确认，研发关心技术边界，测试关心缺陷状态，这些信息通常散落在聊天流、会议纪要和周报里，等需要回看时，已经很难判断哪一句是最终结论。标题里的 Show HN 项目定位很有意思：它希望把产品团队沟通做成一个让人愿意使用、效率又足够高的内部工具。这篇文章不评价任何具体产品，而是从工程实现角度讨论：如果要自建或深度改造一套面向产品团队的沟通协作系统，核心对象怎么设计、技术栈怎么选、数据模型怎么建、实时消息怎么推、验证和排错怎么做。
1. 产品团队沟通为什么需要“可追溯的异步协作”
1.1 信息过载的本质是缺少结构化对象
随便打开一个产品讨论群，都会看到大量诸如“这个按钮文案再确认一下”“颜色改成品牌蓝”“这个需求下个版本做”之类的消息。表面上看这些都是即时聊天，实际上它们分属不同类型：有的是讨论过程，有的是最终结论，有的是待办事项，有的是状态通知。
纯聊天工具把所有类型混在同一个时间流里，人只能靠上下文猜。一个新人加入群聊，要从几百条消息里找出“谁拍板了、在哪一版、什么时候上线”，几乎不可能。解决方式不是做更多频道，而是把信息按语义拆成结构化对象。
在本文方案中，系统只围绕四类对象设计：
- Thread（讨论线程）：承载一个主题的完整讨论。
- Message（消息）：线程里的一条发言或附件。
- Decision（决策）：讨论结束后明确记录的结论。
- Todo（待办）：由决策派生出来的执行任务。
这四类对象就是整个沟通系统的核心实体。有了它们，聊天记录才能从“时间流”变成“可追溯的协作记录”。
1.2 同步沟通与异步沟通的取舍
实时会议和群聊的好处是沟通带宽高，问题能当场澄清；坏处是打断成本高，信息无法沉淀。产品团队通常跨角色、跨时段协作，不可能所有人都保持同时在线。异步沟通更适合沉淀结论：在文档里写清楚背景，在评论区里讨论，在结论区里记录拍板结果。
一个高效产品团队沟通工具，应当默认设计为异步。实时通道只负责把异步讨论中的关键变化推送给相关人，而不是让每个人都实时盯着聊天框。为什么很多团队工具最后变成新的“通知轰炸源”？因为它们把实时推送等同于效率，忘了异步协作的核心是“让重要信息在合适的时机出现在合适的人面前”。
1.3 最小闭环应该长什么样
要验证一个产品团队沟通工具是否有效，不需要等到所有功能开发完。可以先跑通这样一条最小闭环：
- 一个团队创建了一个 Thread，标题是“登录页交互方案评审”。
- 设计师在 Thread 里上传了新版高保真图。
- 产品经理和研发在 Thread 里讨论实现成本。
- 最终产品经理创建了一条 Decision：采用方案 B。
- 系统根据 Decision 自动创建一条 Todo：研发在下周五前完成方案 B 开发。
- 所有相关成员通过实时通道收到更新。
这个闭环说明它不只是一个聊天室，而是一个协作记录系统。用户愿意使用，不是因为功能多，而是因为打开之后能快速知道“现在需要我做什么、之前定了什么”。
1.4 为什么“让人愿意用”是一个技术问题
“让人愿意用”听起来是产品体验问题，实际上很大程度取决于技术实现。打开客户端要等三秒才加载出历史消息，未读数永远不准，消息发出去丢失，这些技术问题会直接摧毁使用意愿。
所以在这套设计里，实时通道、消息幂等、未读游标、权限校验不是可选项，而是基础能力。技术上的可靠性决定了协作过程中的确定性：消息发出去之后，用户知道它一定能被持久化；看到未读数，用户知道它一定意味着有需要处理的内容。这种确定性，才是“愿意使用”的前提。
2. 系统设计和技术选型：先定四个核心对象
2.1 四个核心对象的关系
先确定实体关系，再讨论技术和代码，否则后面每一步都会被数据模型卡住。
一个 Team（团队）包含多个成员；一个 Team 下可以创建多个 Thread；一个 Thread 包含多条 Message；讨论到一定程度后，Thread 上可以挂载 Decision；一条 Decision 可以派生多条 Todo。数据库关系如下：
- Thread 属于 Team，多对一。
- Message 属于 Thread，多对一。
- Decision 属于 Thread，多对一。
- Todo 属于 Decision，多对一。
- Team 和 User 通过 team_members 表建立多对多关系。
这里没有把“会话”作为最高级对象，而是把 Thread 作为最高级对象。关键差异是：会话只是消息容器，Thread 是主题和上下文容器。后续做决策、待办、通知，都要挂到 Thread 上。
2.2 技术选型：为什么用 WebSocket 而不是纯轮询
实时消息是产品团队沟通工具的核心，选型时需要对比几种常见方案。
| 方案 | 实时性 | 服务器开销 | 实现复杂度 | 适用场景 |
|---|---|---|---|---|
| 短轮询 | 秒级 | 高 | 低 | 低频状态查询，如检查任务是否完成 |
| 长轮询 | 准实时 | 中 | 中 | 需要兼容老旧网络或受限客户端 |
| SSE | 准实时 | 低 | 低 | 服务端单向推送，如通知列表 |
| WebSocket | 实时 | 中 | 中 | 双向消息、在线状态、输入状态同步 |
这个项目选择 WebSocket，主要原因是产品团队沟通场景是双向的：用户既要接收新消息，也要发送消息、更新未读状态、看到对方正在输入。WebSocket 的长连接能一次建立、双向复用，比轮询的请求响应模式更适合这种高频低延迟场景。
2.3 技术栈和项目目录
后端使用 Node.js + TypeScript + Express + Socket.IO，数据库使用 PostgreSQL，前端使用 React。这套组合的优点是类型覆盖全链路，Socket.IO 在浏览器和服务端的 API 基本一致，适合快速实现实时协作。
一个可运行的目录结构如下：
team-communication/ ├── docker-compose.yml ├── package.json ├── schema.sql ├── server/ │ ├── server.ts │ ├── db.ts │ └── routes/ │ └── threads.ts └── web/ ├── package.json └── src/ ├── hooks/ │ └── useThreadMessages.ts ├── components/ │ └── ThreadItem.tsx └── App.tsx后端 package.json 可以像下面这样组织，实际项目请根据自己的 Node.js 版本和包管理工具调整：
{ "name": "team-communication", "version": "0.1.0", "private": true, "scripts": { "dev": "tsx watch server/server.ts", "build": "tsc", "start": "node dist/server/server.js" }, "dependencies": { "express": "^4.19.2", "pg": "^8.11.5", "socket.io": "^4.7.5" }, "devDependencies": { "tsx": "^4.7.0", "typescript": "^5.4.0" } }这里把 Socket.IO 和 Express 放在一起，是因为它们共享同一个 HTTP Server，既能处理 REST 接口，也能处理 WebSocket 连接，部署时不需要额外管理两个进程。
2.4 为什么把消息数据库和实时通道分开
实时通道解决“送达”问题，数据库解决“持久化”问题。WebSocket 连接断开时，消息不能丢；服务端收到消息后，必须先写入数据库，再通过 Socket.IO 广播给客户端。如果先广播后落库，一旦数据库写入失败，客户端已经看到消息，刷新后又消失，会造成严重的数据不一致。
后续生产环境还可以引入消息队列做削峰，但第一版不需要。第一版只要保证一个原则：写入数据库成功，广播才发生。
3. 数据模型与消息存储设计
3.1 核心表结构
先建用户和团队表。以下 SQL 使用 PostgreSQL 语法，UUID 主键可以减少数据迁移时的冲突：
CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT NOT NULL, email TEXT UNIQUE NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE teams ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE team_members ( team_id UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, role TEXT NOT NULL DEFAULT 'member', PRIMARY KEY (team_id, user_id) );这里 team_members 表是关键。所有后续接口都要先判断“当前用户是否属于这个团队”，否则任何人都可以拉取和发送消息。
然后是 Thread 和 Message 表：
CREATE TABLE threads ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), team_id UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE, title TEXT NOT NULL, owner_id UUID NOT NULL REFERENCES users(id), status TEXT NOT NULL DEFAULT 'open', created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE messages ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), thread_id UUID NOT NULL REFERENCES threads(id) ON DELETE CASCADE, sender_id UUID NOT NULL REFERENCES users(id), content TEXT NOT NULL, client_message_id TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (thread_id, client_message_id) );messages 表里的 client_message_id 是幂等键。客户端在发送消息前生成一个唯一 ID，同一个 Thread 内不允许出现相同 client_message_id。这样即使客户端因为网络超时重复提交，数据库也能挡住重复消息。
3.2 消息为什么按 Thread 而不是纯会话存储
纯会话设计里，所有消息按时间排列，没有主题边界。产品团队沟通需要的是“围绕一个主题的完整上下文”，Thread 就是这种边界。
例如“登录页交互方案评审”这个 Thread 里，可以包含：
- 设计师的方案稿
- 研发对实现成本的评估
- 产品经理最终的决定
- 后续跟进待办
把这些内容放在同一个 Thread 里，消息自然形成主题聚合。新成员加入时，只需要读这个 Thread，就能理解整件事的来龙去脉。纯会话做不到这一点，因为“登录页”和“改版排期”的消息会混在一起。
3.3 决策与待办的关系设计
决策和待办是产品团队沟通工具区别于普通聊天工具的标志。普通聊天记录里也有“就这么定吧”和“我下周做”，但都是非结构化文本，无法统计和追踪。
决策表：
CREATE TABLE decisions ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), thread_id UUID NOT NULL REFERENCES threads(id) ON DELETE CASCADE, title TEXT NOT NULL, summary TEXT NOT NULL, decided_by UUID NOT NULL REFERENCES users(id), created_at TIMESTAMPTZ NOT NULL DEFAULT now() );待办表：
CREATE TABLE todos ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), decision_id UUID NOT NULL REFERENCES decisions(id) ON DELETE CASCADE, assignee_id UUID NOT NULL REFERENCES users(id), title TEXT NOT NULL, due_date DATE, status TEXT NOT NULL DEFAULT 'open', created_at TIMESTAMPTZ NOT NULL DEFAULT now() );这样待办从决策派生，决策又从讨论沉淀而来，整条链路可回溯。项目评审时问“这个需求谁负责、什么时候完成”，直接查 todo 表就能得到答案，不用去翻聊天记录。
3.4 未读书签：message_reads 表
未读数不是把“所有未读消息数一遍”算出来的，更合理的做法是记录每个用户在每个 Thread 的阅读游标。
CREATE TABLE message_reads ( thread_id UUID NOT NULL REFERENCES threads(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, last_read_message_id UUID NOT NULL REFERENCES messages(id) ON DELETE RESTRICT, updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (thread_id, user_id) );计算未读数时，只需要统计该线程中 created_at 大于用户游标时间、且不是自己发送的消息数量。这个表同时解决了“进入 Thread 后未读数归零”的问题：打开 Thread 时，把当前最大 message id 写入 last_read_message_id。
4. 后端实现：REST 接口 + WebSocket 实时通道
4.1 搭建最小后端
先创建一个最小后端入口，同时启动 HTTP 服务和 Socket.IO：
import express from "express"; import http from "http"; import { Server } from "socket.io"; import { Pool } from "pg"; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? "postgres://app:app@localhost:5432/teamwork", }); const app = express(); app.use(express.json()); const server = http.createServer(app); const io = new Server(server, { cors: { origin: process.env.CORS_ORIGIN ?? "*", }, }); const port = Number(process.env.PORT ?? 3000); server.listen(port, () => { console.log(`server listening on ${port}`); });这里的 Pool 来自 pg 库，负责管理 PostgreSQL 连接池。把 connectionString 放在环境变量里，是为后续部署到不同环境做准备。本地开发可以先用兜底连接串，生产环境必须通过环境变量注入。
4.2 发送消息：先落库，再广播
发送消息接口是整条主线的核心。下面是一个最小实现：
app.post("/api/threads/:threadId/messages", async (req, res) => { const { threadId } = req.params; const { senderId, content, clientMessageId } = req.body; if (!senderId || !content || !clientMessageId) { res.status(400).json({ error: "senderId, content and clientMessageId are required" }); return; } const result = await pool.query( `INSERT INTO messages (thread_id, sender_id, content, client_message_id) VALUES ($1, $2, $3, $4) ON CONFLICT (thread_id, client_message_id) DO NOTHING RETURNING *`, [threadId, senderId, content, clientMessageId] ); if (result.rowCount === 0) { res.json({ duplicated: true }); return; } const message = result.rows[0]; io.to(`thread:${threadId}`).emit("message:created", message); res.json(message); });这个接口有两点值得注意。
第一，ON CONFLICT (thread_id, client_message_id) DO NOTHING。客户端在弱网环境下很可能重复点击发送，如果没有这个约束，同一条消息会插入两次。
第二，必须先完成数据库插入，再调用 io.to().emit()。如果数据库插入失败，接口会返回 500，客户端知道发送失败，可以重试；如果先广播后插入，客户端已经显示了消息，刷新后消息消失，问题更难排查。
注意：生产环境绝不能从请求体里信任 senderId，应该从登录态或 JWT 中解析用户 ID，并在插入前校验用户是否属于该 Thread 所属的团队。
4.3 订阅与通知：Socket 房间与订阅表
Socket.IO 的房间很适合实现 Thread 订阅。客户端连接后，可以加入一个以线程 ID 命名的房间，之后所有发送到该房间的广播都会实时到达。
io.on("connection", (socket) => { const userId = socket.handshake.auth.userId; socket.data.userId = userId; socket.on("thread:join", (threadId: string) => { socket.join(`thread:${threadId}`); }); socket.on("thread:leave", (threadId: string) => { socket.leave(`thread:${threadId}`); }); });这里 socket.handshake.auth.userId 是客户端建立连接时传入的标识。在验权完整实现中，服务端应该校验这个用户是否真实存在，以及他是否有权限访问对应 Thread。
WebSocket 本身只管“推送”，通知列表还需要查询订阅者。为每个 Thread 维护一张订阅表会更灵活：
CREATE TABLE thread_subscribers ( thread_id UUID NOT NULL REFERENCES threads(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, PRIMARY KEY (thread_id, user_id) );在创建消息后，可以查询订阅者并推送摘要通知：
SELECT user_id FROM thread_subscribers WHERE thread_id = $1;4.4 权限校验：接口和房间都不能漏
实时通信场景的权限校验比普通 REST 接口更复杂，因为“加入房间”这个操作很容易被忽略校验。
对于 REST 接口，可以写一个中间件，先解析用户，再判断用户是否属于团队：
app.use("/api/teams/:teamId", async (req, res, next) => { const userId = req.userId; const { teamId } = req.params; const result = await pool.query( `SELECT 1 FROM team_members WHERE team_id = $1 AND user_id = $2`, [teamId, userId] ); if (result.rowCount === 0) { res.status(403).json({ error: "forbidden" }); return; } next(); });对于 thread:join 事件，同样要在服务端查询该用户是否有权限访问目标 Thread，不能只依赖客户端不调用。房间名本身不是权限边界，任何知道房间名的人都能加入，必须在服务端做授权验证。
5. 前端实现：让消息对“人”可见，而不是对“频道”可见
5.1 前端状态结构
前端的核心任务是把后端结构化数据渲染成“人对人”的界面，而不是一堆频道列表。先定义消息类型：
export type Message = { id: string; threadId: string; senderId: string; content: string; clientMessageId: string; createdAt: string; }; export type Thread = { id: string; teamId: string; title: string; status: "open" | "closed"; createdAt: string; }; export type Decision = { id: string; threadId: string; title: string; summary: string; decidedBy: string; createdAt: string; }; export type Todo = { id: string; decisionId: string; assigneeId: string; title: string; dueDate?: string; status: "open" | "done"; };这里的 message 类型与后端返回的 JSON 对应。clientMessageId 在前端也要保留，它不只用于幂等，还用于本地乐观更新时去重。
5.2 线程折叠与消息渲染
产品团队沟通界面的一个常见问题是消息过多。可以设计 ThreadItem 组件，把普通消息、决策、待办区分渲染：
import { Message, Decision, Todo } from "../types"; type Props = { thread: Thread; messages: Message[]; decisions: Decision[]; todos: Todo[]; }; export function ThreadItem({ thread, messages, decisions, todos }: Props) { return ( <div className="thread"> <h2>{thread.title}</h2> <section> <h3>进展消息</h3> {messages.map((message) => ( <div key={message.id} className="message"> <span>{message.senderId}</span> <span>{message.content}</span> <span>{new Date(message.createdAt).toLocaleString()}</span> </div> ))} </section> <section> <h3>结论</h3> {decisions.map((decision) => ( <div key={decision.id} className="decision"> <strong>{decision.title}</strong> <p>{decision.summary}</p> </div> ))} </section> <section> <h3>待办</h3> {todos.map((todo) => ( <div key={todo.id} className="todo"> <input type="checkbox" checked={todo.status === "done"} readOnly /> <span>{todo.title}</span> <span>{todo.dueDate ?? "无截止日期"}</span> </div> ))} </section> </div> ); }这样的渲染方式把“结论”和“讨论”分开，用户不需要滚动几百条消息去找谁拍板。普通消息可以默认折叠，Decision 和 Todo 始终展示在最显眼的位置。
5.3 未读数计算与通知体验
未读数不要在浏览器里遍历消息算，建议服务端直接用 message_reads 游标计算。
获取 Thread 列表时，接口可以返回一个未读数字段：
{ "id": "3f9a...", "title": "登录页交互方案评审", "unreadCount": 5 }前端拿到这个数字后，在 Thread 列表上显示红色数字即可。进入 Thread 后调用已读接口：
app.post("/api/threads/:threadId/read", async (req, res) => { const { threadId } = req.params; const userId = req.userId; const result = await pool.query( `SELECT MAX(id) AS last_message_id FROM messages WHERE thread_id = $1`, [threadId] ); const lastMessageId = result.rows[0]?.last_message_id; if (!lastMessageId) { res.json({ ok: true }); return; } await pool.query( `INSERT INTO message_reads (thread_id, user_id, last_read_message_id) VALUES ($1, $2, $3) ON CONFLICT (thread_id, user_id) DO UPDATE SET last_read_message_id = EXCLUDED.last_read_message_id, updated_at = now()`, [threadId, userId, lastMessageId] ); res.json({ ok: true }); });这里使用MAX(id)而不是MAX(created_at)是因为 UUID 不能保证时间顺序，但消息 ID 自增（或序列）能保证插入顺序。实际生产环境建议使用带时间信息的 ID，比如 ULID 或组合 id，避免排序歧义。
5.4 乐观更新与失败重试
前端可以在用户点击发送后先本地显示一条“发送中”消息，收到服务端 ack 后再替换为正式消息。可以用 useThreadMessages 这个 Hook 管理：
import { useEffect, useState } from "react"; import { io } from "socket.io-client"; const socket = io(import.meta.env.VITE_WS_URL); export function useThreadMessages(threadId: string) { const [messages, setMessages] = useState<Message[]>([]); useEffect(() => { socket.emit("thread:join", threadId); fetch(`/api/threads/${threadId}/messages`) .then((res) => res.json()) .then((data) => setMessages(data)); const handler = (message: Message) => { setMessages((prev) => { if (prev.some((m) => m.clientMessageId === message.clientMessageId)) { return prev; } return [...prev, message]; }); }; socket.on("message:created", handler); return () => { socket.off("message:created", handler); socket.emit("thread:leave", threadId); }; }, [threadId]); return messages; }乐观更新和去重，核心都是 clientMessageId。如果本地临时消息与 WebSocket 推送的消息拥有同一个 clientMessageId，就用服务端正式消息覆盖本地临时消息，避免出现两条重复内容。
6. 本地运行验证：从启动到结果确认
6.1 环境准备与版本建议
本地开发环境建议如下：
| 工具 | 建议版本 | 用途 |
|---|---|---|
| Node.js | 20 LTS 或更高 | 运行后端和构建前端 |
| PostgreSQL | 15 或 16 | 保存结构化数据 |
| Docker Desktop | 最新稳定版 | 快速启动 PostgreSQL |
| npm | 10 或使用 pnpm 9 | 安装依赖 |
这里的版本只是建议，实际项目要以自己团队的基准版本为准。本地不需要安装完整 PostgreSQL，直接用 Docker 更省事。
6.2 启动数据库和后端
在项目根目录准备 docker-compose.yml：
services: postgres: image: postgres:16-alpine environment: POSTGRES_USER: app POSTGRES_PASSWORD: app POSTGRES_DB: teamwork ports: - "5432:5432" volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:启动数据库并执行建表 SQL：
docker compose up -d cat schema.sql | docker compose exec -T postgres psql -U app -d teamwork启动后端：
npm install DATABASE_URL="postgres://app:app@localhost:5432/teamwork" npm run dev看到server listening on 3000就说明 HTTP 服务已经启动。此时不要急着结束，还要继续验证接口和实时推送。
6.3 用 REST 验证基础流程
先创建团队和线程，然后发送一条消息：
curl -X POST http://localhost:3000/api/teams \ -H "Content-Type: application/json" \ -d '{"name":"硬件产品组"}'拿到 teamId 后创建 Thread：
curl -X POST http://localhost:3000/api/teams/<teamId>/threads \ -H "Content-Type: application/json" \ -d '{"title":"登录页交互方案评审","ownerId":"<userId>"}'再向 Thread 发送消息：
curl -X POST http://localhost:3000/api/threads/<threadId>/messages \ -H "Content-Type: application/json" \ -d '{"senderId":"<userId>","content":"建议采用方案B","clientMessageId":"msg-001"}'正常响应应该包含服务端生成的 message 对象，包含 id、createdAt 等字段。如果返回 duplicated: true，说明同一条 clientMessageId 被重复提交了。
6.4 用 Socket.IO 客户端验证实时推送
启动一个 Node 脚本，模拟另一个在线用户：
import { io } from "socket.io-client"; const socket = io("http://localhost:3000", { auth: { userId: "<userId>" }, }); socket.on("connect", () => { console.log("connected"); socket.emit("thread:join", "<threadId>"); }); socket.on("message:created", (message) => { console.log("receive message:", message); });运行该脚本后，再用上面的 curl 命令发送一条新消息，客户端应该能在没有刷新页面的情况下收到 message:created 事件。
注意：不要只验证服务能启动。至少要验证两个客户端同时在线时，一端发消息另一端能实时收到，否则“实时沟通”的核心能力没有闭环。
6.5 验证结果应该是什么
完整的本地验证应该包含四个结果：
- REST 接口能创建团队、线程、消息。
- 数据库 messages 表里有对应记录。
- Socket.IO 客户端能收到实时事件。
- 重复提交同一 clientMessageId 时，数据库不会产生第二条记录。
如果这四个结果都成立，说明最小实时协作闭环已经跑通，可以继续做前端页面和更复杂的权限逻辑。
7. 常见问题排查：消息丢失、重复、未读不准
7.1 消息在弱网下丢失
现象：用户发送消息后，对方没有收到，数据库里也没有记录。
排查顺序：
- 先看服务端日志，接口是否被调用。
- 再看数据库，message 是否插入成功。
- 最后看 Socket.IO 连接，是否在发送前已经断开。
原因通常是客户端发送时网络不稳定，HTTP 请求没有到达服务端，或到达后响应丢失。
解决方式是在客户端引入本地待发送队列。消息先进入 pending 列表，等收到服务端 ack 后再移出。连接恢复后自动重发未 ack 消息，使用同一个 clientMessageId 保证幂等。
7.2 客户端重连后消息重复
现象：同一消息出现两次，前端去重无效。
原因有两个。第一，客户端每次重试时重新生成了 clientMessageId，数据库无法识别为重复。第二，前端去重时只比较了 message.id，但乐观更新阶段本地消息还没有 id。
正确做法：
- 客户端生成 clientMessageId 后整个生命周期都不变。
- 前端去重优先比较 clientMessageId，而不是 id。
- 数据库使用 UNIQUE (thread_id, client_message_id) 兜底。
7.3 未读数一直不准
现象：Thread 列表上的未读数字乱跳，或者进入 Thread 后依旧显示未读。
原因通常是实现里混用了两种方式：一种是全量统计未读消息数，另一种是用游标记录位置。两种方式切换后，统计口径混乱。
推荐统一使用 message_reads 游标。计算未读时，统计该 Thread 中创建时间晚于用户游标消息时间、且 sender_id 不等于当前用户的消息数量。进入 Thread 时服务端更新游标，退出时不要再重复减。
7.4 线程过深，结论淹没在回复里
现象：一个 Thread 下有几十条回复，最终决定藏在中部，新加入的人根本找不到。
这说明 Thread 解决了“主题聚合”，但没有解决“结论固化”。普通回复和最终决策仍然混在一起。
解决方式就是前面设计的 Decision 对象。产品经理在形成结论时，必须在 Thread 下创建一条 Decision，系统把它单独展示在“结论”区域。代码审查时也要检查一个原则：如果 Thread 被标记为已结案，但没有挂载任何 Decision 和 Todo，说明这个线程只是聊完了，没有沉淀出可执行结果。
8. 生产环境落地的关键点与可复用清单
8.1 学习环境与生产环境的差异
本地跑通最小闭环，到生产环境落地，至少还要补齐以下差异：
| 维度 | 学习环境 | 生产环境 |
|---|---|---|
| 数据库 | 单机 Docker | 高可用集群、定期备份 |
| 配置 | 环境变量兜底 | 配置中心或密钥管理 |
| 日志 | 控制台输出 | 结构化日志、集中采集 |
| 监控 | 不关心 | 接口耗时、连接数、消息量 |
| 权限 | 单用户演示 | 完整认证、角色、团队隔离 |
| 部署 | 本地进程 | 容器编排、滚动发布、回滚方案 |
| 幂等 | 已做基本约束 | 全链路幂等，含消息队列重投 |
如果只是内部小团队使用，不一定要一步到位全部实现，但数据库备份和权限校验不能省。
8.2 可复用的发布前检查清单
每次上线新版本，建议逐项检查：
- 所有写操作是否都带有 clientMessageId 幂等键。
- 所有 REST 接口是否都做了团队成员校验。
- WebSocket 连接鉴权是否生效，thread:join 是否校验权限。
- 消息是否先落库再广播。
- 未读游标是否按 thread_id + user_id 更新。
- 日志是否能关联到 messageId、threadId、userId。
- 是否存在单点故障，数据库连接和 Socket.IO 升级是否需要重启。
- 部署脚本是否有回滚步骤。
- 数据备份是否配置并做过恢复演练。
- 通知是否按订阅关系推送，而不是全部广播。
这份清单不需要一次性全部成立，但每一条都应该在迭代计划里被显式安排，否则系统越做越重，越难补。
8.3 扩展方向：搜索、通知网关、AI 摘要
第一版不需要做太多功能，但可以规划好扩展点。
首先，消息全文搜索是早期就需要的能力。PostgreSQL 自带的 tsvector 可以支持基础搜索，消息量上来后再切换 Elasticsearch 或 OpenSearch。
其次，通知网关可以对接邮件、企业微信或钉钉 webhook。目标不是把所有消息都推过去，而是只推送“有人 @我”“有决策已经生成”“我的待办到期”这类关键事件。
最后，当 Thread、Decision、Todo 数据足够完整后，可以基于消息文本做 AI 摘要，自动生成每周讨论总结。但要注意，摘要能力依赖结构化数据质量，如果消息本身没有语义边界，AI 也很难把结论抽出来。
结束语
产品团队真正需要的，不是一个能发更多消息的工具，而是一个能减少无效消息、保留决策轨迹的协作系统。如果只记住一个原则，那就是让讨论最终沉淀为结构化结论，让结论可以追溯、可以执行、可以搜索。
建议先把 Thread、Decision、Todo 这个最小闭环跑通，再考虑会议记录、文档关联和 AI 摘要。这套设计看起来不复杂，但每一步选型都决定了后续能否稳定扩展。消息幂等、未读游标、权限隔离、实时推送这些底层能力，才是“让人愿意使用”的真正基础。
