# 小红书千帆店铺矩阵工具 —— 项目实施计划书

版本：v1.0　　日期：2026-07-18

---

## 一、项目背景与目标

### 1.1 背景
运营方需要同时管理多个小红书千帆店铺，人工逐条撰写商品笔记、上传发布效率低，且难以规模化。本项目旨在打造一套"内容工厂 + 分发工具"，实现：
- 店铺与商品信息的集中管理
- 商品笔记（文案+图片）的批量 AI 生成
- 多浏览器并行、自动化批量发布

### 1.2 目标产出
1. **本地服务（数据与生成中枢）**：Node.js + SQLite，统一管理数据、代理调用 AI 接口
2. **网页版管理端**：账号管理、商品管理、笔记审核、模型与提示词配置
3. **浏览器插件（执行端）**：可在多个浏览器实例中并行运行，自动在千帆发布页完成选品、上传图片、填写文案并发布

### 1.3 非目标（本期不做）
- 不做云端多人协作（如需团队共享，后续可扩展为局域网/云端部署）
- 不做小红书官方 API 对接（官方未开放笔记发布接口，仍走浏览器自动化路径）
- 不做多平台（抖音/快手等）适配，本期仅聚焦小红书千帆

---

## 二、总体架构

```
                        ┌───────────────────────┐
                        │      本地服务 (Local Service)   │
                        │  Node.js + Express + SQLite     │
                        │  - 数据存储（店铺/商品/笔记/配置）│
                        │  - AI 接口代理（Deepseek/生图）  │
                        │  - 图片文件管理与去重             │
                        │  - 任务队列与认领锁               │
                        └───────────┬───────────┘
                     HTTP(localhost:3000)
            ┌────────────────┴────────────────┐
            │                                  │
   ┌────────▼────────┐              ┌──────────▼──────────┐
   │   网页版管理端     │              │   浏览器插件（可多开）  │
   │ React + Vite      │              │ Manifest V3          │
   │ - 账号/商品/笔记管理│              │ - Content Script 注入 │
   │ - AI 配置/提示词管理│              │ - 任务轮询/认领         │
   └────────────────────┘              │ - 自动化发布执行        │
                                        └───────────────────────┘
```

**关键设计原则**：本地服务是唯一数据源与状态权威，网页版和插件都是无状态客户端，通过 HTTP API 读写数据，天然支持多浏览器并行而不冲突。

---

## 三、技术栈选型

| 层 | 技术 | 说明 |
|---|---|---|
| 本地服务 | Node.js 18+ / Express | 轻量、易打包，开发效率高 |
| 数据库 | SQLite（better-sqlite3） | 单文件数据库，免安装，适合本地化部署 |
| 网页版前端 | React + Vite + TailwindCSS | 组件化开发快，生态成熟 |
| 状态管理 | Zustand 或 React Query | React Query 处理服务端数据缓存更合适 |
| 插件框架 | Chrome Extension Manifest V3 | Service Worker + Content Script |
| 图片处理 | Sharp（服务端） | 用于压缩、格式转换、生成缩略图 |
| 图片去重 | pHash（sharp-phash 或自实现） | 感知哈希，判断生成图片相似度 |
| 打包分发 | Electron（可选，做成桌面壳） | 让本地服务"点击即启动"，非技术用户更友好 |
| AI 文案 | Deepseek API | 用户自行配置 Key/模型 |
| AI 生图 | 用户配置的生图模型（如 Agens/其他文生图API） | 服务端统一代理转发，避免 Key 暴露给插件/前端 |

---

## 四、数据库设计（SQLite）

### 4.1 shops（店铺表）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | TEXT PK | UUID |
| shop_id | TEXT | 小红书店铺ID，唯一索引 |
| shop_name | TEXT | 店铺名称 |
| remark | TEXT | 备注 |
| created_at | DATETIME | |
| updated_at | DATETIME | |

### 4.2 products（商品表）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | TEXT PK | UUID |
| shop_id | TEXT FK | 关联 shops.id |
| title | TEXT | 商品标题 |
| status | TEXT | pending / generating / generated |
| created_at / updated_at | DATETIME | |

### 4.3 notes（笔记表，核心表）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | TEXT PK | UUID |
| product_id | TEXT FK | 关联 products.id |
| shop_id | TEXT | 冗余字段，便于按店铺过滤任务 |
| title | TEXT | 笔记标题 |
| content | TEXT | 正文 |
| topics | TEXT(JSON数组) | 热搜话题 |
| image_prompt | TEXT | 生图提示词 |
| image_paths | TEXT(JSON数组) | 生成图片相对路径 |
| status | TEXT | draft(待审核) / approved(已通过) / publishing(发布中) / published(已发布) / rejected / failed |
| worker_id | TEXT | 认领任务的浏览器实例标识（发布中状态使用） |
| claimed_at | DATETIME | 认领时间，用于超时释放 |
| published_at | DATETIME | 实际发布时间 |
| created_at / updated_at | DATETIME | |

