# lightweight-chat

**Repository Path**: mgdh5/lightweight-chat

## Basic Information

- **Project Name**: lightweight-chat
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lightweight Chat

轻量在线咨询聊天系统。它不是一个 npm 组件库，而是一个可独立部署的 H5 + Socket.IO 服务，其他业务项目通常通过链接、内嵌页面或反向代理来接入。

## 适用场景

- 用户端 H5 发起在线咨询。
- 客服端 H5 / 桌面 Web 查看会话并回复。
- 单机轻量部署，目标服务器约 2 vCPU / 2 GiB RAM。
- 第一版只支持文本消息、未读数、历史消息、客服关闭会话、客服只读查看用户历史已关闭会话。

第一版暂不包含：微信真实授权、短信绑定、图片/文件/语音、多客服分配、工单、机器人、多租户、Redis、PostgreSQL、横向扩容。

## 技术栈

- Node.js + Express
- Socket.IO
- Node 内置 `node:sqlite`
- Vite + vanilla TypeScript
- SQLite 数据库，默认 `data/app.db`

建议使用 Node.js 24 或更新版本。当前 `node:sqlite` 可能打印 experimental warning，不影响功能。

## 接入方式

### 方式 1：业务系统跳转到聊天页

部署本服务后，在业务系统中跳转：

- 用户端：`https://your-domain.com/user`
- 客服端：`https://your-domain.com/staff`

这是当前最简单、最稳定的接入方式。

### 方式 2：业务系统通过 iframe 内嵌

可以把 `/user` 内嵌到已有 H5 页面中。需要注意：

- 反向代理和响应头不能禁止 iframe。
- 页面宽度应按手机 H5 适配。
- 登录态目前保存在浏览器 `localStorage`，跨域 iframe 会受浏览器策略影响。

### 方式 3：直接使用 Socket.IO 契约自建前端

如果其他项目想复用后端实时能力，可以按 Socket.IO 契约实现自己的前端。

契约文档：

- [Socket.IO 事件](contracts/socket-events.md)
- [数据模型](contracts/data-model.md)
- [HTTP 路由](contracts/routes.md)

共享 TypeScript 类型在 [src/shared/protocol.ts](src/shared/protocol.ts)。

## HTTP 入口

- `GET /health`：健康检查，返回数据库状态。
- `GET /user`：用户 H5。
- `GET /staff`：客服 H5。
- `/socket.io/`：Socket.IO 服务端。

业务数据操作全部走 Socket.IO，REST 只用于页面、静态资源和健康检查。

## 运行配置

本地 `.env` 示例：

```bash
PORT=3000
DATABASE_PATH=data/app.db
TOKEN_SECRET=dev-secret-change-me
STAFF_PASSWORD=dev-password
```

生产环境至少配置：

```bash
PORT=3000
DATABASE_PATH=/opt/lightweight-chat/data/app.db
TOKEN_SECRET=<strong-random-secret>
STAFF_PASSWORD=<staff-login-password>
NODE_OPTIONS=--max-old-space-size=512
```

不要把真实 `TOKEN_SECRET` 和 `STAFF_PASSWORD` 提交到仓库。

## 本地开发

```bash
npm install
npm run dev
```

默认访问：

- http://localhost:3000/user
- http://localhost:3000/staff
- http://localhost:3000/health

如果要使用生产构建：

```bash
npm run build
PORT=3000 DATABASE_PATH=data/app.db TOKEN_SECRET=dev-secret STAFF_PASSWORD=dev-password npm start
```

## 业务规则

- 用户模拟登录：昵称必填，手机号可选。
- 客服登录：单个固定密码，由 `STAFF_PASSWORD` 配置。
- 同一个用户同一时间最多一个 `open` 会话。
- 客服关闭会话后，该会话变为 `closed`，不再接受新消息。
- 用户下次咨询会创建新的 `open` 会话，旧会话消息不会混入新会话。
- 客服可从当前用户详情进入历史会话，只读查看该用户已关闭会话。
- 用户端第一版不显示历史已关闭会话。
- 历史消息分页每页 20 条；服务端按时间倒序返回，前端按聊天习惯展示为最新在底部。

## 目录说明

```text
contracts/       对外契约：Socket.IO、数据模型、HTTP 路由
docs/            部署说明、QA 报告、方案记录
openspec/        OpenSpec 需求文档和任务记录
src/server/      Express、Socket.IO、SQLite 后端
src/client/user/ 用户端 H5
src/client/staff/客服端 H5
src/shared/      前后端共享协议类型
tests/           Repository 和 Socket.IO 契约烟测
```

## 部署

生产建议直接部署 Node.js 进程，并用 systemd 托管；Nginx 或 Caddy 负责 HTTPS 和 WSS 反向代理。

详细部署说明见 [docs/deployment.md](docs/deployment.md)。

## 验证

提交或部署前建议运行：

```bash
npm run typecheck
npm test
npm run build
```

当前测试覆盖：

- SQLite repository 核心行为。
- Socket.IO ack payload 形状。
- 关闭会话后默认列表排除 closed。
- 同用户关闭后新建 open 会话。
- 客服只读读取 closed 历史会话。
- `/health`、`/user`、`/staff` 路由烟测。

## 接入方注意事项

- 本项目默认是独立服务，不建议直接复制内部模块到其他项目。
- 若自建前端，请以 `contracts/socket-events.md` 为准，不要依赖内部 repository 实现。
- 若部署在业务主域名子路径下，需要同时代理静态资源和 `/socket.io/`。
- SQLite 文件、WAL/SHM 文件、`.env`、`node_modules/`、`dist/` 不应提交到仓库。
- 2C2G 服务器上不建议同机再部署 PostgreSQL、Redis、队列或文件服务。