chat-demo-server/DESIGN.md

# Chat Demo Server 设计说明

## 1. 文档范围

本文依据当前仓库中的代码和 SQL 脚本，记录聊天服务端现有结构、模块职责、接口和消息协议、数据模型及设计取舍。文中“当前行为”指代码已经实现的行为；代码中存在但可能导致运行失败或安全风险的部分会在“已知问题与建议”中单独说明，不将计划性改进描述为已有能力。

## 2. 项目概述

本项目是一个基于 Node.js 的单进程聊天服务端，提供 HTTP REST 接口和 WebSocket 实时连接。Express 和 WebSocket 共用同一个 HTTP Server，监听 3000 端口；MySQL 保存用户、联系人和聊天消息。

当前实现的主要能力：

- 用户注册、用户名密码登录，并在登录成功后签发 JWT。
- 使用 JWT 中间件保护用户信息、联系人和聊天记录查询接口。
- 查询联系人、每个联系人的最近一条消息，以及指定联系人的分页消息。
- WebSocket 连接通过 JWT 验证身份，维护进程内在线用户连接表，并广播在线列表。
- WebSocket 消息处理代码包含消息发送、投递和 ACK 转发逻辑。

## 3. 技术栈与依赖

| 技术/依赖 | 用途 |
| --- | --- |
| Node.js | JavaScript 服务端运行环境 |
| Express 5 | HTTP 服务、JSON 请求体解析和路由分发 |
| `http` | 创建与 Express 共用的 HTTP Server |
| `ws` | WebSocket 服务端实现 |
| `mysql2` | MySQL 单连接及参数化 SQL 查询 |
| `jsonwebtoken` | JWT 签发和验证 |
| `dotenv` | 将 `.env` 配置加载到 `process.env` |
| `nodemon` | 开发时监视文件并重启服务 |

项目使用 CommonJS 模块格式。`npm start` 执行 `node index.js`，`npm run dev` 执行 `nodemon index.js`。当前 `npm test` 是占位脚本，没有自动化测试。

## 4. 代码结构

```text
index.js                     服务启动入口、HTTP 与 WebSocket 组装
db/
  mysql.js                   MySQL 连接创建与导出
  sql.txt                    users、contacts、messages 的建表及样例数据脚本
middleware/
  authMiddleware.js          HTTP 请求 JWT 校验
routes/
  login.js                   注册和登录接口
  user.js                    用户信息与联系人接口
  message.js                 最近聊天、历史消息、REST 消息写入接口
utils/
  jwt.js                     JWT 签发和验证封装
websocket/
  index.js                   WebSocket 握手、协议分发和消息处理
  connectionManager.js       进程内在线连接管理及广播
```

### 模块职责与依赖

- `index.js`：加载环境变量，创建 Express 应用和 HTTP Server，启用 JSON 请求解析，注册 `/api` 路由并将同一个 Server 交给 WebSocket 初始化函数，最后监听 3000 端口。
- `db/mysql.js`：创建一个 `mysql2` 单连接，并作为共享模块导出，路由和 WebSocket 处理器直接调用 `db.query`。
- `routes/login.js`：处理公开的 `/login`、`/register`。登录成功后通过 JWT 工具生成 token。
- `routes/user.js`：依赖 `authMiddleware`，从 `req.user.username` 识别当前用户并提供用户信息与联系人查询。
- `routes/message.js`：历史记录及最近聊天查询依赖认证中间件；当前 REST `/sendMessage` 未挂载认证中间件。
- `middleware/authMiddleware.js`：从 `Authorization` 请求头拆出 token，调用 JWT 验证，将 payload 放入 `req.user` 后继续处理请求。
- `utils/jwt.js`：使用 `JWT_SECRET` 签发和验证 token，签发有效期为 10 分钟。
- `websocket/index.js`：从连接 URL 查询参数读取 token 验证客户端身份；连接建立或关闭时广播在线用户列表；按消息 `type` 分发 WebSocket 消息。
- `websocket/connectionManager.js`：使用模块级 `Map` 以用户名为键保存 WebSocket 连接。该状态仅存在于当前 Node 进程内。
- `db/sql.txt`：描述用户、联系人、消息表，以及本地演示用数据。

