# order-site-backend

快手轻量后端服务。

后端负责订单入库、履约任务编排、kuaishou-lewan / 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`（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`：kuaishou-lewan 履约编排
- `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` 后填写真实值。