136 lines
3.4 KiB
Markdown
136 lines
3.4 KiB
Markdown
# 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` 复制后填写。
|