# WEBCOLLECTOR

**Repository Path**: syq0404/webcollector

## Basic Information

- **Project Name**: WEBCOLLECTOR
- **Description**: 专为 OA/ERP/政务内网打造的网页数据智能录入助手。可视化鼠标点选吸取字段，Alt+S 一键快速追加到本地 Excel，支持智能防重、多Tab穿透与TSV表格一键复制，彻底告别繁琐人工录入！
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 数据录入, 网页转Excel, 办公自动化, 油猴脚本, Python

## README

# 📋 网页数据智能录入助手 (Excel 版) - 交付与使用全指南

> **核心价值**：在浏览器中浏览业务系统、OA 或管理后台时，一键或按快捷键 `Alt + S`，即可将当前页面/弹窗详情（如姓名、部门、工号、电话等）按方案自动追加写入到本地 Excel 文件中。

---

## 目录
1. [📦 交付文件清单（发给他人时包含哪些文件）](#1-交付文件清单)
2. [⚙️ 运行环境准备（零基础保姆级教程）](#2-运行环境准备)
3. [🚀 极速上手 3 步曲](#3-极速上手-3-步曲)
4. [💡 进阶使用技巧](#4-进阶使用技巧)
5. [🛑 服务的关闭与释放](#5-服务的关闭与释放)
6. [❓ 常见问题排查 (FAQ)](#6-常见问题排查-faq)

---

### 1. 交付文件清单

发给同事/他人使用时，只需将本文件夹中以下核心文件打包为一个 `.zip` 压缩包即可：

| 文件名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **`start.bat`** | 启动脚本 | **一键启动**本地后台服务（自带 Python 环境自检与依赖自动安装） |
| **`stop.bat`** | 停止脚本 | **一键彻底关闭**本地后台服务并释放网络端口 |
| **`server.py`** | 核心服务 | 本地 Python 服务端（负责接收数据并安全写入 Excel 表格） |
| **`web_collector.user.js`** | 前端脚本 | 浏览器插件核心代码（吸取、预览、录入面板） |
| **`bookmarklet.txt`** | 浏览器书签 | 零安装书签代码，复制到书签栏即可使用 |
| **`rules.json`** | 方案配置 | 包含预先调优好的现成配置方案（对方解压即用，无需重新配置） |
| **`README.md`** | 使用说明 | 本完整说明文档 |
| **`test_page.html`** | 演练网页 | 本地模拟人员卡片测试页，用于初次熟悉功能 |

> ⚠️ **敏感与临时文件提示**：
> 请**勿**将实际生成的 `*.xlsx` 数据表格、`__pycache__` 缓存目录或 `WORK_LOG.md` 等内部文件发给外部人员。

---

### 2. 运行环境准备

本工具基于极简轻量的 Python 3 本地服务构建，只需满足基础 Python 运行环境：

#### 步骤 1：检查电脑是否安装了 Python
1. 按键盘快捷键 **`Win + R`** 打开运行窗口；
2. 输入 **`cmd`** 并按回车，打开黑色命令行窗口；
3. 输入以下命令并按回车：
   ```cmd
   python --version
   ```
   - 若显示类似 `Python 3.10.x` 或 `Python 3.11.x` 等版本号，说明**已安装**，直接跳到步骤 3；
   - 若提示 `'python' 不是内部或外部命令`，说明尚未安装或未加入环境变量，请看步骤 2。

#### 步骤 2：安装 Python（未安装时）
1. 访问 Python 官方网站下载安装包：[https://www.python.org/downloads/](https://www.python.org/downloads/)（推荐 Python 3.10 或 3.11 版本）；
2. 双击运行下载的安装程序，**⭐ 务必勾选界面最下方的 `Add python.exe to PATH`**（将 Python 添加到系统环境变量，此项至关重要）；
3. 点击 **`Install Now`** 直至安装完成；
4. 重新打开一个 CMD 窗口，再次运行 `python --version` 确认已生效。

#### 步骤 3：安装 Excel 依赖库
在 CMD 命令行中运行以下命令（使用清华国内镜像源高速下载）：
```cmd
pip install openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple
```

> 💡 **贴心设计**：
> 双击运行本目录下的 **`start.bat`** 时，脚本也**自带智能检测**：若发现电脑尚未安装 `openpyxl`，会**全自动下载并完成安装**，零基础用户直接双击启动即可！

---

### 3. 极速上手 3 步曲

#### 第一步：启动本地服务
- 双击运行文件夹中的 **`start.bat`**；
- 看到控制台显示 `>>> Excel 本地数据录入服务已启动！` 即可；
- **保持该黑色窗口开启**（可以将其最小化，但在录入期间请勿关闭）。

#### 第二步：在浏览器中加载录入助手（二选一）

##### 方式 A：书签栏法（⭐ 强烈推荐，免安装任何插件）
1. 在浏览器（Chrome、Edge 等）中按 **`Ctrl + Shift + O`** 打开收藏夹，或在书签栏空白处右键选择 **“添加网页” / “添加书签”**；
2. **名称** 填写：`📌 数据录入助手`；
3. **网址 / URL** 打开本目录下的 `bookmarklet.txt`，复制里面全部内容（即以下这一行代码）并粘贴进去：
   ```javascript
   javascript:(function(){var host=document.getElementById('__web_collector_host__');if(host&&host.shadowRoot){var p=host.shadowRoot.getElementById('main-panel');if(p){p.classList.remove('hidden');}return;}var s=document.createElement('script');s.src='http://127.0.0.1:8765/script.js?t='+Date.now();s.onerror=function(){alert('⚠️【网页数据录入助手】提示：\n\n本地 Excel 写入服务尚未启动！\n请先双击运行文件夹中的【start.bat】启动服务，然后再点击本书签。');};document.body.appendChild(s);})();
   ```
4. 保存书签。以后在任何业务系统网页（如 OA、ERP）上，**点一下这个书签**，页面右侧就会立即弹出录入面板！

##### 方式 B：油猴插件法（Tampermonkey，自动常驻网页）
1. 浏览器安装 Tampermonkey（油猴）扩展插件；
2. 点击油猴图标 -> **“添加新脚本”**；
3. 将本目录下的 **`web_collector.user.js`** 全部内容复制粘贴进去，按 `Ctrl + S` 保存；
4. 以后打开任意网页，右下角会自动常驻绿色悬浮小图标。

#### 第三步：一键录入数据
1. 在业务网页（如 OA）中点击打开某位员工的卡片详情（例如“张三”）；
2. 在录入面板上点击 **【📌 立即录入本页数据】**，或者直接按下键盘快捷键 **`Alt + S`**；
3. 面板弹出绿色提示 `✅ 录入成功`，数据已安全写入目标 Excel 表格；
4. 关闭张三卡片，在表格中点击打开下一个员工（例如“李四”）：
   - 预览区将**秒级自动更新**为李四的姓名与工号等信息；
   - 再次按下 **`Alt + S`**，李四的数据将立刻自动追加到下一行！无需任何重复配置！

---

### 4. 进阶使用技巧

- **已录流水实时查看与一键复制（告别频繁开关 Excel）**：
  录入面板内置「📜 已录数据流水」展示框。每录入一条，面板即时高亮展示刚才存入的字段内容与录入时间：
  - **`[📋 复制单条]` / `[📋 复制最新]`**：快速复制单行字段数据；
  - **`[📑 复制全部]`**：将当前已录入的所有流水以标准表格格式（TSV）一键复制到剪贴板。在任意聊天软件（微信/钉钉/飞书）或 Excel/WPS 中直接按 **`Ctrl + V`**，即可自动恢复为整齐排列的网格表格！
- **方案名自动联动文件名**：
  新建方案时在“方案名称”输入任意名字（例如 `生产车间员工`），目标路径将自动联动为 `.../生产车间员工.xlsx`，每个方案拥有独立文件，省去手动编写路径的麻烦。
- **多工作表（Sheet）智能隔离写入**：
  即使不同方案共用同一个 Excel 文件，系统也会自动以【方案名称】为标签页名称独立存放，各业务表头完全隔离，绝不产生空白单元格错位。
- **鼠标可视化吸取新字段**：
  若需要采集新页面，点击方案旁的 `✏️`（编辑），点击 `👆 吸取` 按钮，然后鼠标点击网页上的任意文字，即可自动吸取该字段并绑定表头。

---

### 5. 服务的关闭与释放

录入工作完成后，可以通过以下任一方式停止后台服务：
1. **网页端直接关停（最推荐）**：直接在录入面板顶部标题栏右侧点击红色的 **【关停服务】** 按钮，服务即优雅安全退出；
2. **双击脚本彻底关停**：双击本目录下的 **`stop.bat`** 脚本，一键彻底释放端口；
3. **控制台退出**：在 `start.bat` 黑窗口中按键盘 `Ctrl + C`，或直接关闭黑窗口。

---

### 6. 常见问题排查 (FAQ)

#### Q1：双击 start.bat 提示“未检测到 Python 环境”？
- **解答**：电脑尚未安装 Python，或者安装时没有勾选 `Add python.exe to PATH`。请重新运行 Python 安装包，选择 `Modify` 并勾选该选项后重新安装。

#### Q2：录入时提示“写入失败：文件正在被其他程序（如 Excel）打开”？
- **解答**：Windows 系统的 Excel 软件在打开文件时会对文件加锁保护，防止并发写入损坏。只需**先关闭打开该表格的 Excel 窗口**，然后重新按 `Alt + S` 即可成功写入。

#### Q3：为什么换下一个人打开新卡片时，不需要重新吸取配置？
- **解答**：同一套业务系统中的卡片结构是高度一致的。配置一次方案后，系统会自动根据元素特征和文本标签进行全局穿透匹配，换人只需点击打开新卡片并按 `Alt + S` 即可实现批量连续追加。

#### Q4：双击打开本地演练页面 test_page.html 时，油猴扩展为什么没有出现悬浮球？
- **解答**：这是浏览器的安全防护策略，默认禁止任何扩展插件在本地文件网址（`file:///...`）上运行代码。
- **解决方法**：在浏览器右上角右键点击“油猴”扩展图标 -> 点击 **【管理扩展】**（或扩展详细信息） -> 找到并开启 **【允许访问文件网址】** 开关，刷新演练页面即可正常出现悬浮球！
  *(注：在真实的 HTTP/HTTPS 业务系统网页如 OA、ERP、内网系统中使用时无需此设置，开箱即用。)*