# web_shop

**Repository Path**: xia5523/web_shop

## Basic Information

- **Project Name**: web_shop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# web_shop

电商管理后台，提供商品、供应商、聊天记录、Shopee 刊登等数据的查看与管理。

后端：FastAPI + MySQL
前端：Vue 3 + Vite
端口：9400

---

## 目录结构

```
web_shop/
├── app.py                  # FastAPI 主程序
├── db.py                   # 数据库查询层（MySQL）
├── requirements.txt        # Python 依赖
├── .env                    # 环境变量（不进 git）
├── .env.example            # 环境变量模板
├── frontend/               # Vue3 前端源码
│   ├── src/
│   │   ├── App.vue         # 主组件
│   │   ├── main.js
│   │   └── style.css
│   ├── dist/               # 构建产物（npm run build 生成）
│   ├── package.json
│   └── vite.config.js
└── deploy/
    └── systemd/
        └── auto_shop_web.service  # systemd 服务单元
```

---

## 环境变量

复制模板后填写：

```bash
cp .env.example .env
```

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MYSQL_HOST` | MySQL 地址 | `127.0.0.1` |
| `MYSQL_PORT` | MySQL 端口 | `33060` |
| `MYSQL_USER` | 用户名 | `root` |
| `MYSQL_PASS` | 密码 | 空 |
| `MYSQL_DB` | 数据库名 | `auto_shop` |
| `WEB_PASSWORD` | 登录密码 | 必填 |
| `WEB_SECRET` | Cookie 签名密钥（随机字符串） | 必填 |
| `WEB_SESSION_TTL_DAYS` | 登录有效期（天） | `30` |

生成随机 `WEB_SECRET`：

```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

---

## 安装与启动

### 首次安装

```bash
cd /data/project/web_shop

# 1. 创建 Python 虚拟环境
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填写 MySQL 密码、WEB_PASSWORD、WEB_SECRET

# 3. 构建前端
cd frontend && npm install && npm run build && cd ..
```

### 开发模式启动

```bash
# 后端（热重载）
.venv/bin/uvicorn app:app --host 0.0.0.0 --port 9400 --reload

# 前端（独立开发服务器，访问 http://localhost:5173）
cd frontend && npm run dev
```

### 生产部署（systemd 系统服务）

```bash
# 安装服务
sudo cp deploy/systemd/auto_shop_web.service /etc/systemd/system/auto_shop_web.service

# 重新加载并设为开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now auto_shop_web
```

---

## 常用管理命令

```bash
# 查看运行状态
sudo systemctl status auto_shop_web

# 重启服务（修改代码或 .env 后执行）
sudo systemctl restart auto_shop_web

# 停止服务
sudo systemctl stop auto_shop_web

# 实时查看日志
journalctl -u auto_shop_web -f

# 查看最近 100 行日志
journalctl -u auto_shop_web -n 100
```

---

## Redis 缓存机制（/reference）

`/api/reference-products` 已使用 **Redis 条件缓存**，用于缓存参考商品查询结果。

### 缓存键组成
缓存 key 会包含以下查询条件：
- `sku`
- `cost_min`
- `cost_max`
- `qty_min`
- `qty_max`

也就是说：**不同筛选条件会写入不同的 Redis key，不会串缓存**。

### 缓存内容
Redis 中缓存的是整批查询结果（最多 200 条）以及：
- `total`
- `items`
- `cache_time`
- `filters`

接口返回时再根据 `offset` / `limit` 做分页切片。

### 缓存配置
`.env` 相关配置：

```bash
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
REF_CACHE_TTL=1800
```

说明：
- `REF_CACHE_TTL` 默认 1800 秒（30 分钟）
- `use_cache=true`：优先读 Redis
- `use_cache=false`：绕过缓存，强制重新查询 TiDB 并回写 Redis

### Redis 运行方式
当前 Redis 使用 Docker 运行：

```bash
docker ps | grep redis
docker exec redis redis-cli ping
```

---

## /reference 页面多选功能

`/reference` 页面已支持多选，与 `/products` 页的交互方式类似。

### 功能说明
- 表头支持 **全选 / 取消全选**
- 每行支持单独勾选
- 选中后顶部会出现批量操作栏
- 点击 **“打开供应商页面”** 后，会遍历所选行中的：
  - `sup1_link`
  - `sup2_link`
  - `sup3_link`
- 每个非空供应商链接都会在新标签页打开

