earthworm

⚡ 简介

通过构造带有连接词的句子，帮助你更好地学习英语~ 😊

🚀 如何开始？

以下提到的操作均基于当前项目的根目录，请注意确保没有错误！

要求

pnpm 版本 >= 8
```
corepack enable
```
Node.js 版本 >= v20

使用 .node-version 中的版本。支持的工具
Postgres 版本 >= 14.0.0
Redis 版本 >= 5.0.0
Docker。请确保它已在你的本地机器上成功安装并运行。

docker --version # Docker 版本 24.0.7, build afdd53b

node --version # v20+

pnpm -v # 8+

编辑器

VSCode

安装推荐的扩展 extensions.json

1. 安装依赖

pnpm install

2. 配置 `.env` 文件

你可以选择将 ./apps/api/.env.example 的内容复制到 ./apps/api/.env。注意，'example' 文件包含示例配置。主要存储系统的环境变量信息，如数据库连接地址、用户名、密码、端口、密钥等。后端服务将从此文件读取配置，当然你也可以将其更改为你自己的配置信息。

Windows 用户建议使用快捷键复制粘贴，Linux 用户可以通过以下命令操作。

服务端

cp ./apps/api/.env.example ./apps/api/.env

客户端

cp ./apps/client/.env.example ./apps/client/.env

3. 恢复 Logto 的数据

将 logto_db_init_data.zip 解压到 .volumes/

unzip logto_db_init_data.zip -d .volumes/

管理员 URL：http://localhost:3011
用户名：admin
密码：WkN7g5-i8ZrJckX

如果你想手动配置 Logto

4. 启动 Docker Compose 服务

后端依赖于 Postgres 和 Redis 服务。使用下面在 package.json 中配置的命令启动和停止这些服务。

# 启动
pnpm docker:start

# 需要时执行以下命令
# 停止
pnpm docker:stop
# 删除
pnpm docker:delete
# 完全删除（包括 Volume 数据）
pnpm docker:down

如果你更喜欢手动操作，可以使用以下命令。

docker compose up -d
docker compose stop
docker compose down

# 兼容旧版 Docker 的命令
docker-compose up -d

5. 初始化数据库架构

执行此命令时，尽量与上一个命令保持一点时间间隔，因为刚才使用的 -d 参数会将其服务执行挂起在后台。此时 docker 服务可能仍在运行。如果发现错误，请再次执行。

pnpm db:init

6. 创建并上传课程数据

仅在初次数据库初始化时执行。

pnpm db:upload

7. 启动后端服务

pnpm dev:serve

8. 启动前端服务

pnpm dev:client

🛠️ 关于测试

在提交代码之前运行测试，并在测试通过后再提交代码，以避免多次提交来解决测试问题。

前端测试

主要是 Vitest 的单元测试和 Cypress 的自动化测试，执行以下命令：

# 进入前端项目目录
cd apps/client

# vitest
pnpm test:unit:run
# cypress
pnpm test:e2e:run

# 监视 vitest，方便热更新查看测试结果
pnpm test:unit:watch

后端测试

主要是 Jest 单元测试和端到端测试，但需要访问测试数据库，所以你需要确保：

Docker Compose 中的 testdb 和 testRedis 服务正常启动。
.env.test 文件中的配置信息正确。如果没有该文件，可以复制 apps/api/.env.test.example 文件的内容到 apps/api/.env.test 文件。提供以下命令直接使用。

执行以下命令：

# 进入后端项目目录
cd apps/api

# 如果已有 .env.test 文件，则不需要运行此步骤
cp .env.test.example .env.test

# 单元测试
pnpm test:unit
# 端到端测试
pnpm test:e2e
# 单元测试和端到端测试一起运行
pnpm test

文档项目

基于 Vitepress 的文档项目，执行以下命令：

# 本地开发
pnpm docs:dev

❓ 常见问题

数据库连接失败

我的 Docker 和里面的数据库都正常运行，但运行 db:init 命令时仍然报错，提示数据库连接失败。

你可以检查 .env 文件中的数据库配置是否正确，甚至是否有这个文件！😠

如何正确更新课程数据？

当你发现课程数据有误并进行修改时，应该使用以下命令来更新数据库中的课程数据。

pnpm db:update

pnpm 安装出错？

有些依赖在安装时需要编译，这就需要相关的构建环境。如果这些环境不存在，编译过程就可能失败。另外，不同模块可能需要不同的构建环境，所以具体问题需要具体分析。以下是遇到的具体问题及其解决方案。

首先尝试以下命令更新 pnpm。

pnpm i -g
# 或
pnpm i -g pnpm
# 或
npx pnpm i -g pnpm@latest

Windows 上安装 argon2 模块出错

安装 Visual Studio 2015 或更高版本，特别是"使用 C++ 的桌面开发"组件。（实际上，任何包含 C++ 开发工具和库的组件都可以。）
如果在编译过程中遇到中文字符显示问题，在命令提示符中执行 chcp 437，然后重新运行安装命令。

Docker 中出现 Docker 权限被拒绝？

在 Windows 中使用 WSL2 作为开发环境时，使用 docker compose up -d 启动 Docker 时出现以下错误：

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json": dial unix /var/run/docker.sock: connect: permission denied

解决方案

将当前用户添加到 docker 组

# 添加 docker 用户组
sudo groupadd docker
# 将登录用户加入到 docker 用户组中
sudo gpasswd -a $USER docker
# 更新用户组
newgrp docker
# 测试 docker 命令是否正常工作
docker images

🤝 前端开发指南

不要解构 Pinia store。
- 使用 store 时可读性会更好
- 解构可能导致响应性丢失，使用 storeToRefs 也比较麻烦
避免在 composables 中包含 UI 逻辑。
- 例如 toast.info()
- 我们将路由器归类为 UI 逻辑，为了便于测试，避免在其中包含路由相关逻辑