## 5. 总体架构与请求路径

```mermaid
flowchart LR
    Client[客户端]
    Entry[index.js / HTTP Server]
    Express[Express 路由]
    Auth[JWT 中间件与工具]
    WS[WebSocket 服务]
    Manager[在线连接 Map]
    DB[(MySQL)]

    Client -->|HTTP /api| Entry
    Entry --> Express
    Express --> Auth
    Express --> DB
    Client <-->|WebSocket| Entry
    Entry --> WS
    WS --> Auth
    WS --> Manager
    WS --> DB
```

HTTP 请求由 Express 根据 `/api` 前缀分发。需要认证的路由先运行 JWT 中间件，随后执行业务 SQL。WebSocket 则在握手后从 URL 查询参数读取 token，再在连接生命周期内以已验证的用户名处理消息。HTTP 与 WebSocket 最终都使用同一 MySQL 模块。

## 6. 数据模型

数据库脚本目标库为 `chat_mysql`，定义以下三张表：

### `users`

| 字段 | 类型 | 约束/用途 |
| --- | --- | --- |
| `username` | `VARCHAR(50)` | 主键，用户唯一标识 |
| `password` | `VARCHAR(255)` | 非空；当前代码保存并直接比较明文密码 |

### `contacts`

| 字段 | 类型 | 约束/用途 |
| --- | --- | --- |
| `user_name` | `VARCHAR(50)` | 联系人所属用户，外键引用 `users.username` |
| `contact_name` | `VARCHAR(50)` | 联系人用户名，外键引用 `users.username` |

`(user_name, contact_name)` 为联合主键。同一用户不能重复添加同一联系人。脚本中的联系人关系按有向关系保存，双向关系需要分别插入两行。

### `messages`

| 字段 | 类型 | 约束/用途 |
| --- | --- | --- |
| `id` | `INT` | 自增主键 |
| `sender_name` | `VARCHAR(50)` | 非空，外键引用发送者 |
| `receiver_name` | `VARCHAR(50)` | 非空，外键引用接收者 |
| `content` | `VARCHAR(1000)` | 非空，消息正文 |
| `created_at` | `DATETIME` | 默认使用数据库当前时间 |

消息以一条记录表示一次单向发送。双方聊天记录通过发送者和接收者字段组合查询；表中没有当前 WebSocket 处理器所写入的 `message_id` 字段。

## 7. HTTP 接口设计

所有路由统一挂载在 `/api` 下，JSON 请求体由 Express 解析。成功/失败响应大多采用 `{ code, message, data }` 结构，但不同接口的 HTTP 状态码与业务 `code` 使用并不完全一致。

| 方法 | 路径 | 认证 | 输入/用途 |
| --- | --- | --- | --- |
| `POST` | `/api/register` | 否 | body：`username`、`password`；插入用户 |
| `POST` | `/api/login` | 否 | body：`username`、`password`；验证凭据并返回 token、用户名 |
| `GET` | `/api/userInfo` | 是 | 从 token 返回当前用户名 |
| `GET` | `/api/contactsInfo` | 是 | 查询当前用户联系人，返回 `contacts` 数组 |
| `GET` | `/api/recentChats` | 是 | 查询当前用户每个聊天对象的最新消息 |
| `POST` | `/api/contactMessagesInfo` | 是 | body：`contactName`、`limit`、`offset`；分页查询双方消息 |
| `POST` | `/api/sendMessage` | **否** | body：`senderName`、`receiverName`、`content`；将消息插入数据库 |

### 认证约定