### 行为细节
- 一条参考商品最多会打开 3 个供应商页面
- 如果某条数据只有 1~2 个供应商链接，则只打开存在的链接
- 如果所选数据没有供应商链接，会弹出提示，不打开页面

---

## 常见故障排查

### 1. 服务启动失败 / 页面打不开
先看服务状态：

```bash
sudo systemctl status auto_shop_web
journalctl -u auto_shop_web -n 100 --no-pager
```

重启服务：

```bash
sudo systemctl restart auto_shop_web
```

---

### 2. 9400 端口被占用
如果日志出现：

```text
[Errno 98] address already in use
```

说明 9400 端口被其他进程占用了。

查看占用者：

```bash
sudo lsof -i :9400
sudo ss -ltnp | grep 9400
```

如果确认是异常残留进程，可以先结束它，再重启服务：

```bash
sudo kill <PID>
sudo systemctl restart auto_shop_web
```

> 不要同时运行多个 uvicorn / 多个 systemd 服务，否则会重复抢占 9400。

---

### 3. 服务文件修改后不生效
如果修改了 `/etc/systemd/system/auto_shop_web.service`，需要：

```bash
sudo systemctl daemon-reload
sudo systemctl restart auto_shop_web
```

---

### 4. 前端改了但页面没变化
前端修改后需要重新构建：

```bash
cd /data/project/web_shop/frontend
npm run build
```

然后刷新浏览器。

如果改的是后端代码、`.env`、依赖或 systemd 配置，则还需要：

```bash
sudo systemctl restart auto_shop_web
```

---

### 5. Redis 缓存异常
检查 Redis 容器是否正常：

```bash
docker ps | grep redis
docker exec redis redis-cli ping
```

检查缓存配置：

```bash
grep -E "REDIS_HOST|REDIS_PORT|REDIS_DB|REF_CACHE_TTL" /data/project/web_shop/.env
```

如果想临时绕过缓存，可在接口请求中使用：

```text
use_cache=false
```

---

### 6. Chrome 进程残留
如果浏览器自动化相关任务异常，或系统里残留大量 Chrome 进程，可先检查：

```bash
ps aux | egrep "chrome|chromium|Google Chrome|headless_shell"
```

清理残留 Chrome：

```bash
pkill -f "/opt/google/chrome/chrome"
pkill -f chrome_crashpad_handler
```

清理后如需恢复 Web 服务：

```bash
sudo systemctl restart auto_shop_web
```

---

## API 一览

### 认证

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/health` | 健康检查（无需登录） |
| `POST` | `/api/login` | 登录，body: `{"password":"..."}` |
| `POST` | `/api/logout` | 登出 |
| `GET` | `/api/me` | 检查登录状态 |

### 商品

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/products` | 商品列表（支持关键词/状态/价格筛选） |
| `GET` | `/api/product/{id}` | 商品详情 |
| `PATCH` | `/api/product/{id}/status` | 修改商品状态 |
| `PATCH` | `/api/products/batch-status` | 批量修改状态 |

商品状态可选值：`候选` / `已通过` / `已上架` / `已拒绝` / `已归档`

### 供应商

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/suppliers` | 供应商列表 |

### 聊天记录

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/chats` | 聊天会话列表 |
| `GET` | `/api/messages` | 消息列表（按 chat_id 筛选） |

### Shopee 刊登

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/shopee-listings` | 刊登列表 |
| `GET` | `/api/shopee-listing/{id}` | 刊登详情 |
| `GET` | `/api/shopee-listing/by-product/{product_id}` | 按商品查刊登 |
| `POST` | `/api/shopee-listing/map-from-product/{product_id}` | 从商品一键生成草稿 |
| `PATCH` | `/api/shopee-listing/{id}` | 更新刊登字段 |
| `GET` | `/api/shopee-listing/{id}/edit-log` | 查看修改记录 |

刊登状态可选值：`草稿` / `待审核` / `已上架` / `已下架` / `失败`

### 其他

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/keyword-pool` | 关键词池 |
| `GET` | `/api/scout-history` | 选品历史 |
| `GET` | `/api/config` | 应用配置 |
| `PUT` | `/api/config/{key}` | 更新配置项 |

交互式 API 文档：`http://localhost:9400/api-docs`

---

## 前端构建

修改前端代码后需要重新构建：

```bash
cd /data/project/web_shop/frontend
npm run build
# 构建完成后通常无需重启；如修改后端代码、.env 或依赖，则执行 sudo systemctl restart auto_shop_web
```