97 lines
2.4 KiB
Markdown
97 lines
2.4 KiB
Markdown
# order-site-backend
|
||
|
||
快手轻量后端服务。
|
||
|
||
后端负责订单入库、履约任务编排、快手 Cloud / 91 卡券 / 快手小店核销配置、后台管理接口和数据库迁移。默认入口就是快手轻量后端。
|
||
|
||
## 快速启动
|
||
|
||
先安装 Node 依赖：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
复制并填写环境变量后启动：
|
||
|
||
```bash
|
||
cp ../../.env.mac-docker.example ../../.env
|
||
npm run dev
|
||
```
|
||
|
||
生产构建：
|
||
|
||
```bash
|
||
npm run build
|
||
npm run start
|
||
```
|
||
|
||
常用验证：
|
||
|
||
```bash
|
||
npm run typecheck
|
||
npm run build
|
||
npm test
|
||
```
|
||
|
||
## 配置
|
||
|
||
后端采用工作区根目录 `.env` 做环境配置：
|
||
|
||
- 通用默认值：`src/config/defaults.ts`
|
||
- 本地/部署覆盖：工作区根目录 `.env`
|
||
|
||
常用配置：
|
||
|
||
- 服务端口 `PORT`
|
||
- 日志级别 `LOG_LEVEL=debug|info|warn|error`
|
||
- 数据库连接 `DATABASE_URL`
|
||
- 后台登录密钥 `ADMIN_SESSION_SECRET`
|
||
- 默认后台用户 `ADMIN_DEFAULT_USERS_JSON`
|
||
- 91 卡券与快手相关平台配置
|
||
|
||
## 接口
|
||
|
||
- `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/webhook-YYYY-MM-DD.log`
|
||
|
||
日志按天切分，默认自动清理 7 天前的旧日志。成功的 `/health`、`/health/live`、`/health/ready` 探活请求默认不写 access log。
|
||
|
||
`data/*.json` 为本地运行配置，可能包含账号、Cookie、token 或平台配置，默认不提交；请复制 `data/*.example.json` 后填写真实值。
|