update at 2025-10-24 22:25:24

ARCHITECTURE.md

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