feat:助手首次改版

2026-08-07 17:34:24 +08:00
parent f88b424301
commit 2083ad1954
29 changed files with 3817 additions and 0 deletions
@@ -0,0 +1,457 @@
+# Ozon Seller Kit：俄文文案生成方案
+
+> 状态：方案稿  
+> 日期：2026-08-07  
+> 后端语言：Python（FastAPI）  
+> 范围：先落地「中文采买信息 → 俄文标题 / 描述 / 标签 + 中文对照」；图片白底、Ozon 上传作为后续阶段预留扩展位。
+
+---
+
+## 1. 背景与目标
+
+当前项目原为根目录散落的纯静态页面工具（`ozonSeller.html` + `js/app.js`），可直接 `file://` 打开，已具备：
+
+- 计价 / 录入 / 上品登记表 / 组合码导出
+- 浏览器 Canvas 水印
+
+后续需要接入大模型 API。浏览器直连 DeepSeek 会遇到 CORS，且 API Key 不能放前端，因此引入 **本地 Python 服务** 做代理与业务编排；仓库采用一体扁平结构，静态页放在 `web/`。
+
+本阶段目标：
+
+1. 在现有页面增加「俄文文案」独立区块。
+2. 用户在单个输入框粘贴采买站商品信息（如有本次特殊要求可直接写在后面），点击生成。
+3. 后端调用 DeepSeek，返回俄文标题 / 描述 / 标签，并同步中文对照。
+4. 前端可编辑、一键复制；可选回填左侧「商品名」。
+
+---
+
+## 2. 总体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  浏览器                                                      │
+│  web/ozonSeller.html + js/ + css/                            │
+│  http://127.0.0.1:8000/ozonSeller.html（由 FastAPI 托管）     │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ fetch JSON
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  同仓 FastAPI（main.py）                                     │
+│  - 挂载 web/ 静态资源                                         │
+│  - /api/ai/copy 文案生成                                      │
+│  - （预留）/api/image/*  /api/ozon/*                           │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ HTTPS + Bearer Key
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  DeepSeek API（OpenAI 兼容）                                  │
+│  https://api.deepseek.com                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+原则：
+
+- **密钥只放 `.env`**（不进 git）；**模型清单放 `config/models.yaml`**（可入库）。
+- **前端只请求本机 API**，不直连大模型、不接触密钥。
+- **一体扁平结构**：不拆 `frontend/` / `backend/`；Python 入口在仓库根，静态资源独占 `web/`。
+- **现有静态能力尽量保留**；服务端先做薄代理 + Prompt 编排。
+- 本地开发统一用 `http://127.0.0.1`，不再依赖 `file://`（`file://` 无法稳定调后端）。
+
+---
+
+## 3. 页面落位（前端交互）
+
+### 3.1 插入位置
+
+在 **计价双栏区域之后**、**上品登记表之前**，新增全宽区块「俄文文案」。
+
+页面顺序变为：
+
+1. Header（外链 + 汇率）
+2. 计价输入 + 计价结果
+3. **俄文文案（新）**
+4. 上品登记表
+5. 上品组合码
+6. 图片水印
+
+### 3.2 区块结构
+
+| 区域 | 内容 |
+|------|------|
+| 左侧输入 | 商品资料（单个大文本，事实与本次要求写在一起）、带入当前商品名/型号（只读提示） |
+| 右侧结果 | 标题 / 描述 / 标签：俄文主展示 + 中文对照；可编辑；各字段复制按钮 |
+| 操作 | 「生成文案」「重新生成」；可选「中文标题填入商品名」 |
+
+### 3.3 与现有字段关系
+
+- 左侧 `productName` / SKU / 型号：仍服务计价与登记，不改成俄文主编辑区。
+- 文案结果独立保存于本区块 DOM / 内存；后续接 Ozon 上传时再读取俄文字段。
+- 「填入商品名」仅把生成的 **中文标题** 写入 `#productName`。
+
+---
+
+## 4. 仓库目录与代码放置
+
+采用 **一体扁平结构**（方案 B）：不拆 `frontend/` / `backend/`。Python 入口与配置在仓库根；静态页独占 `web/`，避免挂载时误暴露源码。
+
+```
+ozon-seller-kit/
+├── docs/
+│   └── ai-copy-backend-plan.md      # 本方案
+├── main.py                          # FastAPI 入口、CORS、挂载 web/
+├── config/
+│   ├── settings.py                  # .env 密钥与运行参数
+│   └── models.yaml                  # 模型目录（可入库，不含密钥）
+├── api/
+│   ├── ai.py                        # /api/ai/*
+│   ├── image.py                     # （预留）/api/image/*
+│   └── ozon.py                      # （预留）/api/ozon/*
+├── services/
+│   ├── models_catalog.py            # 读取 models.yaml、解析密钥
+│   ├── deepseek.py                  # OpenAI 兼容 chat 调用
+│   └── prompts/
+│       └── copy_ru.py
+├── schemas/
+│   └── copy.py
+├── web/
+│   ├── ozonSeller.html
+│   ├── css/
+│   ├── imgs/
+│   └── js/
+│       ├── app.js
+│       ├── ai-copy.js
+│       ├── watermark-data.js
+│       └── tailwind.config.js
+├── requirements.txt
+├── .env.example
+├── start.command
+├── .gitignore
+└── README.md
+```
+
+### 4.1 放置约定
+
+| 内容 | 放哪里 | 说明 |
+|------|--------|------|
+| 页面结构 | `web/ozonSeller.html` | 文案区 DOM、模型下拉 |
+| 文案交互 | `web/js/ai-copy.js` | 拉模型列表、带 model 调生成 |
+| 模型目录 | `config/models.yaml` | id/label/base_url/api_key_env；可入库 |
+| 密钥 | 根目录 `.env` | 仅密钥与 HOST/PORT；不入库 |
+| API 路由 | `api/` | 按业务拆文件 |
+| LLM 调用 | `services/deepseek.py` | 按 ModelSpec 调 OpenAI 兼容接口 |
+| Prompt | `services/prompts/` | 方便单独迭代文案质量 |
+
+### 4.2 静态资源如何被访问
+
+由 FastAPI 挂载 `web/`，一个进程同时提供页面和 API：
+
+```python
+# main.py 示意
+WEB_DIR = Path(__file__).resolve().parent / "web"
+app.mount("/", StaticFiles(directory=WEB_DIR, html=True), name="web")
+```
+
+注意：静态挂载应放在 `/api` 路由注册之后，避免吞掉 API 路径。
+
+访问地址：
+
+- 页面：`http://127.0.0.1:8000/ozonSeller.html`
+- API：`http://127.0.0.1:8000/api/ai/copy`
+
+前端请求基址：
+
+```js
+const API_BASE = window.location.origin; // 同域，无 CORS 烦恼
+```
+
+若暂时用 VS Code Live Server 单独打开 `web/`、Python 另开端口，则需开 CORS，前端写死 `API_BASE = 'http://127.0.0.1:8000'`。**首选同域挂载方案。**
+
+---
+
+## 5. 后端设计
+
+### 5.1 技术选型
+
+| 项 | 选择 | 原因 |
+|----|------|------|
+| Web 框架 | FastAPI | 轻量、类型清晰、异步友好 |
+| HTTP 客户端 | `httpx` | 调 OpenAI 兼容接口 |
+| 密钥/运行参数 | `pydantic-settings` + `.env` | 只放秘密与端口 |
+| 模型目录 | `config/models.yaml` | 可扩展多模型/多厂商 |
+| 运行 | `uvicorn` | 标准 ASGI |
+
+### 5.2 核心依赖
+
+```text
+fastapi
+uvicorn[standard]
+httpx
+pydantic-settings
+python-dotenv
+PyYAML
+```
+
+### 5.3 配置分层（模型目录 + 密钥）
+
+**原则：**
+
+- `config/models.yaml`：模型清单（id、显示名、api_model、base_url、api_key_env），**可入库，不含密钥**。
+- `.env`：只放密钥与 HOST/PORT 等运行参数，**不入库**。
+- 前端通过 `GET /api/ai/models` 获取可选项，**永不接触密钥**。
+
+`config/models.yaml` 示例：
+
+```yaml
+default: deepseek-v4-flash
+models:
+  - id: deepseek-v4-flash
+    label: Flash（快/省）
+    provider: deepseek
+    api_model: deepseek-v4-flash
+    base_url: https://api.deepseek.com
+    api_key_env: DEEPSEEK_API_KEY
+  - id: deepseek-v4-pro
+    label: Pro（质量更好）
+    provider: deepseek
+    api_model: deepseek-v4-pro
+    base_url: https://api.deepseek.com
+    api_key_env: DEEPSEEK_API_KEY
+```
+
+`.env.example`：
+
+```env
+DEEPSEEK_API_KEY=sk-xxxx
+# OPENAI_API_KEY=sk-xxxx   # 若 models.yaml 引用了该变量再配置
+HOST=127.0.0.1
+PORT=8000
+CORS_ORIGINS=
+```
+
+同一厂商可共用一把 Key；按「账号/厂商」分 Key，不必每个模型名硬拆一把。
+
+### 5.4 API 约定
+
+#### `GET /api/ai/models`
+
+```json
+{
+  "default": "deepseek-v4-flash",
+  "models": [
+    { "id": "deepseek-v4-flash", "label": "Flash（快/省）" },
+    { "id": "deepseek-v4-pro", "label": "Pro（质量更好）" }
+  ]
+}
+```
+
+#### `POST /api/ai/copy`
+
+**请求：**
+
+```json
+{
+  "source_text": "从采买站粘贴的中文商品信息，可在末尾附带本次生成要求……",
+  "product_name": "可选，当前表单商品名",
+  "model_code": "可选，型号",
+  "model": "deepseek-v4-pro"
+}
+```
+
+- `model` 可选；空则用 `models.yaml` 的 `default`。
+- 不在白名单 → `400`。
+
+**成功响应：**
+
+```json
+{
+  "titles_ru": ["……", "……"],
+  "titles_zh": ["……", "……"],
+  "description_ru": "……",
+  "description_zh": "……",
+  "tags_ru": ["……", "……"],
+  "tags_zh": ["……", "……"],
+  "model": "deepseek-v4-pro",
+  "usage": {
+    "prompt_tokens": 0,
+    "completion_tokens": 0
+  }
+}
+```
+
+校验规则（后端）：
+
+- `source_text` 必填，去空白后长度 ≥ 10。
+- `model` 必须属于 `models.yaml`（或空=默认）。
+- 要求模型输出 **严格 JSON**，解析失败则重试 1 次或返回 502。
+
+### 5.5 Prompt 策略（概要）
+
+System 角色职责：
+
+- 面向俄罗斯消费者和 Ozon 搜索生成完整商品卡，而非把采买资料压缩成摘要。
+- 优先级固定为：事实准确 > 俄语自然 > 信息完整与转化力 > 关键词覆盖。
+- 标题一次输出 2 个互补方案（`titles_ru` / `titles_zh`），以核心品类词开头，前 30 字符覆盖关键属性，长度 60～90 字符，去除年份、新款、爆款等噪声。
+- 描述采用 `Описание товара / Характеристики / Преимущества` 三段结构，原文明确提到配件时追加 `Комплектация`；资料足够时约 900～1500 个俄文字符。
+- 允许将已有事实改写成温和的使用利益点，但禁止补充原文没有的结构、认证、安全结论、适用年龄、开口位置、礼物节日等硬信息。
+- 对常见行业词做翻译约束，例如“搪胶”优先译为 `винил (ПВХ)`，不擅自译为天然橡胶 `каучук`。
+- 标签输出 10～15 个；每个俄文标签只允许一个单词，不带 `#`，中俄数组按索引一一对应。
+- 中文标题和描述保持与最终俄文相同的事实与段落结构，便于逐项核对。
+- 调用参数使用较稳定的 `temperature=0.45`，并给描述预留充足输出长度。
+
+User 内容拼接：
+
+```
+<当前商品名>…</当前商品名>
+<型号>…</型号>
+<商品资料>
+…
+</商品资料>
+```
+
+输入用边界标签隔离，避免把采买文本中的内容误当作系统指令。实现放在
+`services/prompts/copy_ru.py`，便于单独调优，不必改路由。
+
+### 5.6 服务分层
+
+```
+api/ai.py
+  GET  /models → models_catalog.list_model_options()
+  POST /copy   → deepseek.generate_copy(req)
+
+services/models_catalog.py
+  → 读 models.yaml
+  → 白名单校验
+  → 按 api_key_env 从环境变量取密钥
+
+services/deepseek.py
+  → 组装 messages
+  → 用 ModelSpec.base_url / api_model 调 /chat/completions
+  → 解析 JSON → CopyResponse
+```
+
+---
+
+## 6. 前端设计
+
+### 6.1 DOM 落点
+
+在 `web/ozonSeller.html` 中，计价 `grid` 结束后、上品登记表 `mt-8` 卡片前插入文案区。
+
+模型下拉位于「生成文案」按钮上方；区块标题右侧提供折叠按钮。
+
+| 元素 | id |
+|------|----|
+| 折叠按钮 / 内容区 | `aiToggleBtn` / `aiCopyBody` |
+| 模型下拉 | `aiModelSelect` |
+| 商品资料 | `aiSourceText` |
+| 生成按钮 | `aiGenerateBtn` |
+| 推荐标题容器 | `aiTitlesContainer` |
+| 描述俄/中 | `aiDescRu` / `aiDescZh` |
+| 标签容器 | `aiTagsContainer` |
+| 状态提示 | `aiCopyStatus` |
+
+结果区为只读展示：标题渲染成卡片（含复制俄文、填入商品名），描述用等高只读文本块保留换行，标签渲染成「俄文｜中文」芯片，点击即复制俄文。需要调整文案时通过「生成要求」重新生成。
+
+### 6.2 JS 职责拆分
+
+`web/js/ai-copy.js`：
+
+- 启动时 `GET /api/ai/models` 填充下拉；`localStorage` 记住上次选择
+- 收集输入（含 `#productName`、`#modelCode`、选中的 `model`）
+- `POST /api/ai/copy`
+- 渲染标题卡片、描述文本块、标签芯片，并处理 loading / 错误态
+- 复制（标题、描述、单个标签、全部标签）与「填入商品名」
+- 折叠 / 展开整个文案区
+
+`web/js/app.js`：保持计价、历史、水印。
+
+### 6.3 交互细节
+
+- 生成中：按钮 disabled +「生成中…」。
+- 失败：在 `aiCopyStatus` 显示可读错误。
+- 不在前端存 API Key；模型列表不硬编码（以后加模型只改 `models.yaml`）。
+
+---
+
+## 7. 本地运行方式
+
+### 7.1 一次性准备
+
+在仓库根目录：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+# 编辑 .env，填入 DEEPSEEK_API_KEY
+```
+
+### 7.2 启动
+
+```bash
+source .venv/bin/activate
+uvicorn main:app --reload --host 127.0.0.1 --port 8000
+```
+
+浏览器打开：
+
+`http://127.0.0.1:8000/ozonSeller.html`
+
+### 7.3 `.gitignore` 建议追加
+
+```gitignore
+.venv/
+.env
+**/__pycache__/
+*.pyc
+.DS_Store
+web/ozonSeller.html.bak
+```
+
+---
+
+## 8. 分阶段落地
+
+### Phase 1（本方案当前实施范围）
+
+- [x] 静态资源收拢到 `web/`
+- [x] 一体扁平：`main.py` / `api/` / `services/` / `schemas/`
+- [x] 实现 `POST /api/ai/copy`
+- [x] 页面插入「俄文文案」区块
+- [x] `web/js/ai-copy.js` 对接 API
+- [x] FastAPI 挂载 `web/`，同域静态托管可本地跑通
+- [x] 根目录 `README.md` / `start.command`
+- [x] `config/models.yaml` 模型目录 + `GET /api/ai/models` + 前端下拉切换
+
+### Phase 2（图片）
+
+- `POST /api/image/process`：白底、服务端水印（可选保留前端水印）
+- 预留图生图代理接口
+
+### Phase 3（Ozon）
+
+- `POST /api/ozon/products`：读取文案区俄文字段 + 计价结果上传
+- Client-Id / Api-Key 仅存根目录 `.env`
+
+---
+
+## 9. 风险与约束
+
+| 点 | 说明 |
+|----|------|
+| 不能用 `file://` 调后端 | 需通过 `http://127.0.0.1:8000` 打开页面 |
+| Prompt 质量 | 俄文 listing 需多轮样本调优；Prompt 独立文件便于改 |
+| 模型偶发非 JSON | 后端要做解析容错与明确报错 |
+| Key 泄露 | `.env` 不入库；勿把 Key 打进前端或日志 |
+| 费用 | 前端防连点；可后续加简易速率限制 |
+
+---
+
+## 10. 结论
+
+- **目录**：一体扁平；Python 在仓库根，静态页在 `web/`。
+- **模型配置**：清单在 `config/models.yaml`，密钥在 `.env`；前端只消费 `/api/ai/models`。
+- **服务**：FastAPI（`main.py`）挂载 `web/` 并提供 `/api/*`。
+- **前端**：俄文文案区支持模型下拉；逻辑在 `web/js/ai-copy.js`。
+- **扩展**：`api/image.py`、`api/ozon.py` 预留；加模型只需改 yaml + 对应密钥环境变量。
@@ -0,0 +1,213 @@
+# 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/
+├── main.py              # FastAPI 入口
+├── start.command        # macOS 一键启动
+├── requirements.txt
+├── .env.example         # 环境变量模板
+├── .env                 # 本地密钥（勿提交）
+├── config/
+│   ├── settings.py
+│   └── models.yaml      # 可选模型清单
+└── web/                 # 前端静态页
+```
+
+---
+
+## 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` 由 `config/settings.py` 读取；当前 `start.command` 写死为 `127.0.0.1:8000`。若要改端口，需同步改启动命令或脚本。
+- 以后若在 `config/models.yaml` 中接入其他厂商，按其中的 `api_key_env` 在 `.env` 增加对应变量（例如 `OPENAI_API_KEY`）。
+
+### 3.4 模型清单（可选）
+
+`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 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 requirements.txt
+
+# 确保已配置 .env
+uvicorn main:app --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
+```
+
+生产或长时间挂机可不加 `--reload`：
+
+```bash
+uvicorn main:app --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 --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 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 --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
+```
+
+- 改 Python / yaml：热重载后自动生效（`.env` 除外，需重启）。
+- 改 `web/` 下 HTML/JS/CSS：刷新浏览器即可。