# Ozon Seller Kit：部署与启动

本地一体服务：FastAPI 托管 `web/` 静态页，并提供 `/api/*`。默认只监听本机，适合个人 Mac 开发与日常使用。

---

## 1. 环境要求

| 项 | 说明 |
| --- | --- |
| 系统 | macOS（`start.command` 为 zsh；其他系统用手动启动即可） |
| Python | 3.10+（需已安装 `python3`） |
| 网络 | 生成俄文文案时需能访问 DeepSeek API |
| 端口 | 默认 `8000`，请确保未被占用 |

---

## 2. 获取代码与进入目录

```bash
cd /path/to/ozon-seller-kit
```

项目结构（与启动相关）：

```
ozon-seller-kit/
├── start.command        # macOS 一键启动
├── .env.example         # 环境变量模板
├── .env                 # 本地密钥（勿提交，位于仓库根）
├── server/              # ④ 后端
│   ├── main.py          # FastAPI 入口
│   ├── requirements.txt
│   └── config/
│       ├── settings.py
│       └── models.yaml  # 可选模型清单
└── web/                 # ① 工具台 v1 静态页
```

> 后端在 `server/` 下，但 `.env` 在**仓库根**，由各部分共用。启动时工作目录保持仓库根，靠 `--app-dir server` 定位应用。

---

## 3. 配置环境变量

### 3.1 创建 `.env`

首次启动若没有 `.env`，`start.command` 会从 `.env.example` 复制一份并退出，提示你填密钥。也可手动：

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

### 3.2 必填项

编辑 `.env`：

```env
DEEPSEEK_API_KEY=sk-你的密钥
```

没有有效 `DEEPSEEK_API_KEY` 时，页面可打开，但「俄文文案」生成会失败。

### 3.3 可选项

```env
HOST=127.0.0.1
PORT=8000
# 前后端不同源时再填，逗号分隔；同源挂载可留空
CORS_ORIGINS=
```

说明：

- `HOST` / `PORT` 由 `server/config/settings.py` 读取；当前 `start.command` 写死为 `127.0.0.1:8000`。若要改端口，需同步改启动命令或脚本。
- 以后若在 `server/config/models.yaml` 中接入其他厂商，按其中的 `api_key_env` 在 `.env` 增加对应变量（例如 `OPENAI_API_KEY`）。

### 3.4 模型清单（可选）

`server/config/models.yaml` 控制页面模型下拉与默认模型，可直接改 `default` 或增删 `models` 条目。密钥只通过 `api_key_env` 引用环境变量名，不要把 Key 写进 yaml。

开发模式下改 yaml 会热重载（见下方启动参数 `--reload-include '*.yaml'`）。

---

## 4. 启动方式

### 方式 A：一键启动（推荐，macOS）

双击 `start.command`，或在终端执行：

```bash
chmod +x start.command   # 仅首次需要
./start.command
```

脚本会：

1. 若不存在 `.venv` → 创建虚拟环境并 `pip install -r server/requirements.txt`
2. 若不存在 `.env` → 从 `.env.example` 复制后退出，请填 Key 后再次启动
3. 启动 Uvicorn：`http://127.0.0.1:8000`

停止：终端里 `Ctrl+C`；若是双击打开的窗口，停止后按回车关闭。

### 方式 B：手动启动

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r server/requirements.txt

# 确保已配置 .env（在仓库根）。始终在仓库根执行，靠 --app-dir 定位应用
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
```

生产或长时间挂机可不加 `--reload`：

```bash
uvicorn main:app --app-dir server --host 127.0.0.1 --port 8000
```

---

## 5. 访问与自检

| 地址 | 用途 |
| --- | --- |
| http://127.0.0.1:8000/ozonSeller.html | 主页面 |
| http://127.0.0.1:8000/api/health | 健康检查，应返回 `{"status":"ok"}` |
| http://127.0.0.1:8000/api/ai/models | 模型列表（需服务已启动） |
| http://127.0.0.1:8000/docs | FastAPI 自动文档（Swagger） |

建议自检顺序：

1. 打开健康检查，确认服务在跑。
2. 打开主页面，确认模型下拉有选项。
3. 在「俄文文案」区粘贴一段采买信息，点生成，确认能返回标题/描述/标签。

---

## 6. 主要 API（当前）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 健康检查 |
| GET | `/api/ai/models` | 可选模型列表 |
| POST | `/api/ai/copy` | 中文采买信息 → 俄文文案 + 中文对照 |

预留路由（尚未实现业务）：`/api/image/*`、`/api/ozon/*`。

文案能力与接口约定详见 [`ai-copy-backend-plan.md`](./ai-copy-backend-plan.md)。

---

## 7. 常见问题

### 端口被占用

报错类似 `Address already in use`：换端口启动，或结束占用进程。

```bash
lsof -i :8000
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8001
```

换端口后页面地址改为对应端口。

### `.env` 已填 Key，文案仍失败

- 确认 Key 无多余空格、引号。
- 确认当前进程是从项目根目录启动（`.env` 在仓库根目录加载）。
- 改 `.env` 后需重启服务（环境变量不会像 yaml 那样热更新）。
- 检查本机能否访问 `https://api.deepseek.com`。

### 双击 `start.command` 一闪而过 / 无权限

```bash
chmod +x start.command
```

若仍被 macOS 拦截，可在终端执行 `./start.command`，或在「系统设置 → 隐私与安全性」中允许。

### 依赖安装失败

先确认 `python3` 可用，再手动：

```bash
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r server/requirements.txt
```

### 只想看静态页、不用 AI

仍建议通过本服务打开页面（同源），避免 `file://` 下部分能力受限。没有 Key 时计价、登记、浏览器水印等本地功能仍可使用。

---

## 8. 安全注意

- `.env` 含密钥，已在 `.gitignore` 中忽略，**不要提交到 Git**。
- 默认绑定 `127.0.0.1`，仅本机可访问。若改为 `0.0.0.0` 对外暴露，请自行做好网络隔离与密钥保护；本仓库当前按本机工具设计，未做登录鉴权。

---

## 9. 日常开发建议

```bash
source .venv/bin/activate
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
```

- 改 Python / yaml：热重载后自动生效（`.env` 除外，需重启）。
- 改 `web/` 下 HTML/JS/CSS：刷新浏览器即可。