184 lines
5.5 KiB
Markdown
184 lines
5.5 KiB
Markdown
# order_site
|
||
|
||
快手自动发货与履约管理系统。
|
||
|
||
项目采用前后端分离架构，用于接收订单、匹配快手履约规则、管理云卡资源，并提供后台页面处理平台配置、任务追踪和人工复核。
|
||
|
||
## 技术栈
|
||
|
||
- 前端：Vue 3、Vite、Element Plus、TypeScript
|
||
- 后端：Node.js、Express、PostgreSQL
|
||
- 网关：Caddy
|
||
- 本地与生产运行：Docker Compose
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
apps/
|
||
backend/ 后端 API、任务编排、平台对接、数据库迁移
|
||
src/
|
||
data/ 本地开发运行数据和平台配置
|
||
frontend/ 前端后台、领取页和配置页面
|
||
deploy/
|
||
caddy/ Caddy 反向代理配置
|
||
docker/ 前后端镜像 Dockerfile
|
||
docs/ 平台接口、迁移设计和部署资料
|
||
docker-compose.dev.yml 本地 Docker 开发环境
|
||
docker-compose.yml 生产/服务器 Compose
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
推荐直接使用 Docker，本地不需要额外维护 Node 和 PostgreSQL。
|
||
|
||
```bash
|
||
cp .env.mac-docker.example .env
|
||
docker compose -f docker-compose.dev.yml up -d --build
|
||
```
|
||
|
||
启动后常用入口：
|
||
|
||
- 前端、后台、领取页：`http://localhost`
|
||
- 后端健康检查：`http://localhost/health`
|
||
- 后端 API 前缀：`http://localhost/api/v1/...`
|
||
|
||
查看容器状态：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml ps
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml logs -f backend
|
||
docker compose -f docker-compose.dev.yml logs -f frontend
|
||
```
|
||
|
||
停止环境：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml down
|
||
```
|
||
|
||
## 开发验证
|
||
|
||
本项目以容器内验证为准。
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm run build
|
||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||
docker compose -f docker-compose.dev.yml exec -T frontend npm run build
|
||
```
|
||
|
||
后端数据库迁移通常会在启动时自动执行；需要手动执行时：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate
|
||
```
|
||
|
||
当前数据库脚本只保留新库初始化结构，不维护历史测试库的升级兼容；切换到这版前请重建开发库或重置 Docker volume。
|
||
|
||
## 环境变量
|
||
|
||
本地开发从根目录 `.env` 读取，模板为：
|
||
|
||
```bash
|
||
cp .env.mac-docker.example .env
|
||
```
|
||
|
||
生产部署从 `.env.server.example` 复制：
|
||
|
||
```bash
|
||
cp .env.server.example .env
|
||
```
|
||
|
||
常用变量：
|
||
|
||
- `APP_DOMAIN` / `CADDY_SITE_ADDR`：Caddy 对外域名与监听地址
|
||
- `CLAIM_BASE_URL`：领取页完整地址
|
||
- `DATABASE_URL`：PostgreSQL 连接串
|
||
- `ADMIN_SESSION_SECRET`：后台登录态签名密钥
|
||
- `ADMIN_DEFAULT_USERS_JSON`：默认后台用户
|
||
- `KAQUAN91_USER_ID` / `KAQUAN91_SECRET`：91 卡券开放接口凭据
|
||
|
||
## 运行数据
|
||
|
||
本地开发数据：
|
||
|
||
- 后端配置与运行产物：`apps/backend/data`
|
||
- PostgreSQL 数据：Docker volume `postgres_dev_data`
|
||
- 后端日志：`apps/backend/data/logs`
|
||
|
||
生产部署数据：
|
||
|
||
- 后端数据挂载到 `apps/backend/data`，与本地开发路径保持一致
|
||
- PostgreSQL 数据保存在 Docker volume `postgres_data`
|
||
- Caddy 数据保存在 Docker volume `caddy_data`
|
||
|
||
如果旧部署曾使用 `deploy/data/backend`，升级前请先把其中的 JSON 配置迁移到 `apps/backend/data`。
|
||
|
||
注意：`apps/backend/data/*.json` 中可能包含账号、Cookie、token、平台配置等敏感信息，默认不进入仓库；仓库只保留 `*.example.json` 模板。
|
||
|
||
## 生产部署
|
||
|
||
在服务器上准备 `.env` 后启动：
|
||
|
||
```bash
|
||
cp .env.server.example .env
|
||
mkdir -p apps/backend/data
|
||
sudo chown -R 1001:1001 apps/backend/data
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Ubuntu 服务器也可以使用一键部署脚本：
|
||
|
||
```bash
|
||
bash deploy/ubuntu-deploy.sh
|
||
```
|
||
|
||
第一次执行如果没有 `.env`，脚本会从 `.env.server.example` 生成模板并停止；编辑真实配置后再次执行即可。脚本会自动检查 Docker、检查 `.env` 占位值、修正后端数据目录权限、构建启动服务并等待健康检查通过。
|
||
|
||
生产入口：
|
||
|
||
- 前端与领取页：`https://你的域名/`
|
||
- 后端健康检查：`https://你的域名/health`
|
||
- 后端 API：`https://你的域名/api/v1/...`
|
||
|
||
生产 Compose 会自动：
|
||
|
||
- 启动 PostgreSQL
|
||
- 启动后端并执行 migration
|
||
- 初始化默认后台管理员
|
||
- 同步履约目录
|
||
- 通过 Caddy 暴露前端和 API
|
||
|
||
## 主要业务模块
|
||
|
||
- `apps/backend/src/routes`：API 路由
|
||
- `apps/backend/src/services/order`：订单、商品匹配和履约任务编排
|
||
- `apps/backend/src/services/fulfillment`：快手 Cloud 履约编排
|
||
- `apps/backend/src/services/admin`：后台读写、权限、配置管理
|
||
- `apps/backend/src/repositories`：数据库访问
|
||
- `apps/frontend/src/views/admin`：后台页面
|
||
- `apps/frontend/src/views/claim`：用户领取页
|
||
|
||
## 提交前检查清单
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||
```
|
||
|
||
确认项：
|
||
|
||
- 没有提交真实账号、Cookie、token、手机号或生产配置
|
||
- `.env` 未被提交
|
||
- 数据库 migration 与代码一起提交
|
||
- 领取链接相关改动已在 Docker 环境验证
|