### 4.4 configs（配置表，Key-Value）
| key | value(JSON) |
|---|---|
| deepseek_config | { apiKey, baseUrl, model, temperature } |
| image_config | { provider, apiKey, baseUrl, defaultCount, size } |
| prompt_templates | { title: "...", content: "...", image: "..." } |

### 4.5 图片文件目录规范
```
/data/images/{product_id}/{note_id}_{seq}.png
```
使用 `product_id` 而非商品标题命名文件夹，避免特殊字符/重名问题；标题作为元数据存于 notes 表。

---

## 五、本地服务 API 设计

| 方法 | 路径 | 说明 |
|---|---|---|
| GET/POST/PUT/DELETE | `/api/shops` | 店铺 CRUD |
| POST | `/api/shops/import` | 批量导入店铺（CSV/Excel） |
| GET | `/api/shops/export` | 导出店铺列表 |
| GET/POST/PUT/DELETE | `/api/products` | 商品 CRUD |
| POST | `/api/products/import` | 批量导入商品标题 |
| POST | `/api/notes/generate` | 批量触发生成任务（文案+图片） |
| GET | `/api/notes` | 笔记列表，支持按店铺/商品/状态筛选 |
| POST | `/api/notes/:id/rewrite` | 重新生成单条笔记 |
| POST | `/api/notes/:id/approve` | 审核通过 |
| DELETE | `/api/notes/:id` | 删除笔记 |
| GET | `/api/notes/next?shop_id=` | 插件拉取该店铺下一条待发布任务（内部执行认领事务） |
| POST | `/api/notes/:id/complete` | 插件回调：发布成功 |
| POST | `/api/notes/:id/fail` | 插件回调：发布失败，记录原因 |
| GET | `/api/images/:productId/:filename` | 静态图片资源 |
| GET/PUT | `/api/configs/:key` | 读写配置（Deepseek/生图/提示词） |

**任务认领事务（防并发抢单）**：
```sql
UPDATE notes
SET status = 'publishing', worker_id = ?, claimed_at = CURRENT_TIMESTAMP
WHERE id = (
  SELECT id FROM notes
  WHERE shop_id = ? AND status = 'approved'
  ORDER BY created_at ASC LIMIT 1
)
RETURNING *;
```
SQLite 单文件写锁天然保证该操作串行执行，多个浏览器同时请求也不会拿到同一条。同时启动一个定时任务：`publishing` 状态超过 10 分钟未回调，自动释放回 `approved`，避免浏览器崩溃导致任务卡死。

---

## 六、网页版功能详细设计

### 6.1 账号（店铺）管理页
- 列表字段：店铺ID、店铺名称、备注、创建时间、更新时间、操作
- 支持搜索（按店铺名/ID模糊匹配）
- 新增/编辑：弹窗表单
- 导入：上传 CSV/Excel，字段映射后批量写入，支持重复店铺ID去重提示
- 导出：一键导出当前列表为 CSV

### 6.2 商品管理页
- 按店铺筛选 + 标题搜索
- 批量导入商品标题（每行一个，或 CSV 单列）
- 列表字段：ID、所属店铺、商品标题、状态、更新时间、操作
- **批量生成笔记**：
  1. 勾选商品 → 点击"批量生成"
  2. 弹窗选择：生成图片张数（默认取全局配置，可覆盖）、使用的提示词模板
  3. 前端调用 `/api/notes/generate`，服务端异步串行处理（避免并发打爆 AI 接口配额），生成完成后笔记进入"待审核"
  4. 页面展示生成进度条（轮询任务状态或用 SSE 推送）

### 6.3 笔记审核页（对应"创建笔记功能"）
- 筛选：店铺名称、商品标题、状态
- 列表字段：店铺名称、标题、生图提示词、正文内容（摘要）、热搜话题、操作
- 操作：
  - **预览图片**：弹窗展示该笔记生成的所有图片
  - **重写**：重新调用生成接口，覆盖当前文案/图片（保留历史版本可选）
  - **通过**：状态 draft → approved
  - **删除**：软删除或直接物理删除（含清理对应图片文件）

### 6.4 Deepseek 配置页
- 表单：API Key、Base URL、模型名、温度等参数
- "测试连接"按钮，调用一次简单请求验证配置有效性

### 6.5 生图模型配置页
- 表单：服务商、API Key、Base URL、默认生成张数、图片尺寸
- 全局默认张数会被批量生成时的临时选择覆盖

### 6.6 提示词管理页
- 三类模板：标题生成提示词、正文内容提示词、小红书生图提示词
- 支持变量占位符，如 `{商品标题}`、`{店铺名}`，生成时自动替换
- 可维护多套模板并设置"当前启用"版本

---

## 七、浏览器插件详细设计

