order_site/apps/backend

order-site-backend

快手轻量后端服务。

后端负责订单入库、履约任务编排、快手 Cloud / 91 卡券 / 快手小店核销配置、后台管理接口和数据库迁移。默认入口就是快手轻量后端。

快速启动

先安装 Node 依赖：

npm install

复制并填写环境变量后启动：

cp ../../.env.mac-docker.example ../../.env
npm run dev

生产构建：

npm run build
npm run start

常用验证：

npm run typecheck
npm run build
npm test

配置

后端采用工作区根目录 .env 做环境配置：

• 通用默认值：src/config/defaults.ts
• 本地/部署覆盖：工作区根目录 .env

常用配置：

• 服务端口 PORT（Docker 部署中由根目录 .env 的 BACKEND_PORT 映射）
• 日志级别 LOG_LEVEL=debug|info|warn|error
• 数据库连接 DATABASE_URL
• 后台登录密钥 ADMIN_SESSION_SECRET
• 默认后台用户 ADMIN_DEFAULT_USERS_JSON
• 91 卡券开放接口凭据 KAQUAN91_USER_ID / KAQUAN91_SECRET

接口

• GET /health：健康检查
• GET /health/live：存活检查
• GET /health/ready：就绪检查
• /api/v1/open/91/*：91 卡券开放回调
• /api/v1/claim/*：领取页接口
• /api/v1/admin/*：后台管理接口

目录

• src/index.ts：服务入口
• src/app.ts：Express 应用组装
• src/routes：API 路由
• src/services/order：订单、商品匹配和履约任务编排
• src/services/fulfillment：快手 Cloud 履约编排
• src/services/admin：后台读写、权限、配置管理
• src/repositories：数据库访问
• src/db/migrations：新库初始化脚本

Docker 开发

开发版 Compose 会把源码挂载进容器：

• postgres 容器提供开发库，后端通过 DATABASE_URL 连接
• 后端容器启动时执行依赖安装和 npm run dev
• 平时改 src/ 或 .env，一般不需要重建镜像

只有下面几类改动通常还需要重新构建 backend：

• deploy/docker/backend*.Dockerfile
• Node 版本或系统层依赖
• package.json / package-lock.json

运行产物

运行日志默认保存在：

• data/logs/app-YYYY-MM-DD.log
• data/logs/integration-YYYY-MM-DD.log

日志按天切分，默认自动清理 7 天前的旧日志。成功的 /health、/health/live、/health/ready 探活请求默认不写 access log。

data/*.json 为本地运行配置，可能包含账号、Cookie、token 或平台配置，默认不提交；请复制 data/*.example.json 后填写真实值。