# order-site-workspace

统一工作区版本的订单自动兑换系统。

## 目录结构

```text
apps/
  backend/   Node + Express + Playwright + OCR worker
  frontend/  Vue 3 + Vite + Element Plus
deploy/
  caddy/     Caddy 配置
  docker/    Dockerfile
docs/        迁移与部署文档
docker-compose.yml
```

## 本地开发

前端：

```bash
cd apps/frontend
npm install
npm run dev
```

后端：

```bash
cp .env.mac-docker.example .env
cd apps/backend/subservices/ocr-worker
uv sync
cd apps/backend
npm install
npm run dev
```

## Docker 部署

```bash
cp .env.server.example .env
mkdir -p deploy/data/backend
docker compose up -d
```

生产版 Compose 现在会把后端运行数据直接挂载到宿主机目录：

- `deploy/data/backend`

这样服务器上可以直接查看和备份：

- `logs/`
- `browser-sessions/`
- `redeem-screenshots/`
- `agiso-shops.json`
- `order-fulfillment-bindings.json`

如果你本地已经配好了店铺和履约绑定，首次上线前可以把这两份文件先放进去：

- `deploy/data/backend/agiso-shops.json`
- `deploy/data/backend/order-fulfillment-bindings.json`

后端启动时会自动执行数据库 migration、初始化默认管理员、同步履约目录；但 `/app/data` 下的业务配置文件仍以宿主机目录内容为准。

## Docker 本地开发

```bash
cp .env.mac-docker.example .env
docker compose -f docker-compose.dev.yml up -d --build
```

开发环境现在不再把 Caddy 绑定到固定域名。
这意味着：

- 本地直接访问 `http://localhost` 可用
- 用 ngrok / cloudflared 转发到 `http://localhost:80` 时，不需要因为随机子域名变化而改 Caddy 配置
- 如果要生成发给用户的公网领取链接，只需要更新 `.env` 里的 `APP_BASE_URL`

开发版 Compose 现在是热更新模式：

- `postgres` 容器提供 PostgreSQL
- 后端源码挂载到容器里，运行 `npm run dev`
- 前端源码挂载到容器里，运行 `vite`
- Caddy 只负责把 `80/443` 反代到前后端容器

通常只有首次启动、改 Dockerfile、改系统依赖时才需要 `--build`。

开发版 Compose 会把后端运行产物目录直接挂载到：

- [apps/backend/data](/Users/yml/codes/order-site-workspace/apps/backend/data)

这样本地可以直接看到：

- `data/logs/*.log`
- 浏览器会话产物
- 截图和证明文件

当 `TENCENT_BROWSER_HEADLESS=false` 时，开发版后端容器会自动启动 `Xvfb + x11vnc + noVNC`。
默认可直接在本机访问：

- `http://127.0.0.1:6080/vnc.html`

这样即使整个项目都跑在 Docker 里，也可以直接查看后端 Playwright 浏览器画面。

PostgreSQL 数据则保存在 Docker volume 里：

- `postgres_dev_data`

当前 Dockerfile 已默认针对国内服务器优化以下下载源：

- Debian `apt` 使用腾讯云镜像
- `npm` 使用 `npmmirror`
- Python `pip` 使用腾讯云 PyPI 镜像
- 后端 Playwright 固定为 `1.42.1`，浏览器下载使用 `npmmirror`

如果你的服务器网络环境不同，也可以在构建时覆盖：

```bash
docker compose build \
  --build-arg DEBIAN_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg NPM_REGISTRY=https://registry.npmjs.org \
  --build-arg UV_INDEX_URL=https://pypi.org/simple
```

默认入口：

- 前端与领取页：`https://你的域名/`
- 后端健康检查：`https://你的域名/health`
- 后端接口前缀：`https://你的域名/api/v1/...`

开发环境下的链接生成规则：

- 优先使用 `CLAIM_BASE_URL`
- 如果未设置 `CLAIM_BASE_URL`，后端会自动根据 `APP_BASE_URL` 推导为 `APP_BASE_URL/#/claim`

开发时如果只改业务代码，直接保留 `docker compose -f docker-compose.dev.yml up -d` 即可：

- 改后端 `src/`：容器内自动热重启
- 改前端 `src/`：Vite 自动热更新
- 改 OCR Python：后端下次调用时直接走挂载后的最新源码
- 改数据库 schema：后端启动时会自动执行 migration

详细文档：

- [服务器部署教程](/Users/yml/codes/order-site-workspace/docs/%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%83%A8%E7%BD%B2%E6%95%99%E7%A8%8B.md)
- [首次上线检查清单](/Users/yml/codes/order-site-workspace/docs/%E9%A6%96%E6%AC%A1%E4%B8%8A%E7%BA%BF%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.md)
- [mac 本地 Docker 调试模板](/Users/yml/codes/order-site-workspace/.env.mac-docker.example)
- [服务器部署模板](/Users/yml/codes/order-site-workspace/.env.server.example)

## 迁移原则

- 不重写现有业务代码
- 先统一目录、部署和配置
- 生产环境优先使用 `.env` 和宿主机数据目录挂载
- 本机 Docker 调试优先使用 [docker-compose.dev.yml](/Users/yml/codes/order-site-workspace/docker-compose.dev.yml)