# panqie

**Repository Path**: space_imagination/panqie

## Basic Information

- **Project Name**: panqie
- **Description**: 自动化助手
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 番茄小说自动发布助手 - 技术架构文档

本文档旨在说明项目的技术实现细节，供开发人员维护和扩展参考。

## 1. 技术栈

- **前端 (Extension)**:
  - HTML5 / CSS3 (原生开发，无构建工具)
  - JavaScript (ES6+)
  - Chrome Extension Manifest V3
- **后端 (Local Server)**:
  - Python 3.8+
  - FastAPI (Web 框架)
  - SQLite (轻量级数据库)
  - Uvicorn (ASGI 服务器)

## 2. 系统架构

系统采用 **C/S 架构** 的变体。由于浏览器沙箱限制，复杂的文件处理和持久化存储由本地 Python 后端承担，而浏览器插件负责 UI 交互和页面自动化。

```mermaid
graph LR
    User[用户] -->|上传 TXT| Dashboard(插件前端)
    Dashboard -->|Multipart POST| Server(Python 后端)
    Server -->|Regex 切分| Logic[切分逻辑]
    Logic -->|存储| SQLite[(SQLite 数据库)]
    Server -->|JSON 响应| Dashboard
    
    Dashboard -->|启动任务| Background(Service Worker)
    Background -->|状态同步| Storage(Chrome Storage)
    
    Dashboard -->|打开标签页| Page[番茄作家后台]
    ContentScript(content.js) -->|DOM 操作| Page
    ContentScript -->|读取配置| Storage
```

## 3. 核心模块说明

### 3.1 后端服务 (`server.py`)

- **功能**: 
  - 提供文件上传接口 `/api/split`。
  - 处理 TXT 编码检测 (`chardet`) 和换行符标准化。
  - 执行正则表达式切分章节。
  - 将切分结果持久化到 `panqie_data.db`。
  - 提供章节的增删改查 (CRUD) 接口。

- **关键函数**:
  - `cn2an(cn)`: 将中文数字（一千零一）转换为阿拉伯数字，用于排序。
  - `smart_decode(bytes)`: 智能检测文件编码（UTF-8, GBK 等）。

### 3.2 插件前端 (`dashboard.html` / `.js`)

- **功能**:
  - 任务可视化管理界面。
  - 轮询后端接口同步状态。
  - 写入 `chrome.storage.local` 以驱动 Content Script。
  
- **状态管理**:
  - 不需要复杂的 Vue/React，使用原生 JS 原型对象管理 `chapters` 数组。
  - `isPublishing` 旗标控制全局流水线状态。

### 3.3 自动化核心 (`content.js` & `fanqie-handler.js`)

- **`content.js` (调度器)**:
  - 驻留在番茄小说页面。
  - 监听 `chrome.storage.local` 中的 `publishData` 变化。
  - 实现状态机：`pending` -> `navigating` -> `processing` -> `finished`。
  - 具备重试机制 (`retryAction`)，应对网络卡顿。

- **`fanqie-handler.js` (执行器)**:
  - 封装所有 DOM 操作。
  - **React 兼容性**: 番茄后台使用 React 构建，直接修改 `input.value` 无效。必须通过 `Object.getOwnPropertyDescriptor` 获取原生 setter 并触发 `input` 事件，才能让 React 状态同步。
  - **选择器策略**: 采用多重兜底策略（Class 选择器 -> 属性选择器 -> 文本内容模糊匹配），提高对番茄前端更新的鲁棒性。

## 4. 数据库设计

数据库文件：`panqie_data.db`

### `novels` 表 (小说元数据)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER PK | 自增主键 |
| hash | TEXT | 文件 MD5，防止重复解析 |
| filename | TEXT | 原始文件名 |

### `chapters` 表 (章节详情)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER PK | 自增主键 |
| novel_id | INTEGER FK | 关联 novels.id |
| chapter_index | INTEGER | 排序索引 |
| title | TEXT | 完整标题 (用于发布) |
| content | TEXT | 正文内容 |
| status | TEXT | `waiting`, `processing`, `finished`, `error` |

## 5. 自动化流程逻辑

1. **任务分发**: 
   - Dashboard 将当前要发布的章节信息写入 `chrome.storage.local.publishData`。
   - 打开/激活番茄作家后台标签页。

2. **页面注入**:
   - `content.js` 检测到页面加载。
   - 识别当前是 "首页" 还是 "编辑器页"。
   - 如果是首页，点击 "创建新章节"。
   - 如果是编辑器页，调用 `FanqieSite.fillContent` 等方法注入数据。

3. **操作模拟**:
   - 模拟点击 "下一步"。
   - 处理可能出现的 "风险检测" 弹窗。
   - 勾选用户的 AI 声明选项。
   - 点击最终 "发布" 按钮。

4. **反馈闭环**:
   - 操作成功后，Content Script 更新 Storage 状态为 `finished`。
   - Dashboard 轮询检测到 `finished`，并在后端数据库标记该章状态，然后开始下一章。

## 6. 开发规范

- **异常处理**: 所有 DOM 操作均需包裹在 `try-catch` 或重试逻辑中。
- **编码规范**: Python 遵循 PEP8，JS 使用 ES6+ 语法。
- **安全性**: 
  - 后端仅监听 `127.0.0.1`。
  - 数据库操作使用参数化查询防止 SQL 注入。

---
*文档更新日期: 2025-12-21*