order_site

快手自动发货与履约管理系统。

项目采用前后端分离架构，用于接收订单、匹配快手履约规则、管理云卡资源，并提供后台页面处理平台配置、任务追踪和人工复核。

技术栈

• 前端：Vue 3、Vite、Element Plus、TypeScript
• 后端：Node.js、Express、PostgreSQL
• 网关：Caddy
• 本地与生产运行：Docker Compose

目录结构

apps/
  backend/                  后端 API、任务编排、平台对接、数据库迁移
    src/
    data/                   本地开发运行数据和平台配置
  frontend/                 前端后台、领取页和配置页面
deploy/
  caddy/                    Caddy 反向代理配置
  docker/                   前后端镜像 Dockerfile
docs/                       平台接口、迁移设计和部署资料
docker-compose.dev.yml      本地 Docker 开发环境
docker-compose.yml          生产/服务器 Compose

本地开发

推荐直接使用 Docker，本地不需要额外维护 Node 和 PostgreSQL。

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/...

查看容器状态：

docker compose -f docker-compose.dev.yml ps

查看日志：

docker compose -f docker-compose.dev.yml logs -f backend
docker compose -f docker-compose.dev.yml logs -f frontend

停止环境：

docker compose -f docker-compose.dev.yml down

开发验证

本项目以容器内验证为准。

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

后端数据库迁移通常会在启动时自动执行；需要手动执行时：

docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate

当前数据库脚本只保留新库初始化结构，不维护历史测试库的升级兼容；切换到这版前请重建开发库或重置 Docker volume。

环境变量

本地开发从根目录 .env 读取，模板为：

cp .env.mac-docker.example .env

生产部署从 .env.server.example 复制：

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 后启动：

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 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：用户领取页

提交前检查清单

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 环境验证