# luckysheet-crdt
**Repository Path**: zzzPython/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**: 0
- **Forks**: 19
- **Created**: 2025-01-19
- **Last Updated**: 2025-02-18
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Luckysheet CRDT
简体中文 | [English](./README.md)
## 版权声明
1. 本项目基于 [Luckysheet](https://github.com/mengshukeji/Luckysheet) 源码修改，**请遵循原作者开源协议**，同时，**请不要删除或修改源码头部版权声明**。
2. 本项目以 **Apache2.0 协议开源**，请放心使用，同时，本项目也将回馈于 Luksysheet 社区，丰富社区生态，再次感谢 @[Luckysheet](https://github.com/mengshukeji/Luckysheet) 团队 ❤️
## BUG
1. 个人精力有限，**存在BUG及功能未完善之处**，请提交 [issue](https://gitee.com/wfeng0/luckysheet-crdt/issues/new) ，我会及时处理；
2. 也欢迎大家 fork 项目，提交 pr ，一起完善项目；
## 项目说明
1. 项目为 **Luckysheet 协同增强版（全功能实现）**，意在提供协同实现思路、数据存储服务、协同演示等，项目基于 [Luckysheet](https://github.com/mengshukeji/Luckysheet) 实现，感谢原作者开源。
2. 本项目主要**实现协同功能**模块，对其他内容不做修改，功能使用上并无影响；
3. 项目支持 **可选数据库服务**，没有数据库的用户数据无法持久化存储，协同功能并不受影响。
4. 项目使用 **[Sequelize](https://www.sequelize.cn/)** 作为ORM数据服务技术，支持mysql、sqlite、postgres、mssql等数据库，方便用户快速迁移。
5. 项目使用 **Typescript** 作为主要开发语言，提供完整的类型提示，规范代码，提高开发效率。
6. **项目有 `master` 分支和 `master-alpha` 分支，最新发布的特性，会在 alpha 上进行测试，稳定后会合并到 master 上。**
## 收费声明
1. 请注意，本项目启动、运行、部署等环节，**没有Luckysheet-source 源码，不影响实际协同功能**。
2. 为了更好驱动开源，本项目至 `bf75470121f0f52737e604233add82ad2502218d` git head 起，**不再提供源码修改部分，如有需要，请联系作者收费获取**。
3. **没有 Luckysheet-source源码不影响实际功能，协同部分全部功能均开源**。
4. **没有源码的影响：**
1. 源码仅用于二开场景下，做功能拓展使用；
2. 如果没有二开需求，可不使用源码，如有二开需求，请先联系作者收费使用；
5. **请注意：**
1. Luckysheet-source 会保留，但是不会持续更新，后续的功能升级，仅提供 lib 插件包；
2. 收费标准：**`99 元`**
3. 提供服务：仅提供源码包(不提供持续的功能升级、BUG修复，更不是买产品！)
6. **联系作者**：
1. V: 18276861941
2. qq群: 522121825 (推荐)
## 项目启动
1. 克隆项目：
```bash
git clone https://gitee.com/wfeng0/luckysheet-crdt
```
1. **下载依赖:**
```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` | `http://localhost:9000` 即可体验协同功能。
## 项目部署
1. 先打包前台项目: `npm run build`
```js
build: {
// 打包输出目录 - 会自动打包到 server 目录下
outDir: "./server/public/dist",
rollupOptions: {
input: {
// 前台入口文件 - 请注意，使用的 entry 为入口文件哈
main: "./entry.html",
},
},
},
```
2. 部署 server
```js
// 1. server 运行的时候，会自动构建一个 build 目录，里面是 js 文件，请将以下文件夹部署到服务器上：
- 🗂️wwwroot
+ 📂build // server 打包的 js 文件
+ 📂public // 后台静态资源
+ 🗒️package-lock.json
+ 🗒️package.json
```
## 项目结构说明
```js
// 源码
- 🗂️Luckysheet-source
- 🗂️Luckysheet-source-private // 未开源部分
// 后台服务
- 🗂️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️⃣ 图表协同
1. 已实现vchart图表，请查阅 [Luckysheet-source-vchart](/Luckysheet-source/src/expendPlugins/vchart/plugin.js)
左侧为 `vchart` 渲染，右侧为 `chartmix` 渲染
vchart 图表动画更加流畅，页面简洁美观
vchart 图表设置
2. 拓展实现图表数据更新联动：
chartmix 图表数据联动
vchart 图表数据联动
### 3️⃣ 图片移动性能优化
原效果：
优化后：(调整图片设置打开方式)
### 4️⃣ 文档加密解密
文档加密功能
文档解密功能
打开文档需要密码
配置方法：
```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";
},
}
}
```
### 5️⃣ 文件导入
支持协同~
配置方法：
```js
// 1. 配置导入插件
const options = {
// ...other config
plugins: ["fileImport"],
}
luckysheet.create(options)
```
注意事项：
1. 文件导入依赖于 `luckyexcel` 插件；
2. 故而有些功能受限于插件，如需拓展，请自行实现哈！
3. 请正确配置 `plugins: [ 'fileImport' ]` 后使用导入功能。
### 6️⃣ 文件导出
配置方法：
```js
// 1. 配置导出插件
const options = {
// ...other config
plugins: ["fileExport"],
}
luckysheet.create(options)
```
注意事项：
1. 文件导入依赖于 `exceljs | file-saver` 插件；
2. 故而有些功能受限于插件，如需拓展，请自行实现哈！
3. 请正确配置 `plugins: [ 'fileExport' ]` 后使用导入功能。
### 7️⃣ 拓展菜单功能
配置方法：
```js
const options = {
lang: "zh",
title: "Luckysheet",
// ...other config
menuHandler: {
// 新建
newFile() {},
// 另存为
saveAs() {},
// 分享发送
fileShear(){},
// 退出功能
exit() {}
}
}
```
## 常见问题
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）
```
4. **前台资源引用异常**
```ts
注意： 目前源码中的所有插件依赖，均源自绝对路径哈：
// Dynamically load dependent scripts and styles
const dependScripts = [
"expendPlugins/libs/vue@2.6.11.min.js",
"expendPlugins/libs/vuex.min.js",
"expendPlugins/libs/elementui.min.js",
"expendPlugins/libs/echarts.min.js",
"expendPlugins/chart/chartmix.umd.min.js",
];
那么，就会引发一个问题，前台实际的项目，估计不是 public/expendPlugins/ ** 的路径,请确保 expendPlugins 目录被正确放置并识别。
```
## 开源贡献
1. 提交 [issue](https://gitee.com/wfeng0/luckysheet-crdt/issues/new)
2. fork 本项目，提交 PR
3. 加入交流群：
