01 — 云融（YunRong）· 需求分析文档
项目定位：跨平台企业办公协作桌面客户端，以即时通讯为核心，融合任务通知与文件传输，强化网络编程与通信技术的综合运用。
版本：v0.1
状态：已发布
最后更新：2025-01
1. 项目背景与目标
1.1 项目背景
企业内部协作场景下，员工需要在消息沟通、任务处理、文件共享之间频繁切换。现有商业方案（企业微信、钉钉、Slack）功能臃肿且数据受制于第三方。本项目建设一个轻量、可控、跨平台的协作终端，同时作为 C++ / Qt / 网络编程技术的综合实践平台。
1.2 项目目标
| 维度 | 目标 |
|---|
| 业务目标 | 构建可独立部署的企业协作桌面客户端，覆盖 IM、任务通知、文件传输三大核心场景 |
| 技术目标 | 深度覆盖 TCP/IP、Socket、HTTP/WebSocket、多线程、SQLite/PostgreSQL、Qt GUI、设计模式等技术的实战运用 |
| 学习目标 | 以网络编程和通信技术为核心强化点，协议设计、连接管理、可靠性保障达到生产级理解 |
1.3 目标用户
- 企业内部员工（200–5000 人规模的组织）
- 系统管理员（服务端配置与监控）
- 开发/测试人员（本项目的二次开发与扩展）
2. 功能需求
2.1 即时通讯 (IM)
| 编号 | 功能 | 描述 | 优先级 |
|---|
| F-IM-01 | 文本消息收发 | 支持单聊和群聊，消息实时送达 | P0 |
| F-IM-02 | 消息状态回执 | 发送中 → 已送达 → 已读，三态反馈 | P0 |
| F-IM-03 | 离线消息拉取 | 客户端上线后自动拉取离线期间的消息 | P0 |
| F-IM-04 | 消息本地缓存 | 所有消息存入本地 SQLite，支持关键词搜索 | P0 |
| F-IM-05 | 图片消息 | 缩略图预览 + 原图查看，发送时先上传后发 URL | P1 |
| F-IM-06 | 文件消息 | 以消息卡片形式展示，支持点击下载 | P1 |
| F-IM-07 | 消息引用/回复 | 对特定消息进行引用回复，UI 上展示引用链 | P2 |
| F-IM-08 | @提及提醒 | 群聊中 @某人触发特殊通知 | P2 |
| F-IM-09 | 消息撤回 | 发送方可在 2 分钟内撤回已发消息，撤回后双方均显示”已撤回” | P1 |
| F-IM-10 | 消息编辑 | 发送方可编辑已发文本消息（保留编辑历史），接收方显示”已编辑”标记 | P2 |
2.2 任务与通知
| 编号 | 功能 | 描述 | 优先级 |
|---|
| F-TASK-01 | 任务推送通知 | 服务端推送审批、指派等任务，客户端弹窗 + 通知栏提示 | P1 |
| F-TASK-02 | 任务列表视图 | 按状态（待处理/已处理/我发起的）分类展示 | P1 |
| F-TASK-03 | 任务处理操作 | 审批通过/驳回、任务完成/延期等操作，结果同步服务端 | P1 |
| F-TASK-04 | 系统公告 | 管理员发布的全局公告，支持置顶和已读确认 | P2 |
2.3 文件传输
| 编号 | 功能 | 描述 | 优先级 |
|---|
| F-FILE-01 | 文件上传 | 通过 HTTP multipart 上传，支持大文件（>100MB）分块 | P0 |
| F-FILE-02 | 文件下载 | HTTP Range 断点续传，支持暂停/恢复/取消 | P0 |
| F-FILE-03 | 传输进度展示 | 实时显示上传/下载速度曲线和进度百分比 | P1 |
| F-FILE-04 | 传输历史管理 | 本地记录所有传输任务，支持重试和清理 | P1 |
| F-FILE-05 | 文件秒传 | 根据文件 Hash 判断服务端是否已存在，避免重复上传 | P2 |
| F-FILE-06 | P2P 局域网传输 | （v2 路线图）同一局域网内客户端间直连传输 | v2 |
2.4 用户与组织
| 编号 | 功能 | 描述 | 优先级 |
|---|
| F-ORG-01 | 用户注册/登录 | 账号密码登录，支持 Token 自动续期 | P0 |
| F-ORG-02 | 组织架构浏览 | 树形展示部门-人员结构，支持搜索 | P1 |
| F-ORG-03 | 个人状态设置 | 在线/忙碌/离开/离线，状态同步给其他用户 | P2 |
| F-ORG-04 | 联系人分组 | 自定义分组管理常用联系人 | P2 |
2.5 数据统计与报表
| 编号 | 功能 | 描述 | 优先级 |
|---|
| F-RPT-01 | 个人消息统计 | 日/周/月消息量趋势曲线，活跃时段热力图 | P2 |
| F-RPT-02 | 传输量统计 | 文件上传/下载流量统计，按时间聚合 | P2 |
| F-RPT-03 | 报表导出 | （v2 路线图）支持导出 CSV / PDF / JSON 格式的工作报告 | v2 |
3. 非功能需求
3.1 性能指标
| 指标 | 目标值 | 验证方法 |
|---|
| 消息发送延迟 | < 200ms (局域网)，< 500ms (广域网) | 时间戳打点测试 |
| 消息吞吐量 | 单连接 ≥ 100 条/秒 (1KB 文本消息) | 压力测试脚本 |
| GUI 响应时间 | 主线程事件循环不阻塞超过 50ms | Qt 性能分析器 |
| 内存占用 (空闲) | < 150 MB | 任务管理器长期观察 |
| 内存占用 (10 万条消息加载) | < 500 MB | 批量消息加载测试 |
| 大文件传输速度 | 达到可用带宽的 80% 以上 | 限速环境下的实测对比 |
| 冷启动时间 | < 3 秒 (不含首次登录) | 计时测试 |
3.2 可靠性需求
| 需求 | 描述 |
|---|
| 断线重连 | 网络断开后自动重连，指数退避策略（1s/2s/4s/8s/16s/30s/60s） |
| 消息不丢 | 发送失败的消息本地暂存，恢复后自动重发；接收侧幂等去重 |
| 数据一致性 | 网络异常时本地操作不受影响（离线可用），恢复后增量同步 |
| 崩溃恢复 | 异常退出后自动恢复未发送的消息和未完成的传输任务 |
3.3 跨平台需求
| 平台 | 最低版本 | 备注 |
|---|
| Windows | Windows 10 64-bit | MSVC 2019+ 或 MinGW-w64 |
| Linux | Ubuntu 20.04+ / Debian 11+ | GCC 9+，X11/Wayland |
3.4 安全需求
| 需求 | 描述 |
|---|
| 传输加密 | 全链路 TLS 1.3 (HTTPS + WSS) |
| 本地数据加密 | SQLite 数据库文件 AES-256 加密（SQLCipher 或应用层加密） |
| Token 安全存储 | 使用系统凭据管理器（Windows Credential Manager / Linux Secret Service） |
| 文件传输校验 | SHA-256 校验，确保传输完整性 |
3.5 可维护性需求
- 模块化架构，核心库与 GUI 分离
- 核心模块单元测试覆盖率 ≥ 70%
- CMake 一键构建，无外部 IDE 依赖
- Git 分支管理规范，Commit Message 遵循约定式提交
4. 网络通信需求（重点强化）
4.1 通信架构总览
┌──────────────────────────────────────────────────┐
│ 服务端 │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ REST API │ │WebSocket │ │ 文件存储服务 │ │
│ │ (HTTPS) │ │ (WSS) │ │ (HTTPS Range) │ │
│ └────┬─────┘ └────┬─────┘ └──────┬────────┘ │
└───────┼──────────────┼───────────────┼────────────┘
│ │ │
┌────┴──────────────┴───────────────┴────────┐
│ 客户端 (本项目) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │HTTP Client│ │ WS Client│ │File Trans│ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────────────────────────────────┐ │
│ │ Network Manager │ │
│ │ (连接池 / 心跳 / 重连 / 线程调度) │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
4.2 WebSocket 长连接需求
这是网络编程的「主战场」，需要深度处理以下问题：
| 需求项 | 详细描述 | 涉及技术 |
|---|
| 连接建立 | WSS 建立 TLS 隧道，支持自定义 Header（Token 鉴权） | QWebSocket, OpenSSL |
| 心跳保活 | 客户端每 30s 发送 Ping 帧，服务端回复 Pong，超时 3 次判定断开 | WebSocket Ping/Pong 帧 |
| 断线重连 | 指数退避重连，重连后自动拉取离线消息 + 增量同步 | QTimer, 状态机 |
| 帧协议 | 自定义 JSON 帧：{type, seq, payload, timestamp}，支持 ACK 确认 | JSON 序列化, 序列号管理 |
| 流控 | 服务端推送过快时客户端主动降级（合并通知），防止 GUI 线程拥塞 | 消息队列, 限流 |
| 多路复用 | 同一 WS 连接承载 IM + 通知 + 状态同步三种业务流（文件传输走 HTTP REST，不占用 WS 带宽） | 消息路由, type 字段分发 |
4.3 HTTP REST 短连接需求
| 需求项 | 详细描述 |
|---|
| 认证 | Bearer Token，过期自动用 Refresh Token 续期，续期失败跳转登录 |
| 请求重试 | 网络超时自动重试（最多 3 次），幂等请求可安全重试 |
| 并发控制 | 同一时刻最多 6 个并发 HTTP 请求（连接池上限） |
| 大文件上传 | multipart/form-data，分块传输（每块 1MB），支持断点续传 |
| 文件下载 | Range: bytes=N-M 分块下载，多线程并发下载（每线程一个 Range） |
4.4 协议设计
4.4.1 WebSocket 消息帧（JSON 文本帧）
{
"type": "msg|ack|notify|heartbeat|sync",
"seq": 12345,
"timestamp": 1704067200000,
"payload": {
// 根据 type 不同而不同
}
}
4.4.2 ACK 机制（单向确认）
ACK 仅用于客户端→服务端的消息发送路径。服务端→客户端的推送消息依赖 TCP 可靠传输 + seq 去重，不要求客户端回复 ACK。
| 场景 | 行为 |
|---|
| 客户端发消息 | 服务端收到后回复 {type:"ack", seq:xxx}，客户端收到 ACK 标记”已送达” |
| 客户端收消息 | 客户端根据 seq 去重（收到 seq ≤ last_recv_seq 视为重复，丢弃），不回复 ACK |
| ACK 超时 | 客户端 5s 未收到 ACK，重发（最多 3 次），最终失败标记”发送失败” |
4.4.3 二进制帧（缩略图等小型二进制负载）
- 前 4 字节：帧总长度（大端序）
- 第 5 字节：帧类型 (0x01=缩略图)
- 后续：二进制数据
- 大文件数据传输统一使用 HTTP REST + Range 分块（见 §4.3），不经过 WebSocket
4.5 网络层设计约束
| 约束 | 说明 |
|---|
| 不阻塞 GUI 线程 | 异步网络 IO（QWebSocket/QNetworkAccessManager）在主线程 Qt 事件循环中非阻塞执行；CPU 密集型业务逻辑（编解码/加解密）通过 QueuedConnection 分发给 Worker Pool |
| 连接池可配置 | 最大连接数、超时时间、重试次数均通过配置文件控制 |
| 流量监控 | 实时统计每秒收/发字节数，供曲线绘制使用 |
| 代理支持 | HTTP 代理 / SOCKS5 代理（企业内网常见需求） |
5. 数据存储需求
5.1 本地存储 (SQLite)
| 数据实体 | 预估量级 | 说明 |
|---|
| 消息记录 | ~10 万条/人 | 文本消息 + 元数据，按会话分表或分区 |
| 会话列表 | ~500 个/人 | 单聊 + 群聊会话元信息 |
| 联系人信息 | ~2000 条 | 缓存的组织架构人员信息 |
| 文件传输任务 | ~500 条 | 传输历史记录 |
| 配置/偏好 | ~100 条 | 用户设置、窗口布局等 |
| 草稿 | ~100 条 | 未发送的消息草稿 |
5.2 远程存储 (PostgreSQL)
| 数据实体 | 说明 |
|---|
| 用户账户 | 登录凭据、个人信息 |
| 组织架构 | 部门树、人员关系 |
| 消息归档 | 全量消息持久化（本地的超集） |
| 任务/审批 | 工作流数据 |
| 文件元数据 | 已上传文件的 Hash、路径、上传者 |
5.3 同步策略
采用 Hybrid 模式（参见架构设计文档）：
- 网络正常时：读操作优先本地（快速响应），写操作本地 + 远端并行（Write-through）
- 网络断开时：全部本地操作，连接恢复后增量同步（Write-back）
- 冲突处理：服务端时间戳为准（Last-Write-Wins），特殊场景标记冲突需人工处理
6. 用户界面需求
6.1 主窗口布局
┌──────────┬──────────────────────┬──────────┐
│ 导航栏 │ │ 信息面板 │
│ (图标竖排) │ 内容区域 │ (可选显示) │
│ │ │ │
│ ● 消息 │ ┌────────────────┐ │ 联系人详情 │
│ ● 任务 │ │ 会话列表 │ 聊天 │ │ 文件详情 │
│ ● 文件 │ │ │ 区域 │ │ 搜索面板 │
│ ● 联系人 │ └────────────────┘ │ │
│ ● 设置 │ │ │
└──────────┴──────────────────────┴──────────┘
6.2 关键界面清单
| 界面 | 核心控件 | 备注 |
|---|
| 登录窗口 | QLineEdit, QPushButton, QLabel | 支持记住密码、自动登录 |
| 会话列表 | QListView + 自定义 Delegate | 未读角标、最后消息预览、时间戳 |
| 聊天窗口 | QListView (消息气泡) + QTextEdit (输入) | 自定义消息气泡 Delegate，支持文本/图片/文件卡片 |
| 组织架构树 | QTreeView + 自定义 Model | 懒加载子节点 |
| 文件传输面板 | QTableView + QProgressBar | 实时速度曲线 (QChartView) |
| 数据统计面板 | QChartView (折线图/柱状图) | 日期选择器、导出按钮 |
| 系统托盘 | QSystemTrayIcon | 未读消息数角标、新消息闪烁提示 |
6.3 自定义控件需求
| 控件 | 描述 | 技术点 |
|---|
| 消息气泡 | 自适应文本高度，支持选中/复制/右键菜单 | QStyledItemDelegate, paintEvent |
| 头像控件 | 圆形裁剪 + 在线状态角标 | QPainter, QPixmap 裁剪 |
| 传输速度曲线 | 实时更新的动态曲线，支持缩放 | QChart + QLineSeries |
| 组织架构树 | 支持搜索高亮、拖拽排序 | QTreeView + QSortFilterProxyModel |
| Toast 通知 | 右上角滑入式通知弹窗 | QPropertyAnimation |
7. 系统约束与假设
7.1 技术约束
| 约束项 | 说明 |
|---|
| 语言 | C++17/20 |
| GUI 框架 | Qt 6.x (Widgets，非 QML) |
| 构建系统 | CMake 3.20+ |
| 数据库 | SQLite 3.35+, PostgreSQL 14+ |
| 第三方库 | Qt 6 原生网络模块（QWebSocket + QNetworkAccessManager），nlohmann/json、spdlog 通过 CMake FetchContent 引入 |
| 版本控制 | Git |
| 平台 | Windows 10/11 + Ubuntu 20.04+ |
7.2 外部依赖假设
- 服务端：配套后端使用 Go 实现，提供 REST API (Gin) + WebSocket (gorilla/websocket) + 文件存储接口。客户端以 Mock Server（Qt 进程）辅助开发调试
- 推送服务：桌面通知依赖操作系统原生通知机制（Win: Toast, Linux: D-Bus Notifications）
- 网络环境：假定企业内网环境，延迟 < 50ms，偶有断网但非持续丢包
7.3 不做的事项（范围外）
- ❌ 音视频通话（技术栈无法充分覆盖，且增加大量复杂性）
- ❌ 端到端加密消息（合法合规的企业内部通信，加密在传输层完成）
- ❌ 移动端（仅桌面端）
- ❌ 第三方应用集成/机器人框架
- ❌ 服务端实现（Go 后端独立项目，本项目只含客户端 + Mock Server）
8. 验收标准
8.1 核心验收场景
| 编号 | 场景 | 验收条件 |
|---|
| AC-01 | 两个客户端 A 和 B 互发文本消息 | B 在 500ms 内收到 A 的消息，消息状态正确流转 |
| AC-02 | 客户端在飞行模式下发送消息，恢复网络 | 消息自动重发成功，接收方不出现重复消息 |
| AC-03 | 上传 500MB 文件，中途断网后恢复 | 从断点继续传输，最终文件 SHA-256 校验通过 |
| AC-04 | 客户端运行 24 小时，持续收发消息 | 内存无持续增长（无泄漏），消息计数准确 |
| AC-05 | 同时对 10 个会话发送消息 | GUI 无卡顿，消息顺序正确 |
| AC-06 | 在 Windows 和 Linux 上分别编译运行 | 功能行为一致，UI 风格适配各自平台 |
8.2 技术验收标准
- 网络层代码中至少体现：自定义帧协议、ACK/重传、心跳保活、断线重连、连接池 五项技术
- 至少使用 5 种设计模式，并在文档中标注
- 核心网络模块有独立的单元测试（Mock Server 注入测试）
- SQLite 和 PostgreSQL 的 DAO 层共享接口，可编译时切换
- CMake 工程在 Win/Linux 上一条命令构建成功
附录 A — 术语表
| 术语 | 说明 |
|---|
| WSS | WebSocket Secure，基于 TLS 的 WebSocket |
| ACK | Acknowledgement，消息确认帧 |
| SSO | Single Sign-On，单点登录 |
| DAO | Data Access Object，数据访问对象 |
| SC | Signal-Slot Connection，Qt 信号槽连接 |
| FIFO | First In First Out，先进先出队列 |
附录 B — 需求追溯矩阵
| 需求编号 | 需求简述 | 架构设计 (02) | 通信协议 (03) | 数据库 (04) | 模块设计 (05) | API 接口 (06) | GUI 设计 (07) | 测试计划 (08) |
|---|
| F-IM-01~04 | 文本消息核心收发 | §5-6 | §3.4.3 | §2.2.2 | §2, §4.1 | §3.3, WS | §3.1 | §3.2 场景1 |
| F-IM-05~06 | 图片/文件消息 | §6.3 | §3.4.3 变体, §4 | §2.2.2 | §4.2 | §3.5 | §3.1 文件卡片 | §3.2 场景4 |
| F-IM-07~08 | 引用/@提及 | — | §3.4.3 | §2.2.2 | §2.2.3 | — | §3.1 | — |
| F-TASK-01~04 | 任务推送与处理 | §2 | §3.4.6 | §2.2.6 | §4 | §3.4 | §3.4 | §3.2 场景5 |
| F-FILE-01~02 | 文件上传/下载 | §6.3 | §4, §9 | §2.2.5 | §4.2 | §3.5 | §3.5 | §3.2 场景4 |
| F-FILE-03~06 | 传输进度/秒传 | §6.3 | §4.5, §9.1 | §2.2.5 | §4.2 | §3.5.1 | §3.5, §4.3 | — |
| F-ORG-01~04 | 用户登录/组织 | §7.1 | §3.4.1-§3.4.2 | §3.2.1, §3.2.4 | §3 | §3.1-§3.2 | §3.3 | — |
| NFR-性能 | 性能指标 | §4 | §7 | §5 | — | §2.4 | §3.1 | §5 |
| NFR-可靠性 | 重连/不丢消息 | §5.2-§5.4 | §8 | §4 | §2.2.4, §3.4 | — | — | §3.2 场景2 |
| NFR-安全 | TLS/AES/SHA | §5.1 | §2, §9.2 | §7 | — | §1.3, §5 | — | — |
「—」表示该需求在当前文档中未单独展开，由其他文档覆盖。
附录 C — 文档修订记录
| 版本 | 日期 | 作者 | 变更说明 |
|---|
| v0.1 | 2025-01 | — | 初稿，完成全部章节 |