### 7.1 插件结构（Manifest V3）
```
extension/
├── manifest.json
├── background.js       // Service Worker，负责与本地服务通信、任务调度
├── content_scripts/
│   └── qianfan_publish.js   // 注入千帆发布页，执行DOM自动化
├── popup/
│   └── popup.html/js   // 插件面板：配置 shop_id、启动/暂停、查看进度
└── options/
    └── options.html/js // 可选：配置本地服务地址（默认 localhost:3000）
```

### 7.2 核心流程
1. **配置绑定**：用户在插件 popup 中为当前浏览器/账号绑定 `shop_id`（对应网页版店铺管理中的店铺）
2. **任务轮询**：background.js 定时（如每 15~30 秒，含随机抖动）向本地服务请求 `GET /api/notes/next?shop_id=xxx`
3. **执行发布**：
   - 若在千帆发布页，content script 收到任务后：
     a. 在商品搜索框输入笔记对应商品标题，触发搜索
     b. 点击对应商品进入发布
     c. 通过 `DataTransfer` 构造 `FileList`，模拟文件选择注入图片
     d. 填写正文、话题（用 React/Vue 受控组件时需触发原生 `input`/`change` 事件，不能只赋值 `.value`）
     e. 点击发布按钮
4. **回调状态**：
   - 成功：`POST /api/notes/:id/complete`
   - 失败（如商品未找到、上传超时）：`POST /api/notes/:id/fail`，附带错误信息，便于人工在网页版排查
5. **防风控策略**：
   - 每次发布间隔随机 30~90 秒
   - 单账号单日发布上限（可在插件配置中设置，如 20 条/天），达到后自动停止轮询
   - 出现连续失败（如 3 次以上）自动暂停并提示用户人工检查

### 7.3 DOM 自动化技术要点
- 发布页面结构需要人工先用浏览器开发者工具抓取实际选择器（本文档暂不假设具体 DOM，需在开发阶段第三阶段实测确认）
- 文件上传优先尝试标准 `<input type="file">` + DataTransfer 注入；如遇到自定义上传组件（拖拽区域），需要模拟 `dragenter/dragover/drop` 事件序列
- 富文本编辑器（正文框）若为 contenteditable，需要用 `document.execCommand` 或直接派发 `InputEvent` 写入内容，并触发对应框架的状态同步

---

## 八、开发阶段与里程碑

| 阶段 | 内容 | 产出物 | 预估周期 |
|---|---|---|---|
| 阶段一 | 本地服务骨架 + 数据库表 + 基础CRUD API | 可运行的 Express 服务 | 3-5 天 |
| 阶段二 | 网页版：账号管理 + 商品管理页面 | 可用的管理界面 | 5-7 天 |
| 阶段三 | 接入 Deepseek + 生图 API，打通"批量生成笔记"全流程 | 生成功能可用，含去重逻辑 | 5-7 天 |
| 阶段四 | 笔记审核页 + 提示词/模型配置页 | 网页版功能完整 | 3-4 天 |
| 阶段五 | 插件基础框架 + 单条笔记手动发布验证千帆DOM结构 | 可发布单条笔记的插件原型 | 5-7 天（含DOM调试，具体视千帆页面复杂度） |
| 阶段六 | 插件任务轮询 + 认领机制 + 批量发布 + 防风控策略 | 完整插件，支持多浏览器并行 | 5-7 天 |
| 阶段七 | 联调、异常处理（网络失败/DOM变化容错）、日志与监控 | 稳定可用版本 | 3-5 天 |

**总计预估**：约 30-42 个工作日（单人开发，实际视千帆页面自动化难度浮动较大，建议阶段五留足调试缓冲）。

---

## 九、风险与应对

| 风险 | 影响 | 应对措施 |
|---|---|---|
| 千帆页面 DOM 结构变化 | 插件自动化失效 | Content script 中的选择器集中管理，便于快速修改；增加"选择器失效告警"机制 |
| 平台风控（频繁发布被限流/封号） | 店铺受损 | 随机延时、单日上限、失败自动暂停；建议先小规模试运行观察风控阈值 |
| AI 生成内容质量不稳定 | 笔记需要人工反复重写 | 保留"待审核"环节，人工把关；持续优化提示词模板 |
| 图片生成重复/相似度高 | 内容同质化，可能被平台判定为重复发布 | pHash 去重 + 提示词中加入随机风格变量 |
| API Key 泄露 | 账号安全风险 | Key 只存本地服务端，前端和插件不直接持有；本地服务对本机 localhost 开放，不对外暴露端口 |
| 本地服务未启动导致插件/网页版报错 | 影响使用体验 | 网页版和插件都加入"服务连接状态"检测与友好提示 |

---

## 十、后续可扩展方向（本期不做，仅记录）
- 支持云端部署 + 多人协作（需要引入用户权限体系，SQLite 换成 Postgres）
- 支持发布数据回流（笔记浏览量/互动数据抓取分析）
- 支持多平台适配（抖音、快手等类似发布场景）
- Electron 打包成一体化桌面客户端，进一步降低部署门槛

---

*本计划书为项目启动阶段的设计文档，具体接口字段、页面细节可在开发过程中根据实际情况微调。*