# e-commerce-api

**Repository Path**: y_ttitt/e-commerce-api

## Basic Information

- **Project Name**: e-commerce-api
- **Description**: 跨境电商管理平台后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网站管理系统 — 后端

FastAPI + SQLAlchemy + Redis + Celery，当前重点是认证、搜鞋网账号管理、原品联调接口与后续扩展边界。

## 服务器部署信息

| 项目 | 值 |
|------|------|
| 服务器 | 49.234.53.232 |
| SSH 用户 | ubuntu |
| 项目源码目录 | `/opt/website-management/e-commerce-api` |
| Git 远程仓库 | gitee.com:y_ttitt/e-commerce-api.git |
| Docker 镜像 | `deploy-backend:latest`（基于 `Dockerfile.server`） |
| 后端容器 | `website-management-backend` |
| Crawler Worker 容器 | `website-management-crawler-worker` |
| Celery Worker 容器 | `website-management-celery-worker` |
| MySQL 容器 | `website-management-mysql`（DB: `website_management`） |
| Redis 容器 | `website-management-redis` |
| Scheduler 容器 | `website-management-crawler-scheduler` |

### 日常部署更新（唯一标准入口）

日常前后端统一发布，默认只执行这一个入口：

```bash
# 1. 本地提交并推送前后端代码
git push

# 2. 在后端项目中执行一体化远程部署脚本
bash scripts/deploy_full_remote_update.sh
```

这个总脚本会按顺序完成：
- 调用前端部署脚本：
  - 远程 `git pull`
  - `npm ci`
  - `npm run build`
  - 发布 `dist` 到 `/var/www/website-management/current`
  - reload nginx
- 调用后端部署脚本：
  - 远程 `git pull`
  - 构建统一后端镜像
  - 重建并启动以下容器：
    - `website-management-backend`
    - `website-management-celery-worker`
    - `website-management-crawler-worker`
    - `website-management-crawler-scheduler`
  - 确保 Redis / MySQL / Docker network 可用
  - 执行 `/health` 检查
- 最后统一验证：
  - 前端首页可访问
  - 后端 `/health` 正常
  - 四个后端业务容器都在运行

> **重要**：不要只更新 `website-management-backend`，也不要只在前端仓库手工发布 `dist`。标准流程是从后端项目执行 `bash scripts/deploy_full_remote_update.sh`，统一完成前端静态资源和后端异步容器更新。

### 后端单独发布（仅在明确只改后端时使用）

```bash
bash scripts/deploy_remote_update.sh
```

### 部署后验证

```bash
# 查看前端首页
ssh ubuntu@49.234.53.232 "curl -fsSI http://127.0.0.1/"

# 查看后端健康状态
ssh ubuntu@49.234.53.232 "curl -fsS http://127.0.0.1:8000/health"

# 查看四个后端业务容器是否都在运行
ssh ubuntu@49.234.53.232 "docker ps --format '{{.Names}} {{.Image}} {{.Status}}' | grep -E 'website-management-(backend|celery-worker|crawler-worker|crawler-scheduler)'"
```

### 容器职责

| 容器 | 职责 |
|------|------|
| `website-management-backend` | FastAPI HTTP API |
| `website-management-celery-worker` | Celery 异步任务（如妙手上传解析回写） |
| `website-management-crawler-worker` | 消费 crawler_runs 并执行爬虫脚本 |
| `website-management-crawler-scheduler` | 定时扫描脚本并创建 crawler_runs |

### Crawler Worker 启动参数

当前 worker 不过滤脚本类型（消费所有 builtin + subprocess 类型）：

```bash
python backend/scripts/run_crawler_worker.py --poll-seconds 5 --queue-limit 10
```

> **注意**：如果加了 `--script-type builtin`，则只消费 builtin 类型脚本，collector/downloader/post_processor 类型会一直卡在 queued。

## 快速启动（本地开发）

1. 安装依赖

```bash
python -m pip install -r requirements.txt
```

