collabdocchat 1.0.1 → 1.0.3

package/README.md

@@ -1,521 +1,521 @@
-# CollabDocChat
-
-<div align="center">
-
-![CollabDocChat Logo](https://img.shields.io/badge/CollabDocChat-v1.0.0-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
-![Node](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)
-![MongoDB](https://img.shields.io/badge/MongoDB-%3E%3D5.0-green)
-
-**开源的实时协作文档聊天平台**
-
-集成任务管理 · 多人文档编辑 · 智能点名 · 即时通讯
-
-[快速开始](#快速开始) · [功能特性](#功能特性) · [技术栈](#技术栈) · [贡献指南](#贡献指南)
-
-</div>
-
----
-
-## 📖 项目简介
-
-**CollabDocChat** 是一个轻量级的开源协作平台，专为学习和办公场景设计。它将即时通讯、多人实时文档编辑、任务管理和互动点名功能整合在一起，提供一站式的群体协作解决方案。
-
-### 🎯 核心定位
-
-- **轻量级**：相比飞书、钉钉等重型工具，更加简洁易用
-- **开源免费**：完全开源，可自由部署和定制
-- **实时协作**：基于 WebSocket 的实时同步技术
-- **双端权限**：管理员和用户角色分离，权限清晰
-
----
-
-## ✨ 功能特性
-
-### 👨‍💼 管理员端
-
-- **群组管理**
-  - 创建/管理群组
-  - 添加/移除成员
-  - 查看成员在线状态
-
-- **任务管理**
-  - 发布/编辑/终止任务
-  - 关联文档到任务
-  - 查看任务完成进度
-
-- **文档管理**
-  - 上传/共享文档
-  - 设置文档权限（只读/可编辑）
-  - 查看文档编辑日志
-
-- **随机点名**
-  - 单次/批量随机点名
-  - 查看点名历史记录
-  - 实时响应提醒
-
-### 👥 用户端
-
-- **任务接收**
-  - 实时接收任务通知
-  - 查看待完成/已完成任务
-  - 更新任务状态
-
-- **文档协作**
-  - 多人实时编辑文档
-  - 自动同步内容
-  - 查看版本历史
-  - 显示其他用户编辑状态
-
-- **即时通讯**
-  - 群组聊天
-  - 实时消息推送
-  - 点名响应
-
-- **个人中心**
-  - 查看个人任务
-  - 编辑记录
-  - 群组列表
-
----
-
-## 🛠 技术栈
-
-### 后端
-- **Node.js** + **Express** - 服务器框架
-- **MongoDB** + **Mongoose** - 数据库
-- **WebSocket (ws)** - 实时通信
-- **JWT** - 身份认证
-- **Yjs** - CRDT 实时协作算法
-
-### 前端
-- **原生 JavaScript** - 无框架依赖
-- **Vite** - 构建工具
-- **CSS3** - 现代化 UI 设计
-- **WebSocket API** - 实时通信
-
-### 核心技术
-- **CRDT (Conflict-free Replicated Data Type)** - 无冲突文档同步
-- **WebSocket** - 双向实时通信
-- **JWT** - 无状态身份验证
-
----
-
-## 🚀 快速开始
-
-### 环境要求
-
-- Node.js >= 16.0.0
-- MongoDB >= 5.0
-- npm 或 yarn
-
-### 安装步骤
-
-#### 方式一：通过 npm 安装（推荐）
-
-```bash
-# 安装包
-npm install collabdocchat
-
-# 进入安装目录
-cd node_modules/collabdocchat
-
-# 启动应用（自动打开浏览器）
-npm start
-```
-
-#### 方式二：从源码安装
-
-1. **克隆项目**
-
-```bash
-git clone https://github.com/shijinghao/collabdocchat.git
-cd collabdocchat
-```
-
-2. **安装依赖**
-
-```bash
-npm install
-```
-
-3. **配置环境变量**
-
-复制 `.env.example` 为 `.env` 并修改配置：
-
-```bash
-cp .env.example .env
-```
-
-编辑 `.env` 文件：
-
-```env
-PORT=3000
-MONGODB_URI=mongodb://localhost:27017/collabdocchat
-JWT_SECRET=your_super_secret_jwt_key_change_this
-CLIENT_URL=http://localhost:5173
-```
-
-4. **启动 MongoDB**
-
-```bash
-# Windows
-mongod
-
-# macOS/Linux
-sudo systemctl start mongod
-```
-
-5. **启动项目**
-
-```bash
-# 一键启动（推荐）- 自动启动服务器和客户端，并打开浏览器
-npm start
-
-# 开发模式（同时启动前后端，使用 nodemon 自动重启）
-npm run dev
-
-# 或分别启动
-npm run server  # 后端服务器
-npm run client  # 前端开发服务器
-```
-
-6. **访问应用**
-
-运行 `npm start` 后，浏览器会自动打开并访问 `http://localhost:5173`
-
-或手动访问：`http://localhost:5173`
-
----
-
-## 📁 项目结构
-
-```
-CollabDocChat/
-├── server/                 # 后端代码
-│   ├── models/            # 数据模型
-│   │   ├── User.js
-│   │   ├── Group.js
-│   │   ├── Document.js
-│   │   └── Task.js
-│   ├── routes/            # API 路由
-│   │   ├── auth.js
-│   │   ├── groups.js
-│   │   ├── documents.js
-│   │   └── tasks.js
-│   ├── middleware/        # 中间件
-│   │   └── auth.js
-│   ├── websocket/         # WebSocket 处理
-│   │   └── index.js
-│   └── index.js           # 服务器入口
-├── src/                   # 前端代码
-│   ├── pages/            # 页面组件
-│   │   ├── login.js
-│   │   ├── admin-dashboard.js
-│   │   └── user-dashboard.js
-│   ├── services/         # 服务层
-│   │   ├── api.js
-│   │   ├── auth.js
-│   │   └── websocket.js
-│   ├── styles/           # 样式文件
-│   │   └── main.css
-│   └── main.js           # 前端入口
-├── package.json
-├── vite.config.js
-├── .env.example
-└── README.md
-```
-
----
-
-## 🔌 API 文档
-
-### 认证接口
-
-#### 注册
-```http
-POST /api/auth/register
-Content-Type: application/json
-
-{
-  "username": "string",
-  "email": "string",
-  "password": "string",
-  "role": "admin" | "user"
-}
-```
-
-#### 登录
-```http
-POST /api/auth/login
-Content-Type: application/json
-
-{
-  "email": "string",
-  "password": "string"
-}
-```
-
-### 群组接口
-
-#### 获取群组列表
-```http
-GET /api/groups
-Authorization: Bearer {token}
-```
-
-#### 创建群组（管理员）
-```http
-POST /api/groups
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
-  "name": "string",
-  "description": "string",
-  "members": ["userId1", "userId2"]
-}
-```
-
-#### 随机点名（管理员）
-```http
-POST /api/groups/:id/call
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
-  "count": 1
-}
-```
-
-### 文档接口
-
-#### 获取群组文档
-```http
-GET /api/documents/group/:groupId
-Authorization: Bearer {token}
-```
-
-#### 创建文档
-```http
-POST /api/documents
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
-  "title": "string",
-  "content": "string",
-  "groupId": "string",
-  "permission": "readonly" | "editable"
-}
-```
-
-#### 更新文档
-```http
-PATCH /api/documents/:id
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
-  "content": "string"
-}
-```
-
-### 任务接口
-
-#### 获取我的任务
-```http
-GET /api/tasks/my
-Authorization: Bearer {token}
-```
-
-#### 创建任务（管理员）
-```http
-POST /api/tasks
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
-  "title": "string",
-  "description": "string",
-  "groupId": "string",
-  "assignedTo": ["userId1"],
-  "relatedDocument": "documentId",
-  "deadline": "2024-12-31"
-}
-```
-
----
-
-## 🔄 WebSocket 事件
-
-### 客户端发送
-
-```javascript
-// 认证
-{ type: 'auth', token: 'jwt_token' }
-
-// 加入群组
-{ type: 'join_group', groupId: 'group_id' }
-
-// 发送聊天消息
-{ type: 'chat_message', groupId: 'group_id', username: 'user', content: 'message' }
-
-// 同步文档
-{ type: 'document_sync', documentId: 'doc_id', content: 'text', cursorPosition: 0 }
-
-// 响应点名
-{ type: 'call_response', groupId: 'group_id', username: 'user' }
-
-// 输入状态
-{ type: 'typing', documentId: 'doc_id', username: 'user', isTyping: true }
-```
-
-### 服务器推送
-
-```javascript
-// 认证成功
-{ type: 'auth_success', userId: 'user_id', role: 'admin' }
-
-// 聊天消息
-{ type: 'chat_message', groupId: 'group_id', userId: 'user_id', username: 'user', content: 'message', timestamp: 'ISO8601' }
-
-// 文档更新
-{ type: 'document_update', documentId: 'doc_id', content: 'text', userId: 'user_id', timestamp: 'ISO8601' }
-
-// 用户离线
-{ type: 'user_offline', userId: 'user_id' }
-```
-
----
-
-## 🎨 界面预览
-
-### 登录页面
-- 现代化渐变背景
-- 流畅的动画效果
-- 登录/注册切换
-
-### 管理员仪表板
-- 群组管理面板
-- 任务发布界面
-- 文档权限控制
-- 随机点名功能
-
-### 用户仪表板
-- 任务列表
-- 实时文档编辑器
-- 群组聊天
-- 在线状态显示
-
----
-
-## 🤝 贡献指南
-
-我们欢迎所有形式的贡献！
-
-### 如何贡献
-
-1. Fork 本项目
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 开启 Pull Request
-
-### 代码规范
-
-- 使用 ES6+ 语法
-- 遵循 ESLint 规则
-- 添加必要的注释
-- 编写清晰的提交信息
-
----
-
-## 📦 发布到 npm
-
-### 准备发布
-
-1. **更新版本号**
-
-```bash
-npm version patch  # 1.0.0 -> 1.0.1
-npm version minor  # 1.0.0 -> 1.1.0
-npm version major  # 1.0.0 -> 2.0.0
-```
-
-2. **登录 npm**
-
-```bash
-npm login
-```
-
-3. **发布包**
-
-```bash
-npm publish
-```
-
-### 使用 npm 包
-
-```bash
-npm install collabdocchat
-```
-
----
-
-## 📄 开源协议
-
-本项目采用 [MIT License](LICENSE) 开源协议。
-
----
-
-## 🙏 致谢
-
-感谢以下开源项目：
-
-- [Express](https://expressjs.com/) - Web 框架
-- [MongoDB](https://www.mongodb.com/) - 数据库
-- [Yjs](https://github.com/yjs/yjs) - CRDT 算法
-- [Vite](https://vitejs.dev/) - 构建工具
-
----
-
-## 📞 联系方式
-
-- **项目主页**: [https://github.com/yourusername/collabdocchat](https://github.com/yourusername/collabdocchat)
-- **问题反馈**: [Issues](https://github.com/yourusername/collabdocchat/issues)
-- **邮箱**: your.email@example.com
-
----
-
-## 🗺 路线图
-
-### v1.1.0 (计划中)
-- [ ] 文件上传功能
-- [ ] 富文本编辑器
-- [ ] 消息通知系统
-- [ ] 移动端适配
-
-### v1.2.0 (计划中)
-- [ ] 视频会议集成
-- [ ] 屏幕共享
-- [ ] 白板功能
-- [ ] 插件系统
-
-### v2.0.0 (未来)
-- [ ] 微服务架构
-- [ ] Docker 部署
-- [ ] 多语言支持
-- [ ] AI 助手集成
-
----
-
-<div align="center">
-
-**⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐**
-
-Made with ❤️ by CollabDocChat Team
-
-</div>
-
-
+# CollabDocChat
+
+<div align="center">
+
+![CollabDocChat Logo](https://img.shields.io/badge/CollabDocChat-v1.0.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Node](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)
+![MongoDB](https://img.shields.io/badge/MongoDB-%3E%3D5.0-green)
+
+**开源的实时协作文档聊天平台**
+
+集成任务管理 · 多人文档编辑 · 智能点名 · 即时通讯
+
+[快速开始](#快速开始) · [功能特性](#功能特性) · [技术栈](#技术栈) · [贡献指南](#贡献指南)
+
+</div>
+
+---
+
+## 📖 项目简介
+
+**CollabDocChat** 是一个轻量级的开源协作平台，专为学习和办公场景设计。它将即时通讯、多人实时文档编辑、任务管理和互动点名功能整合在一起，提供一站式的群体协作解决方案。
+
+### 🎯 核心定位
+
+- **轻量级**：相比飞书、钉钉等重型工具，更加简洁易用
+- **开源免费**：完全开源，可自由部署和定制
+- **实时协作**：基于 WebSocket 的实时同步技术
+- **双端权限**：管理员和用户角色分离，权限清晰
+
+---
+
+## ✨ 功能特性
+
+### 👨‍💼 管理员端
+
+- **群组管理**
+  - 创建/管理群组
+  - 添加/移除成员
+  - 查看成员在线状态
+
+- **任务管理**
+  - 发布/编辑/终止任务
+  - 关联文档到任务
+  - 查看任务完成进度
+
+- **文档管理**
+  - 上传/共享文档
+  - 设置文档权限（只读/可编辑）
+  - 查看文档编辑日志
+
+- **随机点名**
+  - 单次/批量随机点名
+  - 查看点名历史记录
+  - 实时响应提醒
+
+### 👥 用户端
+
+- **任务接收**
+  - 实时接收任务通知
+  - 查看待完成/已完成任务
+  - 更新任务状态
+
+- **文档协作**
+  - 多人实时编辑文档
+  - 自动同步内容
+  - 查看版本历史
+  - 显示其他用户编辑状态
+
+- **即时通讯**
+  - 群组聊天
+  - 实时消息推送
+  - 点名响应
+
+- **个人中心**
+  - 查看个人任务
+  - 编辑记录
+  - 群组列表
+
+---
+
+## 🛠 技术栈
+
+### 后端
+- **Node.js** + **Express** - 服务器框架
+- **MongoDB** + **Mongoose** - 数据库
+- **WebSocket (ws)** - 实时通信
+- **JWT** - 身份认证
+- **Yjs** - CRDT 实时协作算法
+
+### 前端
+- **原生 JavaScript** - 无框架依赖
+- **Vite** - 构建工具
+- **CSS3** - 现代化 UI 设计
+- **WebSocket API** - 实时通信
+
+### 核心技术
+- **CRDT (Conflict-free Replicated Data Type)** - 无冲突文档同步
+- **WebSocket** - 双向实时通信
+- **JWT** - 无状态身份验证
+
+---
+
+## 🚀 快速开始
+
+### 环境要求
+
+- Node.js >= 16.0.0
+- MongoDB >= 5.0
+- npm 或 yarn
+
+### 安装步骤
+
+#### 方式一：通过 npm 安装（推荐）
+
+```bash
+# 安装包
+npm install collabdocchat
+
+# 进入安装目录
+cd node_modules/collabdocchat
+
+# 启动应用（自动打开浏览器）
+npm start
+```
+
+#### 方式二：从源码安装
+
+1. **克隆项目**
+
+```bash
+git clone https://github.com/shijinghao/collabdocchat.git
+cd collabdocchat
+```
+
+2. **安装依赖**
+
+```bash
+npm install
+```
+
+3. **配置环境变量**
+
+复制 `.env.example` 为 `.env` 并修改配置：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件：
+
+```env
+PORT=3000
+MONGODB_URI=mongodb://localhost:27017/collabdocchat
+JWT_SECRET=your_super_secret_jwt_key_change_this
+CLIENT_URL=http://localhost:5173
+```
+
+4. **启动 MongoDB**
+
+```bash
+# Windows
+mongod
+
+# macOS/Linux
+sudo systemctl start mongod
+```
+
+5. **启动项目**
+
+```bash
+# 一键启动（推荐）- 自动启动服务器和客户端，并打开浏览器
+npm start
+
+# 开发模式（同时启动前后端，使用 nodemon 自动重启）
+npm run dev
+
+# 或分别启动
+npm run server  # 后端服务器
+npm run client  # 前端开发服务器
+```
+
+6. **访问应用**
+
+运行 `npm start` 后，浏览器会自动打开并访问 `http://localhost:5173`
+
+或手动访问：`http://localhost:5173`
+
+---
+
+## 📁 项目结构
+
+```
+CollabDocChat/
+├── server/                 # 后端代码
+│   ├── models/            # 数据模型
+│   │   ├── User.js
+│   │   ├── Group.js
+│   │   ├── Document.js
+│   │   └── Task.js
+│   ├── routes/            # API 路由
+│   │   ├── auth.js
+│   │   ├── groups.js
+│   │   ├── documents.js
+│   │   └── tasks.js
+│   ├── middleware/        # 中间件
+│   │   └── auth.js
+│   ├── websocket/         # WebSocket 处理
+│   │   └── index.js
+│   └── index.js           # 服务器入口
+├── src/                   # 前端代码
+│   ├── pages/            # 页面组件
+│   │   ├── login.js
+│   │   ├── admin-dashboard.js
+│   │   └── user-dashboard.js
+│   ├── services/         # 服务层
+│   │   ├── api.js
+│   │   ├── auth.js
+│   │   └── websocket.js
+│   ├── styles/           # 样式文件
+│   │   └── main.css
+│   └── main.js           # 前端入口
+├── package.json
+├── vite.config.js
+├── .env.example
+└── README.md
+```
+
+---
+
+## 🔌 API 文档
+
+### 认证接口
+
+#### 注册
+```http
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "username": "string",
+  "email": "string",
+  "password": "string",
+  "role": "admin" | "user"
+}
+```
+
+#### 登录
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "string",
+  "password": "string"
+}
+```
+
+### 群组接口
+
+#### 获取群组列表
+```http
+GET /api/groups
+Authorization: Bearer {token}
+```
+
+#### 创建群组（管理员）
+```http
+POST /api/groups
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "name": "string",
+  "description": "string",
+  "members": ["userId1", "userId2"]
+}
+```
+
+#### 随机点名（管理员）
+```http
+POST /api/groups/:id/call
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "count": 1
+}
+```
+
+### 文档接口
+
+#### 获取群组文档
+```http
+GET /api/documents/group/:groupId
+Authorization: Bearer {token}
+```
+
+#### 创建文档
+```http
+POST /api/documents
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "title": "string",
+  "content": "string",
+  "groupId": "string",
+  "permission": "readonly" | "editable"
+}
+```
+
+#### 更新文档
+```http
+PATCH /api/documents/:id
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "content": "string"
+}
+```
+
+### 任务接口
+
+#### 获取我的任务
+```http
+GET /api/tasks/my
+Authorization: Bearer {token}
+```
+
+#### 创建任务（管理员）
+```http
+POST /api/tasks
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "title": "string",
+  "description": "string",
+  "groupId": "string",
+  "assignedTo": ["userId1"],
+  "relatedDocument": "documentId",
+  "deadline": "2024-12-31"
+}
+```
+
+---
+
+## 🔄 WebSocket 事件
+
+### 客户端发送
+
+```javascript
+// 认证
+{ type: 'auth', token: 'jwt_token' }
+
+// 加入群组
+{ type: 'join_group', groupId: 'group_id' }
+
+// 发送聊天消息
+{ type: 'chat_message', groupId: 'group_id', username: 'user', content: 'message' }
+
+// 同步文档
+{ type: 'document_sync', documentId: 'doc_id', content: 'text', cursorPosition: 0 }
+
+// 响应点名
+{ type: 'call_response', groupId: 'group_id', username: 'user' }
+
+// 输入状态
+{ type: 'typing', documentId: 'doc_id', username: 'user', isTyping: true }
+```
+
+### 服务器推送
+
+```javascript
+// 认证成功
+{ type: 'auth_success', userId: 'user_id', role: 'admin' }
+
+// 聊天消息
+{ type: 'chat_message', groupId: 'group_id', userId: 'user_id', username: 'user', content: 'message', timestamp: 'ISO8601' }
+
+// 文档更新
+{ type: 'document_update', documentId: 'doc_id', content: 'text', userId: 'user_id', timestamp: 'ISO8601' }
+
+// 用户离线
+{ type: 'user_offline', userId: 'user_id' }
+```
+
+---
+
+## 🎨 界面预览
+
+### 登录页面
+- 现代化渐变背景
+- 流畅的动画效果
+- 登录/注册切换
+
+### 管理员仪表板
+- 群组管理面板
+- 任务发布界面
+- 文档权限控制
+- 随机点名功能
+
+### 用户仪表板
+- 任务列表
+- 实时文档编辑器
+- 群组聊天
+- 在线状态显示
+
+---
+
+## 🤝 贡献指南
+
+我们欢迎所有形式的贡献！
+
+### 如何贡献
+
+1. Fork 本项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+### 代码规范
+
+- 使用 ES6+ 语法
+- 遵循 ESLint 规则
+- 添加必要的注释
+- 编写清晰的提交信息
+
+---
+
+## 📦 发布到 npm
+
+### 准备发布
+
+1. **更新版本号**
+
+```bash
+npm version patch  # 1.0.0 -> 1.0.1
+npm version minor  # 1.0.0 -> 1.1.0
+npm version major  # 1.0.0 -> 2.0.0
+```
+
+2. **登录 npm**
+
+```bash
+npm login
+```
+
+3. **发布包**
+
+```bash
+npm publish
+```
+
+### 使用 npm 包
+
+```bash
+npm install collabdocchat
+```
+
+---
+
+## 📄 开源协议
+
+本项目采用 [MIT License](LICENSE) 开源协议。
+
+---
+
+## 🙏 致谢
+
+感谢以下开源项目：
+
+- [Express](https://expressjs.com/) - Web 框架
+- [MongoDB](https://www.mongodb.com/) - 数据库
+- [Yjs](https://github.com/yjs/yjs) - CRDT 算法
+- [Vite](https://vitejs.dev/) - 构建工具
+
+---
+
+## 📞 联系方式
+
+- **项目主页**: [https://github.com/yourusername/collabdocchat](https://github.com/yourusername/collabdocchat)
+- **问题反馈**: [Issues](https://github.com/yourusername/collabdocchat/issues)
+- **邮箱**: your.email@example.com
+
+---
+
+## 🗺 路线图
+
+### v1.1.0 (计划中)
+- [ ] 文件上传功能
+- [ ] 富文本编辑器
+- [ ] 消息通知系统
+- [ ] 移动端适配
+
+### v1.2.0 (计划中)
+- [ ] 视频会议集成
+- [ ] 屏幕共享
+- [ ] 白板功能
+- [ ] 插件系统
+
+### v2.0.0 (未来)
+- [ ] 微服务架构
+- [ ] Docker 部署
+- [ ] 多语言支持
+- [ ] AI 助手集成
+
+---
+
+<div align="center">
+
+**⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐**
+
+Made with ❤️ by CollabDocChat Team
+
+</div>
+
+