docs: 更新文档

Author: baiheyyds

README.md

@@ -19,12 +19,26 @@
 
 ---
 
+## 目录
+
+- [✨ 项目特性](#-项目特性)
+- [📸 截图](#-截图)
+- [🎮 如何使用](#-如何使用)
+- [🏗️ 技术架构](#️-技术架构)
+- [📂 项目结构](#-项目结构)
+- [🚀 快速开始 (环境配置)](#-快速开始-环境配置)
+- [🔧 核心概念与维护](#-核心概念与维护)
+- [🤝 贡献](#-贡献)
+- [📜 授权协议 (License)](#-授权协议-license)
+- [⚠️ 免责声明](#️-免责声明)
+- [📞 联系](#-联系)
+
+---
+
 **Otaku-Sync** 是一个为 Galgame 和同人游戏爱好者打造的自动化信息管理解决方案。它能够从 **DLsite**, **Fanza**, **GGBases**, 以及 **Bangumi** 等主流平台抓取丰富的数据，并将其智能、规范地同步到你的个人 Notion 数据库中。
 
 与繁琐的手动录入说再见。现在，你可以通过一个现代化的图形界面，轻松管理你的游戏收藏，并借助其强大的数据整合与映射能力，确保你的数据库信息高度统一和规范。
 
-![Otaku-Sync GUI 主界面](./assets/gui.png)
-
 ## ✨ 项目特性
 
 -  **优雅的图形用户界面 (GUI)**: 提供一个现代化、直观的图形界面，让搜索、选择、同步的全过程一目了然。所有交互（如处理重复项、翻译新标签）都在可视化的对话框中完成，操作体验流畅。
@@ -41,6 +55,9 @@
 -  **高度可定制**: 通过独立的映射文件和配置文件，你可以轻松自定义 Notion 字段、标签体系和品牌别名。
 -  **高效稳定**: 采用异步 IO 和共享浏览器驱动等技术，显著提升抓取效率，节约系统资源。
 
+## 📸 截图
+
+![Otaku-Sync GUI 主界面](./assets/gui.png)
 ![数据统计](./assets/statistics.png)
 
 ## 🎮 如何使用
@@ -96,7 +113,9 @@ Otaku-Sync/
 ├── core/                 # 核心业务逻辑
 │   ├── interaction.py    # 交互提供者抽象接口
 │   └── ...
+├── gui/                  # GUI 界面
 ├── mapping/              # 品牌、标签等映射文件（可自定义）
+├── scripts/              # 实用工具脚本
 ├── utils/                # 通用工具（日志、驱动、GUI桥接等）
 ├── .env.example          # 环境变量模板
 ├── run_gui.py            # 🚀 图形界面 (GUI) 程序入口
@@ -113,7 +132,18 @@ Otaku-Sync/
 -  **Python**: 推荐版本 `3.8` 或更高。
 -  **Google Chrome**: 请确保你的电脑上已安装最新版的 Chrome 浏览器。
 
-### 2. 下载与安装
+### 2. 依赖
+
+本项目的关键依赖包括：
+
+- **PySide6**: 用于构建图形用户界面。
+- **Notion API**: 用于与 Notion 数据库进行交互。
+- **Selenium**: 用于模拟浏览器操作，抓取动态加载的网页内容。
+- **aiohttp**: 用于执行异步 HTTP 请求。
+
+你可以在 `requirements.txt` 文件中查看完整的依赖列表。
+
+### 3. 下载与安装
 
 克隆本项目，进入目录，并安装所有依赖：
 
@@ -123,7 +153,7 @@ cd Otaku-Sync
 pip install -r requirements.txt
 ```
 
-### 3. Notion 数据库准备 (关键步骤)
+### 4. Notion 数据库准备 (关键步骤)
 
 #### ① 创建数据库
 在你的 Notion 中创建 **3 个** 新的数据库，分别用于存储游戏、品牌和角色信息。
@@ -139,7 +169,7 @@ pip install -r requirements.txt
 在浏览器中打开你的每个数据库页面，从 URL 中复制 32 位的数据库 ID。
 `https://www.notion.so/你的工作区/THIS_IS_YOUR_DATABASE_ID?v=...`
 
-### 4. 配置项目
+### 5. 配置项目
 1. 在项目根目录，复制 `.env.example` 并重命名为 `.env`。
 2. 打开 `.env` 文件，填入你的 **Notion Token** 和三个 **数据库ID**。如果需要 Bangumi 功能，也请填入 **Bangumi Token**。
 
@@ -153,7 +183,7 @@ pip install -r requirements.txt
    ```
    > ⚠️ **安全警告**: `.env` 文件包含了你的私密信息，已被添加到 `.gitignore` 中。**绝对不要**将此文件上传到任何公共仓库！
 
-### 5. 配置 Notion 字段 (必读)
+### 6. 配置 Notion 字段 (必读)
 为了让程序能正确写入数据，你的 Notion 数据库需要包含特定的字段。请严格按照下表创建或修改你的数据库属性。
 
 <details>
@@ -236,6 +266,23 @@ pip install -r requirements.txt
 -  **即时维护**: 使用 GUI 时，程序会实时引导你完成翻译和映射，大大减轻了手动维护负担。
 -  **备份**: `mapping/` 目录是你个性化配置的核心，建议定期备份。
 
+## 🐛 疑难解答
+
+- **Q: 我遇到了 `Auth` 相关的错误。**
+- **A:** 请检查你的 `.env` 文件中的 `NOTION_TOKEN` 是否正确，以及你的集成是否已添加到相应的数据库中。
+
+- **Q: 我遇到了 `KeyError` 或 `字段不存在` 相关的错误。**
+- **A:** 请检查你的 Notion 数据库中的字段名是否与 `config/config_fields.py` 文件中的定义完全一致。
+
+- **Q: 程序运行缓慢或卡住。**
+- **A:** 请确保你的网络连接正常。如果问题仍然存在，请尝试重新启动程序。
+
+## 💡 未来工作
+
+- [ ] **添加更多数据源**: 支持更多游戏信息网站。
+- [ ] **优化性能**: 进一步提高数据抓取和处理的速度。
+- [ ] **完善文档**: 提供更详细的开发和使用文档。
+
 ## 🤝 贡献
 
 欢迎任何形式的贡献！
@@ -251,4 +298,10 @@ pip install -r requirements.txt
 
 -  本项目仅供个人学习、技术研究和数据归档使用。请在遵守当地法律法规的前提下使用本工具。
 -  项目抓取的部分内容可能包含 **NSFW** 元素，请谨慎使用。
--  请妥善保管你的 `.env` 文件和 Notion Token，切勿泄露。
+-  请妥善保管你的 `.env` 文件和 Notion Token，切勿泄露。
+
+## 📞 联系
+
+如果你有任何问题或建议，欢迎通过以下方式联系我：
+
+- **GitHub Issues**: [https://github.com/baiheyyds/Otaku-Sync/issues](https://github.com/baiheyyds/Otaku-Sync/issues)