2. 数据库初始化

```bash
cp .env.example .env
python -m scripts.init_mysql_db
python -m scripts.upgrade_souxie_schema
python -m scripts.upgrade_soft_delete_schema
python -m scripts.upgrade_source_product_asset_schema
```

3. 初始化管理员账号

```bash
python -m scripts.init_admin_user
```

默认会创建或更新管理员账号：`admin / Admin@123456`。

4. 启动 API

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

5. 访问文档

- Swagger: `http://127.0.0.1:8000/docs`
- Health: `http://127.0.0.1:8000/health`

## 容器启动

```bash
mkdir -p data storage runtime
docker network create website-management >/dev/null 2>&1 || true
docker rm -f website-management-backend website-management-redis >/dev/null 2>&1 || true
docker run -d \
  --name website-management-redis \
  --network website-management \
  --network-alias redis \
  --restart unless-stopped \
  redis:7-alpine
docker build -t website-management-backend .
docker run -d \
  --name website-management-backend \
  --network website-management \
  --restart unless-stopped \
  --env-file .env.docker \
  -p 8000:8000 \
  -v "$(pwd)/data:/app/data" \
  -v "$(pwd)/storage:/app/storage" \
  -v "$(pwd)/runtime:/app/runtime" \
  website-management-backend
docker exec website-management-backend python -m scripts.init_admin_user
docker exec website-management-backend python -m scripts.upgrade_souxie_schema
docker exec website-management-backend python -m scripts.upgrade_soft_delete_schema
```

容器内后端会通过 `host.docker.internal:3306` 连接宿主机上的 MySQL；运行态目录统一挂载为 `data/ -> /app/data`、`storage/ -> /app/storage`、`runtime/ -> /app/runtime`，避免把本地运行数据打进镜像。

## 本地开发：复用线上 MySQL / Redis

如果你本地只想启动 backend 容器，不想再起 MySQL / Redis，可以直接复用服务器上的中间件。

### 前提

- 服务器上的 MySQL / Redis 已只绑定到 `127.0.0.1`
- 本地通过 SSH 隧道转发到：
  - `127.0.0.1:3307 -> 服务器 127.0.0.1:3306`
  - `127.0.0.1:6380 -> 服务器 127.0.0.1:6379`
- 本地容器通过 `host.docker.internal` 访问上述端口

### 已准备好的文件

- `.env.local`
- `docker-compose.local.yml`
- `scripts/dev_tunnel.sh`
- `scripts/dev_up.sh`

### 使用方式

1. 启动 SSH 隧道（后台运行）：

```bash
bash scripts/dev_tunnel.sh
```

如果你本机还没配 SSH key，也可以临时传密码：

```bash
SSH_PASSWORD='你的服务器密码' bash scripts/dev_tunnel.sh
```

2. 启动本地 backend 容器：

```bash
bash scripts/dev_up.sh
```

如需停止本地 backend 容器并关闭 SSH 隧道：

```bash
bash scripts/dev_down.sh
```

3. 前端本地开发继续直接运行：

```bash
cd ../e-commerce-admin
npm run dev
```

### 说明

- `scripts/dev_tunnel.sh` 会把本地 `3307 / 6380` 端口映射到服务器的 MySQL / Redis
- `scripts/dev_up.sh` 会先检查本地隧道端口是否存在，再执行 `docker compose -f docker-compose.local.yml up --build`
- 如需修改服务器地址或本地端口，可通过环境变量覆盖，例如：

```bash
SERVER_HOST=1.2.3.4 LOCAL_MYSQL_PORT=3310 LOCAL_REDIS_PORT=6381 bash scripts/dev_tunnel.sh
```

## 当前已打通能力