HTTP 客户端应在受保护接口的请求头中传入 `Authorization: Bearer <token>`。登录接口响应的 token 字符串自身已带 `Bearer ` 前缀。当前中间件通过空格拆分请求头并取第二段作为 token；缺少请求头或验证失败时返回 401。

JWT payload 当前包含 `username`，过期时间为 10 分钟。WebSocket 客户端把 token 放在连接 URL 查询参数 `token` 中。由于登录响应包含 `Bearer ` 前缀，而 WebSocket 端会直接将查询参数交给 `verifyToken`，客户端需要传纯 JWT 部分，不能把 `Bearer ` 前缀一并作为 token 值。

## 8. WebSocket 协议与消息流程

WebSocket 挂载在 HTTP Server 上，客户端连接地址的形式为 `ws://<host>:3000/?token=<JWT>`。连接验证通过后，服务端按用户名登记连接，并广播在线列表。

### 服务端消息类型

| `type` | 方向 | 当前代码行为 |
| --- | --- | --- |
| `userOnline` | 服务端 -> 所有在线客户端 | 连接建立或关闭后，携带 `userList` 在线用户名数组 |
| `newMessage` | 服务端 -> 接收方 | 携带 `message` 对象，包括消息 ID、发送方、接收方和正文 |
| `sendSuccess` | 服务端 -> 发送方 | 携带客户端提供的 `messageId`，表示发送成功 |
| `sendError` | 服务端 -> 发送方 | 数据库写入回调报错时尝试发送，携带 `messageId` 和错误说明 |
| `ack` | 服务端 -> 原发送方 | 将接收方确认的消息 ID 转发给发送方 |

### 客户端消息类型

- `sendMessage`：处理器读取 `messageId`、`receiverName`、`content`；发送者身份来自已验证 WebSocket 连接，不从消息体读取。
- `ack`：处理器预期使用 `messageId` 和 `senderName` 将 ACK 转发给原发送者。

### 预期发送流程

1. 客户端建立携带 JWT 的 WebSocket 连接。
2. 服务端校验 JWT，登记用户名与连接，并广播在线用户列表。
3. 客户端发送 `sendMessage`，服务端使用连接身份确定发送者。
4. 服务端尝试把消息持久化到 MySQL；接收方在线时向其推送 `newMessage`。
5. 接收方返回 `ack` 后，服务端尝试通知原发送方。

步骤 4 当前实现没有等待数据库回调成功再确认和推送；此外建表脚本与插入语句字段不匹配，因此此流程目前不能视为可靠送达流程。具体差异见第 10 节。

## 9. 关键设计思路

- **按职责拆分模块**：入口负责组装，路由负责 HTTP 接口，middleware 负责认证，utils 封装 JWT，websocket 目录处理长连接和连接表，db 统一导出数据库连接。
- **用户名作为用户标识**：用户表以用户名为主键，联系人关系、消息发送接收双方及在线连接表均使用用户名关联。
- **JWT 无服务端会话存储**：服务端通过签名和过期时间验证 token，HTTP 请求和 WebSocket 握手各自执行验证。
- **聊天列表与历史消息分开查询**：`recentChats` 使用窗口函数按聊天对象分组并选出最新消息；历史消息接口按 limit/offset 分页，避免单次返回全部记录。
- **在线状态在内存维护**：当前使用 Map 直接由用户名定位 WebSocket 连接，便于单进程内向在线用户推送消息，但没有跨进程共享能力。
- **SQL 参数化**：业务查询使用 `?` 占位符与参数数组传值，避免把用户输入直接拼入 SQL 文本。

## 10. 已知问题与后续建议

以下内容是基于当前代码与脚本的直接核对结果，应在扩展功能或对外部署前处理：

