文档对齐 React 技术栈，并支持渐进式数据库迁移
将 README 与部署文档从仅 init 改为 001 基线 + 增量迁移约定，并补充 create/status 脚手架与序号校验。
This commit is contained in:
yml2213
@@ -2,14 +2,16 @@
|
||||
|
||||
快手自动发货与履约管理系统。
|
||||
|
||||
项目采用前后端分离架构，用于接收订单、匹配快手履约规则、管理云卡资源，并提供后台页面处理平台配置、任务追踪和人工复核。
|
||||
前后端分离架构：接收外部订单、按规则匹配发货平台、生成统一领取链接，并提供后台做平台配置、任务追踪和人工复核。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 前端：Vue 3、Vite、Element Plus、TypeScript
|
||||
- 后端：Node.js、Express、PostgreSQL
|
||||
- 网关：Caddy
|
||||
- 本地与生产运行：Docker Compose
|
||||
| 层 | 技术 |
|
||||
| --- | --- |
|
||||
| 前端 | React 19、Vite 8、Ant Design 6、React Router 7、TanStack Query、TypeScript |
|
||||
| 后端 | Node.js、Express 5、TypeScript、PostgreSQL、node-pg-migrate |
|
||||
| 网关 | Caddy |
|
||||
| 运行 | Docker Compose（开发 / 生产分离） |
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -17,80 +19,134 @@
|
||||
apps/
|
||||
backend/ 后端 API、任务编排、平台对接、数据库迁移
|
||||
src/
|
||||
data/ 本地开发运行数据和平台配置
|
||||
frontend/ 前端后台、领取页和配置页面
|
||||
db/migrations/ SQL 迁移（001 基线 + 后续渐进增量）
|
||||
data/ 本地运行数据与平台配置（敏感，默认不提交）
|
||||
frontend/ React 管理后台 + 用户领取页
|
||||
deploy/
|
||||
caddy/ Caddy 反向代理配置
|
||||
docker/ 前后端镜像 Dockerfile
|
||||
docs/ 平台接口、迁移设计和部署资料
|
||||
caddy/ Caddy 反向代理
|
||||
docker/ 前后端 Dockerfile
|
||||
mac-dev.sh / ubuntu-deploy.sh
|
||||
docs/ 平台接口、履约链路、部署说明
|
||||
docker-compose.dev.yml 本地 Docker 开发环境
|
||||
docker-compose.yml 生产/服务器 Compose
|
||||
docker-compose.yml 生产 / 服务器 Compose
|
||||
```
|
||||
|
||||
## 业务边界（简图）
|
||||
|
||||
```text
|
||||
91 卡券进单
|
||||
→ 本系统建单 / 匹配商品 / 创建履约任务
|
||||
→ 返回统一 claimUrl
|
||||
用户打开领取页
|
||||
→ 可选：快手行业电子凭证自动核销
|
||||
→ kuaishou-cloud / kuaishou-feifei / 人工 完成发货
|
||||
后台
|
||||
→ 订单任务、平台配置、审计、人工复核
|
||||
```
|
||||
|
||||
更完整的链路说明见：`docs/履约配置/多发货平台与电子凭证整体链路.md`。
|
||||
|
||||
## 本地开发
|
||||
|
||||
推荐直接使用 Docker，本地不需要额外维护 Node 和 PostgreSQL。
|
||||
推荐直接用 Docker，本机不必单独装 Node / PostgreSQL。
|
||||
|
||||
```bash
|
||||
cp .env.mac-docker.example .env
|
||||
docker compose -f docker-compose.dev.yml up -d --build
|
||||
```
|
||||
|
||||
启动后常用入口：
|
||||
常用入口：
|
||||
|
||||
- 前端、后台、领取页：`http://localhost`
|
||||
- 后端健康检查：`http://localhost/health`
|
||||
- 后端 API 前缀：`http://localhost/api/v1/...`
|
||||
| 入口 | 地址 |
|
||||
| --- | --- |
|
||||
| 前端 / 后台 / 领取页 | `http://localhost` |
|
||||
| 后端健康检查 | `http://localhost/health` |
|
||||
| 后端就绪检查 | `http://localhost/health/ready` |
|
||||
| 后端 API 前缀 | `http://localhost/api/v1/...` |
|
||||
|
||||
查看容器状态：
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
查看日志：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml logs -f backend
|
||||
docker compose -f docker-compose.dev.yml logs -f frontend
|
||||
docker compose -f docker-compose.dev.yml down
|
||||
```
|
||||
|
||||
停止环境：
|
||||
Mac 也可使用：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml down
|
||||
bash deploy/mac-dev.sh
|
||||
```
|
||||
|
||||
## 开发验证
|
||||
|
||||
本项目以容器内验证为准。
|
||||
以容器内执行为准：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run build
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run build
|
||||
```
|
||||
|
||||
后端数据库迁移通常会在启动时自动执行；需要手动执行时：
|
||||
## 数据库迁移
|
||||
|
||||
采用 **基线 + 渐进增量** 策略，由 `node-pg-migrate` 管理，记录表为 `schema_migrations`。
|
||||
|
||||
| 文件 | 含义 |
|
||||
| --- | --- |
|
||||
| `001_init.sql` | 空库基线，建立完整业务结构 |
|
||||
| `002_xxx.sql` 起 | 后续结构变更的增量 SQL |
|
||||
|
||||
约定：
|
||||
|
||||
1. **不要修改**已经应用到共享/生产环境的历史迁移文件。
|
||||
2. 结构变更一律新增迁移文件，不要回写 `001_init.sql`。
|
||||
3. 空库按序号依次执行 `001 → 002 → …`；已有库只执行尚未记录的增量。
|
||||
4. 后端启动时自动 `up`；也可手动执行。
|
||||
|
||||
常用命令（容器内）：
|
||||
|
||||
```bash
|
||||
# 查看本地文件与数据库对齐状态
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate:status
|
||||
|
||||
# 手动执行未应用迁移
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate
|
||||
|
||||
# 创建下一份增量迁移（示例）
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate:create -- add_task_priority
|
||||
```
|
||||
|
||||
当前数据库脚本只保留新库初始化结构，不维护历史测试库的升级兼容；切换到这版前请重建开发库或重置 Docker volume。
|
||||
宿主机直连开发库（注意主机名）：
|
||||
|
||||
```bash
|
||||
cd apps/backend
|
||||
DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/order_site npm run db:migrate:status
|
||||
DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/order_site npm run db:migrate
|
||||
```
|
||||
|
||||
本地需要清空数据重建库时（会丢开发数据）：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml down
|
||||
docker volume rm order_site_postgres_dev_data
|
||||
docker compose -f docker-compose.dev.yml up -d --build
|
||||
```
|
||||
|
||||
更多说明见 `docs/部署启动与数据库重建.md`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
本地开发从根目录 `.env` 读取，模板为：
|
||||
本地：
|
||||
|
||||
```bash
|
||||
cp .env.mac-docker.example .env
|
||||
```
|
||||
|
||||
生产部署从 `.env.server.example` 复制：
|
||||
生产：
|
||||
|
||||
```bash
|
||||
cp .env.server.example .env
|
||||
@@ -98,87 +154,78 @@ cp .env.server.example .env
|
||||
|
||||
常用变量：
|
||||
|
||||
- `APP_DOMAIN` / `CADDY_SITE_ADDR`：Caddy 对外域名与监听地址
|
||||
- `CLAIM_BASE_URL`：领取页完整地址
|
||||
- `DATABASE_URL`：PostgreSQL 连接串
|
||||
- `ADMIN_SESSION_SECRET`：后台登录态签名密钥
|
||||
- `ADMIN_DEFAULT_USERS_JSON`：默认后台用户
|
||||
- `KAQUAN91_USER_ID` / `KAQUAN91_SECRET`：91 卡券开放接口凭据
|
||||
| 变量 | 说明 |
|
||||
| --- | --- |
|
||||
| `APP_DOMAIN` / `CADDY_SITE_ADDR` | 对外域名与 Caddy 监听地址 |
|
||||
| `CLAIM_BASE_URL` | 领取页完整前缀，如 `https://域名/#/claim` |
|
||||
| `DATABASE_URL` | PostgreSQL 连接串（容器内主机名用 `postgres`） |
|
||||
| `ADMIN_SESSION_SECRET` | 后台登录态签名密钥 |
|
||||
| `ADMIN_DEFAULT_USERS_JSON` | 默认后台用户 |
|
||||
| `KAQUAN91_USER_ID` / `KAQUAN91_SECRET` | 91 卡券开放接口凭据 |
|
||||
|
||||
## 运行数据
|
||||
|
||||
本地开发数据：
|
||||
| 环境 | 路径 / Volume |
|
||||
| --- | --- |
|
||||
| 本地后端配置与日志 | `apps/backend/data` |
|
||||
| 本地 PostgreSQL | Docker volume `postgres_dev_data` |
|
||||
| 生产后端数据 | `apps/backend/data`（与本地路径一致） |
|
||||
| 生产 PostgreSQL | Docker volume `postgres_data` |
|
||||
| 生产 Caddy | Docker volume `caddy_data` |
|
||||
|
||||
- 后端配置与运行产物：`apps/backend/data`
|
||||
- PostgreSQL 数据：Docker volume `postgres_dev_data`
|
||||
- 后端日志：`apps/backend/data/logs`
|
||||
|
||||
生产部署数据：
|
||||
|
||||
- 后端数据挂载到 `apps/backend/data`，与本地开发路径保持一致
|
||||
- PostgreSQL 数据保存在 Docker volume `postgres_data`
|
||||
- Caddy 数据保存在 Docker volume `caddy_data`
|
||||
|
||||
如果旧部署曾使用 `deploy/data/backend`，升级前请先把其中的 JSON 配置迁移到 `apps/backend/data`。
|
||||
|
||||
注意：`apps/backend/data/*.json` 中可能包含账号、Cookie、token、平台配置等敏感信息，默认不进入仓库；仓库只保留 `*.example.json` 模板。
|
||||
注意：`apps/backend/data/*.json` 可能含账号、Cookie、token 等敏感信息，默认不进仓库；只保留 `*.example.json` 模板。
|
||||
|
||||
## 生产部署
|
||||
|
||||
在服务器上准备 `.env` 后启动：
|
||||
|
||||
```bash
|
||||
cp .env.server.example .env
|
||||
# 编辑真实配置后：
|
||||
mkdir -p apps/backend/data
|
||||
sudo chown -R 1001:1001 apps/backend/data
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Ubuntu 服务器也可以使用一键部署脚本：
|
||||
Ubuntu 一键脚本：
|
||||
|
||||
```bash
|
||||
bash deploy/ubuntu-deploy.sh
|
||||
```
|
||||
|
||||
第一次执行如果没有 `.env`，脚本会从 `.env.server.example` 生成模板并停止；编辑真实配置后再次执行即可。脚本会自动检查 Docker、检查 `.env` 占位值、修正后端数据目录权限、构建启动服务并等待健康检查通过。
|
||||
首次若无 `.env`，脚本会从示例生成模板并退出；填好后再执行一次即可。脚本会检查 Docker、占位配置、数据目录权限，构建启动并等待健康检查。
|
||||
|
||||
生产入口：
|
||||
生产入口示例：
|
||||
|
||||
- 前端与领取页：`https://你的域名/`
|
||||
- 后端健康检查：`https://你的域名/health`
|
||||
- 后端 API：`https://你的域名/api/v1/...`
|
||||
- 健康检查：`https://你的域名/health`
|
||||
- API：`https://你的域名/api/v1/...`
|
||||
|
||||
生产 Compose 会自动：
|
||||
生产 Compose 会：启动 PostgreSQL → 后端自动迁移 → 初始化默认管理员 → 同步履约目录 → Caddy 暴露前端与 API。
|
||||
|
||||
- 启动 PostgreSQL
|
||||
- 启动后端并执行 migration
|
||||
- 初始化默认后台管理员
|
||||
- 同步履约目录
|
||||
- 通过 Caddy 暴露前端和 API
|
||||
## 主要模块
|
||||
|
||||
## 主要业务模块
|
||||
| 路径 | 职责 |
|
||||
| --- | --- |
|
||||
| `apps/backend/src/routes` | 开放接口 / 领取 / 后台 API |
|
||||
| `apps/backend/src/services/order` | 订单入库、商品匹配、任务同步 |
|
||||
| `apps/backend/src/services/fulfillment` | 履约路由与执行器（cloud / feifei / 人工） |
|
||||
| `apps/backend/src/services/platforms` | 外部平台对接 |
|
||||
| `apps/backend/src/services/admin` | 后台鉴权、读写、配置 |
|
||||
| `apps/backend/src/repositories` | 数据访问 |
|
||||
| `apps/backend/src/db/migrations` | 数据库迁移 |
|
||||
| `apps/frontend/src/pages/admin` | 管理后台页面 |
|
||||
| `apps/frontend/src/pages/claim` | 用户领取页 |
|
||||
|
||||
- `apps/backend/src/routes`：API 路由
|
||||
- `apps/backend/src/services/order`：订单、商品匹配和履约任务编排
|
||||
- `apps/backend/src/services/fulfillment`：快手 Cloud 履约编排
|
||||
- `apps/backend/src/services/admin`：后台读写、权限、配置管理
|
||||
- `apps/backend/src/repositories`：数据库访问
|
||||
- `apps/frontend/src/pages/admin`：React 后台页面
|
||||
- `apps/frontend/src/pages/claim`：React 用户领取页
|
||||
- `apps/frontend-vue/src/views`：旧 Vue 前端保留目录
|
||||
|
||||
## 提交前检查清单
|
||||
## 提交前检查
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||||
```
|
||||
|
||||
确认项：
|
||||
确认：
|
||||
|
||||
- 没有提交真实账号、Cookie、token、手机号或生产配置
|
||||
- `.env` 未被提交
|
||||
- 数据库 migration 与代码一起提交
|
||||
- 未提交真实账号、Cookie、token、手机号或生产配置
|
||||
- `.env` 未入库
|
||||
- **结构变更的 migration 与业务代码同 PR 提交**
|
||||
- 领取链接相关改动已在 Docker 环境验证
|
||||
|
||||
Reference in New Issue
Block a user