- 搜鞋纯 HTTP 压缩包下载：容器内无需浏览器，直接登录、探测并下载压缩包
- 搜鞋下载导入全链路：下载 → 后处理 → manifest 生成 → 原品导入 已打通
- 真实认证：`POST /api/v1/auth/login`、`GET /api/v1/auth/me`、`POST /api/v1/auth/logout`
- 搜鞋网账号管理：列表、新增、编辑、软删除、启停、重置配额、Excel 导入
- 原品管理：列表、详情、素材列表、审核记录、审核、直发
- 裂变创建：`POST /api/v1/mutation-tasks`

## 当前约定

- 统一从仓库根目录启动：`uvicorn app.main:app`
- 当前默认使用 MySQL，本地环境变量采用 `DB_*` 命名
- 新库默认名为 `website_management`
- `scripts/init_mysql_db.py` 会自动创建数据库并导入 `网站管理系统_一期建表SQL.sql`
- 所有妙手调用后续统一走“当前登录用户绑定的 token”
- 业务删除统一使用软删除，当前通过 `deleted_at` 字段表示，列表与详情查询默认过滤已删除数据
- 原品表只保留 `souxie_account_id` 单向关联，不在原品表冗余搜鞋网账号名

## 搜鞋网账号导入

```bash
python -m scripts.import_souxie_accounts --entered-by admin
```

导入后可通过 `GET /api/v1/souxie-accounts` 查看账号列表。

## 已验证测试

```bash
pytest tests/test_health.py tests/test_auth.py tests/test_source_products.py tests/test_souxie_accounts.py -q
```

## 妙手登录监听

```bash
python -m scripts.watch_miaoshou_login
```

在妙手 ERP 中完成登录后，再执行这个监听脚本。脚本会抓取 `autoLoginToken`、`accountId` 与 cookies 快照，结果写入 `runtime/miaoshou_login_capture.json`。

注意：这个脚本只适用于开发联调或排障，不适合作为生产环境用户主流程。生产环境更合理的方案是通过浏览器扩展在用户本机读取妙手登录态，再安全回传到当前系统完成绑定。

如果临时采用当前备用流程：仅完成妙手 ERP 登录不会自动把账号绑定到当前系统；仍需回到“妙手账号”页面，上传 `miaoshou_login_capture.json` 或手动粘贴 `autoLoginToken`，由前端调用 `/api/v1/miaoshou/accounts/bind` 完成绑定。


## 搜鞋全链路验证

1. 先按上面的“容器启动”命令拉起 `website-management-backend` 与 `website-management-redis`

2. 初始化内置脚本

```bash
curl -X POST http://127.0.0.1:8000/api/v1/crawler-scripts/bootstrap \
  -H 'Authorization: Bearer <你的JWT>'
```

3. 手动执行容器内全链路脚本

```bash
docker exec website-management-backend \
  python -m scripts.run_souxie_http_download_pipeline \
  --detail-url https://DFXY.sooxie.com/detail/2415693 \
  --output-dir /app/storage/pipeline_smoke \
  --job-name souxie_pipeline_smoke_20260310
```

执行成功后会得到：

- 下载目录：`/app/storage/pipeline_smoke`
- manifest：`/app/storage/pipeline_smoke/souxie_download_manifest.json`
- 导入结果：自动写入 `crawler_jobs / crawler_links / source_products / source_product_assets`

补充说明：

- `souxie_http_archive_downloader` 只负责下载压缩包与 sidecar，不负责导入。
- 推荐优先使用 `souxie_http_download_pipeline`，它会继续执行后处理、manifest 生成与导入。
- `scripts/build_souxie_download_manifest.py` 现在会为图片素材自动生成 `file_md5 / image_phash / image_width / image_height`，导入前图片去重依赖这些字段。
- 历史素材补齐指纹可执行：`python -m scripts.backfill_source_product_asset_fingerprints --dry-run`。

4. 前端联调建议

- 脚本管理页新增内置脚本：`souxie_http_download_pipeline`
- 手动执行时至少传：`detail_url` 或 `input_file`
- 执行结果重点展示：`post_process_result`、`manifest_result`、`import_result`
- 查询运行记录继续用：`GET /api/v1/crawler-scripts/{script_id}/runs`