82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# 架构说明
|
||
|
||
本文档描述项目中的主要模块、职责划分以及关键流程，帮助维护者快速理解整体结构。
|
||
|
||
## 模块概览
|
||
|
||
```
|
||
├── README.md // 使用说明与命令入口
|
||
├── ARCHITECTURE.md // 架构与流程说明（本文档）
|
||
├── login.md // 需求与步骤原始描述
|
||
├── block.md // 滑块破解背景与参考脚本
|
||
├── src/
|
||
│ ├── login.ts // 豆瓣登录主流程（Cookie 复用、短信登录、滑块自动化）
|
||
│ └── slider.ts // 滑块模拟工具函数与命令行入口
|
||
└── typescript-spec.md // TypeScript 编码规范与示例
|
||
```
|
||
|
||
## 登录流程分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ main() │
|
||
│ - 创建浏览器 │
|
||
│ - 复用或创建上下文 │
|
||
│ - 调用 loginWithSms() │
|
||
│ - 保存 Cookies │
|
||
└─────────────────────────────────────────────┘
|
||
│
|
||
┌────────────────▼────────────────────────────┐
|
||
│ loginWithSms() │
|
||
│ - 输入手机号 │
|
||
│ - 点击“获取验证码” │
|
||
│ - trySolveSlider() 自动滑块（可选） │
|
||
│ - 提示人工输入短信验证码 │
|
||
│ - 提交并校验登录状态 │
|
||
└────────────────▲────────────────────────────┘
|
||
│
|
||
┌────────────────▼────────────────────────────┐
|
||
│ trySolveSlider() │
|
||
│ - locateSlider() 识别滑块所在 frame/元素 │
|
||
│ - inferSliderDistance() 推测拖动距离 │
|
||
│ - performSlide() 实际模拟拖动（来自 slider.ts）│
|
||
│ - 检查滑块成功标记 │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
- `prepareContext()`：独立负责 Cookie 复用与上下文创建。
|
||
- `isLoggedIn()`：封装登录状态检测逻辑，避免主流程重复判断。
|
||
- `slider.ts`：抽离通用滑块控制方法，既服务登录流程，也支持命令行调试。
|
||
|
||
## 依赖与交互
|
||
|
||
- Playwright：浏览器自动化；
|
||
- Node.js：运行环境、文件/路径操作；
|
||
- readline：控制台交互，输入验证码；
|
||
- 环境变量：控制手机号、滑块自动化开关与参数；
|
||
- `~/cookies.json`：持久化登录态，供下一次运行直接复用。
|
||
|
||
## 扩展点
|
||
|
||
- **滑块识别**：`sliderHandleSelectors` 与 `sliderTrackSelectors` 可按需扩充、覆盖，以支持不同验证码厂商。
|
||
- **距离计算**：先截取背景图与拼图块做模板匹配确定缺口位置，必要时退回二值化列分析，再配合多组偏移反复尝试；也可用 `DOUBAN_SLIDER_DISTANCE` / `DOUBAN_SLIDER_OFFSETS` 手动覆盖。
|
||
- **距离推断**：默认通过轨道宽度估算，特殊情况可直接设置 `DOUBAN_SLIDER_DISTANCE`。
|
||
- **验证码输入**：目前依赖人工短信验证码，可接入短信网关或 API 进一步自动化。
|
||
- **多账号管理**：现仅支持单账号，可通过配置文件或参数改造为批量登录。
|
||
|
||
## 数据流
|
||
|
||
1. 启动脚本读取 `DOUBAN_PHONE`、Cookies 路径等基础配置；
|
||
2. 初始化浏览器上下文，必要时进入登录页面；
|
||
3. 提交手机号，触发滑块验证；
|
||
4. 若启用自动滑块，定位组件并拖动；否则提示人工操作；
|
||
5. 读取短信验证码，提交登录表单；
|
||
6. 验证成功后将 `storageState` 写入 `cookies.json`；
|
||
7. 后续执行逻辑复用当前登录态或退出浏览器。
|
||
|
||
## 日志与错误处理
|
||
|
||
- 主流程捕获未处理异常并输出错误信息；
|
||
- 自动滑块阶段出现异常时仅发出警告并回退到人工操作；
|
||
- CLI 提示说明每一步的执行结果，便于排查问题。
|