# luckysheet-crdt
**Repository Path**: mofees/luckysheet-crdt
## Basic Information
- **Project Name**: luckysheet-crdt
- **Description**: Luckysheet 协同增强版（全功能实现）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 51
- **Created**: 2025-02-03
- **Last Updated**: 2025-09-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Luckysheet CRDT
简体中文 | [English](./README.md)
## 项目说明
1. 项目为 **Luckysheet 协同增强版（全功能实现）**，意在提供协同实现思路、数据存储服务、协同演示等，项目基于 [Luckysheet](https://github.com/mengshukeji/Luckysheet) 实现，感谢原作者开源。
2. 本项目主要**实现协同功能**模块，对其他内容无影响，基于源码修改的部分，均体现在`Luckysheet-source` 文件夹下。
3. 项目支持 **可选数据库服务**，没有数据库的用户数据无法持久化存储，协同功能并不受影响。
4. 项目使用 **[Sequelize](https://www.sequelize.cn/)** 作为ORM数据服务技术，支持mysql、sqlite、postgres、mssql等数据库，方便用户快速迁移。
5. 项目使用 **Typescript** 作为主要开发语言，提供完整的类型提示，规范代码，提高开发效率。
6. **项目有 `master` 分支和 `master-alpha` 分支，最新发布的特性，会在 alpha 上进行测试，稳定后会合并到 master 上。**
## 项目启动
1. 克隆项目：
```bash
git clone https://gitee.com/wfeng0/luckysheet-crdt
```
2. **下载依赖:**
```bash
## "dep": "npm install --s && cd server && npm install --s"
npm run dep
```
**⛔️ 温馨提示：**
```js
1. 项目依赖分为前台依赖、后台依赖（独立的项目哈）；
2. 推荐大家使用 `npm install` 安装依赖，避免出现版本冲突问题；
3. 如果依赖下载报错，可以尝试删除 `package-lock.json` 文件，重新执行依赖安装；
4. 如果封装命令 `npm run dep` 报错，请尝试执行 `npm install --s` 命令进行前台依赖安装，执行 `cd server && npm install --s` 命令进行后台依赖安装。
**如果还报错，请确认环境是否满足运行条件：**
`node -v ==> v20.x.x` // 请确保 node 版本大于 18
`npm -v ==> 10.x.x` // 请确保 npm 版本大于 7.x.x
```
3. 🚫~~如果无数据库服务，请跳过此步骤~~🚫 配置数据库参数：
```ts
// server/src/Config/index.ts
export const SQL_CONFIG = {
port: 3306,
host: "127.0.0.1", // localhost or 127.0.0.1
database: "luckysheet_crdt",
user: "root",
password: "root",
};
```
4. 🚫~~如果无数据库服务，请跳过此步骤~~🚫 同步数据库表：
```bash
npm run db
```
**⛔️ 温馨提示：**
```ts
1. 请确保数据库配置正确可用
2. 请确保项目执行同步数据库命令 `npm run db`
3. 项目周期只需要执行一次，确保数据库内存在表结构即可。
```
5. 启动服务:
- 前台服务：`npm run dev`
- 后台服务：`npm run server`
6. 打开网址：`http://localhost:5000` 即可体验协同功能。
## 项目结构说明
```js
// 源码
- 🗂️Luckysheet-source
// 后台服务
- 🗂️server
+ 📂public // 静态资源
+ 📂src
+ 📂Config // 项目配置文件：端口、SQL、LOG 等配置
+ 📂Controller // 控制层
+ 📂Interface // 接口类型文件
+ 📂Meddleware // 中间件
+ 📂Router // 路由文件
+ 📂Sequelize // 数据库服务
+ 📂Models // 数据模型
+ 🗒️index.ts // 数据库连接
+ 🗒️synchronization.ts // 数据库表同步脚本
+ 📂Service // 业务逻辑
+ 📂Utils // 工具类
+ 📂WebSocket // websocket服务
+ 🗒️broadcast.ts // 处理广播消息
+ 🗒️database.ts // 数据库操作
+ 🗒️index.ts // websocket服务入口文件
+ 🗒️main.ts // 项目入口文件
// 前台服务
- 🗂️src
+ 📂axios // axios 网络请求
+ 📂config // 前台项目配置文件
+ 📂style // 前台项目样式文件
+ 🗒️main.ts // 前台项目主程序
```
## 协同功能计划表
**已实现功能 ✅️，未实现功能 ❌️**
- 文件导入、导出
- ✅️ 导入文件
- ✅️ 导出文件(导出不需要协同)
- 单元格操作
- ✅️ 单个单元格操作
- ✅️ 范围单元格操作
- config操作
- ✅️ 行隐藏
- ✅️ 列隐藏
- ✅️ 修改行高
- ✅️ 修改列宽
- 通用保存
- ❌️ 冻结行列
- ✅️ 修改工作表名称
- ✅️ 修改工作表颜色
- ✅️ 合并单元格
- ❌️ 筛选范围
- ❌️ 筛选的具体设置
- ❌️ 交替颜色
- ❌️ 条件格式
- ❌️ 数据透视表
- ❌️ 动态数组
- 函数链操作
- ❌️ 函数链操作
- 行列操作
- ❌️ 删除行或列
- ❌️ 增加行或列
- 筛选操作
- ❌️ 清除筛选
- ❌️ 恢复筛选
- sheet操作
- ✅️ 新建sheet
- ✅️ 复制sheet
- ✅️ 删除sheet
- ✅️ 删除sheet后恢复操作
- ✅️ 调整sheet位置
- 切换到指定sheet - 可不实现(开启演示功能时，可以实现该功能，但是仅存在于协同层面即可)
- sheet属性(隐藏或显示)
- ✅️ 隐藏或显示
- 表格信息更改
- ✅️ 修改工作簿名称
- 图表
- ✅️ 新增图表
- ✅️ 移动图表位置
- ✅️ 缩放图表
- ✅️ 修改图表配置
## 服务端口说明
1. 前台服务端口：`5000`
2. 后台服务端口：`9000`
3. 数据库服务端口：`3306`
```js
// 1️⃣ 后台服务端口配置：server/src/Config/index.ts
export const SERVER_PORT = 9000;
```
```js
// 2️⃣ 数据库服务端口配置：server/src/Config/index.ts
export const SQL_CONFIG = {
port: 3306,
// ... other config
};
```
```js
// 3️⃣ 前台服务端口配置：src/config/index.ts
// 导出后台服务地址
export const SERVER_URL = "http://localhost:9000";
// 导出协同服务地址
export const WS_SERVER_URL = "ws://127.0.0.1:9000";
```
## 源项目优化
#### 1️⃣ 页面UI重构
1. 源码UI重构，请查阅 [Luckysheet-source-recover-style](/Luckysheet-source/src/css/recover.css)
#### 2️⃣ 拓展vchart图表
1. 已实现vchart图表，请查阅 [Luckysheet-source-vchart](/Luckysheet-source/src/expendPlugins/vchart/plugin.js)
左侧为 `vchart` 渲染，右侧为 `chartmix` 渲染
vchart 图表动画更加流畅，页面简洁美观
vchart 图表设置
### 3️⃣ 图片移动性能优化
原效果：
优化后：(调整图片设置打开方式)
### 4️⃣ 超级公式
功能仍在开发中...
### 5️⃣ 菜单功能 - 文档加密解密
文档加密功能
文档解密功能
打开文档需要密码
配置方法：
```js
/**
* 这里涉及三个方法及其校验，均交由用户自行处理：
* 1. 加密
* 2. 解密
* 3. 打开文件校验
*/
const options = {
// ...other config
menuHandler:{
exit() {
console.log("==> 点击了退出按钮");
},
shear() {
console.log("==> 点击了分享按钮");
},
// 菜单解密 返回值为 Boolean
decrypt(password) {
// 执行后续 server 操作
console.log("==> 解密文档：", password);
// 解密过程需要校验密码，因此需要提供返回值
return password === "123456";
},
// 菜单加密
encryption: (password) => {
// 拿到password可执行后续 server操作
console.log("==> 文档已加密:", password);
},
// 打开文档输入密码 标记文档是否加密 返回值为 Boolean
openDocumentPassword: (password) => {
console.log("==> 用户输入密码:", password);
return password === "123456";
},
}
}
```
### 6️⃣ 菜单功能 - 文件导入
支持协同~
配置方法：
```js
// 1. 配置导入插件
const options = {
// ...other config
plugins: ["fileImport"],
}
luckysheet.create(options)
```
注意事项：
1. 文件导入依赖于 `luckyexcel` 插件；
2. 故而有些功能受限于插件，如需拓展，请自行实现哈！
3. 请正确配置 `plugins: [ 'fileImport' ]` 后使用导入功能。
### 7️⃣ 菜单功能 - 文件导出
配置方法：
```js
// 1. 配置导出插件
const options = {
// ...other config
plugins: ["fileExport"],
}
luckysheet.create(options)
```
注意事项：
1. 文件导入依赖于 `exceljs | file-saver` 插件；
2. 故而有些功能受限于插件，如需拓展，请自行实现哈！
3. 请正确配置 `plugins: [ 'fileExport' ]` 后使用导入功能。
## 常见问题
1. **导入文件时，提示 `文件格式错误`**：
```ts
目前仅支持 xlsx 格式，请检查文件格式是否正确。
```
2. **页面显示`协同服务不可用，当前为普通模式`**：
```ts
try {
const { data } = await fetch({
url: "/api/getWorkerBook",
method: "post",
data: { gridKey },
});
}
catch (error) {}
当且仅当！ fetch 请求失败时，会进入 catch 块，
此时会提示 `协同服务不可用，当前为普通模式`；
请检查服务是否正常，一般有下列可能：
1. 服务异常
2. 数据库异常
3. 数据库表结构异常
```
3. **数据库数据混乱：**
```ts
造成该原因的唯一可能，就是应用没有相关的 delete 语句，
不是我不写哈，而是大家根据自己的实际业务，进行拓展。
下列步骤可恢复：
1. 删除 luckysheet_crdt 所有数据表;
2. 执行 npm run db 同步数据库表;
3. 执行 npm run server 启动服务;
上诉操作，会自己创建数据库表，同步最新的模型结构，
并且创建一个 gridkey-demo 的 workerbooks、workersheets 记录；
当且仅当，这两个表有记录的场景下，才能渲染 luckysheet；
注意！如果两个表没有一条记录，也可能造成无法协同（问题2）
```
## 开源贡献
1. 提交 [issue](https://gitee.com/wfeng0/luckysheet-crdt/issues/new)
2. fork 本项目，提交 PR
3. 加入交流群：
