docs(07-01): complete QR Code Login Core plan

2026-03-17 17:57:28 +08:00
parent 799bf09acc
commit 4228b1e3a1
3 changed files with 149 additions and 15 deletions
@@ -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*