From 4228b1e3a168fe5b6e970ad042feddc76d9efec7 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Tue, 17 Mar 2026 17:57:28 +0800 Subject: [PATCH] docs(07-01): complete QR Code Login Core plan --- .planning/REQUIREMENTS.md | 4 +- .planning/STATE.md | 29 ++-- .../phases/07-login-auth/07-01-SUMMARY.md | 131 ++++++++++++++++++ 3 files changed, 149 insertions(+), 15 deletions(-) create mode 100644 .planning/phases/07-login-auth/07-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 1ae47e5..fcc3440 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -9,7 +9,7 @@ ### 登录认证 -- [ ] **AUTH-01**: 用户可通过二维码扫码登录知乎 +- [x] **AUTH-01**: 用户可通过二维码扫码登录知乎 - [x] **AUTH-02**: 用户可手动设置 Cookie 进行认证 - [x] **AUTH-03**: Cookie 自动持久化到本地文件，下次自动复用 - [ ] **AUTH-04**: Cookie 过期时自动检测并提示重新登录 @@ -111,7 +111,7 @@ | Requirement | Phase | Status | |-------------|-------|--------| -| AUTH-01 | Phase 7 | Pending | +| AUTH-01 | Phase 7 | Complete | | AUTH-02 | Phase 7 | Complete | | AUTH-03 | Phase 7 | Complete | | AUTH-04 | Phase 7 | Pending | diff --git a/.planning/STATE.md b/.planning/STATE.md index 32954b1..32b85ae 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,9 +3,9 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: Zhihu Crawler status: executing -stopped_at: Plan 07-02 complete -last_updated: "2026-03-17T09:57:30.000Z" -last_activity: 2026-03-17 — Plan 07-02 Cookie Import & Persistence +stopped_at: Plan 07-01 complete +last_updated: "2026-03-17T10:05:00.000Z" +last_activity: 2026-03-17 — Plan 07-01 QR Code Login Core progress: total_phases: 9 completed_phases: 6 @@ -26,21 +26,22 @@ See: .planning/PROJECT.md (updated 2026-03-17) ## Current Position Phase: 7 of 9 (登录认证体系) -Plan: 02 of 03 (Cookie Import & Persistence complete) -Status: Plan 07-02 complete, continuing to 07-03 -Last activity: 2026-03-17 — Plan 07-02 Cookie Import & Persistence +Plan: 01 of 03 (QR Code Login Core complete) +Status: Plan 07-01 complete, continuing to 07-02 +Last activity: 2026-03-17 — Plan 07-01 QR Code Login Core Progress: [█████████░] 95% (v1.2 milestone) ## Performance Metrics **Velocity:** -- Total plans completed: 1 (v1.2) -- Average duration: 5 min -- Total execution time: 5 min +- Total plans completed: 2 (v1.2) +- Average duration: 10 min +- Total execution time: 20 min | Plan | Duration | Tasks | Files | Date | |------|----------|-------|-------|------| +| 07-01 | 15min | 2 | 5 | 2026-03-17 | | 07-02 | 5min | 2 | 4 | 2026-03-17 | ## Accumulated Context @@ -66,6 +67,8 @@ v1.2 decisions: - 整合进现有 Pipeline 架构 - Cookie 文件权限设置为 600 保证安全性 - 保存 Cookie 后清除 get_settings 缓存确保配置刷新 +- 使用 tenacity Retrying 对象而非 @retry 装饰器支持可配置超时 +- 多个 canvas 选择器降级提高 QR 码检测鲁棒性 ### Blockers/Concerns @@ -73,8 +76,8 @@ None. ## Session Continuity -Last session: 2026-03-17T09:57:30.000Z -Stopped at: Plan 07-02 complete -Resume file: .planning/phases/07-login-auth/07-02-SUMMARY.md +Last session: 2026-03-17T10:05:00.000Z +Stopped at: Plan 07-01 complete +Resume file: .planning/phases/07-login-auth/07-01-SUMMARY.md -**Next step:** Continue with plan 07-03 for QR code login integration +**Next step:** Continue with plan 07-02 for Cookie Import & Persistence diff --git a/.planning/phases/07-login-auth/07-01-SUMMARY.md b/.planning/phases/07-login-auth/07-01-SUMMARY.md new file mode 100644 index 0000000..53c02c2 --- /dev/null +++ b/.planning/phases/07-login-auth/07-01-SUMMARY.md @@ -0,0 +1,131 @@ +--- +phase: 07-login-auth +plan: 01 +subsystem: auth +tags: [zhihu, qrcode, playwright, tenacity, pydantic] + +requires: + - phase: 06-metadata + provides: PlaywrightBrowser class for browser automation +provides: + - ZhihuLogin class for QR code login + - ZhihuLoginResult Pydantic model for login results + - Test fixtures for auth module testing +affects: [07-02, 07-03] + +tech-stack: + added: [tenacity (already installed)] + patterns: + - TDD workflow (RED-GREEN-REFACTOR) + - Tenacity Retrying for configurable timeout polling + - Multiple selector fallback for robustness + +key-files: + created: + - kb_workflow/auth/__init__.py + - kb_workflow/auth/zhihu_login.py + - tests/test_auth/__init__.py + - tests/test_auth/conftest.py + - tests/test_auth/test_qrcode_login.py + modified: [] + +key-decisions: + - "Use tenacity Retrying object instead of @retry decorator for configurable timeout" + - "Multiple canvas selectors with fallback for QR code detection" + - "QR code saved to intermediate_path with timestamp filename" + +patterns-established: + - "Mock browser fixtures for unit testing without Playwright" + - "Pydantic model for structured login results" + +requirements-completed: [AUTH-01] + +duration: 15min +completed: 2026-03-17 +--- + +# Phase 7 Plan 1: QR Code Login Core Summary + +**ZhihuLogin class implementing QR code login flow: navigate to signin page, capture canvas screenshot, poll for z_c0 cookie with configurable timeout** + +## Performance + +- **Duration:** 15 min +- **Started:** 2026-03-17T09:47:15Z +- **Completed:** 2026-03-17T10:02:48Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments + +- Created Wave 0 test scaffolding with pytest fixtures for mocking PlaywrightBrowser +- Implemented ZhihuLogin class with full QR code login flow +- All 8 unit tests passing with TDD approach +- Configurable timeout via tenacity Retrying (default 60 seconds) + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create test module and fixtures** - `f90de6b` (test) +2. **Task 2: Implement ZhihuLogin core class** - `fb9bc2d` (test - TDD RED) + `072d83d` (feat - TDD GREEN) + +_Note: TDD tasks have multiple commits (test -> feat)_ + +## Files Created/Modified + +- `kb_workflow/auth/__init__.py` - Module exports ZhihuLogin and ZhihuLoginResult +- `kb_workflow/auth/zhihu_login.py` - Core login implementation (175 lines) +- `tests/test_auth/__init__.py` - Test module init +- `tests/test_auth/conftest.py` - Pytest fixtures (mock_browser, sample_cookies, etc.) +- `tests/test_auth/test_qrcode_login.py` - 8 unit tests for login flow + +## Decisions Made + +- Used tenacity `Retrying` object instead of `@retry` decorator to support configurable timeout per instance +- Multiple canvas selectors (`canvas.SignIn-qrcode`, `canvas[class*='qrcode']`, `canvas`) for robustness against UI changes +- QR code filename format: `zhihu_qrcode_{timestamp}.png` in intermediate directory + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed tenacity reraise behavior in timeout test** +- **Found during:** Task 2 (TDD GREEN phase) +- **Issue:** Test expected `RetryError` but `reraise=True` re-raises the original exception +- **Fix:** Updated test to expect `Exception` with message "Not logged in yet" +- **Files modified:** tests/test_auth/test_qrcode_login.py +- **Verification:** All 8 tests pass +- **Committed in:** `072d83d` (Task 2 GREEN commit) + +--- + +**Total deviations:** 1 auto-fixed (1 bug) +**Impact on plan:** Minor test adjustment, no functional impact + +## Issues Encountered + +- Initial `@retry` decorator had hardcoded 60-second timeout - switched to `Retrying` object for instance-level configuration + +## User Setup Required + +None - no external service configuration required for this plan. + +## Next Phase Readiness + +- ZhihuLogin class ready for integration in 07-02 (Cookie persistence) +- Test fixtures can be reused for cookie import testing +- Need to add CLI command integration in 07-03 + +## Self-Check: PASSED + +- [x] kb_workflow/auth/__init__.py - FOUND +- [x] kb_workflow/auth/zhihu_login.py - FOUND +- [x] tests/test_auth/test_qrcode_login.py - FOUND +- [x] 07-01-SUMMARY.md - FOUND +- [x] Task 1 commit f90de6b - FOUND +- [x] Task 2 commit 072d83d - FOUND + +--- +*Phase: 07-login-auth* +*Completed: 2026-03-17*