# order-site-backend

快手轻量后端：订单入库、履约任务编排、91 卡券 / kuaishou-cloud / kuaishou-feifei / 行业电子凭证对接、后台管理接口，以及数据库迁移。

## 快速启动

```bash
npm install
cp ../../.env.mac-docker.example ../../.env
npm run dev
```

推荐优先用仓库根目录 Docker 开发环境（含 PostgreSQL 与 Caddy）。

生产构建：

```bash
npm run build
npm run start
```

常用验证：

```bash
npm run typecheck
npm run build
npm test
```

## 配置

环境变量来自工作区根目录 `.env`：

- 默认值：`src/config/defaults.ts`
- 覆盖：根目录 `.env`

常用项：

| 变量 | 说明 |
| --- | --- |
| `PORT` | 服务端口（Compose 中常由 `BACKEND_PORT` 映射） |
| `LOG_LEVEL` | `debug` / `info` / `warn` / `error` |
| `DATABASE_URL` | PostgreSQL 连接串 |
| `ADMIN_SESSION_SECRET` | 后台登录态签名密钥 |
| `ADMIN_DEFAULT_USERS_JSON` | 默认后台用户 |
| `KAQUAN91_USER_ID` / `KAQUAN91_SECRET` | 91 卡券凭据 |

## 接口

| 路径 | 说明 |
| --- | --- |
| `GET /health` | 健康检查 |
| `GET /health/live` | 存活 |
| `GET /health/ready` | 就绪 |
| `/api/v1/open/91/*` | 91 卡券开放接口 |
| `/api/v1/open/kuaishou-industry/*` | 快手行业电子凭证 |
| `/api/v1/open/kuaishou-feifei/*` | 发货平台 feifei 回调等 |
| `/api/v1/claim/*` | 领取页接口 |
| `/api/v1/admin/*` | 后台管理 |
| `/s/*` | 短链跳转 |

## 目录

| 路径 | 职责 |
| --- | --- |
| `src/index.ts` | 服务入口 |
| `src/app.ts` | Express 组装 |
| `src/routes` | API 路由 |
| `src/services/order` | 订单与任务同步 |
| `src/services/fulfillment` | 履约路由与执行器 |
| `src/services/platforms` | 外部平台实现 |
| `src/services/admin` | 后台读写与配置 |
| `src/repositories` | 数据库访问 |
| `src/db/migrations` | SQL 迁移 |

## 数据库迁移

策略：**001 基线 + 后续渐进增量**。

| 文件 | 作用 |
| --- | --- |
| `src/db/migrations/001_init.sql` | 空库完整基线结构 |
| `src/db/migrations/002_*.sql` 起 | 增量变更 |

规则：

1. 已应用的迁移文件禁止改内容。
2. 结构变更只新增文件，不回写 `001_init.sql`。
3. 启动时自动执行未应用迁移；记录在 `schema_migrations`。
4. 文件名必须为 `NNN_name.sql`（三位序号）。

命令：

```bash
# 对齐状态
npm run db:migrate:status

# 手动 up
npm run db:migrate

# 创建下一份增量（生成 00N_xxx.sql 模板）
npm run db:migrate:create -- add_something
```

创建后编辑 SQL，与业务代码一并提交。Docker 开发环境示例：

```bash
docker compose -f ../../docker-compose.dev.yml exec -T backend npm run db:migrate:create -- add_something
docker compose -f ../../docker-compose.dev.yml exec -T backend npm run db:migrate
```

## Docker 开发

开发 Compose 会挂载源码：

- `postgres` 提供开发库
- 后端启动时安装依赖并 `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`

按天切分，默认清理过期日志。成功的 `/health*` 探活默认不写 access log。

`data/*.json` 为本地运行配置，可能含敏感信息，默认不提交；请从 `*.example.json` 复制后填写。