# CollabLedger

`CollabLedger` 是一个前后端分离的协作账本/后台管理项目。后端使用 Hono，前端包含 Web 管理端和 Taro 多端应用，根目录 Docker Compose 用于启动 MySQL 和 Redis。

## 项目架构

### 原仓库地址

当前项目是在以下开源项目基础上改造：

- 后端原仓库：<https://github.com/valarchie/collab_ledger-Back-End>
- Web 前端原仓库：<https://github.com/valarchie/collab_ledger-front-end-pure>
- Web UI 上游项目：<https://github.com/pure-admin/vue-pure-admin>

### 目录结构

```text
CollabLedger
├── backend            # Hono 后端
│   ├── prisma              # Prisma schema
│   ├── sql                 # MySQL 初始化 SQL
│   └── src                 # 后端源码
├── frontend
│   ├── web                 # Vite + Vue 3 Web 管理端
│   └── app                 # Taro + Vue 3 多端应用
├── docs                    # 项目开发约定
├── docker-compose.yml      # MySQL、Redis 编排
└── .env.example            # Docker Compose 环境变量示例
```

## 基础环境

- Node.js 22+，推荐配合 Corepack 使用 pnpm
- pnpm 11.1.3+
- Docker Desktop 或 Docker Engine + Docker Compose

项目根目录使用 pnpm workspace 统一管理 `backend`、`frontend/web` 和
`frontend/app`。依赖安装和常用脚本都在根目录执行。

## 开发启动步骤

### 1. 准备环境变量

Docker Compose 在项目根目录执行时会自动读取 `.env`。可以从示例文件复制：

```bash
cp .env.example .env
```

Windows PowerShell：

```powershell
Copy-Item .env.example .env
```

`.env.example` 默认把 MySQL 和 Redis 映射到宿主机 `3306`、`6379`。

### 2. 启动 MySQL 和 Redis

```bash
docker compose up -d mysql redis
```

首次启动 MySQL 容器时，Compose 会把 `backend/sql/init.sql` 挂载到 `/docker-entrypoint-initdb.d/01-init.sql`，由 MySQL 镜像自动初始化数据库。

如果数据库卷已经存在，初始化 SQL 不会重复执行。需要重建本地数据时可以执行：

```bash
docker compose down -v
docker compose up -d mysql redis
```

`docker compose down -v` 会删除本地 MySQL 和 Redis 数据卷，请确认不需要保留本地数据后再执行。

### 3. 安装依赖

```bash
pnpm install
```

### 4. 启动 Hono 后端

本地开发地址为 `http://localhost:3000`。

```bash
pnpm dev:backend
```

如果要按 Vercel 本地模拟方式启动，需要先全局安装 Vercel CLI：

```bash
pnpm add -g vercel
```

然后执行：

```bash
pnpm dev:backend:vercel
```

### 5. 启动 Web 管理端

```bash
pnpm dev:web
```

`frontend/web/.env.development` 默认配置：

```env
VITE_PORT=80
VITE_APP_BASE_API=/dev-api
```

Web 开发服务默认地址：

```text
http://localhost:80
```

开发环境下 `frontend/web/vite.config.ts` 已默认把 `/dev-api` 代理到 `http://localhost:3000`。

如果 80 端口被占用，可以修改 `frontend/web/.env.development` 中的 `VITE_PORT`。

### 6. 启动 App 端，可选

```bash
pnpm dev:app:weapp
```

H5 模式：

```bash
pnpm dev:app:h5
```

`frontend/app/config/dev.ts` 已默认把 `TARO_APP_API_BASE` 指向 `http://localhost:3000`。

## 部署步骤

Hono 后端和 Web 管理端推荐分别部署到 Vercel 或其他 Node.js/静态托管环境。根目录 Docker Compose 只负责启动 MySQL 和 Redis。

### 1. 准备生产环境变量

```bash
cp .env.example .env
```

按实际环境修改 `.env`，至少建议调整：

```env
MYSQL_ROOT_PASSWORD=请替换为强密码
MYSQL_DATABASE=collab_ledger
MYSQL_APP_USERNAME=collab_ledger_app
MYSQL_APP_PASSWORD=请替换为强密码
MYSQL_PORT=13306

REDIS_PASSWORD=请替换为强密码
REDIS_PORT=16379
```

生产环境建议把 `MYSQL_PORT`、`REDIS_PORT` 改成非默认宿主机端口，例如上面的 `13306`、`16379`。这两个变量只影响宿主机暴露端口，不影响容器内部端口。

如果数据库和 Redis 只给后端使用，建议进一步通过服务器防火墙限制这些端口的外部访问，或按实际部署需要移除 `docker-compose.yml` 中 MySQL/Redis 的 `ports` 暴露配置。

不要提交真实生产 `.env` 文件。

### 2. 启动数据库和 Redis

```bash
docker compose up -d mysql redis
```

### 3. 使用 Vercel CLI 部署后端

先全局安装并登录 Vercel CLI：

```bash
pnpm add -g vercel
vercel login
```

后端作为单独的 Vercel Project 部署，Root Directory 为 `backend`：

```bash
cd backend
vercel link
```

按提示创建或关联后端项目。然后配置后端环境变量：

```bash
vercel env add DATABASE_URL production
vercel env add REDIS_URL production
vercel env add JWT_SECRET production
vercel env add PUBLIC_FILE_BASE_URL production
```

常见连接串格式：

```env
DATABASE_URL=mysql://user:password@host:3306/collab_ledger
REDIS_URL=redis://:password@host:6379
```

如果 Redis 服务要求 TLS，使用 `rediss://`。Vercel Functions 不能连接本机 `127.0.0.1`、`localhost` 或 Docker 内网地址，MySQL 和 Redis 必须使用 Vercel 能访问的公网或托管服务地址。

部署后端：

```bash
vercel deploy --prod
cd ..
```

记下部署后的后端域名，例如 `https://your-backend.vercel.app`。

### 4. 使用 Vercel CLI 部署 Web 管理端

Web 管理端作为另一个 Vercel Project 部署，Root Directory 为 `frontend/web`：

```bash
cd frontend/web
vercel link
```

按提示创建或关联 Web 项目。Vercel 识别 Vite 后，构建配置保持：

```text
Install Command: pnpm install
Build Command: pnpm build
Output Directory: dist
```

配置 Web 指向后端公网地址：

```bash
vercel env add VITE_APP_BASE_API production
```

填入上一步得到的后端域名，例如 `https://your-backend.vercel.app`。

部署 Web：

```bash
vercel deploy --prod
cd ../..
```

`frontend/web/vercel.json` 已配置前端路由回退，直接刷新管理端子路由时会返回 `index.html`。

### 5. 常用运维命令

查看数据库和 Redis 状态：

```bash
docker compose ps
```

停止服务：

```bash
docker compose down
```

停止并删除数据卷：

```bash
docker compose down -v
```

`down -v` 会删除数据库和 Redis 数据，生产环境谨慎使用。