用兴趣认识人
用内容保持活跃
用实时通话沉淀关系

一、产品定位与功能

微信擅长维护熟人却难破冰，小红书内容好看却不负责建立关系，Soul 靠匹配但关系常断在第一次对话。

典型场景

六大亮点

核心功能矩阵

设计语言

二、技术方案

模块化单体 + 单一 WebSocket 通道，用最低的运维复杂度跑通完整社交闭环。

技术选型

系统架构分层

客户端层 Flutter（页面 / Riverpod 状态 / Dio REST + WsClient 单连接）
   │  HTTPS REST          │  WSS
   ▼                       ▼
接入层 Nginx（chat.yundudu.top:443）
   ├─ /api/* · /uploads/* · /health → 反代到应用层
   └─ /ws（Upgrade 反代 → WSS）
   ▼
应用层 Go 模块化单体（127.0.0.1:8901）
   ├─ 中间件链：Recovery · Logger · CORS · RateLimit · JWT
   ├─ internal/ws：Hub 连接中心 + Client 读写泵
   └─ 12 个业务模块：auth · user · feed · like · comment · im
                    match · webrtc · notify · relation · topic/search · misc
   ▼
数据层  MySQL 8（库 solink · 12 表）  +  Redis（在线 · 未读 · 通话状态 · 限流）

实时通信设计

单连接 + 多订阅

服务端 Hub 维护 map[uint64]*Client，一个用户一条连接（同用户重复连接顶替旧连接）。同一条 WS 被 im / webrtc / notify / match 四个模块共用，靠信封 event 字段路由。信封的 Payload 是 json.RawMessage——基础层只解到 event 一层，payload 由业务模块自己反序列化，所以新增事件类型 Hub / Client 一行都不用改。

连接活性由读写泵保证：两个 goroutine 任一退出即注销（gorilla 的 *Conn 要求同一时刻只能有一个读者、一个写者）。下行投递非阻塞，队列 256，慢消费者直接断开而不是拖垮广播。客户端侧对称收敛为一条连接，事件用 broadcast Stream 暴露给 N 个订阅者，用 ref.listen 而非 ref.watch（后者会让 Provider 每条事件整体重建）。

消息可靠性：三条机制叠加

• client_msg_id 幂等去重 —— 唯一键 (conv_id, client_msg_id)。针对真实重放场景：消息已落库推送但 ACK 回程丢包 → 客户端重连后重放离线队列 → 无幂等则对方收到两条一样。
• 单事务三写 —— INSERT message + UPDATE conversation 最新消息 + UPDATE 其他成员 unread+1。分开写的后果很具体：② 失败"列表不刷新"，③ 失败"有消息但红点不显示"。
• 真实 ACK —— msg.ack 的 serverMsgId 是落库后的服务端 ID，协议层禁止 pending 假回执。幂等冲突同样返回成功 ACK，只携带原消息 ID。

// backend/internal/module/im/repo.go:189 —— 单事务三写
err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
    // 1) 写入消息;uk_conv_client 冲突 → 幂等重复投递,事务内无任何写入
    if err := tx.Create(m).Error; err != nil {
        if isDuplicateKeyErr(err) {
            return nil // created 保持 false,由服务层回查已有消息
        }
        return err
    }
    created = true
    ...

已读回执与未读双写

未读存在 conversation_member 上而非 conversation 上——同一会话里 A 和 B 的未读数天然不同。策略是 DB 为准、Redis 加速、漂移自愈：发送时 DB 随事务 +1，Redis HINCRBY 只是加速（Redis 异常返回 -1，调用方降级读 DB）；每次拉会话列表时顺手比对并回填修正——没有独立的缓存一致性任务，读的时候顺手修。

-- backend/internal/module/im/repo.go:340 —— GREATEST 保证已读位置单调不减
UPDATE conversation_member
   SET unread = 0,
       last_read_msg_id = GREATEST(last_read_msg_id, ?)
 WHERE conv_id = ? AND user_id = ?

客户端上报已读是频繁且乱序的（每收一条就上报、上滑看历史先上报 500 再上报 480、多端位置不同）。直接赋值会让一次乱序旧值把已读位置"倒退"，已读过的消息又变回未读。GREATEST 让这个字段天然免疫乱序。

会话幂等：member_hash = md5(min:max)

// backend/internal/module/im/model.go:92
func SingleMemberHash(a, b uint64) string {
    lo, hi := a, b
    if lo > hi { lo, hi = b, a }
    sum := md5.Sum([]byte(fmt.Sprintf("%d:%d", lo, hi)))
    return hex.EncodeToString(sum[:])
}

音视频通话架构

1v1 场景下 P2P 完全够用，代价是打洞失败的网络必须靠 TURN 兜底。服务端对 SDP 原样透传、不解析：解耦（SDP 格式随 webrtc 版本演进）、性能（ICE 一次通话几十条）、安全（不解析就不会因解析 bug 崩溃）。服务端只做两件事——校验你是会话成员、找到对端。

事件设计：单一 call.push + action

状态事件与媒体信令分成两条通道：call.push（生命周期状态，一次通话 3~5 条，不能丢）与 call.signal（媒体协商，几十条，丢几条 ICE 不影响）。混在一个事件里服务端每条都要判断"这是状态还是 SDP"，高频 ICE 还会挤占状态事件处理路径。分成两个事件后 onSignal 只有 25 行纯转发，正确性极易验证。

通话状态机：Redis call:state:{convId}

// backend/internal/module/webrtc/signal.go:38
const (
    callStateKeyPrefix = "call:state:"
    inviteTTL          = 60 * time.Second // 呼叫等待窗口(超时自动清理)
    inCallTTL          = 2 * time.Hour    // 通话中保底窗口(防状态残留)
)

两个 TTL 差这么大是有意的：呼叫中 60s = 振铃时长，60s 无人接听 Key 自动消失，状态回到空闲，不需要任何定时任务清理；通话中 2h 不是"最长通话 2 小时"，而是防状态残留的兜底（App 被强杀、手机没电后 2h 自动消失，避免该会话永远打不进）。用 TTL 代替清理任务——Redis 原生能力，零代码，不会漏。

三种并发/异常：同一主叫重复 invite → 幂等重发并刷新 TTL；他人正在呼叫 → 新主叫收 busy；被叫离线 → 主叫收 offline 且刻意不写 Redis（写了状态，被叫上线后最长 60s 内谁都打不进来）。挂断时若客户端没传 duration，服务端用 acceptedAt 自己算——客户端时钟不可信。

模块解耦：依赖倒置 + 两阶段装配

webrtc 需要 im 的能力（校验成员、查对端），im 需要把 call.* 上行信令转交 webrtc——互相 import 会触发 Go 编译期 import cycle。解法是两个接口各自定义在使用方自己的包里：

// backend/internal/app/app.go:169 —— 装配层同时 import 两者并接线
webrtcRelay := webrtc.NewRelay(hub, imSvc, userSvc, redisCache, ...)
// call.* 上行信令从 im WS 分发器转投 webrtc(两阶段注入,防 import 环)
a.IMWSHandler.SetCallDispatcher(webrtcRelay)

三、数据设计、安全与质量

12 张核心表 + 9 类 Redis Key，统一"DB 为准 → 缓存加速 → 降级兜底"。

核心数据模型

Redis Key 约定

安全与隐私

工程质量

统一响应信封 {code, message, data}，错误码按业务分段：1xxx 参数 / 2xxx 业务（2101 验证码错误、2401 配额耗尽、2701 撤回超时）/ 3xxx 鉴权 / 4xxx 资源 / 5xxx 服务。

部署架构

Flutter App → HTTPS/WSS（chat.yundudu.top:443）→ Nginx 反代 → systemd 守护的 Go 服务（127.0.0.1:8901）→ MySQL 8 + Redis。后端为静态编译二进制（约 13MB，stripped），只监听回环地址，端口不对外暴露。

四、当前状态与已知限制

诚实标注——这些是"已知且可改进项"，而非设计缺陷。

版本状态

已知限制

已明确的迭代清单：接入 TURN 中继 · 接入厂商推送通道 · 切换对象存储 · 开放群聊 · 上线搜索与话题系统 · 补 service 层单测。