1. **数据库凭据写在源码中**：`db/mysql.js` 将 MySQL 账号、密码和数据库名直接传给连接创建函数。建议改为读取环境变量，轮换已经放入源码的凭据，并避免将真实密钥写入文档或版本库。
2. **密码以明文存储和比对**：注册直接写入密码，登录 SQL 按用户名与明文密码匹配。应使用成熟密码哈希方案存储和校验，并考虑统一认证失败响应。
3. **REST 消息写入缺少认证**：`/api/sendMessage` 未使用 `authMiddleware`，客户端可自行指定发送者。应要求认证并从 `req.user` 派生发送者身份，同时校验接收方及联系人关系。(已解决)
4. **WebSocket 数据库写入字段不匹配**：`websocket/index.js` 插入 `message_id`，但 `db/sql.txt` 的 `messages` 表没有该列。需统一消息 ID 设计，例如新增唯一字段及迁移，或使用现有自增 `id` 并调整协议和查询。（已解决）
5. **发送确认早于持久化结果**：`sendSuccess` 和接收方推送发生在异步 `db.query` 回调之前。应将成功确认和实时推送放到成功回调中；失败时只返回错误，不推送为已发送消息。（已解决）
6. **连接管理器广播引用未定义的 `WebSocket`**：`connectionManager.js` 的 `broadcast` 检查 `WebSocket.OPEN`，但文件中没有导入 `ws`。当广播函数被调用时可能抛出 `ReferenceError`。应在此模块引入库常量，或由连接对象状态采用明确且可用的检查方式。（已解决）
7. **ACK 参数调用不一致**：消息分发通过 `handleAck(data)` 调用，而函数签名是 `handleAck(receiverName, data)`；函数内部随后读取第二个参数，可能因 `data` 未定义而失败。应统一函数参数并以当前连接用户名作为 ACK 接收者身份。
8. **重复登录连接的关闭竞态**：同一用户名的新连接会覆盖 Map 中旧连接；旧连接关闭时无条件按用户名删除，可能把新连接也从 Map 移除。移除连接时应确认 Map 中仍是即将关闭的那个 WebSocket。
9. **分页和输入校验不足**：`contactMessagesInfo` 未验证 `contactName`、`limit`、`offset` 的类型与范围，也未约束最大页大小。建议验证请求参数并设置默认值和上限。
10. **在线状态及可靠性受单进程限制**：Map 不支持多实例共享、服务重启恢复、离线消息投递或持久化 ACK 状态。若部署多实例，需要共享在线状态/消息协调机制；若要求可靠消息，应定义消息状态、幂等键、重试及离线投递策略。
11. **配置与错误响应尚未统一**：数据库连接配置没有从 `.env` 读取；HTTP 接口混用 HTTP 状态码和响应体 `code`，空结果有时返回业务码 401。建议集中配置并统一 API 错误语义及日志策略。
12. **SQL 初始化脚本需要整理验证**：脚本包含清空用户表的语句，执行前会删除该表全部用户数据。应将演示数据与建表迁移分离，并在测试数据库验证脚本。
13. **缺少自动化测试**：当前测试脚本是占位命令。建议优先为认证边界、参数校验、消息持久化失败/成功和 WebSocket 连接生命周期补充测试。

## 11. 本地运行与部署边界

1. 安装 Node.js 及 MySQL，并在 MySQL 中准备 `chat_mysql` 数据库。
2. 按需执行经过校验的建表脚本；注意当前 `sql.txt` 含删除数据语句，不应直接用于已有数据环境。
3. 设置 `JWT_SECRET`。当前 MySQL 参数仍需在 `db/mysql.js` 中配置；建议先将连接参数迁移到环境变量，再部署。
4. 执行 `npm install`，开发环境使用 `npm run dev`，普通启动使用 `npm start`。
5. 服务监听 `http://localhost:3000`，根路径 `/` 返回运行提示；WebSocket 使用相同主机和端口。

当前代码适用于本地演示和单进程验证，不具备生产环境所需的凭据管理、密码安全、输入校验、多实例在线状态和消息可靠性保障。