基于 C++17 / Qt 6 的即时通讯应用，采用 C/S 架构，当前产品支持 Windows Qt 桌面客户端和 Vue Web 客户端双端互通。
当前按本地开发推进：Windows 运行客户端，WSL Ubuntu 执行 Linux 服务端的
Java/PostgreSQL 集成验证，后续部署到 Linux 服务器。
本地附件服务由 Docker 分配回环端口并严格读取实际映射，避免 WSL 空闲端口被宿主机转发层拒绝。
环境准备、独立检出及临时数据库命令见本地开发指南；
生产签名、云环境和正式发布验收不作为当前本地开发的前置条件。
Windows 提及消息新增独立真实服务检查：成员目录、中文/emoji 提及范围、双方投影、SQLite
重开、会话恢复、新设备历史和非成员拒绝已在原生 Windows 与 WSL 通过；运行普通本地
V2 服务即可，不启用附件候选。复现方式见本地开发指南，完整窗口和发布验收仍独立保留。
本地窗口验收发现并修复了 Windows 传输层遗漏编辑、回应和置顶请求及回包的问题。
真实服务检查现已覆盖提及编辑确认、双方回应/置顶同步，以及编辑后 SQLite、重连和新设备
历史中的提及信息；Windows 与 WSL 均通过。原生本地会话窗口也已完成提及选择、发送、编辑、新接收端历史
及回应/置顶同步，详见验收记录；
完整登录壳和正式发布门槛仍独立保留。
Windows 提及选择器加载期间保留列表焦点，结果返回后可直接按 Enter 插入；刷新按账号
保留选择且不抢走编辑框焦点。当前原生 Windows 面板回归及 WSL 检查通过。
真实服务检查还覆盖离线编辑持久化、客户端对象完全重建后的恢复、多设备编辑冲突及
补齐历史后的显式重提；Windows/WSL 均通过。进一步使用独立测试进程在编辑落盘后强制
终止，验证同设备恢复和冲突处理；真实服务编辑结果在传输/应用边界丢弃后的同设备恢复
也已通过，两次提交不产生重复修订。事务中断、网络层丢包与窗口冲突交互仍单独保留。
Windows 草稿清理已修复空 QString 被绑定为 SQL NULL 的问题，发送后持久化为空文本，
避免旧草稿在重开缓存后恢复。仓库回归与 Windows/WSL 真实发送检查通过。
Windows 编辑在本地入队后立即退出编辑模式并恢复原草稿，不再依赖在线确认刷新按钮；
离线待发时的按钮状态、草稿和键盘焦点已通过 Windows/WSL 面板检查。
真实提及回复检查已覆盖双端投影、引用目标/序号、Unicode 范围、草稿清理和新设备历史。
并发检查暴露的服务端历史页快照不一致已修复：授权、最新序号和条目使用同一只读
可重复读事务；确定性数据库回归与 Windows/WSL 共享账号并发完整检查通过。
Windows V2 编辑框在输入法预编辑期间暂停 Ctrl+Enter 和 Escape 的应用快捷键，
避免未上屏时提前发送或取消回复；上屏后恢复快捷键。Qt 输入法事件回归在 WSL 通过，
真实 Windows 输入法候选窗交互仍需独立验收。
提及选择器现在优先处理 Escape，仅关闭成员列表、保留草稿和回复目标并返回编辑框。
WSL 24 项回归通过；Windows 构建成功，本次原生面板测试被系统代码完整性策略拦截。
原生验收窗口另已确认 Escape 保留普通/回复草稿、回复目标和输入焦点，见交互记录。
本地 PostgreSQL 验证分别检查关系约束与非空字段，兼容 PostgreSQL 18 的目录差异；
真实数据库的 V1 会话集成测试使用当前时钟，避免固定历史日期导致测试会话过期。
WSL 已通过 Redis TLS/ACL 与真实重启、跨网关投递和单网关替换共 6 项检查，
无失败或跳过；命令、源码版本和未覆盖范围见同一份本地开发指南。
HAProxy 本地验证支持显式映射 WSL 网关地址，配置检查保持非 root 只读容器，
摘流场景以实际 DOWN 事件判断入口状态，避免固定等待时长造成误判。
网关崩溃、批量恢复和强制摘流测试也使用同一状态观察，保留有界等待、会话身份
与消息补齐断言；证书轮换和故障恢复的本地结果持续记录在开发指南中。
此前基础 PostgreSQL 检查跳过的 13 项网关条件场景已分别完成本地验证，包含
双入口故障恢复和已提交版本间切换；这不代表生产容量或正式发布验收完成。
本地可用 tools/run_local_v2.py 启动临时 Java V2/PostgreSQL 和 HTTPS Web 页面，
使用两个测试账号互聊；真实 Edge 验收已覆盖认证拒绝、双向 Unicode 消息和
全新浏览器上下文恢复服务器历史，启动步骤见本地开发指南。
消息搜索支持显式本地候选参数，并提供 Web/网关开关组合的真实 Edge 验收；
默认仍关闭，组合检查包含实际搜索与关闭时不发送查询帧。
V2 Web 已修正浏览器不接受的关闭码：协议错误、离线和发送失败使用合法的
应用关闭码，失败连接立即退出当前状态，迟到的数据和关闭事件不会影响重连。
真实 Edge 断线验收覆盖离线消息补齐、会话恢复和搜索不自动重放；Web 搜索结果
现在离线时立即清空，避免在恢复连接前继续展示可能过期的结果。
离线发送也已通过真实 Edge 验收：页面刷新和重新登录后仍保留失败消息，显式
重试才发送；实际提交一次，双方与新浏览器上下文读取的历史均无重复。
Web V2 聊天区域现支持 Ctrl+F 聚焦已启用的会话搜索，搜索区域内 Escape
关闭并恢复按钮焦点；快捷键不自动查询，未启用搜索时保留浏览器原有行为。
WSL 可运行 python3 tools/verify_local_profile_storage.py，以一次性 MinIO/TLS
验证头像对象首次写入、精确重试、读取及清理；独立检查测试桶为空并删除。
本地结果不自动启用头像运行时，也不替代部署目标的存储准入。
同一脚本加 --attachments 可验证附件签名上传、CORS、禁止覆盖重放、校验和及
删除；已通过不允许的来源和正文校验和不一致的真实拒绝路径。
附件本地验收还覆盖签名链接实际过期后拒绝写入，以及重新授权后恢复上传。
新增 --gateway-attachments 场景，将一次性 PostgreSQL、TLS 网关和 MinIO 连通，
验证真实签名 PUT、禁止覆盖重放、READY 落库、重复完成确认和对象清理。
本地启动器支持 --enable-attachments，为该次开发会话创建 TLS MinIO 和独立桶，
启动附件运行时；退出时连同临时数据库与存储一起清理，默认仍关闭。
Web 构建设置 VITE_CHAT_V2_LOCAL_ATTACHMENTS=true 后，可在本机会话中选择文件、
查看上传阶段、取消或重试；真实 Edge 已验证 HTTPS PUT、READY 确认和空文件拒绝。
仅开启上述上传开关时不会发送聊天消息。另加 VITE_CHAT_V2_LOCAL_FILE_MESSAGES=true，
并以 --enable-attachment-messages 启动本地网关，可上传并发送文件消息：先将稳定意图
及附件元数据写入独立 IndexedDB，再提交；支持失败重试、对端接收和刷新后历史恢复。
真实 Edge 已验证该流程，文件内容和签名链接不进入消息缓存。本地文件消息候选现可
点击下载，由服务端按当前身份授权，浏览器直接保存对象；接收方下载后的文件名和
字节与上传内容一致，已通过真实 Edge 验证。
下载授权已新增按消息 ID 查询的 PostgreSQL 边界，检查接收者账号、设备、成员资格、
群生命周期及消息/附件状态；上传完成但尚未发送的对象不提供接收者下载资格。
签名 GET 服务授权前后复核、最长两分钟、强制下载和禁止缓存；本地运行时使用
60 秒授权。V2 类型 138/139 与 Web 临时下载协调器已接入，见 ADR-0418/0419。
后端已补充文件消息的应用层/数据库事务：复用既有类型 2 和附件外键，校验 READY、
会话及所有者设备，原子写入消息、序号和投递事件。
通用消息历史现读取附件 ID、文件名、大小、媒体类型与生命周期状态，保留顺序游标，
不返回对象路径或签名链接。V2 已增加文件消息字段与能力 9，显式专用网关入口支持
提交、历史及实时投递；旧客户端在该入口握手时被明确拒绝。默认运行和本地上传预览
仍不启用文件消息收发；新的本地文件消息候选需单独开启。Windows 文件操作界面
已接入本地候选，WSL/Edge 本地证据不代表 Windows 产品发布验收完成。
Windows 文件消息候选使用显式关闭的能力 9 协商、文件引用提交、附件历史/实时
元数据及下载授权 API。SQLite 版本 8 保存稳定发送意图和附件元数据，支持原设备
重连重放与失败重试；不保存文件字节、磁盘路径或签名链接，撤回会清除附件元数据。
SQLite 现扩展到版本 9，新增账号/原设备隔离的上传恢复意图，保存稳定 ID、大小及哈希，
不保存路径、文件字节或签名链接；每账号最多 16 条，READY 状态只前进。恢复应用 API
已能在同一事务中复用原消息 ID 入队并清除意图，失败不发送；已确认记录不重复发送。
重启后重新选择文件、协调器和恢复界面尚未接入，不能视为已支持完整中断恢复。
迁移与备份恢复要求见 ADR-0423。
Windows 控制器现可显式创建附件协调器，并把 READY 附件交给消息应用服务先落库
再发送。消息展示数据包含本地化文件名、大小、撤销/不可用状态；只对已接受的 READY
文件提供可下载标记，文件消息不显示不支持的回复、编辑、转发等动作。
协调器连接分块哈希、WSS 注册/授权、HTTPS PUT 和 READY 确认。每个协议请求默认
30 秒超时，HTTPS 默认五分钟总超时；取消或会话变化清理临时状态。PUT 结果不确定
时先请求服务端完成确认，不自动重传；READY 后落库失败可直接重试发送。
下载校验大小和 SHA-256 后原子保存，失败、取消或超时保留原目标文件；拒绝重定向，
不复用 Cookie 或保存响应缓存。详情见 ADR-0420/0421/0422。
Windows 文件界面已接入选择文件、另存文件、进度、取消和入队失败重试，并支持中英文。
切换会话、会话失效或关闭界面会取消临时操作；保存位置由用户选择，不自动打开下载文件。
WSL 下启用可选 Widgets 验证后，完整 C++ 构建及 24 项回归通过；文件与 SQLite 为真实
本地数据，网络使用测试替身。默认产品配置仍关闭文件功能，原生系统文件窗口与完整
交互验收按本地开发指南逐项进行。本地候选可通过
CHATROOM_ENABLE_WINDOWS_V2_ATTACHMENT_MESSAGES=ON 显式启用，并要求 V2 预览开启；
配置诊断 schema 6 输出 attachmentMessagesEnabled。复现方式见本地开发指南。
Windows C++ 组件现已在 WSL 通过真实 Java/PostgreSQL/MinIO 联调：文件上传、READY、
发送确认、对端下载与字节校验、拒绝下载保留目标文件、断线恢复，以及新设备历史下载。
联调修复了客户端把服务端设备 UUID 误认为本地安装 ID 的认证问题；继续校验 UUID 和会话
关联。随后已在本机 Windows 11（26200）使用 Qt 6.11.1 / MSVC 14.51 完成原生 Release
构建、运行依赖部署和 5 项文件相关测试，原生程序连接 WSL 真实服务的同一文件链路也已
通过。tools/build_local_windows_files.ps1 可复现本地候选；这些是当前主机开发证据，
不替代正式 MSVC 2022/Windows 支持矩阵或签名发布。
新增 V2WindowsLocalFileUi 手动验收入口，直接复用产品会话界面并连接一次性 WSL 服务。
当前主机已验证原生文件选择/保存窗口、取消后重试，以及发送后下载的 SHA-256 一致性；
单账户入口还通过新设备历史下载，以及系统覆盖提示拒绝后保留原文件的检查。
完整 ChatClient 登录入口、明确双端实时交互、缩放及辅助功能仍需单独验收。
完整 ChatClient 当前仍先走 V1 登录，再启动 V2 预览。新增 tools/run_local_v1.py 可在
Windows 本机启动隔离的真实 V1 服务及同名测试账号，配合 WSL V2 环境准备完整入口验收。
新增独立 ChatClientLocal 本地验收构建，复用完整产品入口并隔离设置、缓存和单实例锁；
显式载入本次开发证书，保留 TLS 主机名校验，禁止外部 V2 地址、备用地址和自动更新。
原生构建、6 项相关回归和真实 TLS 信任/主机名拒绝检查通过；本机应用程序控制策略阻止
启动该完整程序，正常登录及菜单交互仍未验收。正式 ChatClient 不包含该证书载入代码。
PUT 后、READY 前退出的原生恢复也已通过：同设备重启、重新选择源文件、恢复发送、
原生另存和字节一致性检查，见本地验收记录。
恢复区域现按说明、文件列表和操作按钮分行排列，避免窄窗口及大字体把窗口撑宽；
中英文 100%/150%/200% 字体、480 逻辑像素宽度、Tab 顺序与完整文件名辅助接口检查通过。
这是组件布局证据，Windows 系统 DPI 和屏幕阅读器验收仍待完成。
文件另存窗口现可预填通过本地检查的原文件名，路径、设备名和不安全名称保持空白；
默认目录缺失时退回用户主目录。中文预填及取消已在原生 Windows 窗口验证，WSL 24 项
回归通过；最新 Windows 构建的消息面板测试被代码完整性策略阻止启动，尚未补齐该项。
V1 服务新增 --bind-address，本地启动器将 TCP/WS/HTTP 全部绑定 127.0.0.1；临时数据
退出清理，不复制旧数据库或 .env。原有 V1 冒烟、启动器隔离测试及真实监听检查通过。
V1/V2 账号仍是独立夹具，完整产品的本地证书连接与登录交互尚未验收（ADR-0424）。
Windows 文件候选已接入持久化上传与恢复入口：注册前保存记录，当前会话显示未完成文件，
提供继续发送和放弃发送。未完成上传需重选原文件并校验大小/SHA-256，先探测服务端状态，
仅明确缺失时继续上传；已 READY 则沿用原消息身份入队。取消保留恢复记录，放弃仅删除
本地发送意图，不删除源文件。恢复列表按账号、原设备和会话隔离，支持中英文与辅助名称。
组件和控制器回归覆盖持久化、重选取消、内容不符、会话切换、断线及 READY 入队。
Windows 原生联调还验证了注册后、PUT 后尚未确认 READY 时的独立进程退出与恢复；
原设备和消息身份保持一致，已上传场景恢复时不再 PUT，下载字节校验通过。手动验收入口
新增同一服务会话内复用缓存/安装标识的目录参数；本机原生窗口已验证注册后进程退出、
重启显示恢复记录、重选取消再继续、恢复消息另存及 SHA-256 一致性。完整产品入口、
缩放/辅助技术与提供商验收仍待完成（ADR-0423）。
本轮 WSL 全构建/24 项测试和 Windows Release 构建/6 项相关测试通过，恢复面板中文
布局已检查；这仍是本地候选证据，不替代完整原生交互与发布验收。
V2 网关阶段超时处理器已移到握手与认证事件的下游，避免成功登录后仍被旧握手
计时器断开。产品管线回归覆盖握手成功、认证成功后的存活，以及未完成阶段的超时关闭。
Web V2 附件协调器的注册、授权、完成确认现有独立的 30 秒响应超时，网关静默
时释放关联请求和临时字节，返回可重试错误；本地预览上传界面需显式开启。
附件 Fetch 直传默认 5 分钟超时并中止请求，保留用户取消/断线传递，完成后
清理计时器及取消监听器，避免存储无响应时无限等待。
附件协调器现暴露读取、校验、注册、授权、上传、完成确认的阶段状态，供后续
界面展示；取消、失败或完成后恢复空闲，阶段通知不包含文件或授权信息。
附件网关已增加显式管线组装入口，旧启动路径默认关闭；组件为每条连接创建
独立处理器并保留认证检查。网关服务与 WebSocket 升级层现可显式传递该组件，
升级成功后才安装到认证处理器之后。运行时可显式注入存储端口，复用 PostgreSQL
附件元数据和有界工作线程，并提供固定标签的附件指标；默认启动与产品上传入口仍关闭。
Windows 功能候选 CI 会独立保留 90 天的普通/候选二进制配置诊断、 对应 SHA-256、JUnit 交互测试结果及源码/运行标识，便于追溯默认关闭与候选启用状态。 该证据不包含可发布客户端，不替代正式签名、Windows 10/11 支持矩阵或真实端点验收； 已有运行及过期产物的边界见原生 CI 核对记录。
Web 日常验证使用 Chromium 和 Microsoft Edge（Playwright msedge 通道），不再下载或运行 Firefox。
已安装 Edge 的开发机只需安装 Playwright Chromium；Edge 使用本机稳定版，不由 Playwright 锁定版本。
Web CI 分别构建 V2 功能开启候选和关闭候选，在 Chromium/Edge 中执行完整
V2 浏览器场景，覆盖转发、提及、搜索、通知、屏蔽及回滚入口；仍使用协议夹具，
不代表真实网关验收。本机 Chrome 与固定 Chromium 的分组结果，以及 Windows
Firefox 启动限制，见浏览器记录。
- 用户注册 / 登录（新密码使用 libsodium Argon2id，旧 SHA-256 + Salt 在成功登录后渐进升级）
- 唯一用户 ID（可修改，30 天冷却）+ 可变昵称
- 多聊天室（创建 / 加入 / 退出 / 删除 / 重命名 / 密码保护）
- 实时消息收发，自定义气泡渲染
- 表情选择器（96 个 Emoji，8×12 网格）
- 消息撤回（2 分钟内）
- 聊天记录存储与加载（上滑加载更多）
- 图片 / 文件发送（自动识别类型）
- 小文件直传（≤8MB）
- 大文件分块传输（4MB/块，最大 4GB）
- 上传 / 下载暂停、恢复、取消
- 图片 / 视频缩略图预览
- Web 端文件预览（图片缩放拖拽、视频 DPlayer 播放、PDF / 文本 / 音频在线预览）
- 用户头像上传与裁剪（256×256 PNG）
- 个人资料编辑（昵称 / 用户 ID / 密码）
- 在线 / 离线状态显示
- 用户信息弹窗（头像、角色、状态）
- 强制下线（同一账号异地登录）
- 房间管理员设置 / 取消
- 踢出用户
- 删除消息（单条 / 全部清空 / 按日期范围）
- 房间设置（文件大小限制、房间密码）
- 删除房间
- 亮色 / 暗色主题切换（Qt QSS + Web CSS 变量）
- 系统托盘（最小化到托盘、消息通知）—— Windows Qt 端
- 窗口贴边自动隐藏 —— Windows Qt 端
- 断线自动重连 + 自动重新登录
- Web V1/V2 消息输入保留输入法 Enter 确认，避免中文组合输入期间误发送； Shift+Enter 在光标或选区位置换行，V2 组合输入期间的 Escape 不取消回复/编辑。
- 心跳保活（30s 间隔 / 90s 超时）
- Web 端响应式布局（桌面 / 平板 / 手机；不代表原生移动客户端支持）
- 同一页面生命周期内断线重认证；刷新页面后需重新登录（不持久化明文密码）
- Windows 端已支持持久化的中文/英文切换，登录注册、个人资料、 用户信息/头像预览、头像裁剪、房间设置、房间文件管理、受保护房间 密码加入及密码状态反馈、表情选择器、多目标转发和 V2 会话界面共用同一语言偏好； 其余旧界面仍在分批迁移
- Windows 登录设备管理已支持实时中英文切换；加载/撤销/非法目录是稳定 类型状态，切换语言不会改变设备 ID、当前设备保护或正在撤销的请求
- Windows V2 屏蔽账号目录已支持实时中英文切换；本地失败使用稳定类型， 服务端安全原因保持原样，解除屏蔽重试继续复用同一操作 ID
- Windows V2 新消息通知按当前语言显示隐私安全的通用文案；去重和可见 会话抑制策略只保存“普通消息/提及”语义，不保存或暴露消息正文
- Windows 系统托盘的应用提示、“显示主窗口”和“退出”操作已接入同一 语言设置；切换语言只更新展示文本，不重建菜单或改变通知激活路由
- Windows 主窗口标题、顶层菜单、菜单动作和“关于”信息已支持实时 中英文切换；用户昵称、动作对象、快捷键及功能开关的可见状态保持不变
- Windows 屏蔽目录控制器不再伪造中文“服务端原因”；可重试协议错误使用 稳定类型交给界面本地化，真正的安全服务端详情仍保持原文
- Windows 主窗口已把服务器连接状态和上传、下载等操作反馈拆成两个状态 区域；重连不会再覆盖操作进度，连接状态可随语言实时重组
- Windows V1 消息编辑器的表情、文件、输入提示、发送动作和右键换行已 支持实时中英文；语言切换不重建输入框，不影响草稿、选区或光标
- Windows 房间/好友导航控件和好友在线状态已支持实时中英文；好友身份、 选择、未读数和头像保持稳定，在线状态不再拼进持久展示数据
- Windows Qt 桌面客户端通过 TCP 连接（默认端口 9527）
- Vue Web 客户端通过 WebSocket 连接（默认端口 9528）
- 同一服务器同时处理 TCP 和 WebSocket 连接
- 两端用户可在同一房间实时通信
| 组件 | 技术 |
|---|---|
| 语言 | C++17 / Java 21 / JavaScript (ES2020+) |
| GUI 框架 | Qt 6.11.1 (Widgets) |
| Web 框架 | Vue 3 + Vite 5 + Pinia + Vue Router |
| 视频播放 | DPlayer 1.27 |
| 网络 | QTcpServer / QTcpSocket / QWebSocketServer |
| 数据库 | SQLite（Qt 内置驱动，零配置） |
| 构建 | qmake (Qt) / Vite (Web) |
| 协议 | TCP: 自定义二进制帧（4 字节长度头 + JSON） WebSocket: 纯 JSON 文本帧 |
Windows 产品构建固定使用 Qt 6.11.1；Linux qmake 可移植性、CMake
无界面服务端和数据库验证同时保持对 Ubuntu 系统 Qt 6.4 API 范围的
编译兼容性。Linux/macOS 上的 Qt Widgets 可移植性测试默认使用
offscreen 平台，无需图形桌面；Windows 原生交互仍由 Windows 产品门禁验证。
PostgreSQL 真实集成测试的时间夹具对齐 timestamptz 的微秒精度，
避免把 Java 纳秒值与数据库持久值误判为凭证过期契约变化。
Java 消息性能基准会为一次性自聊会话写入完整的 DIRECT 配对关系，确保
账号屏蔽策略验证的是合法会话，而不是因夹具缺行提前拒绝第一条消息。
Java 网关性能基准的单接收方场景也会写入规范化的 DIRECT 双方关系，
避免账号屏蔽策略将合法的首条网关消息误判为会话模型不完整。
Windows V2 会话目录的单击打开路径不再依赖“当前行发生变化”，
首行已是当前行时仍会按隐藏会话标识正确打开会话。
Windows CI 保持 Qt 6.11.1 产品基线，并固定使用已支持 Qt 6.11
架构分目录的 aqtinstall 上游提交，避免误访问旧版双层元数据路径。
Windows 原生 qmake 门禁会先通过 Visual Studio 开发者环境加载 x64 MSVC，
并确认 nmake.exe 可用，避免仅安装 Qt SDK 后因编译工具未进入 PATH 而失败。
V2 Windows 消息编辑、失败重试和冲突变基路径保持显式控制流，Linux
GCC 严格告警构建不会再把同一行中的条件语句误判为非预期执行分支。
V2 Windows WebSocket 传输会按 Qt 版本选择连接错误信号，兼容 Ubuntu
系统 Qt 6.4 与 Windows 产品 Qt 6.11。
附件发件箱的源文件指纹测试使用可写文件句柄恢复修改时间，避免 Windows
拒绝只读句柄修改文件元数据，同时仍验证同尺寸、同时间戳的内容替换。
qmake 在 Windows 上会显式链接 vcpkg 提供的 libsodium.lib，其他平台仍
通过 -lsodium 解析库名，避免 MSVC 把依赖误写成不存在的 sodium.lib。
Windows 安装器信任测试在独立临时目录中使用稳定的 .exe 夹具，确保
Authenticode 验证针对普通安装器路径，不受无扩展名临时文件语义影响。
更新状态仓库在 POSIX 平台检查 owner-only 权限位；Windows 产品路径位于
每用户 AppLocalData，由 NTFS ACL 继承隔离，不将 Qt 映射的 Unix 组/其他位误当成 ACL。
更新安装器下载在 Windows 上使用安全唯一临时文件并继承每用户暂存目录
ACL；POSIX 平台继续显式收紧 owner-only 权限，不依赖 Windows 上无法设置 ACL 的
QFile::setPermissions() 作为下载成功条件。
失败或取消更新下载时会先销毁临时文件对象、释放 Windows 文件资源，
再删除 .part 文件，避免暂存目录遗留不完整安装器。
Windows 客户端的 qmake 与 CMake 产品目标都显式链接 User32，为视频缩略图
截取使用的 GetDC/ReleaseDC 提供稳定的 Win32 链接依赖。Windows CMake
产品图策略校验会把 qmake 源文件路径统一为正斜杠，避免运行器路径分隔符
导致源文件缺失误报。CMake Windows 产品构建继续静态链接 Protobuf/Abseil，
但统一使用与共享 Qt 一致的动态 MSVC 运行库，避免 /MT 与 /MD 混用。
Windows GUI 子系统中的产品配置诊断通过继承的标准输出句柄写入 JSON，确保
PowerShell 门禁可以读取最终 ChatClient.exe 的默认关闭配置；Windows 验证
脚本会显式重定向并等待 GUI 进程，避免 PowerShell 直接调用 GUI 程序时丢失输出。
qmake 回退载荷会从同一 Qt SDK 补齐 CMake V2 产品图所需的 WebSockets 运行库，
使两套构建的可部署 DLL 清单和字节保持一致。
V2 转发目标对话框的独立 CMake 测试目标启用 Qt AUTOMOC，确保 Windows
功能候选构建会生成并链接其元对象代码。
Windows 安装器在校验并切换暂存载荷前会离开暂存目录，避免系统因当前工作目录
仍被安装进程占用而拒绝原子重命名。
Windows CI 会直接发布已经完成安装、升级、降级拒绝和卸载验证的同一份 CMake
安装器，不再紧邻运行第二套重复安装流程，从而避免 NSIS 收尾状态竞争。
ChatRoom/
├── ChatRoom.pro # 顶层 qmake subdirs 项目
├── README.md # 项目说明
├── AGENTS.md # 工程和架构演进规则
├── docs/ # 权威架构、协议、数据与验证文档
├── Common/ # 共享协议层
│ ├── Protocol.h # 消息协议定义（当前 125 种消息类型）
│ └── Message.h/cpp # 消息数据模型
├── Server/ # 服务端（控制台程序，TCP + WebSocket 双协议）
│ ├── ChatServer # TCP + WebSocket 服务器
│ ├── ClientSession # 客户端会话（支持 TCP/WebSocket 双传输层）
│ ├── DatabaseManager # SQLite 数据库操作
│ └── RoomManager # 聊天室管理
├── Client/ # Windows Qt 桌面客户端（GUI 程序）
│ ├── NetworkManager # 网络连接管理（单例）
│ ├── LoginDialog # 登录/注册界面
│ ├── ChatWindow # 主聊天窗口
│ ├── MessageModel # 消息数据模型 (MVC)
│ ├── MessageDelegate # 消息气泡渲染
│ ├── EmojiPicker # 表情选择器
│ ├── FileCache # 文件缓存管理
│ ├── ThemeManager # 主题管理
│ ├── TrayManager # 系统托盘管理
│ └── resources/ # QSS 样式表
└── WebClient/ # Vue Web 客户端
├── package.json # 依赖管理
├── vite.config.js # Vite 构建配置
└── src/
├── main.js # Vue 应用入口
├── App.vue # 根组件（深/浅主题）
├── assets/style.css # 全局样式（CSS 变量主题系统）
├── router/ # 路由配置
├── services/ # WebSocket 服务层
├── stores/ # Pinia 状态管理（user, chat）
├── views/ # 页面（Login, Chat）
└── components/ # UI 组件
├── RoomList.vue # 房间列表
├── MessageList.vue # 消息列表与气泡
├── UserList.vue # 成员列表
├── InputArea.vue # 输入区域
├── EmojiPicker.vue # 表情选择器
├── FilePreview.vue # 文件预览（图片/视频/PDF/音频/文本）
├── ProfileDialog.vue # 个人资料
├── RoomSettingsDialog.vue # 房间设置
├── UserInfoDialog.vue # 用户信息
└── RoomPasswordDialog.vue # 密码输入
项目的长期目标架构、可靠消息模型、Java 后端迁移、Web/Windows 客户端和安装包路线，统一维护在：
架构演进遵循兼容优先、纵向切片、可测量、可回滚原则，不进行一次性全量重写。
- Qt 6.11.1（Windows x64 + MSVC 2022 产品构建基线）
- C++17 编译器
- qmake（当前 Windows 产品构建）
- CMake 3.24+（增量 HeadlessServer 验证路径）
macOS 和 Linux 可以作为开发或服务端验证环境，但不是当前客户端产品 支持范围。
- Node.js 22
- npm
SQLite 驱动已内置于 Qt，无需安装任何数据库。首次运行 Server 时会自动创建
chatroom.db。
聊天室部分操作需要通过“开发者秘钥”执行
服务端的“开发者秘钥”通过 .env 配置，键名为 CHATROOM_DEVELOPER_KEY。
cp .env.example .envWindows PowerShell 可使用：
Copy-Item .env.example .envCHATROOM_DEVELOPER_KEY=请替换成你的强密码建议先使用统一验证入口确认本机工具链：
python3 tools/verify_m0.py --web --db-schema --v1-smoke --performance源码清单校验会统一 Windows、macOS 与 Linux 的路径分隔符和文本换行，
因此同一 Git 修订在不同 Runner 上应得到相同的 M0 指纹。
Java V2 协议验证中的 Windows ViewModel 及其聚合控制器目标会显式链接
共享的本地化目录，以确保协议生成后的 C++ 链接检查与客户端实际依赖保持一致。
CMake 无界面验证会先构建所有已注册的 v1_、m4_、m6_ 测试目标，
再交给 CTest 执行，避免因测试可执行文件未生成而出现伪失败。
服务端 CMake 增量路径可在 macOS 开发机上单独验证：
SODIUM_ROOT="$(brew --prefix libsodium)" \
python3 tools/verify_m0.py --cmake-headlessWindows Qt 产品构建、非产品开发主机命令、依赖与已知工具链边界见 构建指南和支持矩阵。
# 在安装了 Qt 6.11.1 MSVC 2022 和 Visual Studio 2022 的开发终端中运行
vcpkg install --triplet x64-windows
$env:SODIUM_ROOT = (Resolve-Path .\vcpkg_installed\x64-windows).Path.Replace('\', '/')
python tools/verify_m0.py --qtcd WebClient
npm ci
npm run dev# 启动服务端（默认 TCP 9527 + WebSocket 9528）
.\build\m0\windows\server\release\ChatServer.exe
# 启动 Windows Qt 客户端（可同时启动多个）
.\build\m0\windows\client\release\ChatClient.exe
# Web 客户端访问 http://localhost:5173Qt 客户端默认连接 127.0.0.1:9527（TCP），Web 客户端默认连接 127.0.0.1:9528（WebSocket）。
# TCP 端口 8888，WebSocket 端口自动为 8889
ChatServer.exe --port 8888
# 分别指定
ChatServer.exe --port 8888 --ws-port 9999项目当前不提供可信的公网生产部署脚本。旧脚本会在生产机上以 root
身份现场编译、暴露明文 TCP/WebSocket 端口，且没有签名产物、回滚和完整
密钥管理，已从仓库移除。
M1 已完成代码库内的认证、授权和可靠消息基线，但公网部署仍必须在 受信边缘终止 TLS/WSS，并完成密钥、监控和回滚策略。Windows 签名安装包、 自动更新以及 Web 的可回滚发布属于 M4。
| 模式 | 应用 |
|---|---|
| 观察者模式 | NetworkManager 信号/槽分发消息 |
| 单例模式 | NetworkManager、ThemeManager、FileCache |
| MVC 模式 | MessageModel + MessageDelegate + QListView |
| 策略模式 | 主题切换（Light/Dark QSS / CSS 变量） |
| 工厂模式 | Message::createXxxMessage() 系列方法 |
服务端与客户端通过 JSON 消息通信，当前共声明 125 种消息类型。完整、以代码为准的清单见 V1 协议基线：
| 类别 | 消息类型 |
|---|---|
| 认证 | LOGIN_REQ/RSP, REGISTER_REQ/RSP, LOGOUT, FORCE_OFFLINE |
| 聊天 | CHAT_MSG, SYSTEM_MSG |
| 房间 | CREATE/JOIN/LEAVE/DELETE/RENAME_ROOM, ROOM_LIST, ROOM_SETTINGS, SET/GET_ROOM_PASSWORD |
| 用户 | USER_LIST, USER_JOINED/LEFT/ONLINE/OFFLINE |
| 文件 | FILE_SEND/NOTIFY/DOWNLOAD, UPLOAD_START/CHUNK/END/CANCEL, DOWNLOAD_CHUNK |
| 撤回 | RECALL_REQ/RSP/NOTIFY |
| 管理 | SET_ADMIN, KICK_USER, DELETE_MSGS |
| 头像 | AVATAR_UPLOAD/GET/UPDATE_NOTIFY |
| 个人 | CHANGE_NICKNAME/UID/PASSWORD |
| 心跳 | HEARTBEAT/HEARTBEAT_ACK |
- TCP 传输层（Qt 客户端）：
[4字节大端长度][JSON]二进制帧 - WebSocket 传输层（Web 客户端）：纯 JSON 文本消息
MIT