文档对齐 React 技术栈，并支持渐进式数据库迁移

将 README 与部署文档从仅 init 改为 001 基线 + 增量迁移约定，并补充 create/status 脚手架与序号校验。

apps/backend/README.md

@@ -1,24 +1,17 @@
 # order-site-backend
 
-快手轻量后端服务。
-
-后端负责订单入库、履约任务编排、kuaishou-lewan / 91 卡券 / 行业电子凭证配置、后台管理接口和数据库迁移。默认入口就是快手轻量后端。
+快手轻量后端：订单入库、履约任务编排、91 卡券 / kuaishou-cloud / kuaishou-feifei / 行业电子凭证对接、后台管理接口，以及数据库迁移。
 
 ## 快速启动
 
-先安装 Node 依赖：
-
 ```bash
 npm install
-```
-
-复制并填写环境变量后启动：
-
-```bash
 cp ../../.env.mac-docker.example ../../.env
 npm run dev
 ```
 
+推荐优先用仓库根目录 Docker 开发环境（含 PostgreSQL 与 Caddy）。
+
 生产构建：
 
 ```bash
@@ -36,61 +29,107 @@ npm test
 
 ## 配置
 
-后端采用工作区根目录 `.env` 做环境配置：
+环境变量来自工作区根目录 `.env`：
 
-- 通用默认值：`src/config/defaults.ts`
-- 本地/部署覆盖：工作区根目录 `.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`
+| 变量 | 说明 |
+| --- | --- |
+| `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/claim/*`：领取页接口
-- `/api/v1/admin/*`：后台管理接口
+| 路径 | 说明 |
+| --- | --- |
+| `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`：kuaishou-lewan 履约编排
-- `src/services/admin`：后台读写、权限、配置管理
-- `src/repositories`：数据库访问
-- `src/db/migrations`：新库初始化脚本
+| 路径 | 职责 |
+| --- | --- |
+| `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 会把源码挂载进容器：
+开发 Compose 会挂载源码：
 
-- `postgres` 容器提供开发库，后端通过 `DATABASE_URL` 连接
-- 后端容器启动时执行依赖安装和 `npm run dev`
-- 平时改 `src/` 或 `.env`，一般不需要重建镜像
+- `postgres` 提供开发库
+- 后端启动时安装依赖并 `npm run dev`
+- 改 `src/` 或 `.env` 通常不必重建镜像
 
-只有下面几类改动通常还需要重新构建 backend：
+需要重建 backend 镜像的情况：
 
-- `deploy/docker/backend*.Dockerfile`
-- Node 版本或系统层依赖
-- `package.json` / `package-lock.json`
+- `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。
+按天切分，默认清理过期日志。成功的 `/health*` 探活默认不写 access log。
 
-`data/*.json` 为本地运行配置，可能包含账号、Cookie、token 或平台配置，默认不提交；请复制 `data/*.example.json` 后填写真实值。
+`data/*.json` 为本地运行配置，可能含敏感信息，默认不提交；请从 `*.example.json` 复制后填写。