` | 200 / 200 | Exit 0, tra tuần và lấy lịch được |
+| `attendance`, điểm danh chi tiết | 200 / 200 | Exit 0, JSON hợp lệ |
+| `applications` | 200 / 200 | Exit 0, JSON hợp lệ |
+| `other survey` | 200 / 404 | Exit 0, giữ `Data Not Found` và `data: null` |
+| `other feedback`, `other profile` | 200 / 200 | Exit 0, giữ kiểu boolean |
+| `other subjects` | 200 / 200 | Exit 0, JSON hợp lệ |
+| `news` | 200 / 201 | Exit 1, `data: null` |
+| `other notification` | 200 / 201 | Exit 1, `data: null` |
+| `other fee` với `GeFeeByRoll` | 404 / không có envelope FAP | Exit 1, không diễn giải thành không nợ |
+
+Các command JSON đều được chạy với `--stdout`. Khi thành công, toàn bộ stdout parse được thành JSON; khi ba command thất bại, stdout rỗng. Progress và lỗi nằm trên stderr.
+
+ICS có thể parse lại trong process kiểm tra riêng sau khi tăng recursion limit của Python. Parser thư viện `ics` ở giới hạn mặc định đã gặp `RecursionError` với output live; command xuất ICS vẫn exit 0. Chưa kiểm tra import vào Google Calendar hoặc ứng dụng lịch khác.
+
+## Ba vấn đề chưa giải quyết
+
+### Thông báo trả code 201
+
+`GetTop10News` và `GetNotificationByRoll` đều trả HTTP 200, body code 201, `data: null` và `message: null` trong các lần thử. Kiểm tra session bằng `GetSemester` ngay trước đó vẫn trả 200/200; các route dữ liệu khác cũng chạy được.
+
+CLI hiện phân loại code 201 thành `ApiSessionExpiredError`. Bằng chứng live chưa đủ để kết luận hai lỗi này là hết phiên: cần phân biệt lỗi theo operation với tín hiệu session hết hạn rõ ràng. Không refresh cưỡng bức hoặc thay credential để che lỗi. Chưa xác định nguyên nhân ở backend, tài khoản hay contract request.
+
+### Học phí trả HTTP 404
+
+Contract APK v1 dùng `GeFeeByRoll`, nhưng route này trả HTTP 404 trong lần thử thực tế. Một phép chẩn đoán chỉ đọc, chạy riêng ngoài mã runtime, dùng lại request để so sánh tên cũ `GetFeeByRoll`; route cũ cũng trả 404. Không triển khai fallback hoặc thay route theo suy đoán.
+
+Chưa có response học phí v1 thành công để kiểm chứng `IsPaid`, invoice và amount trên backend hiện tại. Các kiểm tra bảo toàn trường vẫn dựa trên fixture tổng hợp. Không suy ra trạng thái thanh toán từ HTTP 404.
+
+### Điều kiện chốt kiểm chứng live
+
+- [ ] Xác định và xử lý nguyên nhân code 201 của hai route thông báo; bổ sung regression tổng hợp khi có contract rõ.
+- [ ] Xác nhận endpoint học phí v1 đang hoạt động hoặc ghi nhận unsupported có căn cứ; cần một response thành công để kiểm chứng schema thực.
+- [ ] Kiểm tra lại ba command sau khi có thay đổi phù hợp. Giữ kết quả thất bại hiện tại trong lịch sử kiểm chứng.
+
+## Giới hạn và bảo vệ dữ liệu
+
+Bạn có thể dùng báo cáo này để đánh giá route và output CLI, chưa thể coi đó là kiểm chứng đầy đủ mọi tài khoản hoặc campus. Survey mới được kiểm chứng trạng thái not-found, chưa có trường hợp thành công có survey bắt buộc. Login mới, OAuth callback, refresh rotation, đổi campus, API v2 và thao tác ghi nghiệp vụ chưa được kiểm thử trong lượt này.
+
+Không đọc, liệt kê, sao chép hoặc kiểm tra trực tiếp thư mục session của người dùng. Chỉ executable CLI tự nạp session theo hành vi sẵn có. Command chạy tuần tự; không chạy `login`, `logout` hoặc `refresh` thủ công.
+
+Stdout/stderr và response thật chỉ được xử lý trong RAM. Chương trình kiểm tra chỉ xuất metadata trong danh sách cho phép: route, mã HTTP/body, loại dữ liệu, exit code và kết quả kiểm tra định dạng. Không lưu response, header, query có giá trị, lịch học, bảng điểm, đơn từ, identity, credential hoặc biến môi trường bí mật vào repo, fixture, commit hay comment PR. Không phát lại HAR/SAZ.
+
+Các script chạy live nằm ngoài repository và không được đưa lên GitHub. Báo cáo này và bản cập nhật checklist chỉ chứa kết quả đã che dữ liệu. `docs/` và `tasks/` vẫn là repository-only, không nằm trong artifact PyPI.
+
+
+
+---
+
+Đường dẫn ban đầu: `docs/phase2-review-fixes.md`
+
+Commit cuối thay đổi file tại commit gốc: `96b4a2ee0d23854964f9ad6dad36c685e20dc92c`
+
+# Sửa lỗi sau review Phase 2
+
+Review ban đầu dựa trên PR #5 ở commit `9573617`. Trong lúc sửa, branch được fast-forward theo merge `937ae7c` để giữ thay đổi README và hướng dẫn phát triển mới từ main. Không sửa branch tài liệu riêng hoặc đọc thư mục session cá nhân.
+
+## Kết luận từng nhận định
+
+| Nhận định | Kết luận và thay đổi |
+|---|---|
+| V1 không tự refresh với body 201 | Có gap. Mở rộng expiry cho mọi FAP read operation có `Authen` khi cả code 201 và message `Token invalid` khớp; không áp mọi 201 |
+| `login --force` bị session v2 cũ chặn | Đúng. Login mới chỉ kế thừa campus, dùng v1/student trừ tham số rõ ràng; session cũ giữ nguyên đến khi login mới thành công |
+| `login` bắt người dùng gõ thêm `--force` khi binding cần xác thực lại | Đúng. CLI chuyển từ `SessionBindingError` sang mở trình duyệt; lỗi mạng hoặc lỗi khác không bị che bằng login mới |
+| ID token thiếu clock skew tolerance | Đúng. Thêm leeway 30 giây cho exp/iat/nbf, giữ chữ ký và các claim khác; buffer access token vẫn riêng |
+| Logout không xóa được JSON hỏng | Đúng. Xóa file thường dưới lock mà không parse JSON, kiểm lại đường dẫn trước unlink |
+| Attendance gọi mạng trước khi báo thiếu cờ | Đúng. Kiểm tra cặp cờ trước khi tạo auth, nạp session hoặc tra kỳ |
+| Dependency pkce không còn được dùng | Đúng. Bỏ khỏi pyproject và uv.lock; PKCE S256 vẫn dùng secrets/hashlib |
+
+## Bằng chứng cho contract 201
+
+Nghiên cứu `analysis/auth-var-v1-v2-comparison.md`, mục 6.1, mô tả v1 dùng body 201 cho hết phiên nhưng chưa chỉ rõ điều kiện theo operation. Đối chiếu caller APK trong workspace xác nhận app kiểm đồng thời `code == 201` và `message == "Token invalid"`:
+
+| Operation đang có trong CLI | Nguồn phân tích APK cục bộ |
+|---|---|
+| GetActivityStudent | `analysis/modules/module_1299.js:719-729` |
+| GetStudentMark | `analysis/modules/module_1302.js:331-340` |
+| GetStudentAttendances | `analysis/modules/module_1332.js:385-394` |
+| GetActivityStudentByWeek | `analysis/modules/module_2598.js:746-756` |
+
+Caller GetBalance cũng có điều kiện này tại `analysis/modules/module_825.js:409-417`, nhưng CLI chưa có operation đó nên không thêm capability hoặc policy chưa dùng. Những nguồn phân tích trên nằm ngoài repository CLI.
+
+News/notification đã có bằng chứng live trả 201 khi cùng session vẫn đọc được dữ liệu. Policy mới chỉ refresh khi message chính xác `Token invalid`; body 201 rỗng của hai route này vẫn là lỗi operation. GetSemester và các FAP read route khác được mở rộng theo cùng guard. Public bootstrap, tra tuần, survey, operation lạ, thao tác ghi và handshake không thuộc allowlist FAP read. Body `201` thiếu hoặc sai message vẫn là lỗi operation. HTTP 401 tiếp tục là tín hiệu expiry rõ ràng cho request đọc.
+
+Allowlist được mở rộng từ bốn lên 17 operation theo yêu cầu QoL của maintainer. `AUTHENTICATED_READ_OPERATIONS` là nguồn dùng chung cho phân loại lỗi và policy retry, tránh danh sách lệch nhau. Bốn caller APK ở bảng trên là bằng chứng trực tiếp; expiry live của 13 operation bổ sung chưa được quan sát trong lượt này.
+
+## Kiểm chứng
+
+Đã tái hiện lỗi bằng fixture trước sửa: login v2 bị chặn, logout không parse được JSON, ID token lệch đồng hồ 0,5 giây bị từ chối, attendance gọi auth trước kiểm tra cờ và body 201 `Token invalid` không kích hoạt refresh.
+
+Regression sau sửa bao gồm login/refresh với JWT ký RSA thật trong bộ test; biên leeway; claim sai kiểu/không hữu hạn; giữ bytes session cũ khi login thất bại; logout corrupt/missing/symlink/reparse; retry một lần với key/checksum mới; second expiry; refresh thất bại; operation/message không khớp và App Check/403/5xx không refresh. CLI schedule vẫn giữ stdout chỉ chứa JSON sau refresh.
+
+Windows/Python 3.9.25 và 3.11 đều chạy 214 test: 210 pass, 4 skip mỗi môi trường theo quyền/mode POSIX hoặc symlink. Console entry point được chạy trực tiếp với file tạm giả: logout JSON hỏng exit 0, session/lock đều được xóa; attendance thiếu `--classname` exit 1, stdout rỗng, báo đúng cờ và không tạo auth lock. Review độc lập theo hai trục Standards/Spec không còn finding sau sửa tài liệu.
+
+Các test xác minh contract APK và xử lý CLI, không chứng minh server live tự hết phiên trả envelope nào trong một phiên cụ thể. Không sửa token thật hoặc tạo lỗi server để lấy bằng chứng. Kết quả test, artifact và CI của commit cuối được cập nhật qua comment PR; PR tiếp tục giữ draft.
+
+
+
+---
+
+Đường dẫn ban đầu: `docs/phase2-verification.md`
+
+Commit cuối thay đổi file tại commit gốc: `a01a1f4235343f425331cf080efac9492da10a4d`
+
+# Kiểm chứng Phase 2
+
+Ngày kiểm tra: 16/10/2026. Branch: `feat/phase2-oauth-session`; [PR #5](https://github.com/WindowScary321/myfap-api-cli/pull/5) giữ draft.
+
+## Offline và artifact
+
+Windows/Python 3.9.25 và 3.11 cùng chạy 179 unittest: 176 pass, 3 skip. Các skip liên quan mode POSIX và quyền tạo symlink trên Windows; trường hợp reparse point có fixture riêng. Test lock dùng process riêng, test JWT dùng key/token sinh riêng trong bộ test. Không test nào cần tài khoản FEID hoặc session thật.
+
+Regression bao phủ callback trùng/sai state/cancel/timeout, chữ ký và claim ID token, binding, session cũ, file hỏng, read retry, request ghi không retry, redirect, lưu token trước validation và lỗi handshake sau rotation. Test cũng chặn command đang chạy nhận nhầm session do process khác đổi tài khoản, campus hoặc version.
+
+`uv build` tạo wheel/sdist version `0.2.0`; Twine strict và artifact validator đều pass. Hai artifact được cài bằng pip vào hai venv sạch ngoài checkout, sau đó chạy `pip check`, `myfap version` và `myfap --help`. Artifact không chứa `docs/`, `tasks/`, fixture, capture hoặc file session.
+
+[CI của commit triển khai `8a369d3`](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38895605533) đã pass toàn bộ 11 job: scope, bốn source job, build, bốn artifact job và ready. Matrix gồm Ubuntu/Windows × Python 3.9/3.11. Kết quả commit tài liệu cuối được cập nhật vào PR khi hoàn tất.
+
+## Live với session tạm trước bổ sung QoL
+
+Người dùng tự đăng nhập trên cửa sổ FEID. CLI dùng `--config` trỏ đến file tạm ngoài repository, không đọc trực tiếp thư mục session cá nhân. Output được giữ trong RAM và chỉ xuất các trường đã cho phép: tên operation, HTTP/body code, kiểu dữ liệu, kết quả validation và exit code. Không lưu URL chứa query, token, MSSV/email, raw response, lịch học hoặc điểm.
+
+| Luồng/command | Kết quả |
+|---|---|
+| `login --force` | Discovery, token endpoint và JWKS HTTP 200; ID token qua validation; handshake HTTP 200/body 200, data list; exit 0 |
+| `semesters` | Probe và request GetSemester HTTP 200/body 200; exit 0 |
+| `news --stdout`, timeout 20 giây | Lỗi mạng/timeout; exit 1; không gọi token endpoint |
+| `news --stdout`, timeout 60 giây | HTTP 200/body 201, data null; exit 1; không refresh |
+| `other notification --stdout` | HTTP 200/body 201, data null; exit 1; không refresh |
+| `refresh` | Token endpoint/JWKS HTTP 200; ID token refresh được trả và qua validation; handshake HTTP 200/body 200; exit 0 |
+| `info student --stdout` sau refresh | Probe và GetStudentById HTTP 200/body 200, data list; stdout parse được JSON; exit 0 |
+| `--campus HCM login` với tài khoản chỉ có APHL | Handshake thật HTTP 200/body 201; exit 1; không gọi request nghiệp vụ; nội dung session được so sánh trong RAM và không đổi |
+| `--campus APHL login` sau lần HCM thất bại | Probe GetSemester HTTP 200/body 200; exit 0 |
+| Fault injection timeout tại handshake sau refresh thật | Refresh token mới được server trả và persist trước lỗi; binding giữ nguyên, FAP đánh dấu cần xác thực lại, exit 1 |
+| `semesters` sau khi bỏ fault handshake | Handshake lại HTTP 200/body 200 rồi GetSemester HTTP 200/body 200; exit 0; không exchange token lần hai |
+| Console entry point `myfap.exe` | Chạy trực tiếp `semesters` và `info student --stdout`, exit 0; JSON hợp lệ |
+| Console entry point `logout` | Xóa session tạm, exit 0 |
+
+Các luồng cần trace operation chạy qua Typer app với tham số CLI thật và Requests thật; console entry point được chạy thêm bằng subprocess để xác minh đường gọi của bản cài editable. Login, đổi campus, token exchange và request phục hồi đều gọi server thật; riêng phép thử lỗi handshake chặn request trong bộ nhớ trước khi gửi, không thay token hay file session bằng dữ liệu giả. Lần mở trình duyệt đầu chưa có callback; lần đăng nhập sau đã hoàn tất. Hai lỗi body 201 vẫn thuộc backend/contract và được giữ là lỗi operation.
+
+## Phần chưa xác nhận live
+
+Đổi campus thất bại với HCM đã được kiểm chứng live và giữ nguyên APHL. Chưa xác nhận chuyển campus thành công vì tài khoản mẫu chỉ có APHL. Phục hồi sau handshake lỗi đã được kiểm bằng fault injection trên session thật; chưa quan sát server tự trả lỗi handshake. FEID trả `expires_in: 3600` khi refresh, nhưng FAP `authenKey` không có contract TTL; hết hạn FEID access token không đồng nghĩa FAP credential hết hạn. Vì vậy HTTP 401 tự refresh/retry mới chỉ có fixture, chưa có bằng chứng phiên thật tự hết hạn. Đổi API version hoàn tất khi có adapter v2 ở Phase 3.
+
+Session cũ chưa có subject OIDC đã xác minh cần `login --force` trước khi refresh. File session vẫn là JSON chứa credential; xem [quy tắc lưu session](docs/oauth-session.md#timeout-và-file-trên-máy). PR này không tạo tag, publish PyPI hoặc triển khai auto release.
+
+## Kiểm chứng QoL trong PR #5
+
+Sau khi bỏ probe `GetSemester`, thêm buffer 30 giây trước khi dùng FEID access token để handshake và dọn lock khi logout, Windows/Python 3.9 và 3.11 cùng chạy 191 test: 188 pass, 3 skip mỗi môi trường. Test số request dùng auth/client thật với HTTP giả; test biên thời hạn cố định đồng hồ; test cleanup dùng process riêng để giữ handle chờ và phát hiện hai khóa song song. POSIX được kiểm trong CI Ubuntu.
+
+Đã đăng nhập mới bằng session tạm riêng và chạy Requests thật:
+
+| Command | Trace sau QoL |
+|---|---|
+| `info student --stdout` | Chỉ GetStudentById HTTP 200/body 200; JSON hợp lệ, exit 0 |
+| `semesters` | Chỉ một GetSemester HTTP 200/body 200; exit 0 |
+| `login` với session đã lưu | Không phát sinh HTTP; exit 0 |
+| `logout` | Exit 0; cả session tạm và `.lock` đều không còn |
+
+Buffer 30 giây được kiểm bằng đồng hồ cố định, không sửa token thật để giả thời hạn. Buffer chỉ refresh sớm trước handshake/phục hồi binding; không kéo dài token hoặc suy thời hạn FAP từ FEID. Trên Windows, logout có thể giữ lock nếu process khác còn mở handle; hành vi này tránh phá đồng bộ giữa các process. Kết quả CI commit QoL được cập nhật qua comment PR.
+
+
+
+---
+
+Đường dẫn ban đầu: `docs/phase3-verification.md`
+
+Commit cuối thay đổi file tại commit gốc: `35b5ea1d47c1c52ed814b78ab0cdc39fd59a576c`
+
+# Kiểm chứng Phase 3
+
+Baseline là `238c718` trên main, sau PR #5. Phase 3 được triển khai tại [PR #7](https://github.com/WindowScary321/myfap-api-cli/pull/7), giữ draft và version package `0.2.0`.
+
+## Offline
+
+Regression dùng credential giả, file session tạm và HTTP mock; không đọc thư mục session cá nhân. Bộ test giữ toàn bộ v1 và bổ sung:
+
+- Header/body/query v2 cho hai bootstrap, handshake, GetSemester và schedule; signing identity đúng theo từng bước.
+- HMAC-SHA256 dùng UTF-8 key, timestamp cố định và padding `%3d`; ngăn decode khóa hex hoặc encode padding hai lần.
+- Precedence option → session → v1; state CLI không bị lẫn giữa các lần gọi. Public bootstrap đọc version mà không restore identity hoặc handshake.
+- Đổi binding v1/v2 hai chiều; handshake lỗi giữ binding cũ; không gửi FAP key của version cũ vào request dữ liệu version mới. Cùng campus/account không được âm thầm đổi MSSV/email.
+- Rotation persist trước validation/handshake, retry đọc tối đa một lần với key/chữ ký mới, App Check/403/5xx và route unsupported không gây fallback.
+- Capability CLI được kiểm trước tra kỳ/tuần cho command chưa hỗ trợ; survey giữ contract riêng.
+
+Windows/Python 3.9.25 và 3.11 chạy 261 test mỗi môi trường: 257 pass, 4 skip theo quyền/mode POSIX hoặc symlink. Build version `0.2.0` qua Twine strict và artifact validator; wheel/sdist được cài bằng pip vào hai venv sạch, `pip check`, version và help đều pass. Review độc lập không còn finding runtime; phần contract matrix đã bổ sung account/path/read-write/retry sau review.
+
+## Live với session tạm
+
+Ngày 17/10/2026, người dùng tự đăng nhập FEID và xác nhận tài khoản mẫu thuộc Hà Nội/Hòa Lạc. Output chỉ được giữ trong RAM và xuất metadata: operation, method, HTTP/body code, kiểu data, kết quả ID token validation, exit code hoặc tính hợp lệ JSON. Không ghi token, MSSV/email, query có credential, lịch học, điểm hay raw response vào repository.
+
+| Phép thử | Kết quả |
+|---|---|
+| V2 GetAllActiveCampus | POST HTTP 200/body 200, data list |
+| V2 GetApiActive gọi rõ để chẩn đoán | POST HTTP 200/body 200, data bool |
+| Login v2 với campus APHL | FEID discovery/token/JWKS HTTP 200, ID token hợp lệ; handshake HTTP 200/body 401, exit 1; không lưu session v2 |
+| Lấy mã campus từ bootstrap v2 | Có CT, DN, HCM, HN, QN; HN là Cơ sở Hà Nội, không có APHL |
+| Login v2 với HN sau xác nhận của người dùng | FEID discovery/token/JWKS HTTP 200, ID token hợp lệ; handshake POST HTTP 200/body 200, data list, exit 0 |
+| `--api-version v2 semesters` | Một GetSemester GET HTTP 200/body 200, data list, exit 0 |
+| `--api-version v2 schedule --stdout` | GetSemester và GetActivityStudent GET HTTP 200/body 200, stdout JSON hợp lệ, exit 0 |
+| `schedule --stdout` cùng session, bỏ option version | Chọn v2 đã lưu; hai operation trên HTTP 200/body 200, JSON hợp lệ, exit 0 |
+| `--api-version v2 marks --stdout` | Exit 1, không phát sinh HTTP vì chưa hỗ trợ |
+| Logout session tạm | Exit 0; session và sidecar lock đều được xóa |
+
+Lần handshake APHL thất bại và lần HN thành công được giữ thành hai kết quả riêng. CLI không tự đổi campus, không đổi version hoặc thêm token App Check để vượt lỗi. Không kết luận mọi body 401 đều do campus; ở lần này mã campus đã được kiểm tra lại bằng bootstrap và người dùng xác nhận.
+
+## Giới hạn
+
+Live mới xác nhận bootstrap, login mới, kỳ học, schedule JSON và lựa chọn version từ session với một campus. Đổi version hai chiều, refresh v2 và các nhánh lỗi có fixture, chưa xác nhận live riêng trong lượt này. Chưa có bằng chứng một session v2 tự hết hạn. Khả năng import lịch ICS và parity các command còn lại thuộc Phase 4.
+
+Kết quả Python 3.9/3.11, build, Twine, artifact validator, pip smoke và CI của commit cuối được cập nhật qua comment PR. Không có tag, GitHub Release hoặc publish PyPI trong Phase 3.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/phase0.md`
+
+Commit cuối thay đổi file tại commit gốc: `5efad9b8c2e8cdfb992db7ddc64b7ef085b5db6a`
+
+# Phase 0 — CI và artifact cho mốc v0.2.0
+
+PR theo dõi: [PR 2](https://github.com/WindowScary321/myfap-api-cli/pull/2). Mọi commit của phase này được push vào `feat/phase0-v0.2.0`; các comment ghi mốc kiểm tra, commit và kết quả CI.
+
+## Phạm vi
+
+Gia cố CI trước các phase sửa v1, OAuth/session và v2. Version package được chuẩn bị thành `0.2.0` trong PR này; chưa tạo tag, publish PyPI hoặc triển khai auto release của Phase 5. Kế hoạch migration uv `0.1.8` trong `tasks/plan.md` và `tasks/todo.md` là lịch sử đã hoàn tất, giữ nguyên.
+
+## Công việc
+
+- [x] Tách branch từ `origin/main`, tạo PR và đồng bộ version với lockfile.
+- [x] Thêm nhóm dependency CI đã khóa; chuyển marker greenlet vào metadata runtime sau khi tái hiện lỗi pip Windows/Python 3.9 cần compiler.
+- [x] Thêm artifact gate cho version, entry point, README/license, file allowlist và manifest SHA-256.
+- [x] Kiểm tra cả wheel/sdist trong venv riêng ngoài checkout bằng pip; chạy check/version/help và ép UTF-8 cho subprocess.
+- [x] Chuyển CI thành source matrix → build Ubuntu một lần → artifact matrix → gate cuối; hỗ trợ reusable workflow outputs.
+- [x] Pin action theo commit SHA, giữ quyền `contents: read` và tắt persist Git credential.
+- [x] Thêm unit test với archive giả, version/hash sai, đường dẫn nhạy cảm, symlink, smoke isolation và UTF-8.
+- [x] Xác nhận source và artifact trên cả bốn môi trường GitHub Actions; tiếp tục kiểm tra lại khi PR có commit mới.
+- [x] Ghi các mốc commit/kiểm tra bằng comment và tổng hợp bằng chứng trong PR.
+
+## Kiểm chứng
+
+- Unit suite local: 32 test pass sau phần mở rộng, gồm regression version và các case scope/ready. Thử đảo điều kiện kiểm manifest khiến test hash thất bại; khôi phục code và suite pass lại.
+- `uv build`, `twine check --strict`, artifact validation và actionlint pass.
+- Pip smoke thật trên Windows/Python 3.9 và 3.11 pass cho wheel lẫn sdist; bốn tổ hợp OS/Python trên GitHub Actions đều pass.
+- [Run CI 38852306858](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38852306858) của commit `393ced9`: 10/10 job thành công. Kết quả commit mới nhất được cập nhật trong PR.
+
+## Giới hạn
+
+CI không đăng nhập FEID hoặc gọi API FAP thật. Allowlist chỉ chặn đường dẫn/file ngoài chính sách; không chứng minh được không có secret hoặc PII ẩn trong nội dung mã Python. Kết quả Phase 0 không xác nhận OAuth/API v1/v2 đã được sửa.
+
+## Mở rộng: docs/tasks chỉ lưu trong repository
+
+- [x] Thêm `scope` lấy danh sách tên path Git, không đọc nội dung hai thư mục. Rename được xét như delete/add để đổi tên từ code sang docs hoặc ngược lại vẫn chạy đầy đủ CI.
+- [x] Chỉ thay đổi `docs/**` hoặc `tasks/**`: bỏ qua source/build/smoke, không tạo artifact; `ready` vẫn trả success. Thay đổi code/mixed và mọi `workflow_call` chạy đủ gate.
+- [x] `ready` dùng `always()` nhưng xác minh trạng thái từng job, không che lỗi/cancel hoặc trạng thái không xác định.
+- [x] Sparse checkout chỉ giữ code/tests/helpers và file build; không checkout docs/tasks trong các job CI. README/license root vẫn được giữ.
+- [x] Dùng `MANIFEST.in` loại hai thư mục khi build full checkout; validator từ chối docs/tasks trong wheel và sdist.
+- [x] Bổ sung test docs-only/tasks-only, code/mixed, rename/delete, reusable call và gate lỗi; artifact giả kiểm tra cả hai định dạng.
+- Kết quả pipeline của commit mở rộng trên GitHub Actions được theo dõi trong check của PR; comment ghi link run và commit tương ứng.
+
+Phần mở rộng giữ nguyên runtime API, entry point, version và các workflow outputs artifact đã có. Không thêm tài liệu vào `package-data` hoặc `data-files`.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/phase1.md`
+
+Commit cuối thay đổi file tại commit gốc: `e2325f5542ea92c4acf7adde547ef4daafb98f1a`
+
+# Phase 1: sửa v1 và lỗi dữ liệu
+
+## Phạm vi
+
+Tiếp nối Phase 0 trên phiên bản `0.2.0`, branch `fix/phase1-v1-data`. API v1 vẫn là mặc định. Công việc gồm query, payload, chọn kỳ học, survey, học phí, stdout và parser. OAuth/session đầy đủ, adapter v2 và auto release thuộc các phase sau.
+
+**Trạng thái sau kiểm chứng API thật ngày 16/10/2026:** phần triển khai và kiểm thử offline đã xong; live còn ba command chưa hoạt động. Chi tiết nằm trong [báo cáo kiểm chứng live](#docs-phase1-live-verification).
+
+## Các bước và tiêu chí hoàn tất
+
+- [x] Chuyển mọi query v1 sang `params=`, gồm kiểm tra session và handshake login/refresh; giữ nguyên case từng trường và kiểm tra encoding bằng credential giả.
+- [x] Kiểm tra HTTP, JSON và body code riêng; bảo toàn envelope và kiểu `data`. Survey not-found không bị diễn giải thành hết phiên hay không còn survey bắt buộc.
+- [x] Chọn kỳ theo `startDate`, giữ thứ tự server khi trùng ngày; ngày lỗi yêu cầu `--semester`, flag explicit không gọi resolver tự động.
+- [x] Tách checksum survey theo contract của app: username trim/lower, campus rỗng, khóa riêng và giờ Việt Nam.
+- [x] Dùng route v1 `GeFeeByRoll` đã đối chiếu với APK; HTTP 404 là lỗi, giữ mọi dòng học phí và `IsPaid`.
+- [x] Giữ stdout chỉ có JSON/ICS khi dùng `--stdout`; log/lỗi đi stderr. `--date` suy ra năm khi thiếu `--year`.
+- [x] Thêm fixture tổng hợp HTML có rowspan/colspan và lịch ICS; chỉ sửa parser khi regression test tái hiện lỗi.
+- [x] Chạy regression trên Python 3.9/3.11, build wheel/sdist mới, Twine strict, artifact gate và cài thử ngoài checkout.
+- [x] Review độc lập, kiểm tra diff và nội dung tiếng Việt; mở draft PR, ghi kết quả kiểm tra qua comment, giữ trạng thái draft.
+- [x] Chạy command trực tiếp với session mẫu; kiểm chứng 20 route, chỉ lưu kết quả đã che dữ liệu.
+- [ ] Giải quyết code 201 của `news` và `other notification`; chưa kết luận đây là lỗi hết phiên.
+- [ ] Xác minh endpoint học phí v1 vì cả `GeFeeByRoll` và phép chẩn đoán `GetFeeByRoll` đều trả HTTP 404.
+
+## Cơ sở đối chiếu
+
+- Kế hoạch chi tiết: `PLAN-PHASES.md`, Phase 1, ở workspace phân tích.
+- Bản so sánh: `analysis/myfap-api-cli-comparison.md` và `analysis/endpoints.md`.
+- Contract v1: `analysis/modules/module_550.js`, gồm route học phí và helper survey.
+- HAR/SAZ ngày 14/10 chỉ xác nhận runtime v2 và survey. Không coi đây là kiểm thử live v1.
+
+Fixture dùng dữ liệu giả, không chứa token, authenKey, chữ ký thực hoặc thông tin cá nhân. `docs/` và `tasks/` chỉ phục vụ đọc trong repository, không thuộc wheel/sdist hoặc phạm vi kiểm tra code của CI.
+
+## Kiểm chứng
+
+Trước thay đổi có 32 unittest. Suite mới tái hiện lỗi query, thứ tự kỳ, học phí HTTP 404, survey, stdout, ngày/năm và rowspan trước khi sửa. Kết quả sau sửa:
+
+- 88 unittest ban đầu; sau bổ sung `--timeout` trong PR #4, suite có 96 test và pass Ubuntu/Windows × Python 3.9/3.11.
+- Mutation đảo thứ tự ngày và sửa sai bộ đếm rowspan đều bị regression test bắt.
+- ICS pass trên Python 3.9 không có `tzdata`, dùng `pytz` sẵn có.
+- Twine strict và artifact validator pass với wheel/sdist mới; pip cài được cả hai artifact trong hai venv riêng ngoài checkout.
+- Mã runtime trong artifact khớp source. `docs/`, `tasks/` và `tests/` không nằm trong artifact; fixture chỉ phục vụ CI từ checkout.
+- Validator tiếng Việt strict không có lỗi hoặc cảnh báo; diff không có lỗi whitespace. Đã review độc lập và đối chiếu giá trị credential/identity từ capture bằng script, chỉ xuất kết quả không trùng, không in giá trị.
+
+PR [#4](https://github.com/WindowScary321/myfap-api-cli/pull/4) đã merge vào branch Phase 1. [CI sau merge timeout](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38875363915) pass cả 11 job trên commit `07fb289` của PR [#3](https://github.com/WindowScary321/myfap-api-cli/pull/3). Trạng thái review/merge do maintainer quyết định; không tự chuyển Ready for review hoặc merge.
+
+Kiểm chứng live trên commit đó: 25 lần chạy command, 22 exit 0 và 3 exit 1, phủ 20 route. Lịch, điểm chi tiết, điểm danh, thông tin, đơn từ, môn học và survey not-found đã có bằng chứng runtime v1. Ba lỗi còn lại được ghi riêng, không bỏ qua trong kết luận.
+
+## Giới hạn
+
+Đã kiểm thử server v1 qua CLI với một session mẫu, không đọc trực tiếp thư mục chứa session. Fixture survey thành công và học phí v1 vẫn là dữ liệu tổng hợp: live chỉ quan sát survey not-found và học phí HTTP 404. Chưa xác minh nhiều tài khoản/campus hoặc đối chiếu toàn bộ nội dung với app chính.
+
+Phase 2 tiếp tục xử lý token validation, campus binding, session lock/atomic write và refresh rotation. Phase 1 không triển khai adapter v2, auto release, tag hoặc publish PyPI. Rollback dùng revert các commit trong PR; không có migration dữ liệu.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/phase2.md`
+
+Commit cuối thay đổi file tại commit gốc: `96b4a2ee0d23854964f9ad6dad36c685e20dc92c`
+
+# Phase 2: OAuth và session
+
+## Phạm vi và thứ tự
+
+Branch `feat/phase2-oauth-session` bắt đầu từ `main` sau PR #3. Giữ version `0.2.0`, API v1 và Playwright. PR riêng phải ở trạng thái draft; chỉ maintainer quyết định chuyển Ready for review hoặc merge.
+
+1. Phân loại lỗi theo version/operation/HTTP/body. Code 201 chưa rõ nghĩa không gây refresh/logout; đọc chỉ retry một lần khi có tín hiệu hết phiên rõ ràng.
+2. Kiểm tra callback chính xác, state/nonce và PKCE mới mỗi login. Dùng discovery và xác minh ID token RS256 bằng JWKS, issuer/audience/azp/exp/sub/nonce/at_hash.
+3. Lưu session atomic và dùng lock xuyên suốt read → refresh → persist. Lưu refresh token mới trước validation/handshake tiếp theo; lỗi sau rotation không được quay về token cũ.
+4. Chọn campus theo parameter → session → default khi login mới. Binding campus/version/account type phải hợp lệ trước request dữ liệu; identity lấy từ handshake, không decode access token để suy MSSV.
+5. Giữ timeout đã có cho discovery/JWKS/token/handshake/API. Kiểm tra offline, build và smoke artifact trước gate live riêng.
+
+## Hợp đồng giữa các phần
+
+- `errors.py`: lỗi an toàn, không chứa credential, response hoặc URL có query; phân loại theo context của operation.
+- `oidc.py`: discovery, login attempt, callback, token request và validation tách biệt để persist rotation trước bước có thể lỗi.
+- `storage.py`: đọc JSON, ghi atomic và khóa file; chỉ auth orchestration điều phối transaction.
+- `auth.py`: vòng đời OAuth/FAP session, binding, identity handshake và rotation; CLI không tự mở file session để refresh.
+- `api.py`: kiểm binding và retry đọc có giới hạn; payload/output hiện có được giữ nguyên.
+
+Các module mới phục vụ trust boundary và tránh circular import; không thêm framework hoặc adapter v2 trong Phase 2.
+
+## Checklist
+
+- [x] Regression cho hai body 201 và ma trận HTTP/body 401, App Check, timeout/5xx, read/write retry.
+- [x] Callback/OIDC có test âm về chữ ký, issuer, audience/azp, nonce, expiry và at_hash; refresh có thể thiếu ID token nhưng nếu có phải cùng subject.
+- [x] Session cũ thiếu version được hiểu là v1; đổi binding bị chặn trước HTTP dữ liệu, handshake lỗi không ghi nhầm binding.
+- [x] Atomic write và lock được kiểm bằng file tạm/process riêng trên Windows và Unix; không đọc session thật trong test offline.
+- [x] Test rotation chứng minh token mới được persist trước handshake và được giữ lại khi validation/handshake lỗi.
+- [x] Matrix Ubuntu/Windows × Python 3.9/3.11, wheel/sdist, Twine và smoke cài bằng pip pass tại commit triển khai `8a369d3`.
+- [x] Live gate ghi rõ phần đã kiểm chứng và phần còn thiếu trong [báo cáo](#docs-phase2-verification); đã kiểm campus ngoài tài khoản, phục hồi sau handshake fault injection và chỉ lưu metadata đã che dữ liệu.
+- [x] Review độc lập, kiểm tra tiếng Việt và scan credential/PII trước commit/push; comment từng mốc vào draft PR.
+
+Đã chạy 179 test trên Windows với Python 3.9.25 và 3.11: mỗi môi trường có 176 pass, 3 skip theo điều kiện hệ điều hành/quyền symlink. Build local qua Twine strict, artifact validator và smoke cài wheel/sdist bằng pip. [CI của commit triển khai](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38895605533) đã pass toàn bộ 11 job, gồm đủ matrix; kết quả commit tài liệu cuối được cập nhật qua comment PR.
+
+Live đã xác nhận login mới, ID token validation, handshake, refresh, đọc JSON sau refresh và logout session tạm. News/notification vẫn trả body 201 và không gây refresh. Kiểm tra HCM bằng tài khoản chỉ có APHL trả body 201 và giữ nguyên session; trở lại APHL thành công. Refresh thật kèm timeout handshake được tạo cục bộ giữ token đã rotate; bỏ fault thì handshake và đọc kỳ thành công mà không exchange token lần hai. Chuyển campus thành công, FAP session tự hết hạn và đổi version chưa được xác nhận live; đổi version chờ Phase 3. PR vẫn giữ draft.
+
+## Giới hạn
+
+Không đọc, liệt kê, sao chép hoặc kiểm tra trực tiếp thư mục session cá nhân. Live chỉ chạy CLI theo luồng thông thường; không lưu token, identity, lịch học, bảng điểm hoặc raw response vào Git. Không phát lại HAR/SAZ.
+
+Phase 4 tiếp tục điều tra lỗi backend/contract của news, notification và fee; sửa phân loại 201 không làm các endpoint đó trở thành thành công. Binding chuyển v2 và live đổi API version hoàn tất khi có adapter Phase 3. Auto release vẫn thuộc Phase 5.
+
+## QoL bổ sung trong PR #5
+
+- [x] Bỏ `GetSemester` probe khỏi nạp session; chỉ tra kỳ khi command cần tự chọn kỳ hoặc chạy `semesters`. Các request dữ liệu giữ refresh/retry một lần trên HTTP 401.
+- [x] Buffer 30 giây để refresh access token sớm trước handshake/phục hồi binding; không kéo dài thời hạn token hoặc thay xác minh ID token.
+- [x] Logout dọn session và lock idle. POSIX kiểm lại inode sau acquire để process chờ không dùng khóa đã unlink; Windows giữ lock nếu process khác còn mở handle.
+- [x] Regression command-level về số request, biên buffer và cleanup có process chờ; 191 test chạy trên Windows/Python 3.9/3.11, mỗi môi trường 188 pass và 3 skip.
+- [x] Live QoL: `info student` không có `GetSemester`, `semesters` chỉ một request, `login` dùng session local và logout xóa session/lock tạm. CI commit mới được cập nhật qua comment PR; xem [báo cáo kiểm chứng](#docs-phase2-verification).
+
+## Sửa lỗi sau review PR #5
+
+- [x] Mở rộng expiry v1 cho 17 FAP read operation có `Authen`: body `201` cùng exact message `Token invalid` kích hoạt retry tối đa một lần. Public/survey, handshake, operation ghi và body 201 thiếu/sai message không refresh; news/notification rỗng vẫn là lỗi operation.
+- [x] Login mới không bị binding v2/donor đã lưu chặn; chỉ kế thừa campus. Lệnh đọc và tham số yêu cầu v2/donor rõ ràng vẫn bị chặn trong Phase 2.
+- [x] `myfap login` tự mở trình duyệt khi session cần xác thực lại hoặc binding không được hỗ trợ, thay vì yêu cầu gõ lại `--force`.
+- [x] Thêm leeway 30 giây khi xác minh `exp/iat/nbf` của ID token, tách biệt buffer refresh sớm access token. Giữ strict type/finite và mọi kiểm tra chữ ký/identity.
+- [x] Logout dọn JSON hỏng mà không parse nội dung, giữ lock và guard đường dẫn.
+- [x] Attendance kiểm tra cặp `--subjectcode/--classname` trước khi nạp session hoặc gọi HTTP.
+- [x] Gỡ dependency `pkce` không còn caller và đồng bộ lockfile.
+
+Các lỗi có regression RED trước sửa và GREEN sau sửa. Tổng hợp kết luận, nguồn APK và kết quả kiểm chứng tại [báo cáo review](#docs-phase2-review-fixes); CI của commit cuối được cập nhật trong comment PR.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/phase3.md`
+
+Commit cuối thay đổi file tại commit gốc: `35b5ea1d47c1c52ed814b78ab0cdc39fd59a576c`
+
+# Phase 3: adapter API v2 tối thiểu
+
+Branch `feat/phase3-v2-adapter` bắt đầu từ `origin/main` tại `238c718`, sau khi PR #5 được merge. Version package giữ `0.2.0`. API v1 tiếp tục là mặc định; API v2 chỉ chạy khi được chọn bằng tham số hoặc đã được lưu trong session.
+
+## Phạm vi
+
+- Thêm option global `--api-version v1|v2` và tham số `api_version` cho các wrapper. Thứ tự chọn: tham số, session, mặc định v1. Không tự đổi version sau lỗi mạng hoặc backend.
+- Giữ wrapper và định dạng output hiện tại. V2 hỗ trợ luồng campuses → login → semesters → schedule; GetApiActive phục vụ chẩn đoán. Operation chưa có adapter báo chưa hỗ trợ trước HTTP; parity đầy đủ thuộc Phase 4.
+- Bootstrap dùng POST với JSON rỗng; handshake dùng FEID access token, request dữ liệu dùng FAP authenKey. Campus bootstrap theo từng operation, không lấy campus cố định cho toàn bộ request.
+- Chữ ký v2 dùng HMAC-SHA256 với khóa UTF-8, timestamp giây và padding `%3d` theo APK. Giữ nguyên query/signature v1 và survey.
+- Mọi request dùng timeout đã chọn và không follow redirect. Đọc chỉ retry một lần khi có tín hiệu hết phiên rõ; App Check là lỗi riêng. Không thêm thao tác ghi hoặc cơ chế né App Check.
+- Đổi campus/version phải handshake trước khi lưu binding mới. Giữ token đã rotate nếu bước sau lỗi; không gửi FAP credential của session v1 vào request dữ liệu v2.
+
+## Kiểm chứng
+
+- [x] Contract matrix ghi method/path/query/body/header, nguồn Bearer và signing identity, account type, read/write và retry. Ghi đủ các route v2 giữ query Authen, kể cả route chưa triển khai.
+- [x] Test chữ ký bằng dữ liệu giả, timestamp cố định; ngăn decode khóa hex và double-encoding padding.
+- [x] Test bootstrap, handshake, kỳ học query rỗng, schedule và lỗi unsupported; giữ regression v1.
+- [x] Test lựa chọn version, session legacy, chuyển v1/v2 hai chiều và rollback binding khi handshake lỗi.
+- [x] Test CLI, stdout, timeout, HTTP/body 401, App Check và retry dùng key/chữ ký mới.
+- [x] Local Windows/Python 3.9/3.11, build, Twine strict, artifact validator và pip smoke.
+- [x] Live bằng session tạm riêng: campuses → login → semesters → schedule. Chỉ ghi metadata đã che; phần chưa kiểm chứng phải được ghi rõ.
+- [x] Review độc lập và rà tiếng Việt cho tài liệu, commit, comment PR. PR giữ draft.
+
+Local chạy 261 test trên mỗi phiên bản Python: 257 pass, 4 skip theo điều kiện Windows. Matrix CI Ubuntu/Windows × Python 3.9/3.11 của commit cuối được xác nhận trong [checks PR #7](https://github.com/WindowScary321/myfap-api-cli/pull/7/checks) và comment sau khi hoàn tất.
+
+Live v2 thành công với campus HN sau khi người dùng xác nhận mã campus; lần APHL trả body 401 được ghi riêng. Đổi version và refresh v2 có fixture, chưa xác nhận live riêng. Xem [hướng dẫn version](docs/api-versions.md), [contract](docs/v2-contracts.md) và [báo cáo](#docs-phase3-verification).
+
+Không đọc trực tiếp thư mục session cá nhân, không đưa token, query có credential, raw response, lịch học hoặc điểm thật vào Git. Nguồn contract là tài liệu và module APK trong workspace; capture không được phát lại. Không tạo tag, publish hoặc chuyển mặc định sang v2 trong phase này.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/phase4.md`
+
+Commit cuối thay đổi file tại commit gốc: `b013703a899a008fa0a4db7bd31008eaa142a46e`
+
+# Phase 4: phủ các command đọc hiện có
+
+Nhánh `feat/phase4-command-parity` bắt đầu từ main tại `74dd8e5`, sau khi PR #7 được merge. Giữ version package `0.2.0`, Python >=3.9 và entry point hiện có. V1 tiếp tục là mặc định; v2 được chọn bằng option hoặc session.
+
+## Phạm vi triển khai
+
+- Phủ v2 cho lịch học, lịch tuần, điểm tổng hợp/chi tiết, lịch thi, điểm danh tổng hợp/chi tiết, đơn từ, news, thông tin sinh viên/campus, fee, subjects và các lệnh kiểm tra feedback/profile/notification hiện có.
+- Giữ host và checksum riêng của survey. Không biến trạng thái not-found thành danh sách rỗng hoặc kết luận không có khảo sát bắt buộc.
+- Giữ JSON/ICS, tên trường, lựa chọn kỳ học theo ngày và stdout sạch. Mọi request dùng timeout đã chọn, không follow redirect hoặc fallback version.
+- Giữ query theo từng operation, bao gồm CampusCode, Semester/semester, CourseId và bốn route hiện có vẫn mang Authen. Điểm danh chi tiết dùng GetCourseAttendance trên v2 và getCourseAttendance trên v1.
+- Credential/signature/legacy Authen phải được dựng lại khi retry sau refresh. Chỉ retry đọc một lần khi có tín hiệu expiry rõ; App Check, timeout, 403 và 5xx không kích refresh.
+- Bảng coverage phân biệt bằng chứng APK, capture, fixture, live thành công/thất bại và phần chưa kiểm chứng. HTTP 404 không tự chứng minh route đã ngừng hỗ trợ.
+
+Không thêm transcript, balance, ảnh, news search, GetVersion, form feedback hoặc thao tác ghi vào CLI trong phase này. Những route đó thuộc Phase 6. Không phát hành, tạo tag hay đổi mặc định sang v2.
+
+## Kiểm chứng
+
+- [x] Contract test ở biên HTTP và wrapper cho các route đọc v1/v2; dữ liệu fixture hoàn toàn tổng hợp.
+- [x] CLI test cho nhóm command hiện có, stdout JSON/ICS, capability, option và lỗi trước HTTP.
+- [x] Regression cho retry dùng key/checksum/Authen mới và giới hạn một lần.
+- [x] Kiểm tra ICS bằng dữ liệu tổng hợp và một reader độc lập; ghi rõ giới hạn của reader hiện tại nếu còn.
+- [x] Live trên session tạm riêng, không đọc thư mục session cá nhân. Chỉ giữ metadata đã lọc, không giữ lịch/điểm/hồ sơ hoặc credential thật trong Git.
+- [x] Chạy lại news, notification và fee của v1; ghi nguyên trạng lỗi còn lại và giới hạn theo version/campus. Không dùng CI xanh thay kết luận live.
+- [x] Review độc lập, kiểm tra tiếng Việt, test Python 3.9/3.11, build, Twine, artifact validator và pip smoke.
+- [x] Draft PR riêng, comment tiếng Việt sau các mốc quan trọng; maintainer quyết định Ready for review và merge.
+
+Đã có bằng chứng cho 8 mục trong phạm vi kiểm chứng hiện tại. Theo quyết định của người dùng ngày 19/10/2026, positive fee/survey được chuyển sang [TODO chờ dữ liệu phù hợp](tasks/todo.md#kiểm-chứng-hoãn-chờ-dữ-liệu-phù-hợp), không chặn chuyển sang Phase 5. Contract và CLI được kiểm tra tại `tests/test_phase4_transport.py`, `tests/test_api_v2.py`, `tests/test_cli_v2_capabilities.py` và các regression v1. Test ICS dùng reader `icalendar` độc lập. Kết quả live v2 HN đã ghi 21 operation khác nhau, 23 request và dọn session/lock tạm; xem [coverage Phase 4](docs/phase4-coverage.md). Matrix Ubuntu/Windows × Python 3.9/3.11, build và cài artifact được ghi tại [checks PR #8](https://github.com/WindowScary321/myfap-api-cli/pull/8/checks).
+
+Đã chạy lại ba lệnh v1/APHL ngày 19/10/2026 với login mới: news/notification vẫn trả HTTP 200/body 201, fee vẫn trả HTTP 404; lệnh đối chứng đọc thông tin sinh viên đạt 200/200 trước và sau. Session và lock tạm đã dọn. Mục chạy lại live được đánh dấu vì đã có kết quả và giới hạn, không có nghĩa ba lỗi response đã được sửa. Xem [kết quả v1](docs/phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
+
+Positive fee/survey được hoãn, schema live vẫn chưa kiểm chứng: fee v2 trả HTTP/body 200 chưa đủ để kết luận positive case, còn survey trả body 404. Các lỗi response v1 vẫn mở trong TODO; chưa có cơ sở suy ra body 201 là rỗng hợp lệ hoặc HTTP 404 là route ngừng hỗ trợ toàn bộ. Các ô đã đánh dấu không có nghĩa mọi route đều đã hoạt động hoặc toàn bộ schema live đã được xác nhận.
+
+Parser điểm đã được sửa cho cấu trúc ba cột `Item`, `Weight`, `Value` khi không có cột ghi chú, gồm cả dòng đầu tiên và dòng tiếp theo trong `rowspan`. Hàng ba `| ` theo fallback category/item/value cũ vẫn được giữ để tránh thay đổi output tương thích.
+
+Xuất ICS cũng đã xử lý khoảng trắng quanh dấu `-` và dấu ngoặc trong `slotTime`; regression xác nhận giờ bắt đầu/kết thúc không thay đổi. Hai lỗi parser được tái hiện và kiểm thử bằng dữ liệu tổng hợp, chưa dùng dữ liệu tài khoản thật trong lượt sửa này.
+
+Các bản sửa bổ sung xử lý bảng Rich trên stdout `cp1252`, cho `login` tự phục hồi session sai cấu trúc và thêm nhóm dependency `ci` vào hai bước sync/test của workflow publish. Việc này sửa lỗi thiếu `icalendar` trên runner sạch; pipeline tag → reusable CI → publish → smoke → GitHub Release của Phase 5 vẫn chưa được triển khai. Không chạy publish hoặc thay đổi trigger release trong lượt sửa này.
+
+Sau bàn giao 19/10/2026, đã sửa thêm refresh `invalid_grant` không đánh dấu cần đăng nhập lại, student session thiếu `mssv`/`email`, help trên stdout `cp1252` và ICS thiếu `DTSTAMP`. Bộ test có 313 case; các nhánh lỗi session dùng fixture. Live v2/HN đã xác nhận login, refresh, đọc dữ liệu và ICS có đủ `UID`/`DTSTAMP` UTC, sau đó dọn session/lock tạm. Xem [kết quả sau sửa](docs/phase4-coverage.md#kiểm-chứng-sau-bàn-giao-ngày-19102026); không dùng kết quả này đóng các TODO live v1 hoặc positive fee/survey.
+
+## Quy tắc dữ liệu và thiết bị
+
+Fiddler và Android chỉ phục vụ đối chiếu luồng đọc đã được cho phép. Dữ liệu request/response hoặc màn hình được xử lý cục bộ; chỉ tên operation, method, HTTP/body code, kiểu dữ liệu và kết quả kiểm tra được xuất ra. Không replay token từ capture, không đọc hoặc in token bằng tool, không gửi dữ liệu cá nhân ra ngoài PC. Không thay proxy, certificate, quyền truy cập hoặc dữ liệu tài khoản nếu không cần cho phép thử.
+
+Các kết quả live chưa đạt vẫn phải được ghi trong coverage. Nếu backend chưa đáp ứng hoặc thiếu positive case, phạm vi phát hành cần maintainer quyết định; không đánh dấu parity đầy đủ chỉ từ fixture.
+
+
+
+---
+
+Đường dẫn ban đầu: `tasks/plan.md`
+
+Commit cuối thay đổi file tại commit gốc: `60c6a9c0193b00eed5fee7c4633abca816e6a569`
+
+# Kế hoạch chuyển quy trình dev sang uv
+
+## Phạm vi
+
+Quản lý môi trường dev và dependencies bằng uv; sửa `myfap version` để đọc metadata của package `myfap`. Giữ setuptools, tên package và phạm vi Python >=3.9. Bump phiên bản lên 0.1.8 cho thay đổi này.
+
+## Thứ tự thực hiện
+
+1. Chọn Python 3.11 cho dev, tạo `uv.lock` và hướng dẫn README. Xác nhận `uv sync --locked` cài được package ở chế độ editable.
+2. Thêm regression test qua lệnh CLI `version`, xác nhận test thất bại trước khi sửa tên distribution và thành công sau khi sửa.
+3. Chuyển build CI sang uv, chạy test trên PR và giữ Trusted Publishing khi có release. Kiểm tra wheel và source distribution.
+4. Review diff, kiểm tra tiếng Việt, tạo hai commit theo phạm vi và mở PR mới kèm bình luận kết quả kiểm tra.
+
+## Rủi ro và cách kiểm tra
+
+- Dependencies hiện chỉ có giới hạn phiên bản tối thiểu: lockfile cố định các phiên bản đã resolve; kiểm tra cài đặt và CLI trên Python 3.9/3.11.
+- `greenlet` 3.2.5 thiếu wheel Python 3.9 trên Windows: giới hạn phiên bản qua cấu hình uv cho đúng môi trường này để tránh yêu cầu compiler C++.
+- Playwright cần browser riêng khi đăng nhập: ghi rõ Chrome/Edge và Firefox dự phòng trong README; test version không đăng nhập hay gọi API.
+- Môi trường dev và package phát hành khác nhau: kiểm tra `myfap version` cả sau editable install và sau cài wheel.
+
+Danh sách công việc và trạng thái nằm trong [todo.md](tasks/todo.md).
diff --git a/tasks/phase0.md b/tasks/phase0.md
deleted file mode 100644
index 8ba937f..0000000
--- a/tasks/phase0.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Phase 0 — CI và artifact cho mốc v0.2.0
-
-PR theo dõi: [PR 2](https://github.com/WindowScary321/myfap-api-cli/pull/2). Mọi commit của phase này được push vào `feat/phase0-v0.2.0`; các comment ghi mốc kiểm tra, commit và kết quả CI.
-
-## Phạm vi
-
-Gia cố CI trước các phase sửa v1, OAuth/session và v2. Version package được chuẩn bị thành `0.2.0` trong PR này; chưa tạo tag, publish PyPI hoặc triển khai auto release của Phase 5. Kế hoạch migration uv `0.1.8` trong `tasks/plan.md` và `tasks/todo.md` là lịch sử đã hoàn tất, giữ nguyên.
-
-## Công việc
-
-- [x] Tách branch từ `origin/main`, tạo PR và đồng bộ version với lockfile.
-- [x] Thêm nhóm dependency CI đã khóa; chuyển marker greenlet vào metadata runtime sau khi tái hiện lỗi pip Windows/Python 3.9 cần compiler.
-- [x] Thêm artifact gate cho version, entry point, README/license, file allowlist và manifest SHA-256.
-- [x] Kiểm tra cả wheel/sdist trong venv riêng ngoài checkout bằng pip; chạy check/version/help và ép UTF-8 cho subprocess.
-- [x] Chuyển CI thành source matrix → build Ubuntu một lần → artifact matrix → gate cuối; hỗ trợ reusable workflow outputs.
-- [x] Pin action theo commit SHA, giữ quyền `contents: read` và tắt persist Git credential.
-- [x] Thêm unit test với archive giả, version/hash sai, đường dẫn nhạy cảm, symlink, smoke isolation và UTF-8.
-- [x] Xác nhận source và artifact trên cả bốn môi trường GitHub Actions; tiếp tục kiểm tra lại khi PR có commit mới.
-- [x] Ghi các mốc commit/kiểm tra bằng comment và tổng hợp bằng chứng trong PR.
-
-## Kiểm chứng
-
-- Unit suite local: 32 test pass sau phần mở rộng, gồm regression version và các case scope/ready. Thử đảo điều kiện kiểm manifest khiến test hash thất bại; khôi phục code và suite pass lại.
-- `uv build`, `twine check --strict`, artifact validation và actionlint pass.
-- Pip smoke thật trên Windows/Python 3.9 và 3.11 pass cho wheel lẫn sdist; bốn tổ hợp OS/Python trên GitHub Actions đều pass.
-- [Run CI 38852306858](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38852306858) của commit `393ced9`: 10/10 job thành công. Kết quả commit mới nhất được cập nhật trong PR.
-
-## Giới hạn
-
-CI không đăng nhập FEID hoặc gọi API FAP thật. Allowlist chỉ chặn đường dẫn/file ngoài chính sách; không chứng minh được không có secret hoặc PII ẩn trong nội dung mã Python. Kết quả Phase 0 không xác nhận OAuth/API v1/v2 đã được sửa.
-
-## Mở rộng: docs/tasks chỉ lưu trong repository
-
-- [x] Thêm `scope` lấy danh sách tên path Git, không đọc nội dung hai thư mục. Rename được xét như delete/add để đổi tên từ code sang docs hoặc ngược lại vẫn chạy đầy đủ CI.
-- [x] Chỉ thay đổi `docs/**` hoặc `tasks/**`: bỏ qua source/build/smoke, không tạo artifact; `ready` vẫn trả success. Thay đổi code/mixed và mọi `workflow_call` chạy đủ gate.
-- [x] `ready` dùng `always()` nhưng xác minh trạng thái từng job, không che lỗi/cancel hoặc trạng thái không xác định.
-- [x] Sparse checkout chỉ giữ code/tests/helpers và file build; không checkout docs/tasks trong các job CI. README/license root vẫn được giữ.
-- [x] Dùng `MANIFEST.in` loại hai thư mục khi build full checkout; validator từ chối docs/tasks trong wheel và sdist.
-- [x] Bổ sung test docs-only/tasks-only, code/mixed, rename/delete, reusable call và gate lỗi; artifact giả kiểm tra cả hai định dạng.
-- Kết quả pipeline của commit mở rộng trên GitHub Actions được theo dõi trong check của PR; comment ghi link run và commit tương ứng.
-
-Phần mở rộng giữ nguyên runtime API, entry point, version và các workflow outputs artifact đã có. Không thêm tài liệu vào `package-data` hoặc `data-files`.
diff --git a/tasks/phase1.md b/tasks/phase1.md
deleted file mode 100644
index 212eb97..0000000
--- a/tasks/phase1.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Phase 1: sửa v1 và lỗi dữ liệu
-
-## Phạm vi
-
-Tiếp nối Phase 0 trên phiên bản `0.2.0`, branch `fix/phase1-v1-data`. API v1 vẫn là mặc định. Công việc gồm query, payload, chọn kỳ học, survey, học phí, stdout và parser. OAuth/session đầy đủ, adapter v2 và auto release thuộc các phase sau.
-
-**Trạng thái sau kiểm chứng API thật ngày 16/10/2026:** phần triển khai và kiểm thử offline đã xong; live còn ba command chưa hoạt động. Chi tiết nằm trong [báo cáo kiểm chứng live](../docs/phase1-live-verification.md).
-
-## Các bước và tiêu chí hoàn tất
-
-- [x] Chuyển mọi query v1 sang `params=`, gồm kiểm tra session và handshake login/refresh; giữ nguyên case từng trường và kiểm tra encoding bằng credential giả.
-- [x] Kiểm tra HTTP, JSON và body code riêng; bảo toàn envelope và kiểu `data`. Survey not-found không bị diễn giải thành hết phiên hay không còn survey bắt buộc.
-- [x] Chọn kỳ theo `startDate`, giữ thứ tự server khi trùng ngày; ngày lỗi yêu cầu `--semester`, flag explicit không gọi resolver tự động.
-- [x] Tách checksum survey theo contract của app: username trim/lower, campus rỗng, khóa riêng và giờ Việt Nam.
-- [x] Dùng route v1 `GeFeeByRoll` đã đối chiếu với APK; HTTP 404 là lỗi, giữ mọi dòng học phí và `IsPaid`.
-- [x] Giữ stdout chỉ có JSON/ICS khi dùng `--stdout`; log/lỗi đi stderr. `--date` suy ra năm khi thiếu `--year`.
-- [x] Thêm fixture tổng hợp HTML có rowspan/colspan và lịch ICS; chỉ sửa parser khi regression test tái hiện lỗi.
-- [x] Chạy regression trên Python 3.9/3.11, build wheel/sdist mới, Twine strict, artifact gate và cài thử ngoài checkout.
-- [x] Review độc lập, kiểm tra diff và nội dung tiếng Việt; mở draft PR, ghi kết quả kiểm tra qua comment, giữ trạng thái draft.
-- [x] Chạy command trực tiếp với session mẫu; kiểm chứng 20 route, chỉ lưu kết quả đã che dữ liệu.
-- [ ] Giải quyết code 201 của `news` và `other notification`; chưa kết luận đây là lỗi hết phiên.
-- [ ] Xác minh endpoint học phí v1 vì cả `GeFeeByRoll` và phép chẩn đoán `GetFeeByRoll` đều trả HTTP 404.
-
-## Cơ sở đối chiếu
-
-- Kế hoạch chi tiết: `PLAN-PHASES.md`, Phase 1, ở workspace phân tích.
-- Bản so sánh: `analysis/myfap-api-cli-comparison.md` và `analysis/endpoints.md`.
-- Contract v1: `analysis/modules/module_550.js`, gồm route học phí và helper survey.
-- HAR/SAZ ngày 14/10 chỉ xác nhận runtime v2 và survey. Không coi đây là kiểm thử live v1.
-
-Fixture dùng dữ liệu giả, không chứa token, authenKey, chữ ký thực hoặc thông tin cá nhân. `docs/` và `tasks/` chỉ phục vụ đọc trong repository, không thuộc wheel/sdist hoặc phạm vi kiểm tra code của CI.
-
-## Kiểm chứng
-
-Trước thay đổi có 32 unittest. Suite mới tái hiện lỗi query, thứ tự kỳ, học phí HTTP 404, survey, stdout, ngày/năm và rowspan trước khi sửa. Kết quả sau sửa:
-
-- 88 unittest ban đầu; sau bổ sung `--timeout` trong PR #4, suite có 96 test và pass Ubuntu/Windows × Python 3.9/3.11.
-- Mutation đảo thứ tự ngày và sửa sai bộ đếm rowspan đều bị regression test bắt.
-- ICS pass trên Python 3.9 không có `tzdata`, dùng `pytz` sẵn có.
-- Twine strict và artifact validator pass với wheel/sdist mới; pip cài được cả hai artifact trong hai venv riêng ngoài checkout.
-- Mã runtime trong artifact khớp source. `docs/`, `tasks/` và `tests/` không nằm trong artifact; fixture chỉ phục vụ CI từ checkout.
-- Validator tiếng Việt strict không có lỗi hoặc cảnh báo; diff không có lỗi whitespace. Đã review độc lập và đối chiếu giá trị credential/identity từ capture bằng script, chỉ xuất kết quả không trùng, không in giá trị.
-
-PR [#4](https://github.com/WindowScary321/myfap-api-cli/pull/4) đã merge vào branch Phase 1. [CI sau merge timeout](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38875363915) pass cả 11 job trên commit `07fb289` của PR [#3](https://github.com/WindowScary321/myfap-api-cli/pull/3). Trạng thái review/merge do maintainer quyết định; không tự chuyển Ready for review hoặc merge.
-
-Kiểm chứng live trên commit đó: 25 lần chạy command, 22 exit 0 và 3 exit 1, phủ 20 route. Lịch, điểm chi tiết, điểm danh, thông tin, đơn từ, môn học và survey not-found đã có bằng chứng runtime v1. Ba lỗi còn lại được ghi riêng, không bỏ qua trong kết luận.
-
-## Giới hạn
-
-Đã kiểm thử server v1 qua CLI với một session mẫu, không đọc trực tiếp thư mục chứa session. Fixture survey thành công và học phí v1 vẫn là dữ liệu tổng hợp: live chỉ quan sát survey not-found và học phí HTTP 404. Chưa xác minh nhiều tài khoản/campus hoặc đối chiếu toàn bộ nội dung với app chính.
-
-Phase 2 tiếp tục xử lý token validation, campus binding, session lock/atomic write và refresh rotation. Phase 1 không triển khai adapter v2, auto release, tag hoặc publish PyPI. Rollback dùng revert các commit trong PR; không có migration dữ liệu.
diff --git a/tasks/phase2.md b/tasks/phase2.md
deleted file mode 100644
index c6691bc..0000000
--- a/tasks/phase2.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Phase 2: OAuth và session
-
-## Phạm vi và thứ tự
-
-Branch `feat/phase2-oauth-session` bắt đầu từ `main` sau PR #3. Giữ version `0.2.0`, API v1 và Playwright. PR riêng phải ở trạng thái draft; chỉ maintainer quyết định chuyển Ready for review hoặc merge.
-
-1. Phân loại lỗi theo version/operation/HTTP/body. Code 201 chưa rõ nghĩa không gây refresh/logout; đọc chỉ retry một lần khi có tín hiệu hết phiên rõ ràng.
-2. Kiểm tra callback chính xác, state/nonce và PKCE mới mỗi login. Dùng discovery và xác minh ID token RS256 bằng JWKS, issuer/audience/azp/exp/sub/nonce/at_hash.
-3. Lưu session atomic và dùng lock xuyên suốt read → refresh → persist. Lưu refresh token mới trước validation/handshake tiếp theo; lỗi sau rotation không được quay về token cũ.
-4. Chọn campus theo parameter → session → default khi login mới. Binding campus/version/account type phải hợp lệ trước request dữ liệu; identity lấy từ handshake, không decode access token để suy MSSV.
-5. Giữ timeout đã có cho discovery/JWKS/token/handshake/API. Kiểm tra offline, build và smoke artifact trước gate live riêng.
-
-## Hợp đồng giữa các phần
-
-- `errors.py`: lỗi an toàn, không chứa credential, response hoặc URL có query; phân loại theo context của operation.
-- `oidc.py`: discovery, login attempt, callback, token request và validation tách biệt để persist rotation trước bước có thể lỗi.
-- `storage.py`: đọc JSON, ghi atomic và khóa file; chỉ auth orchestration điều phối transaction.
-- `auth.py`: vòng đời OAuth/FAP session, binding, identity handshake và rotation; CLI không tự mở file session để refresh.
-- `api.py`: kiểm binding và retry đọc có giới hạn; payload/output hiện có được giữ nguyên.
-
-Các module mới phục vụ trust boundary và tránh circular import; không thêm framework hoặc adapter v2 trong Phase 2.
-
-## Checklist
-
-- [x] Regression cho hai body 201 và ma trận HTTP/body 401, App Check, timeout/5xx, read/write retry.
-- [x] Callback/OIDC có test âm về chữ ký, issuer, audience/azp, nonce, expiry và at_hash; refresh có thể thiếu ID token nhưng nếu có phải cùng subject.
-- [x] Session cũ thiếu version được hiểu là v1; đổi binding bị chặn trước HTTP dữ liệu, handshake lỗi không ghi nhầm binding.
-- [x] Atomic write và lock được kiểm bằng file tạm/process riêng trên Windows và Unix; không đọc session thật trong test offline.
-- [x] Test rotation chứng minh token mới được persist trước handshake và được giữ lại khi validation/handshake lỗi.
-- [x] Matrix Ubuntu/Windows × Python 3.9/3.11, wheel/sdist, Twine và smoke cài bằng pip pass tại commit triển khai `8a369d3`.
-- [x] Live gate ghi rõ phần đã kiểm chứng và phần còn thiếu trong [báo cáo](../docs/phase2-verification.md); đã kiểm campus ngoài tài khoản, phục hồi sau handshake fault injection và chỉ lưu metadata đã che dữ liệu.
-- [x] Review độc lập, kiểm tra tiếng Việt và scan credential/PII trước commit/push; comment từng mốc vào draft PR.
-
-Đã chạy 179 test trên Windows với Python 3.9.25 và 3.11: mỗi môi trường có 176 pass, 3 skip theo điều kiện hệ điều hành/quyền symlink. Build local qua Twine strict, artifact validator và smoke cài wheel/sdist bằng pip. [CI của commit triển khai](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38895605533) đã pass toàn bộ 11 job, gồm đủ matrix; kết quả commit tài liệu cuối được cập nhật qua comment PR.
-
-Live đã xác nhận login mới, ID token validation, handshake, refresh, đọc JSON sau refresh và logout session tạm. News/notification vẫn trả body 201 và không gây refresh. Kiểm tra HCM bằng tài khoản chỉ có APHL trả body 201 và giữ nguyên session; trở lại APHL thành công. Refresh thật kèm timeout handshake được tạo cục bộ giữ token đã rotate; bỏ fault thì handshake và đọc kỳ thành công mà không exchange token lần hai. Chuyển campus thành công, FAP session tự hết hạn và đổi version chưa được xác nhận live; đổi version chờ Phase 3. PR vẫn giữ draft.
-
-## Giới hạn
-
-Không đọc, liệt kê, sao chép hoặc kiểm tra trực tiếp thư mục session cá nhân. Live chỉ chạy CLI theo luồng thông thường; không lưu token, identity, lịch học, bảng điểm hoặc raw response vào Git. Không phát lại HAR/SAZ.
-
-Phase 4 tiếp tục điều tra lỗi backend/contract của news, notification và fee; sửa phân loại 201 không làm các endpoint đó trở thành thành công. Binding chuyển v2 và live đổi API version hoàn tất khi có adapter Phase 3. Auto release vẫn thuộc Phase 5.
-
-## QoL bổ sung trong PR #5
-
-- [x] Bỏ `GetSemester` probe khỏi nạp session; chỉ tra kỳ khi command cần tự chọn kỳ hoặc chạy `semesters`. Các request dữ liệu giữ refresh/retry một lần trên HTTP 401.
-- [x] Buffer 30 giây để refresh access token sớm trước handshake/phục hồi binding; không kéo dài thời hạn token hoặc thay xác minh ID token.
-- [x] Logout dọn session và lock idle. POSIX kiểm lại inode sau acquire để process chờ không dùng khóa đã unlink; Windows giữ lock nếu process khác còn mở handle.
-- [x] Regression command-level về số request, biên buffer và cleanup có process chờ; 191 test chạy trên Windows/Python 3.9/3.11, mỗi môi trường 188 pass và 3 skip.
-- [x] Live QoL: `info student` không có `GetSemester`, `semesters` chỉ một request, `login` dùng session local và logout xóa session/lock tạm. CI commit mới được cập nhật qua comment PR; xem [báo cáo kiểm chứng](../docs/phase2-verification.md).
-
-## Sửa lỗi sau review PR #5
-
-- [x] Mở rộng expiry v1 cho 17 FAP read operation có `Authen`: body `201` cùng exact message `Token invalid` kích hoạt retry tối đa một lần. Public/survey, handshake, operation ghi và body 201 thiếu/sai message không refresh; news/notification rỗng vẫn là lỗi operation.
-- [x] Login mới không bị binding v2/donor đã lưu chặn; chỉ kế thừa campus. Lệnh đọc và tham số yêu cầu v2/donor rõ ràng vẫn bị chặn trong Phase 2.
-- [x] `myfap login` tự mở trình duyệt khi session cần xác thực lại hoặc binding không được hỗ trợ, thay vì yêu cầu gõ lại `--force`.
-- [x] Thêm leeway 30 giây khi xác minh `exp/iat/nbf` của ID token, tách biệt buffer refresh sớm access token. Giữ strict type/finite và mọi kiểm tra chữ ký/identity.
-- [x] Logout dọn JSON hỏng mà không parse nội dung, giữ lock và guard đường dẫn.
-- [x] Attendance kiểm tra cặp `--subjectcode/--classname` trước khi nạp session hoặc gọi HTTP.
-- [x] Gỡ dependency `pkce` không còn caller và đồng bộ lockfile.
-
-Các lỗi có regression RED trước sửa và GREEN sau sửa. Tổng hợp kết luận, nguồn APK và kết quả kiểm chứng tại [báo cáo review](../docs/phase2-review-fixes.md); CI của commit cuối được cập nhật trong comment PR.
diff --git a/tasks/phase3.md b/tasks/phase3.md
deleted file mode 100644
index b5d476e..0000000
--- a/tasks/phase3.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Phase 3: adapter API v2 tối thiểu
-
-Branch `feat/phase3-v2-adapter` bắt đầu từ `origin/main` tại `238c718`, sau khi PR #5 được merge. Version package giữ `0.2.0`. API v1 tiếp tục là mặc định; API v2 chỉ chạy khi được chọn bằng tham số hoặc đã được lưu trong session.
-
-## Phạm vi
-
-- Thêm option global `--api-version v1|v2` và tham số `api_version` cho các wrapper. Thứ tự chọn: tham số, session, mặc định v1. Không tự đổi version sau lỗi mạng hoặc backend.
-- Giữ wrapper và định dạng output hiện tại. V2 hỗ trợ luồng campuses → login → semesters → schedule; GetApiActive phục vụ chẩn đoán. Operation chưa có adapter báo chưa hỗ trợ trước HTTP; parity đầy đủ thuộc Phase 4.
-- Bootstrap dùng POST với JSON rỗng; handshake dùng FEID access token, request dữ liệu dùng FAP authenKey. Campus bootstrap theo từng operation, không lấy campus cố định cho toàn bộ request.
-- Chữ ký v2 dùng HMAC-SHA256 với khóa UTF-8, timestamp giây và padding `%3d` theo APK. Giữ nguyên query/signature v1 và survey.
-- Mọi request dùng timeout đã chọn và không follow redirect. Đọc chỉ retry một lần khi có tín hiệu hết phiên rõ; App Check là lỗi riêng. Không thêm thao tác ghi hoặc cơ chế né App Check.
-- Đổi campus/version phải handshake trước khi lưu binding mới. Giữ token đã rotate nếu bước sau lỗi; không gửi FAP credential của session v1 vào request dữ liệu v2.
-
-## Kiểm chứng
-
-- [x] Contract matrix ghi method/path/query/body/header, nguồn Bearer và signing identity, account type, read/write và retry. Ghi đủ các route v2 giữ query Authen, kể cả route chưa triển khai.
-- [x] Test chữ ký bằng dữ liệu giả, timestamp cố định; ngăn decode khóa hex và double-encoding padding.
-- [x] Test bootstrap, handshake, kỳ học query rỗng, schedule và lỗi unsupported; giữ regression v1.
-- [x] Test lựa chọn version, session legacy, chuyển v1/v2 hai chiều và rollback binding khi handshake lỗi.
-- [x] Test CLI, stdout, timeout, HTTP/body 401, App Check và retry dùng key/chữ ký mới.
-- [x] Local Windows/Python 3.9/3.11, build, Twine strict, artifact validator và pip smoke.
-- [x] Live bằng session tạm riêng: campuses → login → semesters → schedule. Chỉ ghi metadata đã che; phần chưa kiểm chứng phải được ghi rõ.
-- [x] Review độc lập và rà tiếng Việt cho tài liệu, commit, comment PR. PR giữ draft.
-
-Local chạy 261 test trên mỗi phiên bản Python: 257 pass, 4 skip theo điều kiện Windows. Matrix CI Ubuntu/Windows × Python 3.9/3.11 của commit cuối được xác nhận trong [checks PR #7](https://github.com/WindowScary321/myfap-api-cli/pull/7/checks) và comment sau khi hoàn tất.
-
-Live v2 thành công với campus HN sau khi người dùng xác nhận mã campus; lần APHL trả body 401 được ghi riêng. Đổi version và refresh v2 có fixture, chưa xác nhận live riêng. Xem [hướng dẫn version](../docs/api-versions.md), [contract](../docs/v2-contracts.md) và [báo cáo](../docs/phase3-verification.md).
-
-Không đọc trực tiếp thư mục session cá nhân, không đưa token, query có credential, raw response, lịch học hoặc điểm thật vào Git. Nguồn contract là tài liệu và module APK trong workspace; capture không được phát lại. Không tạo tag, publish hoặc chuyển mặc định sang v2 trong phase này.
diff --git a/tasks/phase4.md b/tasks/phase4.md
deleted file mode 100644
index c605759..0000000
--- a/tasks/phase4.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Phase 4: phủ các command đọc hiện có
-
-Nhánh `feat/phase4-command-parity` bắt đầu từ main tại `74dd8e5`, sau khi PR #7 được merge. Giữ version package `0.2.0`, Python >=3.9 và entry point hiện có. V1 tiếp tục là mặc định; v2 được chọn bằng option hoặc session.
-
-## Phạm vi triển khai
-
-- Phủ v2 cho lịch học, lịch tuần, điểm tổng hợp/chi tiết, lịch thi, điểm danh tổng hợp/chi tiết, đơn từ, news, thông tin sinh viên/campus, fee, subjects và các lệnh kiểm tra feedback/profile/notification hiện có.
-- Giữ host và checksum riêng của survey. Không biến trạng thái not-found thành danh sách rỗng hoặc kết luận không có khảo sát bắt buộc.
-- Giữ JSON/ICS, tên trường, lựa chọn kỳ học theo ngày và stdout sạch. Mọi request dùng timeout đã chọn, không follow redirect hoặc fallback version.
-- Giữ query theo từng operation, bao gồm CampusCode, Semester/semester, CourseId và bốn route hiện có vẫn mang Authen. Điểm danh chi tiết dùng GetCourseAttendance trên v2 và getCourseAttendance trên v1.
-- Credential/signature/legacy Authen phải được dựng lại khi retry sau refresh. Chỉ retry đọc một lần khi có tín hiệu expiry rõ; App Check, timeout, 403 và 5xx không kích refresh.
-- Bảng coverage phân biệt bằng chứng APK, capture, fixture, live thành công/thất bại và phần chưa kiểm chứng. HTTP 404 không tự chứng minh route đã ngừng hỗ trợ.
-
-Không thêm transcript, balance, ảnh, news search, GetVersion, form feedback hoặc thao tác ghi vào CLI trong phase này. Những route đó thuộc Phase 6. Không phát hành, tạo tag hay đổi mặc định sang v2.
-
-## Kiểm chứng
-
-- [x] Contract test ở biên HTTP và wrapper cho các route đọc v1/v2; dữ liệu fixture hoàn toàn tổng hợp.
-- [x] CLI test cho nhóm command hiện có, stdout JSON/ICS, capability, option và lỗi trước HTTP.
-- [x] Regression cho retry dùng key/checksum/Authen mới và giới hạn một lần.
-- [x] Kiểm tra ICS bằng dữ liệu tổng hợp và một reader độc lập; ghi rõ giới hạn của reader hiện tại nếu còn.
-- [x] Live trên session tạm riêng, không đọc thư mục session cá nhân. Chỉ giữ metadata đã lọc, không giữ lịch/điểm/hồ sơ hoặc credential thật trong Git.
-- [x] Chạy lại news, notification và fee của v1; ghi nguyên trạng lỗi còn lại và giới hạn theo version/campus. Không dùng CI xanh thay kết luận live.
-- [x] Review độc lập, kiểm tra tiếng Việt, test Python 3.9/3.11, build, Twine, artifact validator và pip smoke.
-- [x] Draft PR riêng, comment tiếng Việt sau các mốc quan trọng; maintainer quyết định Ready for review và merge.
-
-Đã có bằng chứng cho 8 mục trong phạm vi kiểm chứng hiện tại. Theo quyết định của người dùng ngày 19/10/2026, positive fee/survey được chuyển sang [TODO chờ dữ liệu phù hợp](todo.md#kiểm-chứng-hoãn-chờ-dữ-liệu-phù-hợp), không chặn chuyển sang Phase 5. Contract và CLI được kiểm tra tại `tests/test_phase4_transport.py`, `tests/test_api_v2.py`, `tests/test_cli_v2_capabilities.py` và các regression v1. Test ICS dùng reader `icalendar` độc lập. Kết quả live v2 HN đã ghi 21 operation khác nhau, 23 request và dọn session/lock tạm; xem [coverage Phase 4](../docs/phase4-coverage.md). Matrix Ubuntu/Windows × Python 3.9/3.11, build và cài artifact được ghi tại [checks PR #8](https://github.com/WindowScary321/myfap-api-cli/pull/8/checks).
-
-Đã chạy lại ba lệnh v1/APHL ngày 19/10/2026 với login mới: news/notification vẫn trả HTTP 200/body 201, fee vẫn trả HTTP 404; lệnh đối chứng đọc thông tin sinh viên đạt 200/200 trước và sau. Session và lock tạm đã dọn. Mục chạy lại live được đánh dấu vì đã có kết quả và giới hạn, không có nghĩa ba lỗi response đã được sửa. Xem [kết quả v1](../docs/phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
-
-Positive fee/survey được hoãn, schema live vẫn chưa kiểm chứng: fee v2 trả HTTP/body 200 chưa đủ để kết luận positive case, còn survey trả body 404. Các lỗi response v1 vẫn mở trong TODO; chưa có cơ sở suy ra body 201 là rỗng hợp lệ hoặc HTTP 404 là route ngừng hỗ trợ toàn bộ. Các ô đã đánh dấu không có nghĩa mọi route đều đã hoạt động hoặc toàn bộ schema live đã được xác nhận.
-
-Parser điểm đã được sửa cho cấu trúc ba cột `Item`, `Weight`, `Value` khi không có cột ghi chú, gồm cả dòng đầu tiên và dòng tiếp theo trong `rowspan`. Hàng ba ` | ` theo fallback category/item/value cũ vẫn được giữ để tránh thay đổi output tương thích.
-
-Xuất ICS cũng đã xử lý khoảng trắng quanh dấu `-` và dấu ngoặc trong `slotTime`; regression xác nhận giờ bắt đầu/kết thúc không thay đổi. Hai lỗi parser được tái hiện và kiểm thử bằng dữ liệu tổng hợp, chưa dùng dữ liệu tài khoản thật trong lượt sửa này.
-
-Các bản sửa bổ sung xử lý bảng Rich trên stdout `cp1252`, cho `login` tự phục hồi session sai cấu trúc và thêm nhóm dependency `ci` vào hai bước sync/test của workflow publish. Việc này sửa lỗi thiếu `icalendar` trên runner sạch; pipeline tag → reusable CI → publish → smoke → GitHub Release của Phase 5 vẫn chưa được triển khai. Không chạy publish hoặc thay đổi trigger release trong lượt sửa này.
-
-Sau bàn giao 19/10/2026, đã sửa thêm refresh `invalid_grant` không đánh dấu cần đăng nhập lại, student session thiếu `mssv`/`email`, help trên stdout `cp1252` và ICS thiếu `DTSTAMP`. Bộ test có 313 case; các nhánh lỗi session dùng fixture. Live v2/HN đã xác nhận login, refresh, đọc dữ liệu và ICS có đủ `UID`/`DTSTAMP` UTC, sau đó dọn session/lock tạm. Xem [kết quả sau sửa](../docs/phase4-coverage.md#kiểm-chứng-sau-bàn-giao-ngày-19102026); không dùng kết quả này đóng các TODO live v1 hoặc positive fee/survey.
-
-## Quy tắc dữ liệu và thiết bị
-
-Fiddler và Android chỉ phục vụ đối chiếu luồng đọc đã được cho phép. Dữ liệu request/response hoặc màn hình được xử lý cục bộ; chỉ tên operation, method, HTTP/body code, kiểu dữ liệu và kết quả kiểm tra được xuất ra. Không replay token từ capture, không đọc hoặc in token bằng tool, không gửi dữ liệu cá nhân ra ngoài PC. Không thay proxy, certificate, quyền truy cập hoặc dữ liệu tài khoản nếu không cần cho phép thử.
-
-Các kết quả live chưa đạt vẫn phải được ghi trong coverage. Nếu backend chưa đáp ứng hoặc thiếu positive case, phạm vi phát hành cần maintainer quyết định; không đánh dấu parity đầy đủ chỉ từ fixture.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 118be59..eabc295 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -6,7 +6,7 @@ Nhóm command đọc đã có implementation và fixture CLI/HTTP; xem [coverage
## Quy tắc xuyên suốt
-- Tái sử dụng wrapper, common options, resolver kỳ và output JSON hiện có; không refactor auth/CI ngoài phạm vi. Không thay `tasks/plan.md` vì đó là lịch sử migration.
+- Tái sử dụng wrapper, common options, resolver kỳ và output JSON hiện có; không refactor auth/CI ngoài phạm vi. Không thay [`tasks/plan.md`](../history.md#tasks-plan) vì đó là lịch sử migration.
- Kiểm capability và option/input trước HTTP; giữ binding campus/API version/student và bảo toàn token đã rotate. Không fallback version, không trả dữ liệu rỗng giả cho stub/lỗi.
- Retry đọc tối đa một lần chỉ khi expiry rõ. Thao tác ghi không replay dù endpoint dùng GET; timeout hoặc kết quả không rõ không được báo thành công hoặc tự gửi lại.
- JSON/ICS stdout giữ UTF-8; log/lỗi stderr. `save_output` không phải binary writer.
diff --git a/tasks/plan.md b/tasks/plan.md
deleted file mode 100644
index 81ef19f..0000000
--- a/tasks/plan.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Kế hoạch chuyển quy trình dev sang uv
-
-## Phạm vi
-
-Quản lý môi trường dev và dependencies bằng uv; sửa `myfap version` để đọc metadata của package `myfap`. Giữ setuptools, tên package và phạm vi Python >=3.9. Bump phiên bản lên 0.1.8 cho thay đổi này.
-
-## Thứ tự thực hiện
-
-1. Chọn Python 3.11 cho dev, tạo `uv.lock` và hướng dẫn README. Xác nhận `uv sync --locked` cài được package ở chế độ editable.
-2. Thêm regression test qua lệnh CLI `version`, xác nhận test thất bại trước khi sửa tên distribution và thành công sau khi sửa.
-3. Chuyển build CI sang uv, chạy test trên PR và giữ Trusted Publishing khi có release. Kiểm tra wheel và source distribution.
-4. Review diff, kiểm tra tiếng Việt, tạo hai commit theo phạm vi và mở PR mới kèm bình luận kết quả kiểm tra.
-
-## Rủi ro và cách kiểm tra
-
-- Dependencies hiện chỉ có giới hạn phiên bản tối thiểu: lockfile cố định các phiên bản đã resolve; kiểm tra cài đặt và CLI trên Python 3.9/3.11.
-- `greenlet` 3.2.5 thiếu wheel Python 3.9 trên Windows: giới hạn phiên bản qua cấu hình uv cho đúng môi trường này để tránh yêu cầu compiler C++.
-- Playwright cần browser riêng khi đăng nhập: ghi rõ Chrome/Edge và Firefox dự phòng trong README; test version không đăng nhập hay gọi API.
-- Môi trường dev và package phát hành khác nhau: kiểm tra `myfap version` cả sau editable install và sau cài wheel.
-
-Danh sách công việc và trạng thái nằm trong [todo.md](todo.md).
diff --git a/tasks/todo.md b/tasks/todo.md
index 18957ec..7db4c96 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -14,7 +14,7 @@ Kết quả GitHub Actions và bình luận kiểm tra được theo dõi trực
- [ ] Xác định nguyên nhân body 201 của `other notification` v1. Request khớp path/query/checksum của app; session đối chứng vẫn đọc được, chưa xác nhận lỗi thuộc backend hay điều kiện tài khoản.
- [ ] Xác nhận `GeFeeByRoll` v1 có response thành công hoặc có bằng chứng từ đơn vị vận hành về phạm vi hỗ trợ. HTTP 404 trên APHL chưa đủ để kết luận route đã ngừng hỗ trợ trên mọi campus hoặc suy ra schema.
-Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](phase4.md) và [báo cáo coverage](../docs/phase4-coverage.md).
+Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](../history.md#tasks-phase4) và [báo cáo coverage](../docs/phase4-coverage.md).
## Kiểm chứng hoãn chờ dữ liệu phù hợp
From 649f1f29f717ae1a3888847ee01fb7a03e28acb8 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Wed, 28 Oct 2026 17:28:53 +0700
Subject: [PATCH 5/9] =?UTF-8?q?docs:=20d=E1=BA=ABn=20l=E1=BB=8Bch=20s?=
=?UTF-8?q?=E1=BB=AD=20t=E1=BB=9Bi=20commit=20g=E1=BB=91c?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/2026-10-19-pr8-bug-handoff.md | 2 +-
docs/api-versions.md | 2 +-
docs/development.md | 2 +-
docs/history.md | 10 +
history.md | 547 -----------------------------
tasks/phase6.md | 2 +-
tasks/todo.md | 2 +-
7 files changed, 15 insertions(+), 552 deletions(-)
create mode 100644 docs/history.md
delete mode 100644 history.md
diff --git a/docs/2026-10-19-pr8-bug-handoff.md b/docs/2026-10-19-pr8-bug-handoff.md
index 2d4671a..c3e31fc 100644
--- a/docs/2026-10-19-pr8-bug-handoff.md
+++ b/docs/2026-10-19-pr8-bug-handoff.md
@@ -201,6 +201,6 @@ Các command đọc trong phạm vi Phase 4 chưa có thiếu sót tích hợp n
- Phase 5: pipeline tag → validate → reusable CI → publish → kiểm tra sau publish → GitHub Release.
- Phase 6: transcript, điểm tổng kết/phong trào, môn/khóa học theo kỳ, balance, ảnh, tìm news, server `GetVersion`, feedback list/form/submit, rating, push và donor/employee.
-Nguồn phạm vi: [`tasks/phase4.md`](../history.md#tasks-phase4), `tasks/todo.md`, `docs/v2-contracts.md` và `../PLAN-PHASES.md`. Không đóng các mục live bằng fixture hoặc CI xanh; không coi backlog Phase 5/6 là regression của PR #8.
+Nguồn phạm vi: [`tasks/phase4.md`](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md), `tasks/todo.md`, `docs/v2-contracts.md` và `../PLAN-PHASES.md`. Không đóng các mục live bằng fixture hoặc CI xanh; không coi backlog Phase 5/6 là regression của PR #8.
Tài liệu này bàn giao kết quả kiểm chứng để sửa code. Chưa có xác nhận live trên tài khoản thật hoặc thử nhập ICS vào ứng dụng lịch.
diff --git a/docs/api-versions.md b/docs/api-versions.md
index b1b95ba..25600b7 100644
--- a/docs/api-versions.md
+++ b/docs/api-versions.md
@@ -59,4 +59,4 @@ V2 phân biệt HTTP/body 401, lỗi operation và App Check. Request đọc ch
Timeout vẫn theo `--timeout`, `MYFAP_TIMEOUT`, rồi mặc định hiện có. Mọi request mới giữ cấu hình đó và không follow redirect. Chữ ký v2 ở header, không đưa FEID token hay FAP Bearer token vào URL của các operation Phase 3.
-Xem [kết quả kiểm chứng](../history.md#docs-phase3-verification) để biết phần nào đã chạy live và phần nào chỉ có fixture. Không đưa session hoặc dữ liệu xuất ra Git; file session vẫn chứa credential dạng JSON trên máy.
+Xem [kết quả kiểm chứng](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase3-verification.md) để biết phần nào đã chạy live và phần nào chỉ có fixture. Không đưa session hoặc dữ liệu xuất ra Git; file session vẫn chứa credential dạng JSON trên máy.
diff --git a/docs/development.md b/docs/development.md
index cab6700..9377f9b 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -77,7 +77,7 @@ Bộ test và fixture chỉ nằm trong repo, không đóng gói vào wheel/sdis
**Môi trường & Timezone:** File ICS sử dụng timezone Việt Nam từ `pytz`, không phụ thuộc vào timezone database của hệ điều hành trên Windows
-Chi tiết trạng thái và giới hạn kiểm chứng xem tại [tasks/phase1.md](../history.md#tasks-phase1)
+Chi tiết trạng thái và giới hạn kiểm chứng xem tại [tasks/phase1.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase1.md)
## Chuẩn bị phát hành Phase 5
diff --git a/docs/history.md b/docs/history.md
new file mode 100644
index 0000000..018f9db
--- /dev/null
+++ b/docs/history.md
@@ -0,0 +1,10 @@
+- [docs/phase1-live-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase1-live-verification.md)
+- [docs/phase2-review-fixes.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-review-fixes.md)
+- [docs/phase2-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-verification.md)
+- [docs/phase3-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase3-verification.md)
+- [tasks/phase0.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase0.md)
+- [tasks/phase1.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase1.md)
+- [tasks/phase2.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase2.md)
+- [tasks/phase3.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase3.md)
+- [tasks/phase4.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md)
+- [tasks/plan.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/plan.md)
diff --git a/history.md b/history.md
deleted file mode 100644
index eb7caca..0000000
--- a/history.md
+++ /dev/null
@@ -1,547 +0,0 @@
-# Lưu trữ lịch sử
-
-Commit gốc của checkout khi lưu trữ: `467df1edb2220261dcd21392fbe3eaf008d6c662`. Mỗi mục ghi đường dẫn ban đầu và commit cuối cùng đã thay đổi file tại commit gốc. Nội dung lịch sử được giữ nguyên, trừ đích liên kết tương đối được điều chỉnh theo vị trí lưu trữ.
-
-
-
----
-
-Đường dẫn ban đầu: `docs/phase1-live-verification.md`
-
-Commit cuối thay đổi file tại commit gốc: `eb8f0e302436c076a3a8644a4e7aa18718481fbb`
-
-# Kiểm chứng CLI với API thật, ngày 16/10/2026
-
-Đây là báo cáo lịch sử tại commit `07fb289`. Kiểm chứng lại ngày 19/10/2026 trên v1/APHL đã xác nhận cùng các mã lỗi của ba route; policy hiện tại coi body 201 không có message `Token invalid` là lỗi operation, không phải hết phiên. Xem [kết quả mới](docs/phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
-
-## Kết quả
-
-Đã chạy executable CLI từ checkout commit `07fb289`, dùng session mẫu qua luồng nạp session thông thường. Đợt kiểm chứng chuẩn gồm 25 lần chạy command, phủ 20 route: 22 lần exit 0, 3 lần exit 1. Có thử điểm ở một kỳ có dữ liệu để kiểm tra điểm chi tiết; không ghi kỳ, mã môn hoặc nội dung điểm vào báo cáo.
-
-Phase 1 đã có kiểm chứng live cho các luồng đọc chính, nhưng còn ba lỗi ở `news`, `other notification` và `other fee`. Kết quả unit test và CI thành công không thay thế việc giải quyết ba lỗi này.
-
-| Command hoặc biến thể | HTTP / body code | Kết quả |
-|---|---|---|
-| `version`, `--help` | Không gọi HTTP | Exit 0 |
-| `campuses`, `semesters` | 200 / 200 | Exit 0, bảng hiển thị được |
-| `info student`, `info campus` | 200 / 200 | Exit 0, JSON hợp lệ |
-| `schedule` tự chọn kỳ | 200 / 200 | Exit 0, JSON hợp lệ |
-| `schedule --ics` | 200 / 200 | Exit 0, cấu trúc ICS hợp lệ |
-| `marks` tự chọn kỳ và chỉ định kỳ | 200 / 200 | Exit 0, xử lý được cả danh sách rỗng và có dữ liệu |
-| `marks --courseid ` | 200 / 200 | Exit 0, giữ HTML trong JSON |
-| `marks --courseid --pretty` | 200 / 200 | Exit 0, HTML được chuyển thành danh sách JSON |
-| `exams` | 200 / 200 | Exit 0, danh sách rỗng vẫn hợp lệ |
-| `week-timetable --date ` | 200 / 200 | Exit 0, tra tuần và lấy lịch được |
-| `attendance`, điểm danh chi tiết | 200 / 200 | Exit 0, JSON hợp lệ |
-| `applications` | 200 / 200 | Exit 0, JSON hợp lệ |
-| `other survey` | 200 / 404 | Exit 0, giữ `Data Not Found` và `data: null` |
-| `other feedback`, `other profile` | 200 / 200 | Exit 0, giữ kiểu boolean |
-| `other subjects` | 200 / 200 | Exit 0, JSON hợp lệ |
-| `news` | 200 / 201 | Exit 1, `data: null` |
-| `other notification` | 200 / 201 | Exit 1, `data: null` |
-| `other fee` với `GeFeeByRoll` | 404 / không có envelope FAP | Exit 1, không diễn giải thành không nợ |
-
-Các command JSON đều được chạy với `--stdout`. Khi thành công, toàn bộ stdout parse được thành JSON; khi ba command thất bại, stdout rỗng. Progress và lỗi nằm trên stderr.
-
-ICS có thể parse lại trong process kiểm tra riêng sau khi tăng recursion limit của Python. Parser thư viện `ics` ở giới hạn mặc định đã gặp `RecursionError` với output live; command xuất ICS vẫn exit 0. Chưa kiểm tra import vào Google Calendar hoặc ứng dụng lịch khác.
-
-## Ba vấn đề chưa giải quyết
-
-### Thông báo trả code 201
-
-`GetTop10News` và `GetNotificationByRoll` đều trả HTTP 200, body code 201, `data: null` và `message: null` trong các lần thử. Kiểm tra session bằng `GetSemester` ngay trước đó vẫn trả 200/200; các route dữ liệu khác cũng chạy được.
-
-CLI hiện phân loại code 201 thành `ApiSessionExpiredError`. Bằng chứng live chưa đủ để kết luận hai lỗi này là hết phiên: cần phân biệt lỗi theo operation với tín hiệu session hết hạn rõ ràng. Không refresh cưỡng bức hoặc thay credential để che lỗi. Chưa xác định nguyên nhân ở backend, tài khoản hay contract request.
-
-### Học phí trả HTTP 404
-
-Contract APK v1 dùng `GeFeeByRoll`, nhưng route này trả HTTP 404 trong lần thử thực tế. Một phép chẩn đoán chỉ đọc, chạy riêng ngoài mã runtime, dùng lại request để so sánh tên cũ `GetFeeByRoll`; route cũ cũng trả 404. Không triển khai fallback hoặc thay route theo suy đoán.
-
-Chưa có response học phí v1 thành công để kiểm chứng `IsPaid`, invoice và amount trên backend hiện tại. Các kiểm tra bảo toàn trường vẫn dựa trên fixture tổng hợp. Không suy ra trạng thái thanh toán từ HTTP 404.
-
-### Điều kiện chốt kiểm chứng live
-
-- [ ] Xác định và xử lý nguyên nhân code 201 của hai route thông báo; bổ sung regression tổng hợp khi có contract rõ.
-- [ ] Xác nhận endpoint học phí v1 đang hoạt động hoặc ghi nhận unsupported có căn cứ; cần một response thành công để kiểm chứng schema thực.
-- [ ] Kiểm tra lại ba command sau khi có thay đổi phù hợp. Giữ kết quả thất bại hiện tại trong lịch sử kiểm chứng.
-
-## Giới hạn và bảo vệ dữ liệu
-
-Bạn có thể dùng báo cáo này để đánh giá route và output CLI, chưa thể coi đó là kiểm chứng đầy đủ mọi tài khoản hoặc campus. Survey mới được kiểm chứng trạng thái not-found, chưa có trường hợp thành công có survey bắt buộc. Login mới, OAuth callback, refresh rotation, đổi campus, API v2 và thao tác ghi nghiệp vụ chưa được kiểm thử trong lượt này.
-
-Không đọc, liệt kê, sao chép hoặc kiểm tra trực tiếp thư mục session của người dùng. Chỉ executable CLI tự nạp session theo hành vi sẵn có. Command chạy tuần tự; không chạy `login`, `logout` hoặc `refresh` thủ công.
-
-Stdout/stderr và response thật chỉ được xử lý trong RAM. Chương trình kiểm tra chỉ xuất metadata trong danh sách cho phép: route, mã HTTP/body, loại dữ liệu, exit code và kết quả kiểm tra định dạng. Không lưu response, header, query có giá trị, lịch học, bảng điểm, đơn từ, identity, credential hoặc biến môi trường bí mật vào repo, fixture, commit hay comment PR. Không phát lại HAR/SAZ.
-
-Các script chạy live nằm ngoài repository và không được đưa lên GitHub. Báo cáo này và bản cập nhật checklist chỉ chứa kết quả đã che dữ liệu. `docs/` và `tasks/` vẫn là repository-only, không nằm trong artifact PyPI.
-
-
-
----
-
-Đường dẫn ban đầu: `docs/phase2-review-fixes.md`
-
-Commit cuối thay đổi file tại commit gốc: `96b4a2ee0d23854964f9ad6dad36c685e20dc92c`
-
-# Sửa lỗi sau review Phase 2
-
-Review ban đầu dựa trên PR #5 ở commit `9573617`. Trong lúc sửa, branch được fast-forward theo merge `937ae7c` để giữ thay đổi README và hướng dẫn phát triển mới từ main. Không sửa branch tài liệu riêng hoặc đọc thư mục session cá nhân.
-
-## Kết luận từng nhận định
-
-| Nhận định | Kết luận và thay đổi |
-|---|---|
-| V1 không tự refresh với body 201 | Có gap. Mở rộng expiry cho mọi FAP read operation có `Authen` khi cả code 201 và message `Token invalid` khớp; không áp mọi 201 |
-| `login --force` bị session v2 cũ chặn | Đúng. Login mới chỉ kế thừa campus, dùng v1/student trừ tham số rõ ràng; session cũ giữ nguyên đến khi login mới thành công |
-| `login` bắt người dùng gõ thêm `--force` khi binding cần xác thực lại | Đúng. CLI chuyển từ `SessionBindingError` sang mở trình duyệt; lỗi mạng hoặc lỗi khác không bị che bằng login mới |
-| ID token thiếu clock skew tolerance | Đúng. Thêm leeway 30 giây cho exp/iat/nbf, giữ chữ ký và các claim khác; buffer access token vẫn riêng |
-| Logout không xóa được JSON hỏng | Đúng. Xóa file thường dưới lock mà không parse JSON, kiểm lại đường dẫn trước unlink |
-| Attendance gọi mạng trước khi báo thiếu cờ | Đúng. Kiểm tra cặp cờ trước khi tạo auth, nạp session hoặc tra kỳ |
-| Dependency pkce không còn được dùng | Đúng. Bỏ khỏi pyproject và uv.lock; PKCE S256 vẫn dùng secrets/hashlib |
-
-## Bằng chứng cho contract 201
-
-Nghiên cứu `analysis/auth-var-v1-v2-comparison.md`, mục 6.1, mô tả v1 dùng body 201 cho hết phiên nhưng chưa chỉ rõ điều kiện theo operation. Đối chiếu caller APK trong workspace xác nhận app kiểm đồng thời `code == 201` và `message == "Token invalid"`:
-
-| Operation đang có trong CLI | Nguồn phân tích APK cục bộ |
-|---|---|
-| GetActivityStudent | `analysis/modules/module_1299.js:719-729` |
-| GetStudentMark | `analysis/modules/module_1302.js:331-340` |
-| GetStudentAttendances | `analysis/modules/module_1332.js:385-394` |
-| GetActivityStudentByWeek | `analysis/modules/module_2598.js:746-756` |
-
-Caller GetBalance cũng có điều kiện này tại `analysis/modules/module_825.js:409-417`, nhưng CLI chưa có operation đó nên không thêm capability hoặc policy chưa dùng. Những nguồn phân tích trên nằm ngoài repository CLI.
-
-News/notification đã có bằng chứng live trả 201 khi cùng session vẫn đọc được dữ liệu. Policy mới chỉ refresh khi message chính xác `Token invalid`; body 201 rỗng của hai route này vẫn là lỗi operation. GetSemester và các FAP read route khác được mở rộng theo cùng guard. Public bootstrap, tra tuần, survey, operation lạ, thao tác ghi và handshake không thuộc allowlist FAP read. Body `201` thiếu hoặc sai message vẫn là lỗi operation. HTTP 401 tiếp tục là tín hiệu expiry rõ ràng cho request đọc.
-
-Allowlist được mở rộng từ bốn lên 17 operation theo yêu cầu QoL của maintainer. `AUTHENTICATED_READ_OPERATIONS` là nguồn dùng chung cho phân loại lỗi và policy retry, tránh danh sách lệch nhau. Bốn caller APK ở bảng trên là bằng chứng trực tiếp; expiry live của 13 operation bổ sung chưa được quan sát trong lượt này.
-
-## Kiểm chứng
-
-Đã tái hiện lỗi bằng fixture trước sửa: login v2 bị chặn, logout không parse được JSON, ID token lệch đồng hồ 0,5 giây bị từ chối, attendance gọi auth trước kiểm tra cờ và body 201 `Token invalid` không kích hoạt refresh.
-
-Regression sau sửa bao gồm login/refresh với JWT ký RSA thật trong bộ test; biên leeway; claim sai kiểu/không hữu hạn; giữ bytes session cũ khi login thất bại; logout corrupt/missing/symlink/reparse; retry một lần với key/checksum mới; second expiry; refresh thất bại; operation/message không khớp và App Check/403/5xx không refresh. CLI schedule vẫn giữ stdout chỉ chứa JSON sau refresh.
-
-Windows/Python 3.9.25 và 3.11 đều chạy 214 test: 210 pass, 4 skip mỗi môi trường theo quyền/mode POSIX hoặc symlink. Console entry point được chạy trực tiếp với file tạm giả: logout JSON hỏng exit 0, session/lock đều được xóa; attendance thiếu `--classname` exit 1, stdout rỗng, báo đúng cờ và không tạo auth lock. Review độc lập theo hai trục Standards/Spec không còn finding sau sửa tài liệu.
-
-Các test xác minh contract APK và xử lý CLI, không chứng minh server live tự hết phiên trả envelope nào trong một phiên cụ thể. Không sửa token thật hoặc tạo lỗi server để lấy bằng chứng. Kết quả test, artifact và CI của commit cuối được cập nhật qua comment PR; PR tiếp tục giữ draft.
-
-
-
----
-
-Đường dẫn ban đầu: `docs/phase2-verification.md`
-
-Commit cuối thay đổi file tại commit gốc: `a01a1f4235343f425331cf080efac9492da10a4d`
-
-# Kiểm chứng Phase 2
-
-Ngày kiểm tra: 16/10/2026. Branch: `feat/phase2-oauth-session`; [PR #5](https://github.com/WindowScary321/myfap-api-cli/pull/5) giữ draft.
-
-## Offline và artifact
-
-Windows/Python 3.9.25 và 3.11 cùng chạy 179 unittest: 176 pass, 3 skip. Các skip liên quan mode POSIX và quyền tạo symlink trên Windows; trường hợp reparse point có fixture riêng. Test lock dùng process riêng, test JWT dùng key/token sinh riêng trong bộ test. Không test nào cần tài khoản FEID hoặc session thật.
-
-Regression bao phủ callback trùng/sai state/cancel/timeout, chữ ký và claim ID token, binding, session cũ, file hỏng, read retry, request ghi không retry, redirect, lưu token trước validation và lỗi handshake sau rotation. Test cũng chặn command đang chạy nhận nhầm session do process khác đổi tài khoản, campus hoặc version.
-
-`uv build` tạo wheel/sdist version `0.2.0`; Twine strict và artifact validator đều pass. Hai artifact được cài bằng pip vào hai venv sạch ngoài checkout, sau đó chạy `pip check`, `myfap version` và `myfap --help`. Artifact không chứa `docs/`, `tasks/`, fixture, capture hoặc file session.
-
-[CI của commit triển khai `8a369d3`](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38895605533) đã pass toàn bộ 11 job: scope, bốn source job, build, bốn artifact job và ready. Matrix gồm Ubuntu/Windows × Python 3.9/3.11. Kết quả commit tài liệu cuối được cập nhật vào PR khi hoàn tất.
-
-## Live với session tạm trước bổ sung QoL
-
-Người dùng tự đăng nhập trên cửa sổ FEID. CLI dùng `--config` trỏ đến file tạm ngoài repository, không đọc trực tiếp thư mục session cá nhân. Output được giữ trong RAM và chỉ xuất các trường đã cho phép: tên operation, HTTP/body code, kiểu dữ liệu, kết quả validation và exit code. Không lưu URL chứa query, token, MSSV/email, raw response, lịch học hoặc điểm.
-
-| Luồng/command | Kết quả |
-|---|---|
-| `login --force` | Discovery, token endpoint và JWKS HTTP 200; ID token qua validation; handshake HTTP 200/body 200, data list; exit 0 |
-| `semesters` | Probe và request GetSemester HTTP 200/body 200; exit 0 |
-| `news --stdout`, timeout 20 giây | Lỗi mạng/timeout; exit 1; không gọi token endpoint |
-| `news --stdout`, timeout 60 giây | HTTP 200/body 201, data null; exit 1; không refresh |
-| `other notification --stdout` | HTTP 200/body 201, data null; exit 1; không refresh |
-| `refresh` | Token endpoint/JWKS HTTP 200; ID token refresh được trả và qua validation; handshake HTTP 200/body 200; exit 0 |
-| `info student --stdout` sau refresh | Probe và GetStudentById HTTP 200/body 200, data list; stdout parse được JSON; exit 0 |
-| `--campus HCM login` với tài khoản chỉ có APHL | Handshake thật HTTP 200/body 201; exit 1; không gọi request nghiệp vụ; nội dung session được so sánh trong RAM và không đổi |
-| `--campus APHL login` sau lần HCM thất bại | Probe GetSemester HTTP 200/body 200; exit 0 |
-| Fault injection timeout tại handshake sau refresh thật | Refresh token mới được server trả và persist trước lỗi; binding giữ nguyên, FAP đánh dấu cần xác thực lại, exit 1 |
-| `semesters` sau khi bỏ fault handshake | Handshake lại HTTP 200/body 200 rồi GetSemester HTTP 200/body 200; exit 0; không exchange token lần hai |
-| Console entry point `myfap.exe` | Chạy trực tiếp `semesters` và `info student --stdout`, exit 0; JSON hợp lệ |
-| Console entry point `logout` | Xóa session tạm, exit 0 |
-
-Các luồng cần trace operation chạy qua Typer app với tham số CLI thật và Requests thật; console entry point được chạy thêm bằng subprocess để xác minh đường gọi của bản cài editable. Login, đổi campus, token exchange và request phục hồi đều gọi server thật; riêng phép thử lỗi handshake chặn request trong bộ nhớ trước khi gửi, không thay token hay file session bằng dữ liệu giả. Lần mở trình duyệt đầu chưa có callback; lần đăng nhập sau đã hoàn tất. Hai lỗi body 201 vẫn thuộc backend/contract và được giữ là lỗi operation.
-
-## Phần chưa xác nhận live
-
-Đổi campus thất bại với HCM đã được kiểm chứng live và giữ nguyên APHL. Chưa xác nhận chuyển campus thành công vì tài khoản mẫu chỉ có APHL. Phục hồi sau handshake lỗi đã được kiểm bằng fault injection trên session thật; chưa quan sát server tự trả lỗi handshake. FEID trả `expires_in: 3600` khi refresh, nhưng FAP `authenKey` không có contract TTL; hết hạn FEID access token không đồng nghĩa FAP credential hết hạn. Vì vậy HTTP 401 tự refresh/retry mới chỉ có fixture, chưa có bằng chứng phiên thật tự hết hạn. Đổi API version hoàn tất khi có adapter v2 ở Phase 3.
-
-Session cũ chưa có subject OIDC đã xác minh cần `login --force` trước khi refresh. File session vẫn là JSON chứa credential; xem [quy tắc lưu session](docs/oauth-session.md#timeout-và-file-trên-máy). PR này không tạo tag, publish PyPI hoặc triển khai auto release.
-
-## Kiểm chứng QoL trong PR #5
-
-Sau khi bỏ probe `GetSemester`, thêm buffer 30 giây trước khi dùng FEID access token để handshake và dọn lock khi logout, Windows/Python 3.9 và 3.11 cùng chạy 191 test: 188 pass, 3 skip mỗi môi trường. Test số request dùng auth/client thật với HTTP giả; test biên thời hạn cố định đồng hồ; test cleanup dùng process riêng để giữ handle chờ và phát hiện hai khóa song song. POSIX được kiểm trong CI Ubuntu.
-
-Đã đăng nhập mới bằng session tạm riêng và chạy Requests thật:
-
-| Command | Trace sau QoL |
-|---|---|
-| `info student --stdout` | Chỉ GetStudentById HTTP 200/body 200; JSON hợp lệ, exit 0 |
-| `semesters` | Chỉ một GetSemester HTTP 200/body 200; exit 0 |
-| `login` với session đã lưu | Không phát sinh HTTP; exit 0 |
-| `logout` | Exit 0; cả session tạm và `.lock` đều không còn |
-
-Buffer 30 giây được kiểm bằng đồng hồ cố định, không sửa token thật để giả thời hạn. Buffer chỉ refresh sớm trước handshake/phục hồi binding; không kéo dài token hoặc suy thời hạn FAP từ FEID. Trên Windows, logout có thể giữ lock nếu process khác còn mở handle; hành vi này tránh phá đồng bộ giữa các process. Kết quả CI commit QoL được cập nhật qua comment PR.
-
-
-
----
-
-Đường dẫn ban đầu: `docs/phase3-verification.md`
-
-Commit cuối thay đổi file tại commit gốc: `35b5ea1d47c1c52ed814b78ab0cdc39fd59a576c`
-
-# Kiểm chứng Phase 3
-
-Baseline là `238c718` trên main, sau PR #5. Phase 3 được triển khai tại [PR #7](https://github.com/WindowScary321/myfap-api-cli/pull/7), giữ draft và version package `0.2.0`.
-
-## Offline
-
-Regression dùng credential giả, file session tạm và HTTP mock; không đọc thư mục session cá nhân. Bộ test giữ toàn bộ v1 và bổ sung:
-
-- Header/body/query v2 cho hai bootstrap, handshake, GetSemester và schedule; signing identity đúng theo từng bước.
-- HMAC-SHA256 dùng UTF-8 key, timestamp cố định và padding `%3d`; ngăn decode khóa hex hoặc encode padding hai lần.
-- Precedence option → session → v1; state CLI không bị lẫn giữa các lần gọi. Public bootstrap đọc version mà không restore identity hoặc handshake.
-- Đổi binding v1/v2 hai chiều; handshake lỗi giữ binding cũ; không gửi FAP key của version cũ vào request dữ liệu version mới. Cùng campus/account không được âm thầm đổi MSSV/email.
-- Rotation persist trước validation/handshake, retry đọc tối đa một lần với key/chữ ký mới, App Check/403/5xx và route unsupported không gây fallback.
-- Capability CLI được kiểm trước tra kỳ/tuần cho command chưa hỗ trợ; survey giữ contract riêng.
-
-Windows/Python 3.9.25 và 3.11 chạy 261 test mỗi môi trường: 257 pass, 4 skip theo quyền/mode POSIX hoặc symlink. Build version `0.2.0` qua Twine strict và artifact validator; wheel/sdist được cài bằng pip vào hai venv sạch, `pip check`, version và help đều pass. Review độc lập không còn finding runtime; phần contract matrix đã bổ sung account/path/read-write/retry sau review.
-
-## Live với session tạm
-
-Ngày 17/10/2026, người dùng tự đăng nhập FEID và xác nhận tài khoản mẫu thuộc Hà Nội/Hòa Lạc. Output chỉ được giữ trong RAM và xuất metadata: operation, method, HTTP/body code, kiểu data, kết quả ID token validation, exit code hoặc tính hợp lệ JSON. Không ghi token, MSSV/email, query có credential, lịch học, điểm hay raw response vào repository.
-
-| Phép thử | Kết quả |
-|---|---|
-| V2 GetAllActiveCampus | POST HTTP 200/body 200, data list |
-| V2 GetApiActive gọi rõ để chẩn đoán | POST HTTP 200/body 200, data bool |
-| Login v2 với campus APHL | FEID discovery/token/JWKS HTTP 200, ID token hợp lệ; handshake HTTP 200/body 401, exit 1; không lưu session v2 |
-| Lấy mã campus từ bootstrap v2 | Có CT, DN, HCM, HN, QN; HN là Cơ sở Hà Nội, không có APHL |
-| Login v2 với HN sau xác nhận của người dùng | FEID discovery/token/JWKS HTTP 200, ID token hợp lệ; handshake POST HTTP 200/body 200, data list, exit 0 |
-| `--api-version v2 semesters` | Một GetSemester GET HTTP 200/body 200, data list, exit 0 |
-| `--api-version v2 schedule --stdout` | GetSemester và GetActivityStudent GET HTTP 200/body 200, stdout JSON hợp lệ, exit 0 |
-| `schedule --stdout` cùng session, bỏ option version | Chọn v2 đã lưu; hai operation trên HTTP 200/body 200, JSON hợp lệ, exit 0 |
-| `--api-version v2 marks --stdout` | Exit 1, không phát sinh HTTP vì chưa hỗ trợ |
-| Logout session tạm | Exit 0; session và sidecar lock đều được xóa |
-
-Lần handshake APHL thất bại và lần HN thành công được giữ thành hai kết quả riêng. CLI không tự đổi campus, không đổi version hoặc thêm token App Check để vượt lỗi. Không kết luận mọi body 401 đều do campus; ở lần này mã campus đã được kiểm tra lại bằng bootstrap và người dùng xác nhận.
-
-## Giới hạn
-
-Live mới xác nhận bootstrap, login mới, kỳ học, schedule JSON và lựa chọn version từ session với một campus. Đổi version hai chiều, refresh v2 và các nhánh lỗi có fixture, chưa xác nhận live riêng trong lượt này. Chưa có bằng chứng một session v2 tự hết hạn. Khả năng import lịch ICS và parity các command còn lại thuộc Phase 4.
-
-Kết quả Python 3.9/3.11, build, Twine, artifact validator, pip smoke và CI của commit cuối được cập nhật qua comment PR. Không có tag, GitHub Release hoặc publish PyPI trong Phase 3.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/phase0.md`
-
-Commit cuối thay đổi file tại commit gốc: `5efad9b8c2e8cdfb992db7ddc64b7ef085b5db6a`
-
-# Phase 0 — CI và artifact cho mốc v0.2.0
-
-PR theo dõi: [PR 2](https://github.com/WindowScary321/myfap-api-cli/pull/2). Mọi commit của phase này được push vào `feat/phase0-v0.2.0`; các comment ghi mốc kiểm tra, commit và kết quả CI.
-
-## Phạm vi
-
-Gia cố CI trước các phase sửa v1, OAuth/session và v2. Version package được chuẩn bị thành `0.2.0` trong PR này; chưa tạo tag, publish PyPI hoặc triển khai auto release của Phase 5. Kế hoạch migration uv `0.1.8` trong `tasks/plan.md` và `tasks/todo.md` là lịch sử đã hoàn tất, giữ nguyên.
-
-## Công việc
-
-- [x] Tách branch từ `origin/main`, tạo PR và đồng bộ version với lockfile.
-- [x] Thêm nhóm dependency CI đã khóa; chuyển marker greenlet vào metadata runtime sau khi tái hiện lỗi pip Windows/Python 3.9 cần compiler.
-- [x] Thêm artifact gate cho version, entry point, README/license, file allowlist và manifest SHA-256.
-- [x] Kiểm tra cả wheel/sdist trong venv riêng ngoài checkout bằng pip; chạy check/version/help và ép UTF-8 cho subprocess.
-- [x] Chuyển CI thành source matrix → build Ubuntu một lần → artifact matrix → gate cuối; hỗ trợ reusable workflow outputs.
-- [x] Pin action theo commit SHA, giữ quyền `contents: read` và tắt persist Git credential.
-- [x] Thêm unit test với archive giả, version/hash sai, đường dẫn nhạy cảm, symlink, smoke isolation và UTF-8.
-- [x] Xác nhận source và artifact trên cả bốn môi trường GitHub Actions; tiếp tục kiểm tra lại khi PR có commit mới.
-- [x] Ghi các mốc commit/kiểm tra bằng comment và tổng hợp bằng chứng trong PR.
-
-## Kiểm chứng
-
-- Unit suite local: 32 test pass sau phần mở rộng, gồm regression version và các case scope/ready. Thử đảo điều kiện kiểm manifest khiến test hash thất bại; khôi phục code và suite pass lại.
-- `uv build`, `twine check --strict`, artifact validation và actionlint pass.
-- Pip smoke thật trên Windows/Python 3.9 và 3.11 pass cho wheel lẫn sdist; bốn tổ hợp OS/Python trên GitHub Actions đều pass.
-- [Run CI 38852306858](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38852306858) của commit `393ced9`: 10/10 job thành công. Kết quả commit mới nhất được cập nhật trong PR.
-
-## Giới hạn
-
-CI không đăng nhập FEID hoặc gọi API FAP thật. Allowlist chỉ chặn đường dẫn/file ngoài chính sách; không chứng minh được không có secret hoặc PII ẩn trong nội dung mã Python. Kết quả Phase 0 không xác nhận OAuth/API v1/v2 đã được sửa.
-
-## Mở rộng: docs/tasks chỉ lưu trong repository
-
-- [x] Thêm `scope` lấy danh sách tên path Git, không đọc nội dung hai thư mục. Rename được xét như delete/add để đổi tên từ code sang docs hoặc ngược lại vẫn chạy đầy đủ CI.
-- [x] Chỉ thay đổi `docs/**` hoặc `tasks/**`: bỏ qua source/build/smoke, không tạo artifact; `ready` vẫn trả success. Thay đổi code/mixed và mọi `workflow_call` chạy đủ gate.
-- [x] `ready` dùng `always()` nhưng xác minh trạng thái từng job, không che lỗi/cancel hoặc trạng thái không xác định.
-- [x] Sparse checkout chỉ giữ code/tests/helpers và file build; không checkout docs/tasks trong các job CI. README/license root vẫn được giữ.
-- [x] Dùng `MANIFEST.in` loại hai thư mục khi build full checkout; validator từ chối docs/tasks trong wheel và sdist.
-- [x] Bổ sung test docs-only/tasks-only, code/mixed, rename/delete, reusable call và gate lỗi; artifact giả kiểm tra cả hai định dạng.
-- Kết quả pipeline của commit mở rộng trên GitHub Actions được theo dõi trong check của PR; comment ghi link run và commit tương ứng.
-
-Phần mở rộng giữ nguyên runtime API, entry point, version và các workflow outputs artifact đã có. Không thêm tài liệu vào `package-data` hoặc `data-files`.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/phase1.md`
-
-Commit cuối thay đổi file tại commit gốc: `e2325f5542ea92c4acf7adde547ef4daafb98f1a`
-
-# Phase 1: sửa v1 và lỗi dữ liệu
-
-## Phạm vi
-
-Tiếp nối Phase 0 trên phiên bản `0.2.0`, branch `fix/phase1-v1-data`. API v1 vẫn là mặc định. Công việc gồm query, payload, chọn kỳ học, survey, học phí, stdout và parser. OAuth/session đầy đủ, adapter v2 và auto release thuộc các phase sau.
-
-**Trạng thái sau kiểm chứng API thật ngày 16/10/2026:** phần triển khai và kiểm thử offline đã xong; live còn ba command chưa hoạt động. Chi tiết nằm trong [báo cáo kiểm chứng live](#docs-phase1-live-verification).
-
-## Các bước và tiêu chí hoàn tất
-
-- [x] Chuyển mọi query v1 sang `params=`, gồm kiểm tra session và handshake login/refresh; giữ nguyên case từng trường và kiểm tra encoding bằng credential giả.
-- [x] Kiểm tra HTTP, JSON và body code riêng; bảo toàn envelope và kiểu `data`. Survey not-found không bị diễn giải thành hết phiên hay không còn survey bắt buộc.
-- [x] Chọn kỳ theo `startDate`, giữ thứ tự server khi trùng ngày; ngày lỗi yêu cầu `--semester`, flag explicit không gọi resolver tự động.
-- [x] Tách checksum survey theo contract của app: username trim/lower, campus rỗng, khóa riêng và giờ Việt Nam.
-- [x] Dùng route v1 `GeFeeByRoll` đã đối chiếu với APK; HTTP 404 là lỗi, giữ mọi dòng học phí và `IsPaid`.
-- [x] Giữ stdout chỉ có JSON/ICS khi dùng `--stdout`; log/lỗi đi stderr. `--date` suy ra năm khi thiếu `--year`.
-- [x] Thêm fixture tổng hợp HTML có rowspan/colspan và lịch ICS; chỉ sửa parser khi regression test tái hiện lỗi.
-- [x] Chạy regression trên Python 3.9/3.11, build wheel/sdist mới, Twine strict, artifact gate và cài thử ngoài checkout.
-- [x] Review độc lập, kiểm tra diff và nội dung tiếng Việt; mở draft PR, ghi kết quả kiểm tra qua comment, giữ trạng thái draft.
-- [x] Chạy command trực tiếp với session mẫu; kiểm chứng 20 route, chỉ lưu kết quả đã che dữ liệu.
-- [ ] Giải quyết code 201 của `news` và `other notification`; chưa kết luận đây là lỗi hết phiên.
-- [ ] Xác minh endpoint học phí v1 vì cả `GeFeeByRoll` và phép chẩn đoán `GetFeeByRoll` đều trả HTTP 404.
-
-## Cơ sở đối chiếu
-
-- Kế hoạch chi tiết: `PLAN-PHASES.md`, Phase 1, ở workspace phân tích.
-- Bản so sánh: `analysis/myfap-api-cli-comparison.md` và `analysis/endpoints.md`.
-- Contract v1: `analysis/modules/module_550.js`, gồm route học phí và helper survey.
-- HAR/SAZ ngày 14/10 chỉ xác nhận runtime v2 và survey. Không coi đây là kiểm thử live v1.
-
-Fixture dùng dữ liệu giả, không chứa token, authenKey, chữ ký thực hoặc thông tin cá nhân. `docs/` và `tasks/` chỉ phục vụ đọc trong repository, không thuộc wheel/sdist hoặc phạm vi kiểm tra code của CI.
-
-## Kiểm chứng
-
-Trước thay đổi có 32 unittest. Suite mới tái hiện lỗi query, thứ tự kỳ, học phí HTTP 404, survey, stdout, ngày/năm và rowspan trước khi sửa. Kết quả sau sửa:
-
-- 88 unittest ban đầu; sau bổ sung `--timeout` trong PR #4, suite có 96 test và pass Ubuntu/Windows × Python 3.9/3.11.
-- Mutation đảo thứ tự ngày và sửa sai bộ đếm rowspan đều bị regression test bắt.
-- ICS pass trên Python 3.9 không có `tzdata`, dùng `pytz` sẵn có.
-- Twine strict và artifact validator pass với wheel/sdist mới; pip cài được cả hai artifact trong hai venv riêng ngoài checkout.
-- Mã runtime trong artifact khớp source. `docs/`, `tasks/` và `tests/` không nằm trong artifact; fixture chỉ phục vụ CI từ checkout.
-- Validator tiếng Việt strict không có lỗi hoặc cảnh báo; diff không có lỗi whitespace. Đã review độc lập và đối chiếu giá trị credential/identity từ capture bằng script, chỉ xuất kết quả không trùng, không in giá trị.
-
-PR [#4](https://github.com/WindowScary321/myfap-api-cli/pull/4) đã merge vào branch Phase 1. [CI sau merge timeout](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38875363915) pass cả 11 job trên commit `07fb289` của PR [#3](https://github.com/WindowScary321/myfap-api-cli/pull/3). Trạng thái review/merge do maintainer quyết định; không tự chuyển Ready for review hoặc merge.
-
-Kiểm chứng live trên commit đó: 25 lần chạy command, 22 exit 0 và 3 exit 1, phủ 20 route. Lịch, điểm chi tiết, điểm danh, thông tin, đơn từ, môn học và survey not-found đã có bằng chứng runtime v1. Ba lỗi còn lại được ghi riêng, không bỏ qua trong kết luận.
-
-## Giới hạn
-
-Đã kiểm thử server v1 qua CLI với một session mẫu, không đọc trực tiếp thư mục chứa session. Fixture survey thành công và học phí v1 vẫn là dữ liệu tổng hợp: live chỉ quan sát survey not-found và học phí HTTP 404. Chưa xác minh nhiều tài khoản/campus hoặc đối chiếu toàn bộ nội dung với app chính.
-
-Phase 2 tiếp tục xử lý token validation, campus binding, session lock/atomic write và refresh rotation. Phase 1 không triển khai adapter v2, auto release, tag hoặc publish PyPI. Rollback dùng revert các commit trong PR; không có migration dữ liệu.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/phase2.md`
-
-Commit cuối thay đổi file tại commit gốc: `96b4a2ee0d23854964f9ad6dad36c685e20dc92c`
-
-# Phase 2: OAuth và session
-
-## Phạm vi và thứ tự
-
-Branch `feat/phase2-oauth-session` bắt đầu từ `main` sau PR #3. Giữ version `0.2.0`, API v1 và Playwright. PR riêng phải ở trạng thái draft; chỉ maintainer quyết định chuyển Ready for review hoặc merge.
-
-1. Phân loại lỗi theo version/operation/HTTP/body. Code 201 chưa rõ nghĩa không gây refresh/logout; đọc chỉ retry một lần khi có tín hiệu hết phiên rõ ràng.
-2. Kiểm tra callback chính xác, state/nonce và PKCE mới mỗi login. Dùng discovery và xác minh ID token RS256 bằng JWKS, issuer/audience/azp/exp/sub/nonce/at_hash.
-3. Lưu session atomic và dùng lock xuyên suốt read → refresh → persist. Lưu refresh token mới trước validation/handshake tiếp theo; lỗi sau rotation không được quay về token cũ.
-4. Chọn campus theo parameter → session → default khi login mới. Binding campus/version/account type phải hợp lệ trước request dữ liệu; identity lấy từ handshake, không decode access token để suy MSSV.
-5. Giữ timeout đã có cho discovery/JWKS/token/handshake/API. Kiểm tra offline, build và smoke artifact trước gate live riêng.
-
-## Hợp đồng giữa các phần
-
-- `errors.py`: lỗi an toàn, không chứa credential, response hoặc URL có query; phân loại theo context của operation.
-- `oidc.py`: discovery, login attempt, callback, token request và validation tách biệt để persist rotation trước bước có thể lỗi.
-- `storage.py`: đọc JSON, ghi atomic và khóa file; chỉ auth orchestration điều phối transaction.
-- `auth.py`: vòng đời OAuth/FAP session, binding, identity handshake và rotation; CLI không tự mở file session để refresh.
-- `api.py`: kiểm binding và retry đọc có giới hạn; payload/output hiện có được giữ nguyên.
-
-Các module mới phục vụ trust boundary và tránh circular import; không thêm framework hoặc adapter v2 trong Phase 2.
-
-## Checklist
-
-- [x] Regression cho hai body 201 và ma trận HTTP/body 401, App Check, timeout/5xx, read/write retry.
-- [x] Callback/OIDC có test âm về chữ ký, issuer, audience/azp, nonce, expiry và at_hash; refresh có thể thiếu ID token nhưng nếu có phải cùng subject.
-- [x] Session cũ thiếu version được hiểu là v1; đổi binding bị chặn trước HTTP dữ liệu, handshake lỗi không ghi nhầm binding.
-- [x] Atomic write và lock được kiểm bằng file tạm/process riêng trên Windows và Unix; không đọc session thật trong test offline.
-- [x] Test rotation chứng minh token mới được persist trước handshake và được giữ lại khi validation/handshake lỗi.
-- [x] Matrix Ubuntu/Windows × Python 3.9/3.11, wheel/sdist, Twine và smoke cài bằng pip pass tại commit triển khai `8a369d3`.
-- [x] Live gate ghi rõ phần đã kiểm chứng và phần còn thiếu trong [báo cáo](#docs-phase2-verification); đã kiểm campus ngoài tài khoản, phục hồi sau handshake fault injection và chỉ lưu metadata đã che dữ liệu.
-- [x] Review độc lập, kiểm tra tiếng Việt và scan credential/PII trước commit/push; comment từng mốc vào draft PR.
-
-Đã chạy 179 test trên Windows với Python 3.9.25 và 3.11: mỗi môi trường có 176 pass, 3 skip theo điều kiện hệ điều hành/quyền symlink. Build local qua Twine strict, artifact validator và smoke cài wheel/sdist bằng pip. [CI của commit triển khai](https://github.com/WindowScary321/myfap-api-cli/actions/runs/38895605533) đã pass toàn bộ 11 job, gồm đủ matrix; kết quả commit tài liệu cuối được cập nhật qua comment PR.
-
-Live đã xác nhận login mới, ID token validation, handshake, refresh, đọc JSON sau refresh và logout session tạm. News/notification vẫn trả body 201 và không gây refresh. Kiểm tra HCM bằng tài khoản chỉ có APHL trả body 201 và giữ nguyên session; trở lại APHL thành công. Refresh thật kèm timeout handshake được tạo cục bộ giữ token đã rotate; bỏ fault thì handshake và đọc kỳ thành công mà không exchange token lần hai. Chuyển campus thành công, FAP session tự hết hạn và đổi version chưa được xác nhận live; đổi version chờ Phase 3. PR vẫn giữ draft.
-
-## Giới hạn
-
-Không đọc, liệt kê, sao chép hoặc kiểm tra trực tiếp thư mục session cá nhân. Live chỉ chạy CLI theo luồng thông thường; không lưu token, identity, lịch học, bảng điểm hoặc raw response vào Git. Không phát lại HAR/SAZ.
-
-Phase 4 tiếp tục điều tra lỗi backend/contract của news, notification và fee; sửa phân loại 201 không làm các endpoint đó trở thành thành công. Binding chuyển v2 và live đổi API version hoàn tất khi có adapter Phase 3. Auto release vẫn thuộc Phase 5.
-
-## QoL bổ sung trong PR #5
-
-- [x] Bỏ `GetSemester` probe khỏi nạp session; chỉ tra kỳ khi command cần tự chọn kỳ hoặc chạy `semesters`. Các request dữ liệu giữ refresh/retry một lần trên HTTP 401.
-- [x] Buffer 30 giây để refresh access token sớm trước handshake/phục hồi binding; không kéo dài thời hạn token hoặc thay xác minh ID token.
-- [x] Logout dọn session và lock idle. POSIX kiểm lại inode sau acquire để process chờ không dùng khóa đã unlink; Windows giữ lock nếu process khác còn mở handle.
-- [x] Regression command-level về số request, biên buffer và cleanup có process chờ; 191 test chạy trên Windows/Python 3.9/3.11, mỗi môi trường 188 pass và 3 skip.
-- [x] Live QoL: `info student` không có `GetSemester`, `semesters` chỉ một request, `login` dùng session local và logout xóa session/lock tạm. CI commit mới được cập nhật qua comment PR; xem [báo cáo kiểm chứng](#docs-phase2-verification).
-
-## Sửa lỗi sau review PR #5
-
-- [x] Mở rộng expiry v1 cho 17 FAP read operation có `Authen`: body `201` cùng exact message `Token invalid` kích hoạt retry tối đa một lần. Public/survey, handshake, operation ghi và body 201 thiếu/sai message không refresh; news/notification rỗng vẫn là lỗi operation.
-- [x] Login mới không bị binding v2/donor đã lưu chặn; chỉ kế thừa campus. Lệnh đọc và tham số yêu cầu v2/donor rõ ràng vẫn bị chặn trong Phase 2.
-- [x] `myfap login` tự mở trình duyệt khi session cần xác thực lại hoặc binding không được hỗ trợ, thay vì yêu cầu gõ lại `--force`.
-- [x] Thêm leeway 30 giây khi xác minh `exp/iat/nbf` của ID token, tách biệt buffer refresh sớm access token. Giữ strict type/finite và mọi kiểm tra chữ ký/identity.
-- [x] Logout dọn JSON hỏng mà không parse nội dung, giữ lock và guard đường dẫn.
-- [x] Attendance kiểm tra cặp `--subjectcode/--classname` trước khi nạp session hoặc gọi HTTP.
-- [x] Gỡ dependency `pkce` không còn caller và đồng bộ lockfile.
-
-Các lỗi có regression RED trước sửa và GREEN sau sửa. Tổng hợp kết luận, nguồn APK và kết quả kiểm chứng tại [báo cáo review](#docs-phase2-review-fixes); CI của commit cuối được cập nhật trong comment PR.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/phase3.md`
-
-Commit cuối thay đổi file tại commit gốc: `35b5ea1d47c1c52ed814b78ab0cdc39fd59a576c`
-
-# Phase 3: adapter API v2 tối thiểu
-
-Branch `feat/phase3-v2-adapter` bắt đầu từ `origin/main` tại `238c718`, sau khi PR #5 được merge. Version package giữ `0.2.0`. API v1 tiếp tục là mặc định; API v2 chỉ chạy khi được chọn bằng tham số hoặc đã được lưu trong session.
-
-## Phạm vi
-
-- Thêm option global `--api-version v1|v2` và tham số `api_version` cho các wrapper. Thứ tự chọn: tham số, session, mặc định v1. Không tự đổi version sau lỗi mạng hoặc backend.
-- Giữ wrapper và định dạng output hiện tại. V2 hỗ trợ luồng campuses → login → semesters → schedule; GetApiActive phục vụ chẩn đoán. Operation chưa có adapter báo chưa hỗ trợ trước HTTP; parity đầy đủ thuộc Phase 4.
-- Bootstrap dùng POST với JSON rỗng; handshake dùng FEID access token, request dữ liệu dùng FAP authenKey. Campus bootstrap theo từng operation, không lấy campus cố định cho toàn bộ request.
-- Chữ ký v2 dùng HMAC-SHA256 với khóa UTF-8, timestamp giây và padding `%3d` theo APK. Giữ nguyên query/signature v1 và survey.
-- Mọi request dùng timeout đã chọn và không follow redirect. Đọc chỉ retry một lần khi có tín hiệu hết phiên rõ; App Check là lỗi riêng. Không thêm thao tác ghi hoặc cơ chế né App Check.
-- Đổi campus/version phải handshake trước khi lưu binding mới. Giữ token đã rotate nếu bước sau lỗi; không gửi FAP credential của session v1 vào request dữ liệu v2.
-
-## Kiểm chứng
-
-- [x] Contract matrix ghi method/path/query/body/header, nguồn Bearer và signing identity, account type, read/write và retry. Ghi đủ các route v2 giữ query Authen, kể cả route chưa triển khai.
-- [x] Test chữ ký bằng dữ liệu giả, timestamp cố định; ngăn decode khóa hex và double-encoding padding.
-- [x] Test bootstrap, handshake, kỳ học query rỗng, schedule và lỗi unsupported; giữ regression v1.
-- [x] Test lựa chọn version, session legacy, chuyển v1/v2 hai chiều và rollback binding khi handshake lỗi.
-- [x] Test CLI, stdout, timeout, HTTP/body 401, App Check và retry dùng key/chữ ký mới.
-- [x] Local Windows/Python 3.9/3.11, build, Twine strict, artifact validator và pip smoke.
-- [x] Live bằng session tạm riêng: campuses → login → semesters → schedule. Chỉ ghi metadata đã che; phần chưa kiểm chứng phải được ghi rõ.
-- [x] Review độc lập và rà tiếng Việt cho tài liệu, commit, comment PR. PR giữ draft.
-
-Local chạy 261 test trên mỗi phiên bản Python: 257 pass, 4 skip theo điều kiện Windows. Matrix CI Ubuntu/Windows × Python 3.9/3.11 của commit cuối được xác nhận trong [checks PR #7](https://github.com/WindowScary321/myfap-api-cli/pull/7/checks) và comment sau khi hoàn tất.
-
-Live v2 thành công với campus HN sau khi người dùng xác nhận mã campus; lần APHL trả body 401 được ghi riêng. Đổi version và refresh v2 có fixture, chưa xác nhận live riêng. Xem [hướng dẫn version](docs/api-versions.md), [contract](docs/v2-contracts.md) và [báo cáo](#docs-phase3-verification).
-
-Không đọc trực tiếp thư mục session cá nhân, không đưa token, query có credential, raw response, lịch học hoặc điểm thật vào Git. Nguồn contract là tài liệu và module APK trong workspace; capture không được phát lại. Không tạo tag, publish hoặc chuyển mặc định sang v2 trong phase này.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/phase4.md`
-
-Commit cuối thay đổi file tại commit gốc: `b013703a899a008fa0a4db7bd31008eaa142a46e`
-
-# Phase 4: phủ các command đọc hiện có
-
-Nhánh `feat/phase4-command-parity` bắt đầu từ main tại `74dd8e5`, sau khi PR #7 được merge. Giữ version package `0.2.0`, Python >=3.9 và entry point hiện có. V1 tiếp tục là mặc định; v2 được chọn bằng option hoặc session.
-
-## Phạm vi triển khai
-
-- Phủ v2 cho lịch học, lịch tuần, điểm tổng hợp/chi tiết, lịch thi, điểm danh tổng hợp/chi tiết, đơn từ, news, thông tin sinh viên/campus, fee, subjects và các lệnh kiểm tra feedback/profile/notification hiện có.
-- Giữ host và checksum riêng của survey. Không biến trạng thái not-found thành danh sách rỗng hoặc kết luận không có khảo sát bắt buộc.
-- Giữ JSON/ICS, tên trường, lựa chọn kỳ học theo ngày và stdout sạch. Mọi request dùng timeout đã chọn, không follow redirect hoặc fallback version.
-- Giữ query theo từng operation, bao gồm CampusCode, Semester/semester, CourseId và bốn route hiện có vẫn mang Authen. Điểm danh chi tiết dùng GetCourseAttendance trên v2 và getCourseAttendance trên v1.
-- Credential/signature/legacy Authen phải được dựng lại khi retry sau refresh. Chỉ retry đọc một lần khi có tín hiệu expiry rõ; App Check, timeout, 403 và 5xx không kích refresh.
-- Bảng coverage phân biệt bằng chứng APK, capture, fixture, live thành công/thất bại và phần chưa kiểm chứng. HTTP 404 không tự chứng minh route đã ngừng hỗ trợ.
-
-Không thêm transcript, balance, ảnh, news search, GetVersion, form feedback hoặc thao tác ghi vào CLI trong phase này. Những route đó thuộc Phase 6. Không phát hành, tạo tag hay đổi mặc định sang v2.
-
-## Kiểm chứng
-
-- [x] Contract test ở biên HTTP và wrapper cho các route đọc v1/v2; dữ liệu fixture hoàn toàn tổng hợp.
-- [x] CLI test cho nhóm command hiện có, stdout JSON/ICS, capability, option và lỗi trước HTTP.
-- [x] Regression cho retry dùng key/checksum/Authen mới và giới hạn một lần.
-- [x] Kiểm tra ICS bằng dữ liệu tổng hợp và một reader độc lập; ghi rõ giới hạn của reader hiện tại nếu còn.
-- [x] Live trên session tạm riêng, không đọc thư mục session cá nhân. Chỉ giữ metadata đã lọc, không giữ lịch/điểm/hồ sơ hoặc credential thật trong Git.
-- [x] Chạy lại news, notification và fee của v1; ghi nguyên trạng lỗi còn lại và giới hạn theo version/campus. Không dùng CI xanh thay kết luận live.
-- [x] Review độc lập, kiểm tra tiếng Việt, test Python 3.9/3.11, build, Twine, artifact validator và pip smoke.
-- [x] Draft PR riêng, comment tiếng Việt sau các mốc quan trọng; maintainer quyết định Ready for review và merge.
-
-Đã có bằng chứng cho 8 mục trong phạm vi kiểm chứng hiện tại. Theo quyết định của người dùng ngày 19/10/2026, positive fee/survey được chuyển sang [TODO chờ dữ liệu phù hợp](tasks/todo.md#kiểm-chứng-hoãn-chờ-dữ-liệu-phù-hợp), không chặn chuyển sang Phase 5. Contract và CLI được kiểm tra tại `tests/test_phase4_transport.py`, `tests/test_api_v2.py`, `tests/test_cli_v2_capabilities.py` và các regression v1. Test ICS dùng reader `icalendar` độc lập. Kết quả live v2 HN đã ghi 21 operation khác nhau, 23 request và dọn session/lock tạm; xem [coverage Phase 4](docs/phase4-coverage.md). Matrix Ubuntu/Windows × Python 3.9/3.11, build và cài artifact được ghi tại [checks PR #8](https://github.com/WindowScary321/myfap-api-cli/pull/8/checks).
-
-Đã chạy lại ba lệnh v1/APHL ngày 19/10/2026 với login mới: news/notification vẫn trả HTTP 200/body 201, fee vẫn trả HTTP 404; lệnh đối chứng đọc thông tin sinh viên đạt 200/200 trước và sau. Session và lock tạm đã dọn. Mục chạy lại live được đánh dấu vì đã có kết quả và giới hạn, không có nghĩa ba lỗi response đã được sửa. Xem [kết quả v1](docs/phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
-
-Positive fee/survey được hoãn, schema live vẫn chưa kiểm chứng: fee v2 trả HTTP/body 200 chưa đủ để kết luận positive case, còn survey trả body 404. Các lỗi response v1 vẫn mở trong TODO; chưa có cơ sở suy ra body 201 là rỗng hợp lệ hoặc HTTP 404 là route ngừng hỗ trợ toàn bộ. Các ô đã đánh dấu không có nghĩa mọi route đều đã hoạt động hoặc toàn bộ schema live đã được xác nhận.
-
-Parser điểm đã được sửa cho cấu trúc ba cột `Item`, `Weight`, `Value` khi không có cột ghi chú, gồm cả dòng đầu tiên và dòng tiếp theo trong `rowspan`. Hàng ba `` theo fallback category/item/value cũ vẫn được giữ để tránh thay đổi output tương thích.
-
-Xuất ICS cũng đã xử lý khoảng trắng quanh dấu `-` và dấu ngoặc trong `slotTime`; regression xác nhận giờ bắt đầu/kết thúc không thay đổi. Hai lỗi parser được tái hiện và kiểm thử bằng dữ liệu tổng hợp, chưa dùng dữ liệu tài khoản thật trong lượt sửa này.
-
-Các bản sửa bổ sung xử lý bảng Rich trên stdout `cp1252`, cho `login` tự phục hồi session sai cấu trúc và thêm nhóm dependency `ci` vào hai bước sync/test của workflow publish. Việc này sửa lỗi thiếu `icalendar` trên runner sạch; pipeline tag → reusable CI → publish → smoke → GitHub Release của Phase 5 vẫn chưa được triển khai. Không chạy publish hoặc thay đổi trigger release trong lượt sửa này.
-
-Sau bàn giao 19/10/2026, đã sửa thêm refresh `invalid_grant` không đánh dấu cần đăng nhập lại, student session thiếu `mssv`/`email`, help trên stdout `cp1252` và ICS thiếu `DTSTAMP`. Bộ test có 313 case; các nhánh lỗi session dùng fixture. Live v2/HN đã xác nhận login, refresh, đọc dữ liệu và ICS có đủ `UID`/`DTSTAMP` UTC, sau đó dọn session/lock tạm. Xem [kết quả sau sửa](docs/phase4-coverage.md#kiểm-chứng-sau-bàn-giao-ngày-19102026); không dùng kết quả này đóng các TODO live v1 hoặc positive fee/survey.
-
-## Quy tắc dữ liệu và thiết bị
-
-Fiddler và Android chỉ phục vụ đối chiếu luồng đọc đã được cho phép. Dữ liệu request/response hoặc màn hình được xử lý cục bộ; chỉ tên operation, method, HTTP/body code, kiểu dữ liệu và kết quả kiểm tra được xuất ra. Không replay token từ capture, không đọc hoặc in token bằng tool, không gửi dữ liệu cá nhân ra ngoài PC. Không thay proxy, certificate, quyền truy cập hoặc dữ liệu tài khoản nếu không cần cho phép thử.
-
-Các kết quả live chưa đạt vẫn phải được ghi trong coverage. Nếu backend chưa đáp ứng hoặc thiếu positive case, phạm vi phát hành cần maintainer quyết định; không đánh dấu parity đầy đủ chỉ từ fixture.
-
-
-
----
-
-Đường dẫn ban đầu: `tasks/plan.md`
-
-Commit cuối thay đổi file tại commit gốc: `60c6a9c0193b00eed5fee7c4633abca816e6a569`
-
-# Kế hoạch chuyển quy trình dev sang uv
-
-## Phạm vi
-
-Quản lý môi trường dev và dependencies bằng uv; sửa `myfap version` để đọc metadata của package `myfap`. Giữ setuptools, tên package và phạm vi Python >=3.9. Bump phiên bản lên 0.1.8 cho thay đổi này.
-
-## Thứ tự thực hiện
-
-1. Chọn Python 3.11 cho dev, tạo `uv.lock` và hướng dẫn README. Xác nhận `uv sync --locked` cài được package ở chế độ editable.
-2. Thêm regression test qua lệnh CLI `version`, xác nhận test thất bại trước khi sửa tên distribution và thành công sau khi sửa.
-3. Chuyển build CI sang uv, chạy test trên PR và giữ Trusted Publishing khi có release. Kiểm tra wheel và source distribution.
-4. Review diff, kiểm tra tiếng Việt, tạo hai commit theo phạm vi và mở PR mới kèm bình luận kết quả kiểm tra.
-
-## Rủi ro và cách kiểm tra
-
-- Dependencies hiện chỉ có giới hạn phiên bản tối thiểu: lockfile cố định các phiên bản đã resolve; kiểm tra cài đặt và CLI trên Python 3.9/3.11.
-- `greenlet` 3.2.5 thiếu wheel Python 3.9 trên Windows: giới hạn phiên bản qua cấu hình uv cho đúng môi trường này để tránh yêu cầu compiler C++.
-- Playwright cần browser riêng khi đăng nhập: ghi rõ Chrome/Edge và Firefox dự phòng trong README; test version không đăng nhập hay gọi API.
-- Môi trường dev và package phát hành khác nhau: kiểm tra `myfap version` cả sau editable install và sau cài wheel.
-
-Danh sách công việc và trạng thái nằm trong [todo.md](tasks/todo.md).
diff --git a/tasks/phase6.md b/tasks/phase6.md
index eabc295..72cd761 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -6,7 +6,7 @@ Nhóm command đọc đã có implementation và fixture CLI/HTTP; xem [coverage
## Quy tắc xuyên suốt
-- Tái sử dụng wrapper, common options, resolver kỳ và output JSON hiện có; không refactor auth/CI ngoài phạm vi. Không thay [`tasks/plan.md`](../history.md#tasks-plan) vì đó là lịch sử migration.
+- Tái sử dụng wrapper, common options, resolver kỳ và output JSON hiện có; không refactor auth/CI ngoài phạm vi. Không thay [`tasks/plan.md`](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/plan.md) vì đó là lịch sử migration.
- Kiểm capability và option/input trước HTTP; giữ binding campus/API version/student và bảo toàn token đã rotate. Không fallback version, không trả dữ liệu rỗng giả cho stub/lỗi.
- Retry đọc tối đa một lần chỉ khi expiry rõ. Thao tác ghi không replay dù endpoint dùng GET; timeout hoặc kết quả không rõ không được báo thành công hoặc tự gửi lại.
- JSON/ICS stdout giữ UTF-8; log/lỗi stderr. `save_output` không phải binary writer.
diff --git a/tasks/todo.md b/tasks/todo.md
index 7db4c96..acf3c4a 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -14,7 +14,7 @@ Kết quả GitHub Actions và bình luận kiểm tra được theo dõi trực
- [ ] Xác định nguyên nhân body 201 của `other notification` v1. Request khớp path/query/checksum của app; session đối chứng vẫn đọc được, chưa xác nhận lỗi thuộc backend hay điều kiện tài khoản.
- [ ] Xác nhận `GeFeeByRoll` v1 có response thành công hoặc có bằng chứng từ đơn vị vận hành về phạm vi hỗ trợ. HTTP 404 trên APHL chưa đủ để kết luận route đã ngừng hỗ trợ trên mọi campus hoặc suy ra schema.
-Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](../history.md#tasks-phase4) và [báo cáo coverage](../docs/phase4-coverage.md).
+Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md) và [báo cáo coverage](../docs/phase4-coverage.md).
## Kiểm chứng hoãn chờ dữ liệu phù hợp
From 131a9d4124e23b4518a11a22792ed29217044f82 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Wed, 28 Oct 2026 17:38:03 +0700
Subject: [PATCH 6/9] =?UTF-8?q?docs:=20th=C3=AAm=20t=C3=B3m=20t=E1=BA=AFt?=
=?UTF-8?q?=20v=C3=A0o=20t=E1=BB=ABng=20file=20md=20=C4=91=C3=A3=20xo?=
=?UTF-8?q?=C3=A1=20v=C3=A0o=20history.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/history.md | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)
diff --git a/docs/history.md b/docs/history.md
index 018f9db..ca80713 100644
--- a/docs/history.md
+++ b/docs/history.md
@@ -1,10 +1,12 @@
-- [docs/phase1-live-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase1-live-verification.md)
-- [docs/phase2-review-fixes.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-review-fixes.md)
-- [docs/phase2-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-verification.md)
-- [docs/phase3-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase3-verification.md)
-- [tasks/phase0.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase0.md)
-- [tasks/phase1.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase1.md)
-- [tasks/phase2.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase2.md)
-- [tasks/phase3.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase3.md)
-- [tasks/phase4.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md)
-- [tasks/plan.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/plan.md)
+# Các file md đã xoá để cleanup docs
+
+- [docs/phase1-live-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase1-live-verification.md): Kết quả kiểm thử CLI với API thật và các lỗi v1 được ghi nhận ở Phase 1
+- [docs/phase2-review-fixes.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-review-fixes.md): Các phát hiện review và bản sửa trong Phase 2
+- [docs/phase2-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase2-verification.md): Kết quả kiểm thử offline, live và các giới hạn kiểm chứng của Phase 2
+- [docs/phase3-verification.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/docs/phase3-verification.md): Kết quả kiểm chứng adapter API v2 trong Phase 3
+- [tasks/phase0.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase0.md): Checklist chuẩn bị CI và kiểm tra artifact
+- [tasks/phase1.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase1.md): Checklist sửa API v1 và kiểm chứng Phase 1
+- [tasks/phase2.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase2.md): Checklist triển khai OAuth, quản lý session và sửa lỗi sau review
+- [tasks/phase3.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase3.md): Checklist triển khai adapter v2 ban đầu
+- [tasks/phase4.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md): Checklist mở rộng và kiểm chứng v2, gồm các mục được hoãn
+- [tasks/plan.md](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/plan.md): Kế hoạch chuyển dự án sang uv cho phiên bản 0.1.8
From 69606aebae3265ca1fa8b14f7a2f7f7a343e82d8 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Wed, 28 Oct 2026 17:55:01 +0700
Subject: [PATCH 7/9] =?UTF-8?q?docs:=20thay=20=C4=91=E1=BB=95i=20c?=
=?UTF-8?q?=E1=BA=A5u=20tr=C3=BAc=20th=C6=B0=20m=E1=BB=A5c=20c=E1=BB=A7a?=
=?UTF-8?q?=20c=C3=A1c=20file=20md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 4 ++--
README.md | 8 ++++----
docs/{ => cli}/Example.md | 0
docs/{ => cli}/api-versions.md | 4 ++--
docs/{ => cli}/command-endpoints.md | 18 ++++++++---------
docs/{ => cli}/development.md | 6 +++---
docs/{ => cli}/oauth-session.md | 4 ++--
docs/{ => cli}/releasing.md | 4 ++--
docs/{ => cli}/v2-contracts.md | 6 +++---
.../2026-10-19-pr8-bug-handoff.md | 6 +++---
docs/{ => discovery}/endpoint-gap-analysis.md | 4 ++--
docs/{ => discovery}/history.md | 0
docs/{ => discovery}/phase4-coverage.md | 6 +++---
{tasks => docs/discovery}/phase5.md | 10 +++++-----
docs/{ => discovery}/phase6-coverage.md | 8 ++++----
docs/{ => discovery}/phase6-write-gates.md | 2 +-
{tasks => docs/discovery}/phase6.md | 12 +++++------
{tasks => docs/discovery}/todo.md | 20 +++++++++----------
tests/test_ci_scope.py | 1 +
19 files changed, 62 insertions(+), 61 deletions(-)
rename docs/{ => cli}/Example.md (100%)
rename docs/{ => cli}/api-versions.md (97%)
rename docs/{ => cli}/command-endpoints.md (92%)
rename docs/{ => cli}/development.md (85%)
rename docs/{ => cli}/oauth-session.md (96%)
rename docs/{ => cli}/releasing.md (97%)
rename docs/{ => cli}/v2-contracts.md (96%)
rename docs/{ => discovery}/2026-10-19-pr8-bug-handoff.md (96%)
rename docs/{ => discovery}/endpoint-gap-analysis.md (95%)
rename docs/{ => discovery}/history.md (100%)
rename docs/{ => discovery}/phase4-coverage.md (89%)
rename {tasks => docs/discovery}/phase5.md (92%)
rename docs/{ => discovery}/phase6-coverage.md (97%)
rename docs/{ => discovery}/phase6-write-gates.md (97%)
rename {tasks => docs/discovery}/phase6.md (89%)
rename {tasks => docs/discovery}/todo.md (84%)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 36325fd..5d51e8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@
- Thêm `myfap other feedbacks` đọc danh sách feedback student qua `GetStudentFeedbacks`, chỉ có trên proxy API v2; envelope đã kiểm chứng live nhưng item schema chưa có positive (danh sách rỗng trên tài khoản kiểm chứng).
- `transcript --pretty` phân tích HTML bảng điểm toàn khóa thành JSON cấu trúc: mỗi bảng giữ header riêng (bảng chính 10 cột `No`…`Status`, bảng phụ 7 cột) và hàng dữ liệu keyed theo header, chuẩn hoá ` `; không dùng `--pretty` vẫn giữ chuỗi HTML nguyên bản theo contract.
- `doctor --api-version v2 --online` báo thêm `backend_version` qua `GetVersion` POST bootstrap; GET bị proxy từ chối 405 và route v1 đã 404. `myfap version` vẫn chỉ đọc package version offline.
-- Thêm [phân tích khoảng trống endpoint](docs/endpoint-gap-analysis.md) đối chiếu 82 route của APK với adapter: CLI phủ toàn bộ operation đọc student (ngoại trừ `GetStudentFeedbackForm` đang gate có chủ đích chờ `feedbackId` thực tế); donor/employee, login thay thế và OTA được ghi rõ out of scope.
+- Thêm [phân tích khoảng trống endpoint](docs/discovery/endpoint-gap-analysis.md) đối chiếu 82 route của APK với adapter: CLI phủ toàn bộ operation đọc student (ngoại trừ `GetStudentFeedbackForm` đang gate có chủ đích chờ `feedbackId` thực tế); donor/employee, login thay thế và OTA được ghi rõ out of scope.
- Chuyển training và nhóm rating vào `other`: dùng `myfap other training` và `myfap other rating list`, không giữ command root cũ. Endpoint, policy retry và capability từng version không đổi.
- Đặt API v2 làm mặc định khi chưa có session. Thứ tự chọn version: option `--api-version`, biến môi trường `MYFAP_API_VER`, binding session, rồi v2; session cũ thiếu trường version vẫn được hiểu là v1. Không tự chuyển version khi gặp lỗi.
@@ -39,7 +39,7 @@
- **Fee/survey positive:** theo quyết định ngày 19/10/2026, chờ dữ liệu nghiệp vụ phù hợp và không chặn chuyển sang Phase 5. Schema live có dữ liệu vẫn **chưa kiểm chứng**; fee HTTP/body 200 hoặc survey not-found không đủ để đóng các mục này.
- ICS đã được đọc bằng reader độc lập `icalendar`; chưa xác nhận import vào Google Calendar/Outlook. Reader `ics` hiện có giới hạn recursion với lịch lớn.
- Phase 6 đã bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary, doctor và (24/10/2026) `other feedbacks` cùng `backend_version` cho doctor online; xem coverage Phase 6 và phân tích khoảng trống endpoint. Rating list student/v1 đã có code/fixture; v2 stub bị chặn. Feedback form/submit và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
-- **Finding robustness từ review Phase 6 (24/10/2026) — đã sửa theo quyết định maintainer trước khi phát hành:** `rowspan` không phải số nguyên không còn làm parser bảng điểm chi tiết crash (coi như 1); ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang ngày hôm sau và `slotTime` thiếu dấu gạch báo lỗi rõ ràng; tên file xuất thay ký tự đường dẫn để không thoát thư mục `--output`. Chi tiết tại [TODO](tasks/todo.md).
+- **Finding robustness từ review Phase 6 (24/10/2026) — đã sửa theo quyết định maintainer trước khi phát hành:** `rowspan` không phải số nguyên không còn làm parser bảng điểm chi tiết crash (coi như 1); ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang ngày hôm sau và `slotTime` thiếu dấu gạch báo lỗi rõ ràng; tên file xuất thay ký tự đường dẫn để không thoát thư mục `--output`. Chi tiết tại [TODO](docs/discovery/todo.md).
- Maintainer phải chấp nhận rõ phạm vi hỗ trợ và các lỗi v1 còn mở trước khi tạo tag. CI xanh không thay thế nghiệm thu API thật hoặc quyết định này.
## [0.1.8] - Mốc trước 0.2.0
diff --git a/README.md b/README.md
index 01084c7..b3a7fe5 100644
--- a/README.md
+++ b/README.md
@@ -122,10 +122,10 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
## Thông tin thêm
-- [Chọn API v1 hoặc v2](./docs/api-versions.md): v2 là mặc định khi chưa có session; xem thứ tự ưu tiên và cách dùng v1
-- [Các ví dụ sử dụng](./docs/Example.md)
-- [Tạo môi trường dev bằng uv](./docs/development.md)
-- [CI và kiểm tra artifact](./docs/development.md#ci-và-kiểm-tra-artifact)
+- [Chọn API v1 hoặc v2](./docs/cli/api-versions.md): v2 là mặc định khi chưa có session; xem thứ tự ưu tiên và cách dùng v1
+- [Các ví dụ sử dụng](./docs/cli/Example.md)
+- [Tạo môi trường dev bằng uv](./docs/cli/development.md)
+- [CI và kiểm tra artifact](./docs/cli/development.md#ci-và-kiểm-tra-artifact)
## Ghi công
- Api đã dc reverse engineered từ [myFAP android](https://play.google.com/store/apps/details?id=com.fuct): phiên bản *2.0.6*, versionCode: *31*
diff --git a/docs/Example.md b/docs/cli/Example.md
similarity index 100%
rename from docs/Example.md
rename to docs/cli/Example.md
diff --git a/docs/api-versions.md b/docs/cli/api-versions.md
similarity index 97%
rename from docs/api-versions.md
rename to docs/cli/api-versions.md
index 25600b7..a536636 100644
--- a/docs/api-versions.md
+++ b/docs/cli/api-versions.md
@@ -1,6 +1,6 @@
# Chọn API v1 hoặc v2
-[Quay lại README](../README.md) · [Đăng nhập và session](oauth-session.md)
+[Quay lại README](../../README.md) · [Đăng nhập và session](oauth-session.md)
## Chọn version
@@ -36,7 +36,7 @@ Nếu FEID cấp token nhưng handshake FAP bị từ chối, CLI hướng dẫn
| `semesters` | GetSemester với query rỗng |
| `schedule`, gồm JSON/ICS hiện có | GetActivityStudent |
| `other survey` | Dùng dịch vụ survey riêng cho cả v1/v2; có thông báo trên stderr khi dùng v2 |
-| Các command đọc FAP khác đã có trong CLI | Đã có adapter v2 trong Phase 4; xem [bảng coverage](phase4-coverage.md) |
+| Các command đọc FAP khác đã có trong CLI | Đã có adapter v2 trong Phase 4; xem [bảng coverage](../discovery/phase4-coverage.md) |
| Operation chưa có capability | Chặn trước khi nạp session; không fallback sang v1 |
`MyFapEssential.get_api_active()` chỉ gọi khi cần chẩn đoán proxy v2. CLI không dùng kết quả này để tự chọn version hoặc campus. Ma trận method/path/query/body/header, credential và capability nằm trong [contract v2](v2-contracts.md).
diff --git a/docs/command-endpoints.md b/docs/cli/command-endpoints.md
similarity index 92%
rename from docs/command-endpoints.md
rename to docs/cli/command-endpoints.md
index 71fd7fb..09c6188 100644
--- a/docs/command-endpoints.md
+++ b/docs/cli/command-endpoints.md
@@ -4,12 +4,12 @@ Tài liệu này hợp nhất mapping command → operation → method/URL → c
## Bổ sung Phase 6 đang review
-Mapping theo mốc Phase 5 trong tài liệu này được giữ làm lịch sử. Capability đọc mới, query ngoại lệ, doctor và giới hạn hiện tại nằm tại [coverage Phase 6](phase6-coverage.md); đối chiếu toàn bộ 82 route của APK với CLI nằm tại [phân tích khoảng trống endpoint](endpoint-gap-analysis.md). Các dòng “chưa tích hợp” ở phần inventory Phase 5 bên dưới cần đọc theo mốc commit ban đầu, không phải trạng thái code Phase 6 mới nhất. Chưa publish Phase 6 hoặc đánh dấu các luồng ghi đã đạt.
+Mapping theo mốc Phase 5 trong tài liệu này được giữ làm lịch sử. Capability đọc mới, query ngoại lệ, doctor và giới hạn hiện tại nằm tại [coverage Phase 6](../discovery/phase6-coverage.md); đối chiếu toàn bộ 82 route của APK với CLI nằm tại [phân tích khoảng trống endpoint](../discovery/endpoint-gap-analysis.md). Các dòng “chưa tích hợp” ở phần inventory Phase 5 bên dưới cần đọc theo mốc commit ban đầu, không phải trạng thái code Phase 6 mới nhất. Chưa publish Phase 6 hoặc đánh dấu các luồng ghi đã đạt.
## Phạm vi theo kế hoạch
-- **Phase 4:** phủ command đọc hiện có, lập coverage và kiểm chứng live. Xem [coverage Phase 4](phase4-coverage.md).
-- **Phase 5:** chuẩn bị và nghiệm thu pipeline phát hành. Có code và CI xanh chưa đồng nghĩa đã publish `0.2.0`; xem [checklist Phase 5](../tasks/phase5.md).
+- **Phase 4:** phủ command đọc hiện có, lập coverage và kiểm chứng live. Xem [coverage Phase 4](../discovery/phase4-coverage.md).
+- **Phase 5:** chuẩn bị và nghiệm thu pipeline phát hành. Có code và CI xanh chưa đồng nghĩa đã publish `0.2.0`; xem [checklist Phase 5](../discovery/phase5.md).
- **Phase 6:** thêm các chức năng/API mới, nghiệm thu trước khi tạo tag/publish theo quyết định ngày 23/10/2026. Không tự mở route chỉ vì có tên trong APK; cần contract, capability, fixture và kiểm chứng riêng.
Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md` của workspace phân tích. Hai file kế hoạch nằm ngoài repository CLI; không cần đóng gói chúng vào artifact.
@@ -71,7 +71,7 @@ Chạy trên commit `bc8a7ee3131093432de427e1954743ee34618f45`, **v2/HN**, brows
- Refresh FEID và handshake thành công; `info student` sau refresh vẫn HTTP/body 200. Không chạy thao tác ghi nghiệp vụ, không gây lỗi session có chủ ý.
- Session/lock và thư mục tạm đã dọn. Chỉ metadata allowlist được giữ; không lưu raw response, nội dung học vụ, thông tin tài khoản, credential, query có giá trị hoặc ảnh màn hình vào repository/GitHub.
-Không chạy lại v1 trong lượt này. Kết quả v2 không đóng ba finding v1 trong [TODO](../tasks/todo.md).
+Không chạy lại v1 trong lượt này. Kết quả v2 không đóng ba finding v1 trong [TODO](../discovery/todo.md).
## Các endpoint còn lại không thuộc triển khai Phase 5
@@ -91,8 +91,8 @@ Inventory và method từng route proxy nằm trong [ma trận v2](v2-contracts.
## Nguồn kiểm tra
-- [Command và resolver](../myfap/cli.py).
-- [Wrapper nghiệp vụ v1/v2 và survey](../myfap/api.py).
-- [Allowlist, alias, method và query v2](../myfap/v2.py).
-- [Auth/handshake](../myfap/auth.py), [discovery/OIDC](../myfap/oidc.py).
-- Regression: [v1 API](../tests/test_api.py), [v2 API](../tests/test_api_v2.py), [transport Phase 4](../tests/test_phase4_transport.py), [CLI capability](../tests/test_cli_v2_capabilities.py).
+- [Command và resolver](../../myfap/cli.py).
+- [Wrapper nghiệp vụ v1/v2 và survey](../../myfap/api.py).
+- [Allowlist, alias, method và query v2](../../myfap/v2.py).
+- [Auth/handshake](../../myfap/auth.py), [discovery/OIDC](../../myfap/oidc.py).
+- Regression: [v1 API](../../tests/test_api.py), [v2 API](../../tests/test_api_v2.py), [transport Phase 4](../../tests/test_phase4_transport.py), [CLI capability](../../tests/test_cli_v2_capabilities.py).
diff --git a/docs/development.md b/docs/cli/development.md
similarity index 85%
rename from docs/development.md
rename to docs/cli/development.md
index 9377f9b..9e987b6 100644
--- a/docs/development.md
+++ b/docs/cli/development.md
@@ -34,7 +34,7 @@ Dùng `uv add ` hoặc `uv remove ` để cập nh
- **Cảnh báo: AI SLOP, đọc như đấm vào mồm**
-Với PR hoặc push `main` chỉ sửa `docs/` hoặc `tasks/`, CI bỏ qua luôn. Nếu có thay đổi ở code hoặc file khác, CI vẫn chạy. `README.md` và `LICENSE` ở root vẫn thuộc phạm vi kiểm tra vì cần cho metadata package
+Với PR hoặc push `main` chỉ sửa `docs/`, CI bỏ qua luôn; quy tắc cũng giữ hỗ trợ đường dẫn `tasks/` cũ. Nếu có thay đổi ở code hoặc file khác, CI vẫn chạy. `README.md` và `LICENSE` ở root vẫn thuộc phạm vi kiểm tra vì cần cho metadata package
Khi chạy đầy đủ, CI kiểm tra source trên Ubuntu và Windows, mỗi hệ điều hành dùng Python 3.9 và 3.11. Job build tạo một bộ wheel/sdist trên Ubuntu, kiểm metadata bằng Twine rồi tạo `SHA256SUMS`. Sau đó, cả bốn môi trường cài wheel và sdist bằng pip vào hai venv, chạy `pip check`, `myfap version` và `myfap --help`. Các bước này không đăng nhập FEID, gọi API FAP hoặc cài trình duyệt Playwright (nặng vl, mấy ô muốn đợi à)
@@ -55,7 +55,7 @@ Smoke test dùng pip để resolve dependency từ metadata package, không áp
### Phạm vi package và kết quả CI
-**Quy tắc đóng gói:** Thư mục `docs/` và `tasks/` chỉ lưu ở repo, được `MANIFEST.in` loại khỏi sdist (kể cả khi build local). CI không đọc hai thư mục này khi build/test; artifact validator sẽ báo lỗi nếu chúng xuất hiện trong wheel hoặc sdist
+**Quy tắc đóng gói:** Thư mục `docs/` chỉ lưu ở repo và được `MANIFEST.in` loại khỏi sdist (kể cả khi build local); quy tắc cũng loại `tasks/` cũ. CI không đọc các thư mục này khi build/test; artifact validator sẽ báo lỗi nếu chúng xuất hiện trong wheel hoặc sdist
**Reusable workflow (`workflow_call`):** Nhận input `ref`. Job `ready` sẽ fail nếu bước `scope`, source, build hoặc smoke test thất bại. Khi toàn bộ kiểm tra thành công, workflow xuất ra `artifact_name`, `package_version` và `manifest_sha256`
@@ -81,6 +81,6 @@ Chi tiết trạng thái và giới hạn kiểm chứng xem tại [tasks/phase1
## Chuẩn bị phát hành Phase 5
-Quy trình tag → reusable CI → Trusted Publishing → post-publish smoke → GitHub Release nằm trong [runbook phát hành](releasing.md). Theo dõi kết quả và các gate chưa kiểm chứng tại [tasks/phase5.md](../tasks/phase5.md); release notes và known issues nằm trong [CHANGELOG.md](../CHANGELOG.md).
+Quy trình tag → reusable CI → Trusted Publishing → post-publish smoke → GitHub Release nằm trong [runbook phát hành](releasing.md). Theo dõi kết quả và các gate chưa kiểm chứng tại [docs/discovery/phase5.md](../discovery/phase5.md); release notes và known issues nằm trong [CHANGELOG.md](../../CHANGELOG.md).
Chỉ maintainer tạo/push tag sau khi PR chuẩn bị release đã merge và phạm vi hỗ trợ đã được duyệt. Test offline hoặc cài artifact thành công không xác nhận Trusted Publisher, publish thật hay nghiệm thu backend.
diff --git a/docs/oauth-session.md b/docs/cli/oauth-session.md
similarity index 96%
rename from docs/oauth-session.md
rename to docs/cli/oauth-session.md
index 55bb11e..411d77b 100644
--- a/docs/oauth-session.md
+++ b/docs/cli/oauth-session.md
@@ -1,6 +1,6 @@
# Đăng nhập và quản lý session
-[Quay lại README](../README.md) · [Hướng dẫn phát triển](development.md)
+[Quay lại README](../../README.md) · [Hướng dẫn phát triển](development.md)
## Đăng nhập mới
@@ -63,6 +63,6 @@ Session là JSON chứa credential trên máy và không được mã hóa. CLI
Logout xóa session và dọn `.lock` khi có thể xóa an toàn. Trên Windows, handle của process khác có thể ngăn xóa sidecar; khi đó CLI giữ file khóa để bảo toàn đồng bộ. File này không chứa token và không nên xóa thủ công khi CLI đang chạy.
-Giữ session, file xuất dữ liệu, HAR/SAZ và biến bí mật ngoài Git. `docs/` và `tasks/` chỉ thuộc repository, không nằm trong artifact PyPI. CI dùng dữ liệu giả; đăng nhập FEID và API thật được kiểm chứng thủ công với session tạm riêng.
+Giữ session, file xuất dữ liệu, HAR/SAZ và biến bí mật ngoài Git. `docs/` chỉ thuộc repository, không nằm trong artifact PyPI. CI dùng dữ liệu giả; đăng nhập FEID và API thật được kiểm chứng thủ công với session tạm riêng.
`logout` không parse nội dung session, nên vẫn dọn được file JSON hỏng. CLI chỉ xóa file thường sau khi lấy lock và kiểm tra lại đường dẫn; symlink, reparse point và thư mục đều bị từ chối.
diff --git a/docs/releasing.md b/docs/cli/releasing.md
similarity index 97%
rename from docs/releasing.md
rename to docs/cli/releasing.md
index 9208253..11b0e4e 100644
--- a/docs/releasing.md
+++ b/docs/cli/releasing.md
@@ -2,7 +2,7 @@
Tài liệu này là runbook Phase 5 cho distribution `myfap`. Pipeline được chuẩn bị trong mã nguồn không đồng nghĩa đã được nghiệm thu trên GitHub Actions hoặc đã publish. Chỉ maintainer tạo/push tag sau khi PR chuẩn bị release đã merge và phạm vi hỗ trợ đã được duyệt. Không tự phát hành theo push `main`.
-Xem [release notes](../CHANGELOG.md), [checklist Phase 5](../tasks/phase5.md) và [coverage API](phase4-coverage.md).
+Xem [release notes](../../CHANGELOG.md), [checklist Phase 5](../discovery/phase5.md) và [coverage API](../discovery/phase4-coverage.md).
## 1. Quyết định phạm vi trước release
@@ -140,7 +140,7 @@ TestPyPI upload cũng là hành động ra dịch vụ ngoài; chỉ chạy sau
## 7. Ghi nhận nghiệm thu
-Ghi kết quả tại [tasks/phase5.md](../tasks/phase5.md): commit, lệnh, exit code, matrix đã chạy và phần bị skip/chưa kiểm chứng. Phân biệt rõ:
+Ghi kết quả tại [docs/discovery/phase5.md](../discovery/phase5.md): commit, lệnh, exit code, matrix đã chạy và phần bị skip/chưa kiểm chứng. Phân biệt rõ:
- **Offline:** fixture tổng hợp và kiểm cấu hình; không gọi FEID/FAP.
- **Local live:** CLI thật với session tạm được phép, payload chỉ xử lý cục bộ; chỉ metadata đã lọc được ghi vào báo cáo.
diff --git a/docs/v2-contracts.md b/docs/cli/v2-contracts.md
similarity index 96%
rename from docs/v2-contracts.md
rename to docs/cli/v2-contracts.md
index be016ff..2519818 100644
--- a/docs/v2-contracts.md
+++ b/docs/cli/v2-contracts.md
@@ -14,7 +14,7 @@ Tài liệu này ghi lại adapter v2 và phạm vi các route còn lại. CLI m
| `GetSemester` | v2/student/semesters | GET `/MyFAP/GetSemester` | `{}` | Không có | FAP key của binding v2 | Campus của binding | Đọc; refresh/retry tối đa một lần khi expiry rõ | `module_599.js:153-158,898-919` |
| `GetActivityStudent` | v2/student/schedule | GET `/MyFAP/GetActivityStudent` | `CampusCode`, `rollNumber`, `Semester` | Không có | FAP key của binding v2 | Campus của binding, khớp query | Đọc; refresh/retry tối đa một lần khi expiry rõ | `module_599.js:294-300,898-919` |
-Bảng trên nêu các contract nền tảng của bootstrap, handshake và lịch học. Ma trận bên dưới là nguồn trạng thái đầy đủ của operation trong adapter hiện tại; kết quả live theo từng nhóm command nằm trong [coverage Phase 4](phase4-coverage.md).
+Bảng trên nêu các contract nền tảng của bootstrap, handshake và lịch học. Ma trận bên dưới là nguồn trạng thái đầy đủ của operation trong adapter hiện tại; kết quả live theo từng nhóm command nằm trong [coverage Phase 4](../discovery/phase4-coverage.md).
Mọi request v2 dùng `ClientCode: MyFAP`, `CampusCode`, `Authorization` và `Checksum: :`. Các header client theo bản ghi app gồm `User-Agent: okhttp/4.9.2`, `Accept: application/json, text/plain, */*` và `Accept-Encoding: gzip`, áp dụng cho cả GET lẫn POST. GET không có body và không thêm `Content-Type`; POST gửi JSON có `Content-Type: application/json`.
@@ -30,7 +30,7 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
## Ma trận route v2
-`supported` nghĩa là operation nằm trong `SUPPORTED_OPERATIONS` của adapter v2 hiện tại; `unsupported` nghĩa là chưa có capability trong adapter. `stub` là hàm trong APK không có implementation nghiệp vụ đủ để dựng thành capability. Adapter không giả lập route bằng cách trả danh sách rỗng. Trạng thái triển khai không thay thế bằng chứng live hoặc positive case; xem [coverage Phase 4](phase4-coverage.md).
+`supported` nghĩa là operation nằm trong `SUPPORTED_OPERATIONS` của adapter v2 hiện tại; `unsupported` nghĩa là chưa có capability trong adapter. `stub` là hàm trong APK không có implementation nghiệp vụ đủ để dựng thành capability. Adapter không giả lập route bằng cách trả danh sách rỗng. Trạng thái triển khai không thay thế bằng chứng live hoặc positive case; xem [coverage Phase 4](../discovery/phase4-coverage.md).
| Operation | Method | Trạng thái adapter | Ghi chú contract |
|---|---:|---|---|
@@ -78,7 +78,7 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `GetConnect` | Không có | stub | APK chỉ nối lại một đối tượng kết nối đã có |
| `GetLoginDonor` | Không có | stub | APK trả trạng thái tạm, chưa có contract login donor |
-Sau nhóm đọc Phase 6 và đợt mở rộng endpoint 24/10/2026, ma trận có 31 operation được hỗ trợ trong code: 27 operation đọc, 3 bootstrap và 1 handshake. `doctor --api-version v2 --online` gọi `GetApiActive` rồi `GetVersion` bằng bootstrap, không xác nhận session hoặc campus tài khoản. Capability mới chưa đồng nghĩa đã nghiệm thu live; xem [coverage Phase 6](phase6-coverage.md). Xem thêm [bảng hợp nhất command/method/URL v1 và v2](command-endpoints.md) để phân biệt capability trong adapter, command thực sự tồn tại và kết quả live.
+Sau nhóm đọc Phase 6 và đợt mở rộng endpoint 24/10/2026, ma trận có 31 operation được hỗ trợ trong code: 27 operation đọc, 3 bootstrap và 1 handshake. `doctor --api-version v2 --online` gọi `GetApiActive` rồi `GetVersion` bằng bootstrap, không xác nhận session hoặc campus tài khoản. Capability mới chưa đồng nghĩa đã nghiệm thu live; xem [coverage Phase 6](../discovery/phase6-coverage.md). Xem thêm [bảng hợp nhất command/method/URL v1 và v2](command-endpoints.md) để phân biệt capability trong adapter, command thực sự tồn tại và kết quả live.
Bảy route giữ `Authen` trong query của adapter app là `CheckUpdateProfile` (`module_599.js:136`), `GetSemesterMark` (`223`), `GetApplication` (`429`), `CheckOpenFeedBack` (`443`), `AddRate` (`467`), `GetNotificationByRoll` (`491`) và `GetNotificationByDonor` (`532`). Trong số này, CLI đã triển khai năm route `CheckUpdateProfile`, `GetApplication`, `CheckOpenFeedBack`, `GetNotificationByRoll` và `GetSemesterMark`; `AddRate`/`GetNotificationByDonor` vẫn chưa được hỗ trợ. Route điểm danh chi tiết đổi từ `getCourseAttendance` của v1 sang `GetCourseAttendance` ở v2 (`module_599.js:363-364`); wrapper v1 không đủ để ghi nhận capability v2.
diff --git a/docs/2026-10-19-pr8-bug-handoff.md b/docs/discovery/2026-10-19-pr8-bug-handoff.md
similarity index 96%
rename from docs/2026-10-19-pr8-bug-handoff.md
rename to docs/discovery/2026-10-19-pr8-bug-handoff.md
index c3e31fc..95241a8 100644
--- a/docs/2026-10-19-pr8-bug-handoff.md
+++ b/docs/discovery/2026-10-19-pr8-bug-handoff.md
@@ -24,7 +24,7 @@ Kiểm tra đối chứng: refresh timeout trên v1/v2 không đổi file sessio
- [Lệnh, exit code, trạng thái session và kết quả ICS sau sửa](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-recheck-_8hm6jvn/results.json).
- [ICS 250 sự kiện sau sửa](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-recheck-_8hm6jvn/schedule-250.ics).
-Các ca CLI độc lập vẫn chỉ dùng session/HTTP tổng hợp và sentinel chặn browser như mô tả ở dưới. Lượt này không gọi server thật hoặc thử nhập ICS vào ứng dụng lịch. Theo báo cáo mới của agent chính trong `docs/phase4-coverage.md`, ba lệnh v1 đã được chạy lại nhưng news/notification vẫn trả body 201 và fee vẫn HTTP 404; positive fee/survey còn mở. Đây là các giới hạn riêng, không bị đóng theo kết quả sửa bốn finding.
+Các ca CLI độc lập vẫn chỉ dùng session/HTTP tổng hợp và sentinel chặn browser như mô tả ở dưới. Lượt này không gọi server thật hoặc thử nhập ICS vào ứng dụng lịch. Theo báo cáo mới của agent chính trong `docs/discovery/phase4-coverage.md`, ba lệnh v1 đã được chạy lại nhưng news/notification vẫn trả body 201 và fee vẫn HTTP 404; positive fee/survey còn mở. Đây là các giới hạn riêng, không bị đóng theo kết quả sửa bốn finding.
## Đánh giá chuyển từ Phase 4 sang Phase 5
@@ -46,7 +46,7 @@ Các ca CLI độc lập vẫn chỉ dùng session/HTTP tổng hợp và sentine
Phần việc đầu tiên của Phase 5 cần giải quyết:
1. Chốt phạm vi release cho news/notification/fee v1: có bằng chứng sửa thành công, hoặc maintainer chấp nhận giới hạn cụ thể theo version/campus và ghi rõ trong release notes. Không tự đổi mặc định sang v2 hoặc fallback để che lỗi.
-2. Positive fee/survey đã được người dùng đồng ý hoãn ngày 19/10/2026 vì chưa thể kiểm chứng hiện tại. Theo dõi tại `tasks/todo.md`, giữ schema là chưa kiểm chứng và ghi rõ giới hạn trong release notes; mục này không chặn chuyển Phase 5.
+2. Positive fee/survey đã được người dùng đồng ý hoãn ngày 19/10/2026 vì chưa thể kiểm chứng hiện tại. Theo dõi tại `docs/discovery/todo.md`, giữ schema là chưa kiểm chứng và ghi rõ giới hạn trong release notes; mục này không chặn chuyển Phase 5.
3. Thêm `CHANGELOG.md` cùng known issues và phạm vi đã chốt. File này chưa có; đây là đầu việc được giao cho Phase 5, không phải tính năng bị bỏ sót của Phase 4.
4. Sau review/merge và quyết định phạm vi, mới tạo tag/publish theo kế hoạch. Không sử dụng workflow publish cũ như pipeline Phase 5 đã hoàn thành.
@@ -201,6 +201,6 @@ Các command đọc trong phạm vi Phase 4 chưa có thiếu sót tích hợp n
- Phase 5: pipeline tag → validate → reusable CI → publish → kiểm tra sau publish → GitHub Release.
- Phase 6: transcript, điểm tổng kết/phong trào, môn/khóa học theo kỳ, balance, ảnh, tìm news, server `GetVersion`, feedback list/form/submit, rating, push và donor/employee.
-Nguồn phạm vi: [`tasks/phase4.md`](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md), `tasks/todo.md`, `docs/v2-contracts.md` và `../PLAN-PHASES.md`. Không đóng các mục live bằng fixture hoặc CI xanh; không coi backlog Phase 5/6 là regression của PR #8.
+Nguồn phạm vi: [`tasks/phase4.md`](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md), `docs/discovery/todo.md`, `docs/cli/v2-contracts.md` và `../PLAN-PHASES.md`. Không đóng các mục live bằng fixture hoặc CI xanh; không coi backlog Phase 5/6 là regression của PR #8.
Tài liệu này bàn giao kết quả kiểm chứng để sửa code. Chưa có xác nhận live trên tài khoản thật hoặc thử nhập ICS vào ứng dụng lịch.
diff --git a/docs/endpoint-gap-analysis.md b/docs/discovery/endpoint-gap-analysis.md
similarity index 95%
rename from docs/endpoint-gap-analysis.md
rename to docs/discovery/endpoint-gap-analysis.md
index df2f84c..043282a 100644
--- a/docs/endpoint-gap-analysis.md
+++ b/docs/discovery/endpoint-gap-analysis.md
@@ -20,7 +20,7 @@ Quy tắc riêng tư: mọi probe live dưới đây là GET/POST chỉ đọc b
## Nhóm B — Thao tác ghi đang gate có chủ đích
-`AddRate` (rating submit, checksum `rateid` v1 / query `Authen` v2), `UpdateTokedevices` (push register, v1 ký bằng email, token chỉ đọc từ file), `SubmitStudentFeedback` (body runtime). Theo quyết định ghi tại [todo](../tasks/todo.md), tài khoản hiện tại không thể xác minh ack/schema thao tác ghi; gate và trình tự validate → preview → confirmation → auth giữ nguyên.
+`AddRate` (rating submit, checksum `rateid` v1 / query `Authen` v2), `UpdateTokedevices` (push register, v1 ký bằng email, token chỉ đọc từ file), `SubmitStudentFeedback` (body runtime). Theo quyết định ghi tại [todo](todo.md), tài khoản hiện tại không thể xác minh ack/schema thao tác ghi; gate và trình tự validate → preview → confirmation → auth giữ nguyên.
## Nhóm C — Out of scope theo thiết kế CLI
@@ -44,4 +44,4 @@ Thí nghiệm ngày 24/10/2026 (chi tiết tại [coverage Phase 6](phase6-cover
- Positive item schema cho `GetStudentFeedbacks` và `GetStudentRate` (cả hai đang list rỗng trên tài khoản kiểm chứng).
- `feedbackId` thật để mở `GetStudentFeedbackForm`.
-- Các finding v1 (404/201) và positive fee/survey tại [todo](../tasks/todo.md).
+- Các finding v1 (404/201) và positive fee/survey tại [todo](todo.md).
diff --git a/docs/history.md b/docs/discovery/history.md
similarity index 100%
rename from docs/history.md
rename to docs/discovery/history.md
diff --git a/docs/phase4-coverage.md b/docs/discovery/phase4-coverage.md
similarity index 89%
rename from docs/phase4-coverage.md
rename to docs/discovery/phase4-coverage.md
index 58b3478..b3a3ab4 100644
--- a/docs/phase4-coverage.md
+++ b/docs/discovery/phase4-coverage.md
@@ -1,6 +1,6 @@
# Coverage Phase 4
-Phase 4 bổ sung adapter v2 cho các command đọc đã có trong CLI; tại thời điểm đó v1 là mặc định. Quy tắc hiện tại được mô tả tại [hướng dẫn chọn version](api-versions.md). Bảng dưới đây phân biệt fixture, capture và kết quả smoke live v2 trên HN đã ghi ở phần cuối tài liệu. HTTP/body 200 không tự xác nhận payload có dữ liệu nghiệp vụ. Theo quyết định của người dùng ngày 19/10/2026, positive fee/survey được hoãn vào [TODO chờ dữ liệu phù hợp](../tasks/todo.md#kiểm-chứng-hoãn-chờ-dữ-liệu-phù-hợp), không chặn chuyển sang Phase 5; schema live vẫn chưa kiểm chứng. Trạng thái operation đã triển khai nằm trong [ma trận route v2](v2-contracts.md#ma-trận-route-v2).
+Phase 4 bổ sung adapter v2 cho các command đọc đã có trong CLI; tại thời điểm đó v1 là mặc định. Quy tắc hiện tại được mô tả tại [hướng dẫn chọn version](../cli/api-versions.md). Bảng dưới đây phân biệt fixture, capture và kết quả smoke live v2 trên HN đã ghi ở phần cuối tài liệu. HTTP/body 200 không tự xác nhận payload có dữ liệu nghiệp vụ. Theo quyết định của người dùng ngày 19/10/2026, positive fee/survey được hoãn vào [TODO chờ dữ liệu phù hợp](todo.md#kiểm-chứng-hoãn-chờ-dữ-liệu-phù-hợp), không chặn chuyển sang Phase 5; schema live vẫn chưa kiểm chứng. Trạng thái operation đã triển khai nằm trong [ma trận route v2](../cli/v2-contracts.md#ma-trận-route-v2).
| Nhóm command | Operation v1 | Operation v2 | Trạng thái sau Phase 4 |
|---|---|---|---|
@@ -23,7 +23,7 @@ Phase 4 bổ sung adapter v2 cho các command đọc đã có trong CLI; tại t
## Bảng command, endpoint và URL hợp nhất
-Xem [command → method → endpoint → URL → capability](command-endpoints.md) cho cả v1/v2, helper không có command riêng và các route còn thuộc Phase 6. Bảng kèm kết quả live mới ngày 23/10/2026 trên commit `bc8a7ee`: 22 lần chạy command exit 0, 28 request FAP/survey thuộc 19 operation. Điểm chi tiết và điểm danh chi tiết bị skip vì chưa lấy được tham số phù hợp; không ghi live pass cho hai nhóm đó. Fee có data không rỗng nhưng chưa đối chiếu schema nghiệp vụ; survey vẫn not-found. Các kết quả lịch sử bên dưới giữ nguyên, không bị diễn giải thành mọi route đã đạt.
+Xem [command → method → endpoint → URL → capability](../cli/command-endpoints.md) cho cả v1/v2, helper không có command riêng và các route còn thuộc Phase 6. Bảng kèm kết quả live mới ngày 23/10/2026 trên commit `bc8a7ee`: 22 lần chạy command exit 0, 28 request FAP/survey thuộc 19 operation. Điểm chi tiết và điểm danh chi tiết bị skip vì chưa lấy được tham số phù hợp; không ghi live pass cho hai nhóm đó. Fee có data không rỗng nhưng chưa đối chiếu schema nghiệp vụ; survey vẫn not-found. Các kết quả lịch sử bên dưới giữ nguyên, không bị diễn giải thành mọi route đã đạt.
## Quy tắc transport
@@ -86,4 +86,4 @@ CLI tiếp tục báo lỗi operation cho body 201 không có message `Token inv
Để dùng các lệnh này trên tài khoản Hà Nội đã kiểm chứng, có thể chọn `--api-version v2 --campus HN` và đăng nhập bằng `--config` trỏ tới session v2 riêng. V2/HN đã trả HTTP/body 200 trong lượt live trước đó; đây là cách chọn adapter rõ ràng, không phải bản sửa backend v1. Positive fee/survey vẫn chưa được kiểm chứng.
-Session và lock tạm đã xóa sau `logout`. Chỉ ghi metadata trong bảng, không lưu response, query có giá trị, credential hoặc dữ liệu tài khoản vào Git. Việc chạy lại live đã hoàn tất; các lỗi response v1 vẫn nằm trong [TODO](../tasks/todo.md#kiểm-chứng-live-còn-mở-trước-khi-phát-hành).
+Session và lock tạm đã xóa sau `logout`. Chỉ ghi metadata trong bảng, không lưu response, query có giá trị, credential hoặc dữ liệu tài khoản vào Git. Việc chạy lại live đã hoàn tất; các lỗi response v1 vẫn nằm trong [TODO](todo.md#kiểm-chứng-live-còn-mở-trước-khi-phát-hành).
diff --git a/tasks/phase5.md b/docs/discovery/phase5.md
similarity index 92%
rename from tasks/phase5.md
rename to docs/discovery/phase5.md
index 6a1740b..dbffb61 100644
--- a/tasks/phase5.md
+++ b/docs/discovery/phase5.md
@@ -6,18 +6,18 @@ Phạm vi phase là chuẩn bị release notes, gate tag/version/artifact, Trust
**Quyết định ngày 23/10/2026:** hoãn tag/publish đến sau khi hoàn thiện và nghiệm thu phạm vi [Phase 6](phase6.md). Phase 5 hiện là pipeline đã chuẩn bị, không phải bản đã phát hành. Giữ `0.2.0`, v1 mặc định/v2 opt-in; chưa tạo tag, publish PyPI/TestPyPI hoặc GitHub Release. Nghiệm thu dịch vụ, tạo/push tag, upload và thay đổi cấu hình vẫn cần maintainer cho phép riêng.
-Mapping command → method → endpoint → URL → capability được hợp nhất tại [command-endpoints.md](../docs/command-endpoints.md), kèm danh sách route còn chưa tích hợp. Không dùng trạng thái triển khai pipeline hoặc live command cốt lõi để tuyên bố đã thêm toàn bộ endpoint.
+Mapping command → method → endpoint → URL → capability được hợp nhất tại [command-endpoints.md](../cli/command-endpoints.md), kèm danh sách route còn chưa tích hợp. Không dùng trạng thái triển khai pipeline hoặc live command cốt lõi để tuyên bố đã thêm toàn bộ endpoint.
Hai commit mã nguồn đã kiểm: `671ca5f06b63ce4ae826732fb4f1a3a64c252f62` (công cụ và regression release) và `e0178737b07de80878231f9875a049e755953939` (pipeline và regression workflow). Commit tài liệu bàn giao nằm tiếp sau, không đổi code đã test.
## Phạm vi hỗ trợ cần duyệt trước tag
-- [ ] Maintainer duyệt mục `0.2.0` trong [CHANGELOG.md](../CHANGELOG.md), coverage và known issues.
+- [ ] Maintainer duyệt mục `0.2.0` trong [CHANGELOG.md](../../CHANGELOG.md), coverage và known issues.
- [ ] Ghi rõ quyết định với ba lỗi live v1/APHL còn mở: news/notification HTTP 200/body 201, fee HTTP 404. Không tuyên bố đã sửa hoặc parity đầy đủ.
- [ ] Giữ positive fee/survey là TODO hoãn chờ dữ liệu phù hợp; schema live có dữ liệu chưa kiểm chứng. Quyết định hoãn ngày 19/10/2026 cho phép chuyển Phase 5, không chứng minh backend đạt.
- [ ] Giữ giới hạn ICS: reader độc lập đã kiểm; import vào ứng dụng lịch thật chưa kiểm chứng.
-Các finding v1 và positive case nằm trong [TODO](todo.md) và [coverage Phase 4](../docs/phase4-coverage.md). Theo quyết định ngày 23/10/2026, nghiệm thu phạm vi Phase 6 diễn ra trước khi phát hành bằng pipeline này; việc hoãn positive fee/survey trước đó vẫn được giữ, không chuyển thành bằng chứng schema đã đạt.
+Các finding v1 và positive case nằm trong [TODO](todo.md) và [coverage Phase 4](phase4-coverage.md). Theo quyết định ngày 23/10/2026, nghiệm thu phạm vi Phase 6 diễn ra trước khi phát hành bằng pipeline này; việc hoãn positive fee/survey trước đó vẫn được giữ, không chuyển thành bằng chứng schema đã đạt.
## Gate kỹ thuật
@@ -87,7 +87,7 @@ Không ghi nhận HTTP status ở harness này, không suy ra HTTP 200 chỉ t
### Lượt live mới và CI của PR #9
-Ngày 23/10/2026, trên commit `bc8a7ee3131093432de427e1954743ee34618f45`, đã login mới hoàn toàn rồi chạy 22 lần command trên v2/HN: tất cả exit 0; 28 request FAP/survey thuộc 19 operation. Lượt này ghi được HTTP/body code tại biên HTTP thật, không thay response. ICS và JSON hợp lệ; refresh và đọc sau refresh đạt. Hai nhóm chi tiết điểm/điểm danh bị skip vì không lấy được tham số phù hợp. Fee có data không rỗng nhưng schema nghiệp vụ chưa được đối chiếu; survey vẫn HTTP 200/body 404. Session/lock tạm đã dọn; chỉ metadata đã lọc được lưu. Xem [mapping và kết quả chi tiết](../docs/command-endpoints.md#lượt-live-mới-ngày-23102026).
+Ngày 23/10/2026, trên commit `bc8a7ee3131093432de427e1954743ee34618f45`, đã login mới hoàn toàn rồi chạy 22 lần command trên v2/HN: tất cả exit 0; 28 request FAP/survey thuộc 19 operation. Lượt này ghi được HTTP/body code tại biên HTTP thật, không thay response. ICS và JSON hợp lệ; refresh và đọc sau refresh đạt. Hai nhóm chi tiết điểm/điểm danh bị skip vì không lấy được tham số phù hợp. Fee có data không rỗng nhưng schema nghiệp vụ chưa được đối chiếu; survey vẫn HTTP 200/body 404. Session/lock tạm đã dọn; chỉ metadata đã lọc được lưu. Xem [mapping và kết quả chi tiết](../cli/command-endpoints.md#lượt-live-mới-ngày-23102026).
[CI run 39960229451](https://github.com/WindowScary321/myfap-api-cli/actions/runs/39960229451) của Draft PR #9 trên commit `bc8a7ee` đã đạt 11/11 job, gồm source và artifact smoke Ubuntu/Windows × Python 3.9/3.11. Đây là CI của PR, không phải một lượt push tag → PyPI → GitHub Release. Lượt local trước đó vẫn có giới hạn môi trường như đã ghi, không được đổi thành kết quả Ubuntu local.
@@ -105,4 +105,4 @@ Các mục này **chưa kiểm chứng**, không tự đánh dấu từ test off
## Bàn giao
-Xem [runbook phát hành](../docs/releasing.md). Khi báo kết quả, ghi đúng commit và trạng thái working tree, lệnh/exit code đã chạy, phần chưa chạy và mọi giới hạn. Không khẳng định hoàn tất phát hành `0.2.0` nếu PyPI/GitHub Release chưa được kiểm chứng.
+Xem [runbook phát hành](../cli/releasing.md). Khi báo kết quả, ghi đúng commit và trạng thái working tree, lệnh/exit code đã chạy, phần chưa chạy và mọi giới hạn. Không khẳng định hoàn tất phát hành `0.2.0` nếu PyPI/GitHub Release chưa được kiểm chứng.
diff --git a/docs/phase6-coverage.md b/docs/discovery/phase6-coverage.md
similarity index 97%
rename from docs/phase6-coverage.md
rename to docs/discovery/phase6-coverage.md
index 54bfa9e..01bd7ee 100644
--- a/docs/phase6-coverage.md
+++ b/docs/discovery/phase6-coverage.md
@@ -1,6 +1,6 @@
# Coverage Phase 6 — đang triển khai
-Nhóm đọc ban đầu tại `c829b7004ea2dbb7f99cf1dc3827070039bb9ea5`, bổ sung rating list v1 tại `4c29b81f0e61d11ccb6d047060680cbcf60ab121`, được ghi nhận trong [PR #10](https://github.com/WindowScary321/myfap-api-cli/pull/10). Các kết quả kiểm chứng bên dưới là lịch sử theo commit/version được nêu, không chứng minh mọi endpoint hoạt động live. Quy tắc chọn version hiện tại (mặc định v2 khi chưa có session) được mô tả tại [hướng dẫn chọn version](api-versions.md).
+Nhóm đọc ban đầu tại `c829b7004ea2dbb7f99cf1dc3827070039bb9ea5`, bổ sung rating list v1 tại `4c29b81f0e61d11ccb6d047060680cbcf60ab121`, được ghi nhận trong [PR #10](https://github.com/WindowScary321/myfap-api-cli/pull/10). Các kết quả kiểm chứng bên dưới là lịch sử theo commit/version được nêu, không chứng minh mọi endpoint hoạt động live. Quy tắc chọn version hiện tại (mặc định v2 khi chưa có session) được mô tả tại [hướng dẫn chọn version](../cli/api-versions.md).
## Command và contract đã nối qua CLI
@@ -33,7 +33,7 @@ Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus
- Với transcript/training/summary, caller của APK (module_599.js) gọi wrapper GET **không truyền credential header**: wrapper (dòng 898–906) mặc định credential chuỗi rỗng khi thiếu tham số thứ tư, `_buildHeaders` (747–781) khi đó tạo header không `Authorization` và `_makeChecksum` (726–746) ký bằng bootstrap token. Chỉ `GetSemesterMark` (218–224) đặt FAP key trong query `Authen`; `AcademicTranscript` (266–272) và `GetDiemphongtrao` (280–286) chỉ có query campus/roll/semester. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại** cho cả ba — không sao chép credential rỗng của app, không thử unauth rồi fallback, không nới reader chung. Thí nghiệm transport có kiểm soát (bảng cuối file) cho thấy proxy hiện tại **từ chối** mọi biến thể lệch khỏi policy này; vậy nhánh credential rỗng trong bytecode không được server chấp nhận — hoặc app thật bơm token ở tầng khác (Axios wrapper `module_1(Axios2)` chưa phục dựng) hoặc proxy đã đổi hành vi so với APK build 31. CLI không thay đổi.
- Reader tổng kết chỉ dành cho `GetSemesterMark`: raw JSON array, envelope có data list, hoặc JSON string chứa trọn array. Giới hạn xử lý cục bộ 1 MiB. Không cắt tùy tiện chuỗi giữa dấu ngoặc; XML/HTML wrapper chưa xác minh bị từ chối bằng lỗi payload an toàn. Reader chung của operation khác không được nới lỏng.
- Photo JSON không đồng nghĩa đã hỗ trợ xuất ảnh binary. Không tự fetch URL bất kỳ hoặc chuyển credential sang host ảnh.
-- Rating list v1 có code/fixture; URL là `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentRate`. Rating list v2 là stub và bị chặn. Rating submit/push/feedback đầy đủ chưa được mở bởi các thay đổi này. Những gate tại [tasks/phase6.md](../tasks/phase6.md) vẫn còn pending, Phase 6 **chưa hoàn tất**.
+- Rating list v1 có code/fixture; URL là `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentRate`. Rating list v2 là stub và bị chặn. Rating submit/push/feedback đầy đủ chưa được mở bởi các thay đổi này. Những gate tại [docs/discovery/phase6.md](phase6.md) vẫn còn pending, Phase 6 **chưa hoàn tất**.
- `GetVersion` đã mở cho `doctor --online` ngày 24/10/2026 sau khi chốt contract bằng probe: caller APK dùng GET nhưng proxy trả 405; POST body `{}` bootstrap đạt 200 với data chuỗi ngắn (chấp nhận bootstrap lẫn FAP key Bearer); route v1 trả 404. `myfap version` tiếp tục chỉ đọc package version.
## Kiểm chứng
@@ -96,7 +96,7 @@ Người dùng xác nhận mở browser/context mới, session tạm riêng trê
Khảo sát caller bổ sung: training dùng **semesterName** tại `module_1303.js:114–117,288–302` và `module_1300.js:108–110,222–229`; không có căn cứ đổi thành termID. Với courses, chỉ thấy facade forward (`549_AlertMaintain.js:262–265`), chưa có UI caller chứng minh semesterName hay termID ở v1. Search UI (`module_1291.js:251–263,345–358`) còn có trim/lower và bước XML entity encoding với receiver phục dựng chưa rõ; CLI hiện truyền search text qua params. Input live tổng quát đã trim/lower, chưa xác nhận đây là nguyên nhân 201 hoặc có căn cứ sửa contract từ decompile. Không dùng các bất định này để tự thử ID/alias khác hay double URL-encode.
-Regression tổng hợp `V1ObservedFailureTests` giữ bốn trạng thái 404/201 là lỗi CLI với stdout rỗng, một request, không refresh/fallback và không đổi session. Đây là test policy bằng mã/shape đã lọc, không phải bằng chứng sửa backend hoặc dữ liệu thật làm fixture. Theo dõi nguyên nhân tại [TODO](../tasks/todo.md). Rating submit/push/feedback ghi vẫn chưa mở; Phase 6 chưa hoàn tất.
+Regression tổng hợp `V1ObservedFailureTests` giữ bốn trạng thái 404/201 là lỗi CLI với stdout rỗng, một request, không refresh/fallback và không đổi session. Đây là test policy bằng mã/shape đã lọc, không phải bằng chứng sửa backend hoặc dữ liệu thật làm fixture. Theo dõi nguyên nhân tại [TODO](todo.md). Rating submit/push/feedback ghi vẫn chưa mở; Phase 6 chưa hoàn tất.
## Live nghiệm thu mục 2 (24/10/2026, v2/HN)
@@ -109,7 +109,7 @@ Chạy trên máy cá nhân bằng session thật của người dùng ở code
| `other training` (tự chọn kỳ mới nhất) | 200 / 200 | List rỗng; không phải positive nghiệp vụ |
| `marks --summary` | 200 / 200 | Envelope data list 32 phần tử; mỗi phần tử đúng 5 khóa `SubjectCode`, `ClassName`, `AverageMark`, `Status`, `GradeStatus` — positive schema thật đầu tiên cho GetSemesterMark |
-Lượt này cùng bằng chứng bytecode ở phần Policy khép hộp credential v2 của transcript/training/summary trong [phase6.md](../tasks/phase6.md) mục 2. Schema nghiệp vụ transcript (HTML) và training vẫn giữ nhãn chưa kiểm chứng; positive schema summary là xác nhận dạng dữ liệu trên một tài khoản, chưa phải nghiệm thu backend mọi campus.
+Lượt này cùng bằng chứng bytecode ở phần Policy khép hộp credential v2 của transcript/training/summary trong [phase6.md](phase6.md) mục 2. Schema nghiệp vụ transcript (HTML) và training vẫn giữ nhãn chưa kiểm chứng; positive schema summary là xác nhận dạng dữ liệu trên một tài khoản, chưa phải nghiệm thu backend mọi campus.
### Thí nghiệm transport có kiểm soát (24/10/2026)
diff --git a/docs/phase6-write-gates.md b/docs/discovery/phase6-write-gates.md
similarity index 97%
rename from docs/phase6-write-gates.md
rename to docs/discovery/phase6-write-gates.md
index 8713e4e..98d68c8 100644
--- a/docs/phase6-write-gates.md
+++ b/docs/discovery/phase6-write-gates.md
@@ -29,4 +29,4 @@ Nguồn nội bộ workspace: `analysis/modules/module_550.js:484–521`, `modul
4. Fixture tạo lại bằng dữ liệu tổng hợp, không copy response/capture nguyên bản. Mỗi version có test exact query/body/signing identity và lỗi riêng.
5. Khi đủ contract mới mở capability: validate input → capability → preview không bí mật → confirmation/`--yes` → auth → một lần gửi. Cancel hoặc input lỗi không load/refresh session; 401/timeout/5xx/App Check không replay mutation.
-Các gate là công việc còn mở, không bị bỏ khỏi scope âm thầm. Maintainer cần bổ sung bằng chứng hoặc chốt thay đổi phạm vi tường minh trước khi nghiệm thu Phase 6 và tiếp tục phát hành. Xem [checklist](../tasks/phase6.md) và [coverage](phase6-coverage.md).
+Các gate là công việc còn mở, không bị bỏ khỏi scope âm thầm. Maintainer cần bổ sung bằng chứng hoặc chốt thay đổi phạm vi tường minh trước khi nghiệm thu Phase 6 và tiếp tục phát hành. Xem [checklist](phase6.md) và [coverage](phase6-coverage.md).
diff --git a/tasks/phase6.md b/docs/discovery/phase6.md
similarity index 89%
rename from tasks/phase6.md
rename to docs/discovery/phase6.md
index 72cd761..2080d39 100644
--- a/tasks/phase6.md
+++ b/docs/discovery/phase6.md
@@ -2,7 +2,7 @@
Nhánh triển khai `feat/phase6-command-expansion` bắt đầu từ `main` tại `75fc7b4aa33a13b9b39eab898f61e2e693f4baf9`, sau khi [PR #9](https://github.com/WindowScary321/myfap-api-cli/pull/9) được merge. Theo quyết định ngày **23/10/2026**, Phase 5 chỉ chuẩn bị pipeline; **hoãn tag/publish đến sau khi hoàn thiện và nghiệm thu phạm vi Phase 6**. Giữ baseline `0.2.0`, Python >=3.9, v1 mặc định và v2 opt-in.
-Nhóm command đọc đã có implementation và fixture CLI/HTTP; xem [coverage Phase 6](../docs/phase6-coverage.md). Dấu đã kiểm bên dưới chỉ áp dụng cho code/fixture được nêu, không thay thế live hoặc nghiệm thu backend. Phần thiếu contract/schema vẫn giữ gate rõ; không đánh dấu toàn Phase 6 hoàn tất khi các yêu cầu bắt buộc còn mở.
+Nhóm command đọc đã có implementation và fixture CLI/HTTP; xem [coverage Phase 6](phase6-coverage.md). Dấu đã kiểm bên dưới chỉ áp dụng cho code/fixture được nêu, không thay thế live hoặc nghiệm thu backend. Phần thiếu contract/schema vẫn giữ gate rõ; không đánh dấu toàn Phase 6 hoàn tất khi các yêu cầu bắt buộc còn mở.
## Quy tắc xuyên suốt
@@ -50,12 +50,12 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## Checkpoint: nhóm đọc
- [x] Focused/full regression, build/Twine/artifact validator và pip smoke đạt; không có docs/tasks/tests/session/capture trong distribution.
-- [x] Cập nhật [mapping command/endpoint/URL](../docs/command-endpoints.md), [contract v2](../docs/v2-contracts.md) và coverage Phase 6 với capability theo version/account rõ ràng.
+- [x] Cập nhật [mapping command/endpoint/URL](../cli/command-endpoints.md), [contract v2](../cli/v2-contracts.md) và coverage Phase 6 với capability theo version/account rõ ràng.
- [x] Live đọc bằng session/browser mới; ghi riêng success, empty, not-found, failure, skip và unverified. Không dùng 200 hoặc nonempty để đóng positive fee/survey; không dùng v2 để đóng finding v1.
## 4. Rating và push — chỉ mở sau gate contract
-Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ PII được liệt kê tại [phase6-write-gates.md](../docs/phase6-write-gates.md). Không dùng body/query tùy ý để thay cho schema; caller code 200 của AddRate đã biết nhưng ack nghiệp vụ/positive item chưa được xác minh.
+Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ PII được liệt kê tại [phase6-write-gates.md](phase6-write-gates.md). Không dùng body/query tùy ý để thay cho schema; caller code 200 của AddRate đã biết nhưng ack nghiệp vụ/positive item chưa được xác minh.
*Ghi chú phạm vi (24/10/2026):* Năm (5) hộp việc bên dưới liên quan đến thao tác ghi (`AddRate`, `UpdateTokedevices`, tách luồng retry, test invalid/cancel không replay, và xác nhận live ghi) tiếp tục **giữ trạng thái gate/unsupported có chủ đích** do tài khoản kiểm chứng hiện tại trả danh sách rating rỗng, không thể xác minh schema/ack thực tế. Tuyệt đối không đánh dấu tick khi chưa có bằng chứng và không diễn giải thành "mọi hộp việc đã hoàn tất".
@@ -79,7 +79,7 @@ Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ
- [x] Dùng red → green từng feature qua CLI thật và HTTP giả; mutation check cho casing, signing identity và no-retry. Không dùng dữ liệu account làm fixture.
- [x] Chạy từ checkout: `uv sync --locked --group ci`, focused tests, rồi `uv run --locked --group ci python -m unittest discover -s tests -v` trên Python 3.9/3.11; `git diff --check`.
-- [x] Build, Twine, artifact validator và pip smoke theo [development.md](../docs/development.md); CI xác nhận Ubuntu/Windows × Python 3.9/3.11.
+- [x] Build, Twine, artifact validator và pip smoke theo [development.md](../cli/development.md); CI xác nhận Ubuntu/Windows × Python 3.9/3.11.
- [x] Review độc lập phần query/credential/parser/write safety và cập nhật README/CHANGELOG/coverage theo đúng kết quả.
- [x] Draft PR Phase 6 được tạo từ nhánh mới; mỗi commit push có comment ngay sau commit, gồm SHA, thay đổi, lệnh/exit code và giới hạn.
- [x] Maintainer nghiệm thu phạm vi Phase 6 trước khi tiếp tục [gate phát hành Phase 5](phase5.md). Không tự merge/tag/publish.
@@ -94,7 +94,7 @@ Build, Twine và artifact validator đã đạt với bộ `dist-phase6-reads`,
Lượt thử live đầu chưa hoàn tất login (exit 1, chưa có response FAP); doctor local đạt, các command xác thực sau login chưa chạy; đã dọn session/thư mục tạm. Lượt sau ngày 24/10/2026, người dùng xác nhận login mới v2/HN: **14 lần command đều exit 0**, JSON hợp lệ; courses, subjects theo kỳ, balance, search, transcript, training, summary, photo JSON và doctor bootstrap đều HTTP/body 200. Training list rỗng hợp lệ; balance/transcript/photo là string, chưa suy schema nghiệp vụ hoặc định dạng ảnh. Refresh và đọc sau refresh đạt, session/lock/thư mục tạm đã dọn.
-CI của code `0e0c01c` đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064917612). Xem [metadata và giới hạn live](../docs/phase6-coverage.md#live-đọc-v2hn-ngày-24102026). Sau đó đã login mới và chạy v1/APHL trên `ca09b11`: 14 lần command, 10 exit 0/4 exit 1, harness exit 1. Subjects/balance/transcript/photo/rating list đọc được, nhưng transcript rỗng, photo null và rating list rỗng chưa xác minh positive schema. Courses/summary HTTP 404; search/training HTTP 200/body 201, chưa rõ nguyên nhân. Không fallback hoặc che lỗi bằng empty; đã dọn session/lock. Xem [kết quả v1](../docs/phase6-coverage.md#live-đọc-v1aphl-ngày-24102026). Rating submit/push/feedback vẫn gate, không tuyên bố Phase 6 hoàn tất. Các finding v1 và positive fee/survey giữ tại [todo.md](todo.md).
+CI của code `0e0c01c` đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064917612). Xem [metadata và giới hạn live](phase6-coverage.md#live-đọc-v2hn-ngày-24102026). Sau đó đã login mới và chạy v1/APHL trên `ca09b11`: 14 lần command, 10 exit 0/4 exit 1, harness exit 1. Subjects/balance/transcript/photo/rating list đọc được, nhưng transcript rỗng, photo null và rating list rỗng chưa xác minh positive schema. Courses/summary HTTP 404; search/training HTTP 200/body 201, chưa rõ nguyên nhân. Không fallback hoặc che lỗi bằng empty; đã dọn session/lock. Xem [kết quả v1](phase6-coverage.md#live-đọc-v1aphl-ngày-24102026). Rating submit/push/feedback vẫn gate, không tuyên bố Phase 6 hoàn tất. Các finding v1 và positive fee/survey giữ tại [todo.md](todo.md).
Sau khi thêm `V1ObservedFailureTests` bằng status/shape tổng hợp: focused nhóm đọc với FORCE_COLOR=1 đạt 15/15 trên cả Python 3.11/3.9, exit 0. Full chuẩn của repo chạy tuần tự có **392 test mỗi version, 388 đạt/4 skip, exit 0**. Không sửa runtime để che bốn lỗi server v1. Lượt thử ép FORCE_COLOR=1 lên toàn suite (không phải môi trường gate chuẩn) có 5 failure ở assertion màu/spinner cũ trong test_auth_contract/test_cli/test_cli_output; chưa ghi nhận hỗ trợ full suite ở mode đó. Chỉ focused màu và full chuẩn được ghi đạt; không xóa/nới các assertion cũ.
@@ -102,7 +102,7 @@ Nghiệm thu nhóm mục 1 hoàn tất ngày 24/10/2026 bằng lớp `ReadSliceA
Nghiệm thu nhóm mục 2 hoàn tất ngày 24/10/2026. (1) Từ chối tổ hợp `--summary` với `--semester`/`--courseid`/`--pretty` đã có code chặn trước auth và test `test_conflicting_summary_options_fail_before_auth`. (2) Reader `read_semester_marks_response` kiểm HTTP/App Check/expiry trước khi đọc, giới hạn 1 MiB và từ chối wrapper chưa xác minh bằng payload error — phủ bởi 5 test reader trong tests/test_phase6_summary.py, gồm phân loại 401/503 cho body lỗi quá lớn. (3) Credential v2 chốt bằng bytecode caller: trong module_599.js của APK, wrapper GET (closure_21, dòng 898–906) mặc định credential là chuỗi rỗng khi caller không truyền tham số thứ tư; `_buildHeaders` (dòng 747–781) với credential rỗng tạo header **không Authorization** và `_makeChecksum` (dòng 726–746) ký bằng bootstrap token. Cả ba `_getSemesterMark` (dòng 218–224), `_getAcademicTranscript` (dòng 266–272) và `_getDiemphongtrao` (dòng 280–286) đều gọi wrapper không truyền credential header; chỉ GetSemesterMark đặt FAP key trong query `Authen`. CLI giữ chủ đích policy authenticated-read (Bearer FAP key + Checksum theo key) cho cả ba, không sao chép credential rỗng, không thử unauth rồi fallback, không nới reader chung; khác biệt với app được ghi tại coverage. Kiểm đọc live v2/HN bằng chính CLI đạt HTTP/body 200 cả ba operation ở lượt 24/10 và lượt nghiệm thu hôm nay. Lượt nghiệm thu chạy trên máy cá nhân với session thật; output raw chỉ xử lý cục bộ trên máy đó, đã xóa sau khi trích metadata và không đưa lên Git. Metadata được ghi: info student đối chứng 200 (list 1); transcript 200 data chuỗi ~10,5 KB là mảnh HTML bảng (53 `` bao); training 200 list rỗng kỳ mới nhất; marks --summary 200 envelope data list 32 phần tử, mỗi phần tử đúng 5 khóa `SubjectCode`/`ClassName`/`AverageMark`/`Status`/`GradeStatus` — positive schema thật đầu tiên cho summary. Formatter nghiệp vụ transcript/training vẫn giữ nhãn chưa kiểm chứng; fixture trong test luôn synthetic. Theo yêu cầu của maintainer, biến thể credential rỗng được kiểm chứng thêm bằng thí nghiệm transport có kiểm soát trước khi đổi CLI: proxy từ chối HTTP 400 mọi biến thể không Authorization hoặc checksum lệch credential (và 500 khi dùng bootstrap token làm credential dữ liệu); duy nhất Bearer FAP key + checksum theo cùng key đạt 200 — policy CLI được xác nhận hai chiều và giữ nguyên; chi tiết tại coverage Phase 6.
-Nghiệm thu mục 3 và mở rộng endpoint hoàn tất ngày 24/10/2026 sau khi đối chiếu toàn bộ 82 route của APK với adapter (xem [phân tích khoảng trống](../docs/endpoint-gap-analysis.md)). `GetVersion` chốt contract bằng probe: GET bị 405, POST body `{}` bootstrap đạt 200 với data chuỗi ngắn, route v1 404 — mở cho `doctor --online` với `backend_version` trong report, `myfap version` vẫn offline; test doctor hiện có cập nhật cho hai probe và test mới chặn version không phải chuỗi, trong đó test bắt một lỗi thứ tự thật (probe version trước khi validate active) đã sửa. `GetStudentFeedbacks` mở `other feedbacks` theo envelope live 200/list rỗng và bytecode query `{CampusCode, rollNumber}`; RED 3 test → GREEN. Nhóm C/D của phân tích (donor/employee, login thay thế, OTA, Linking features) được ghi rõ là out of scope/QoL trong docs. Full suite 403 test, 399 đạt/4 skip, exit 0 trên Windows Python 3.11; kiểm CLI thật với session cá nhân: `other feedbacks` exit 0 (200, list rỗng), `doctor --online` exit 0 (`backend_version` chuỗi ngắn). Các finding v1 và mục 4–6 còn lại giữ nguyên trạng thái mở.
+Nghiệm thu mục 3 và mở rộng endpoint hoàn tất ngày 24/10/2026 sau khi đối chiếu toàn bộ 82 route của APK với adapter (xem [phân tích khoảng trống](endpoint-gap-analysis.md)). `GetVersion` chốt contract bằng probe: GET bị 405, POST body `{}` bootstrap đạt 200 với data chuỗi ngắn, route v1 404 — mở cho `doctor --online` với `backend_version` trong report, `myfap version` vẫn offline; test doctor hiện có cập nhật cho hai probe và test mới chặn version không phải chuỗi, trong đó test bắt một lỗi thứ tự thật (probe version trước khi validate active) đã sửa. `GetStudentFeedbacks` mở `other feedbacks` theo envelope live 200/list rỗng và bytecode query `{CampusCode, rollNumber}`; RED 3 test → GREEN. Nhóm C/D của phân tích (donor/employee, login thay thế, OTA, Linking features) được ghi rõ là out of scope/QoL trong docs. Full suite 403 test, 399 đạt/4 skip, exit 0 trên Windows Python 3.11; kiểm CLI thật với session cá nhân: `other feedbacks` exit 0 (200, list rỗng), `doctor --online` exit 0 (`backend_version` chuỗi ngắn). Các finding v1 và mục 4–6 còn lại giữ nguyên trạng thái mở.
Checkpoint nhóm đọc khép ngày 24/10/2026. (1) Build/Twine/validator/pip smoke chạy lại trên code mới: `uv build` wheel+sdist 0.2.0, Twine strict PASSED cả hai, artifact validator exit 0 với manifest SHA-256 `abcaef1b70e20a1e200b6458c58677d3d6d876c2b50819e6f5e8df73b900dae7` (không docs/tasks/tests/session/capture trong distribution), pip smoke hai venv sạch exit 0; full regression 403 test như trên. (2) Mapping/contract/coverage đã cập nhật kèm phân tích khoảng trống endpoint. (3) Quét toàn bộ lệnh đọc bằng **login/browser mới** với session tạm (hai lượt, đều đã logout): 29 lệnh chạy trong lượt chính — success có dữ liệu gồm cả **attendance detail positive đầu tiên** (param trích cục bộ từ courses) và **news search v2 list(50)**; data rỗng hợp lệ (marks, applications, training, feedbacks, marks --courseid str rỗng); survey giữ not-found theo contract; fee v2 list không rỗng nhưng **không đóng positive fee**; rating list exit 1 đúng thiết kế v1-only trên session v2; lệnh bảng semesters đạt ở lượt phụ (lượt chính sai cú pháp `--stdout` do harness, exit 2 không phải lỗi CLI). Chi tiết metadata tại coverage Phase 6; không dùng 200/nonempty để đóng positive fee/survey và không dùng v2 để đóng finding v1.
diff --git a/tasks/todo.md b/docs/discovery/todo.md
similarity index 84%
rename from tasks/todo.md
rename to docs/discovery/todo.md
index acf3c4a..b2cef08 100644
--- a/tasks/todo.md
+++ b/docs/discovery/todo.md
@@ -9,12 +9,12 @@ Kết quả GitHub Actions và bình luận kiểm tra được theo dõi trực
## Kiểm chứng live còn mở trước khi phát hành
-- [x] Chạy lại `news`, `other notification` và `other fee` trên v1/APHL bằng session tạm ngày 19/10/2026. News/notification nhận HTTP 200/body 201; fee nhận HTTP 404. Lệnh đối chứng `info student` đạt 200/200 trước và sau; session/lock tạm đã xóa. Xem [báo cáo live v1](../docs/phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
+- [x] Chạy lại `news`, `other notification` và `other fee` trên v1/APHL bằng session tạm ngày 19/10/2026. News/notification nhận HTTP 200/body 201; fee nhận HTTP 404. Lệnh đối chứng `info student` đạt 200/200 trước và sau; session/lock tạm đã xóa. Xem [báo cáo live v1](phase4-coverage.md#chạy-lại-ba-lệnh-v1-ngày-19102026).
- [ ] Xác minh ý nghĩa body 201 của `news` v1 và đối chiếu trường hợp có dữ liệu. Lượt live mới vẫn có `data: null`, message null hoặc không có. Không gộp mọi code 201 vào hết phiên hoặc coi đó là danh sách rỗng hợp lệ.
- [ ] Xác định nguyên nhân body 201 của `other notification` v1. Request khớp path/query/checksum của app; session đối chứng vẫn đọc được, chưa xác nhận lỗi thuộc backend hay điều kiện tài khoản.
- [ ] Xác nhận `GeFeeByRoll` v1 có response thành công hoặc có bằng chứng từ đơn vị vận hành về phạm vi hỗ trợ. HTTP 404 trên APHL chưa đủ để kết luận route đã ngừng hỗ trợ trên mọi campus hoặc suy ra schema.
-Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md) và [báo cáo coverage](../docs/phase4-coverage.md).
+Mỗi mục cần session tạm, kết quả ghi rõ API version/campus và metadata đã lọc trước khi đóng. Không đưa credential, thông tin cá nhân hoặc raw response lên Git. CI xanh, fixture hoặc kết quả API v2 không thay thế kiểm chứng live v1. Xem [checklist Phase 4](https://github.com/WindowScary321/myfap-api-cli/blob/467df1edb2220261dcd21392fbe3eaf008d6c662/tasks/phase4.md) và [báo cáo coverage](phase4-coverage.md).
## Kiểm chứng hoãn chờ dữ liệu phù hợp
@@ -27,7 +27,7 @@ Khi có điều kiện kiểm chứng, dùng session tạm, ghi rõ API version/
## Chuẩn bị phát hành Phase 5
-Theo dõi triển khai, kết quả kiểm tra và gate dịch vụ còn mở tại [phase5.md](phase5.md). [Runbook phát hành](../docs/releasing.md) mô tả kiểm tag/version/artifact, Trusted Publishing, retry và TestPyPI; [CHANGELOG.md](../CHANGELOG.md) giữ release notes cùng known issues.
+Theo dõi triển khai, kết quả kiểm tra và gate dịch vụ còn mở tại [phase5.md](phase5.md). [Runbook phát hành](../cli/releasing.md) mô tả kiểm tag/version/artifact, Trusted Publishing, retry và TestPyPI; [CHANGELOG.md](../../CHANGELOG.md) giữ release notes cùng known issues.
Chuyển Phase 5 không tự đóng ba lỗi live v1, không xác nhận positive fee/survey và không cho phép tạo/push tag hoặc publish. Maintainer phải duyệt phạm vi hỗ trợ và các gate phát hành trước khi thực hiện.
@@ -44,15 +44,15 @@ Checklist, tiêu chí và gate bằng chứng nằm tại [phase6.md](phase6.md)
- [x] Bổ sung xuất lịch thi `exams --ics` (RFC 5545, CRLF, UTC UID/DTSTAMP) và cờ `--full` (hoàn tất 26/10/2026).
- [x] Kiểm regression, artifact, CI và live đọc riêng; giữ nguyên mọi skip/failure/unverified và TODO v1/positive fee/survey ở trên (420 test đạt trên Python 3.9/3.11).
- [x] Đồng bộ tài liệu và đóng các điểm lệch phạm vi trước merge (Pre-merge Docs Sync):
- - [x] Khớp lại ghi chú mục 4–5 trong `tasks/phase6.md` (khẳng định 8 hộp việc giữ gate/unsupported có chủ đích, không tick khi chưa có schema live).
- - [x] Chuẩn hóa tuyên bố trong `docs/endpoint-gap-analysis.md` (ghi nhận CLI phủ toàn bộ thao tác đọc sinh viên ngoại trừ `GetStudentFeedbackForm`).
- - [x] Đồng bộ thứ tự phát hành trong `docs/releasing.md` (khớp quyết định phát hành sau khi nghiệm thu phạm vi Phase 6).
+ - [x] Khớp lại ghi chú mục 4–5 trong `docs/discovery/phase6.md` (khẳng định 8 hộp việc giữ gate/unsupported có chủ đích, không tick khi chưa có schema live).
+ - [x] Chuẩn hóa tuyên bố trong `docs/discovery/endpoint-gap-analysis.md` (ghi nhận CLI phủ toàn bộ thao tác đọc sinh viên ngoại trừ `GetStudentFeedbackForm`).
+ - [x] Đồng bộ thứ tự phát hành trong `docs/cli/releasing.md` (khớp quyết định phát hành sau khi nghiệm thu phạm vi Phase 6).
- [x] Cập nhật Draft PR Phase 6; mỗi commit push có comment ngay sau commit, không tự merge/tag/publish.
- [ ] Maintainer duyệt phạm vi Phase 6 và các gate dịch vụ Phase 5 trước khi phát hành thật.
### Lỗi live v1 mới ngày 24/10/2026
-Các command đã chạy thật trên v1/APHL sau login mới; chi tiết tại [coverage Phase 6](../docs/phase6-coverage.md#live-đọc-v1aphl-ngày-24102026). Không dùng kết quả v2 hoặc fixture để đóng các mục này:
+Các command đã chạy thật trên v1/APHL sau login mới; chi tiết tại [coverage Phase 6](phase6-coverage.md#live-đọc-v1aphl-ngày-24102026). Không dùng kết quả v2 hoặc fixture để đóng các mục này:
- [ ] Xác định nguyên nhân GetCourseOfSemester HTTP 404; request hiện giữ casing/signing theo caller v1.
- [ ] Xác định nguyên nhân GetSemesterMark HTTP 404; không tự thêm checksum/kỳ hoặc đổi route để thử.
@@ -69,11 +69,11 @@ Theo đánh giá của maintainer ngày 24/10/2026, **các mục 4 (rating/push)
- **Push register (`UpdateTokedevices`)**: thao tác ghi thiết bị; cần contract student đã chốt và xác nhận riêng trước khi live ghi.
- **`GetStudentFeedbackForm`**: `other feedbacks` trả list rỗng — không có feedbackId thật; không đoán ID theo quy tắc plan.
- **`SubmitStudentFeedback`**: cần feedback đang mở để có form/ack hợp lệ.
-- **Donor/employee và login thay thế** (`GetNotificationByDonor`, `GetTokenWithEmp`, `UpdateTokenDonor`, Google/username/FeIdCode): đã ghi out of scope tại [phân tích khoảng trống endpoint](../docs/endpoint-gap-analysis.md), không dự định triển khai trong Phase 6.
+- **Donor/employee và login thay thế** (`GetNotificationByDonor`, `GetTokenWithEmp`, `UpdateTokenDonor`, Google/username/FeIdCode): đã ghi out of scope tại [phân tích khoảng trống endpoint](endpoint-gap-analysis.md), không dự định triển khai trong Phase 6.
-Hệ quả khi chốt phạm vi Phase 6 và phát hành `0.2.0`: Tám (8) hộp việc ở mục 4–5 trong `tasks/phase6.md` tiếp tục giữ trạng thái **gate/unsupported có chủ đích** (không tick trong `phase6.md`), không đánh dấu hoàn tất và không mở generic submit; `docs/endpoint-gap-analysis.md` đã chuẩn hóa tuyên bố phủ toàn bộ đọc sinh viên ngoại trừ `GetStudentFeedbackForm`; maintainer duyệt phát hành với known issues này. Khi có tài khoản hoặc dữ liệu phù hợp:
+Hệ quả khi chốt phạm vi Phase 6 và phát hành `0.2.0`: Tám (8) hộp việc ở mục 4–5 trong `docs/discovery/phase6.md` tiếp tục giữ trạng thái **gate/unsupported có chủ đích** (không tick trong `phase6.md`), không đánh dấu hoàn tất và không mở generic submit; `docs/discovery/endpoint-gap-analysis.md` đã chuẩn hóa tuyên bố phủ toàn bộ đọc sinh viên ngoại trừ `GetStudentFeedbackForm`; maintainer duyệt phát hành với known issues này. Khi có tài khoản hoặc dữ liệu phù hợp:
-- [ ] Thu thập input schema và ack của `AddRate` (v1 checksum `rateid`, v2 query `Authen`, body `{}`) và các form feedback theo [phase6-write-gates.md](../docs/phase6-write-gates.md) trước khi mở command.
+- [ ] Thu thập input schema và ack của `AddRate` (v1 checksum `rateid`, v2 query `Authen`, body `{}`) và các form feedback theo [phase6-write-gates.md](phase6-write-gates.md) trước khi mở command.
- [ ] `push register --token-file` cần contract student đã chốt và xác nhận riêng của người dùng trước khi live ghi; token thiết bị chỉ đọc từ regular file, không đưa vào argv/preview/log/error.
Các gate và trình tự validate → capability → preview → confirmation → auth vẫn áp dụng; không cố tình thử ghi để tạo dữ liệu, không coi list rỗng là route lỗi, và việc chưa xác minh được không tự đóng cũng không nới gate.
diff --git a/tests/test_ci_scope.py b/tests/test_ci_scope.py
index baa9f62..04594a4 100644
--- a/tests/test_ci_scope.py
+++ b/tests/test_ci_scope.py
@@ -14,6 +14,7 @@
class ScopePolicyTests(unittest.TestCase):
def test_repository_only_changes_skip_checks(self):
for paths in ([], ["docs/Example.md"], ["tasks/phase0.md"],
+ ["docs/cli/Example.md", "docs/discovery/todo.md"],
["docs/old.md", "docs/new.md", "tasks/todo.md"]):
with self.subTest(paths=paths):
self.assertFalse(ci_scope.paths_require_checks(paths))
From 25758ad46dd01ad1c62c51dd7085ca68f107d893 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Wed, 18 Nov 2026 09:38:14 +0700
Subject: [PATCH 8/9] =?UTF-8?q?docs:=20ch=E1=BB=89nh=20s=E1=BB=ADa=201=20s?=
=?UTF-8?q?=E1=BB=91=20docs=20v=C3=A0=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 7 +------
docs/discovery/2026-10-19-pr8-bug-handoff.md | 10 +++++-----
2 files changed, 6 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index b3a7fe5..deda84c 100644
--- a/README.md
+++ b/README.md
@@ -135,9 +135,4 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
- [Playwright](https://playwright.dev/): chịu trắch nhiệm chính trong quy trình login
- [Typer](https://typer.tiangolo.com/) & [Rich](https://rich.readthedocs.io/): nền tảng giao diện cli của repo này
- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/): bóc tách và xử lý dữ liệu html
-- [ics.py](https://icspy.readthedocs.io/): tạo và chuẩn hóa định dạng iCalendar giúp dễ dàng import vào các ứng dụng lịch
-
-## Các model đã sử dụng
-- [Gemini 3 Pro Preview](https://openrouter.ai/google/gemini-3-pro-preview): Hoàn thành phiên bản myFAP đầu tiên (trước v0.2.0), tích hợp API v1
-- [GPT-6.1 Sol](https://openrouter.ai/openai/gpt-6.1-sol): Agent chính lên kế hoạch cho việc tích hợp API v2, viết testcase dành cho unittesting và viết script CI/CD
-- [Gemini 3.8 Flash](https://openrouter.ai/google/gemini-3.8-flash), [DeepSeek V4.1 Flash](https://openrouter.ai/deepseek/deepseek-v4.1-flash), [GLM 5.3 Flash](https://openrouter.ai/z-ai/glm-5.3-flash): Các subagent thực hiện code và test
+- [ics.py](https://icspy.readthedocs.io/): tạo và chuẩn hóa định dạng iCalendar giúp dễ dàng import vào các ứng dụng lịch
\ No newline at end of file
diff --git a/docs/discovery/2026-10-19-pr8-bug-handoff.md b/docs/discovery/2026-10-19-pr8-bug-handoff.md
index 95241a8..3eb98f3 100644
--- a/docs/discovery/2026-10-19-pr8-bug-handoff.md
+++ b/docs/discovery/2026-10-19-pr8-bug-handoff.md
@@ -21,8 +21,8 @@ Kiểm tra đối chứng: refresh timeout trên v1/v2 không đổi file sessio
Đã chạy 25 tiến trình CLI độc lập và toàn bộ suite tại commit mới: **313 test, 309 đạt, 4 skip**. GitHub CI của commit này đạt 11/11 job: . Chưa thấy regression mới có đủ bằng chứng trong phần code sửa.
-- [Lệnh, exit code, trạng thái session và kết quả ICS sau sửa](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-recheck-_8hm6jvn/results.json).
-- [ICS 250 sự kiện sau sửa](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-recheck-_8hm6jvn/schedule-250.ics).
+- [Lệnh, exit code, trạng thái session và kết quả ICS sau sửa](../../../work/pr8-cli-recheck-_8hm6jvn/results.json).
+- [ICS 250 sự kiện sau sửa](../../../work/pr8-cli-recheck-_8hm6jvn/schedule-250.ics).
Các ca CLI độc lập vẫn chỉ dùng session/HTTP tổng hợp và sentinel chặn browser như mô tả ở dưới. Lượt này không gọi server thật hoặc thử nhập ICS vào ứng dụng lịch. Theo báo cáo mới của agent chính trong `docs/discovery/phase4-coverage.md`, ba lệnh v1 đã được chạy lại nhưng news/notification vẫn trả body 201 và fee vẫn HTTP 404; positive fee/survey còn mở. Đây là các giới hạn riêng, không bị đóng theo kết quả sửa bốn finding.
@@ -60,9 +60,9 @@ Hạ tầng có thể tái sử dụng: `.github/workflows/ci.yml` đã có `wor
Riêng `MyFapAuth._authorize` được thay bằng một hàm báo `REVIEW_BROWSER_REQUESTED` để xác nhận chương trình đã đi tới bước yêu cầu mở browser. Exit 1 có sentinel này là điểm dừng chủ động của phép thử, **không phải một lỗi đăng nhập mới**.
-- [Toàn bộ lệnh, exit code và HTTP trace đã lọc](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-verification-efcl8s7o/results.json).
-- [File ICS do CLI xuất từ fixture tổng hợp](C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-verification-efcl8s7o/schedule.ics).
-- Thư mục chứa stdout/stderr riêng cho từng ca: `C:/Users/tubeo/Downloads/com.fuct-2.0.6-build31-analysis/work/pr8-cli-verification-efcl8s7o/`.
+- [Toàn bộ lệnh, exit code và HTTP trace đã lọc](../../../work/pr8-cli-verification-efcl8s7o/results.json).
+- [File ICS do CLI xuất từ fixture tổng hợp](../../../work/pr8-cli-verification-efcl8s7o/schedule.ics).
+- Thư mục chứa stdout/stderr riêng cho từng ca: `../../../work/pr8-cli-verification-efcl8s7o/`.
Các lệnh có `--config` trong phần dưới được chạy với đường dẫn session tạm riêng. Để tái hiện lỗi cần server phản hồi, phải dựng đúng HTTP fixture đã mô tả; chỉ chạy lệnh bằng tài khoản thật không bảo đảm gặp điều kiện đó.
From 933da6f8b3b43870c5b1a7b51f26660611741d43 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Wed, 18 Nov 2026 10:47:24 +0700
Subject: [PATCH 9/9] =?UTF-8?q?fix:=20ch=E1=BA=B7n=20s=E1=BB=9Bm=20operati?=
=?UTF-8?q?on=20v1=20kh=C3=B4ng=20h=E1=BB=97=20tr=E1=BB=A3=20v=C3=A0=20ki?=
=?UTF-8?q?=E1=BB=83m=20tra=20ch=E1=BA=B7t=20option/parser=20CLI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.gitignore | 1 +
docs/cli/Example.md | 29 +++++++++-----
docs/cli/v2-contracts.md | 2 +-
myfap/api.py | 18 ++++++++-
myfap/auth.py | 10 ++++-
myfap/cli.py | 78 ++++++++++++++++++++++++------------
myfap/parsers.py | 25 ++++++++----
tests/test_auth_lifecycle.py | 10 +++++
tests/test_cli_options.py | 34 ++++++++++++++++
tests/test_cli_version.py | 8 ++--
tests/test_parsers.py | 35 ++++++++++++++++
tests/test_phase6_reads.py | 14 ++++++-
12 files changed, 212 insertions(+), 52 deletions(-)
diff --git a/.gitignore b/.gitignore
index 51300de..d786463 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@ __pycache__/
build/
develop-eggs/
dist/
+dist-*/
downloads/
eggs/
.eggs/
diff --git a/docs/cli/Example.md b/docs/cli/Example.md
index ed1b30f..a7f9297 100644
--- a/docs/cli/Example.md
+++ b/docs/cli/Example.md
@@ -14,26 +14,29 @@
CLI Tool dựa trên MyFAP dành cho Sinh Viên FPTU
Options:
- -c, --campus TEXT Mã cơ sở; dùng session, APHL chỉ mặc định cho v1
- --config TEXT Đường dẫn file session tùy chỉnh (thay vì mặc định
- ~/.myfap-api-cli/session.json)
- --timeout SECONDS Timeout HTTP theo giây; ưu tiên hơn MYFAP_TIMEOUT
- --help Show this message and exit.
+ -c, --campus Mã cơ sở; dùng session, APHL chỉ mặc định cho v1
+ --config Đường dẫn file session tùy chỉnh
+ --timeout SECONDS Timeout HTTP theo giây; ưu tiên hơn MYFAP_TIMEOUT
+ --api-version [v1|v2] Chọn v1/v2; ưu tiên option, MYFAP_API_VER, session, rồi v2
+ --help Show this message and exit.
Commands:
version Hiển thị phiên bản MyFap API CLI
+ doctor Chẩn đoán cấu hình explicit/default; không đọc hoặc làm mới session.
login Đăng nhập vào hệ thống FEID
logout Đăng xuất (Xóa session)
refresh Làm mới token (Refresh Token)
campuses Xem danh sách các cơ sở (Campus)
semesters Xem danh sách kỳ học
schedule Xem lịch học
- marks Xem bảng điểm
+ transcript Lấy bảng điểm toàn khóa theo contract API đã chọn.
+ courses Lấy danh sách khóa học theo kỳ.
+ marks Xem bảng điểm theo kỳ, chi tiết môn hoặc tổng kết.
exams Xem lịch thi
week-timetable Xem lịch học theo tuần
attendance Xem thông tin điểm danh
applications Xem danh sách đơn từ đã gửi cho trường
- news Xem 10 thông báo gần nhất
+ news Xem tin gần nhất hoặc tìm kiếm thông báo.
info Xem thông tin chung (sinh viên, campus)
other Các chức năng phụ trợ khác (survey, feedback, fee...)
```
@@ -137,15 +140,23 @@ Trước đây biến môi trường chỉ áp dụng cho request dữ liệu; n
Các chức năng phụ trợ khác (survey, feedback, fee...)
Options:
- --help Show this message and exit.
+ -c, --campus Mã cơ sở; dùng session, APHL chỉ mặc định cho v1
+ --config Đường dẫn file session tùy chỉnh
+ --timeout SECONDS Timeout HTTP theo giây; ưu tiên hơn MYFAP_TIMEOUT
+ --api-version [v1|v2] Chọn v1/v2; ưu tiên option, MYFAP_API_VER, session, rồi v2
+ --help Show this message and exit.
Commands:
+ training Lấy điểm phong trào theo kỳ.
survey Kiểm tra các survey chưa thực hiện
feedback Kiểm tra Feedback
+ feedbacks Lấy danh sách feedback student (chỉ API v2); item schema chưa kiểm chứng positive.
profile Kiểm tra Update Profile
notification Xem thông báo qua MSSV
fee Lấy danh sách học phí và trạng thái thanh toán từng khoản
- subjects Lấy danh sách tất cả môn học
+ balance Lấy số dư tài khoản; không diễn giải thành trạng thái nợ học phí.
+ subjects Lấy tất cả môn học hoặc các môn của một kỳ chỉ định.
+ rating Đánh giá dịch vụ; list hiện chỉ hỗ trợ API v1
```
### Refresh thủ công ``authen_key`` trong trường hợp cli bị lỗi
```
diff --git a/docs/cli/v2-contracts.md b/docs/cli/v2-contracts.md
index 2519818..c29f7e9 100644
--- a/docs/cli/v2-contracts.md
+++ b/docs/cli/v2-contracts.md
@@ -86,7 +86,7 @@ Bảy route giữ `Authen` trong query của adapter app là `CheckUpdateProfile
- Chưa tích hợp auto-detect/fallback; `GetApiActive` chỉ là request chẩn đoán.
- Chưa xác nhận live schema của proxy cho các route unsupported.
-- Chưa thêm v2 vào command mặc định hoặc đổi phiên bản session đã lưu khi handshake thất bại.
+- Không tự động đổi phiên bản session đã lưu khi handshake thất bại.
- Không dùng response rỗng để che route stub, HTTP 404 hoặc capability chưa biết.
Inventory được đối chiếu với các caller `MyFAP/*` trong `module_599.js`; các hàm stub nằm tại `21-31` và `458-460`. Service survey tiếp tục dùng host, checksum và contract riêng, không đi qua transport proxy này.
diff --git a/myfap/api.py b/myfap/api.py
index 97901af..66a3c27 100644
--- a/myfap/api.py
+++ b/myfap/api.py
@@ -123,9 +123,13 @@ def build_params():
auth=auth, operation=operation, params_factory=build_params, preserve_data=preserve_data)
+def _validate_text(value, message):
+ if not isinstance(value, str) or not value.strip() or any(ord(character) < 32 or ord(character) == 127 for character in value):
+ raise ApiError(message)
+
+
def _validate_semester(semester):
- if not isinstance(semester, str) or not semester.strip() or any(ord(character) < 32 for character in semester):
- raise ApiError("Kỳ học phải là chuỗi không rỗng, không chứa ký tự điều khiển.")
+ _validate_text(semester, "Kỳ học phải là chuỗi không rỗng, không chứa ký tự điều khiển.")
def _semester_start(semester):
@@ -292,6 +296,7 @@ def __init__(self, auth, timeout=None, api_version=None):
def get_schedule(self, semester: str):
"""Lấy lịch học theo kỳ."""
+ _validate_semester(semester)
return _authenticated_get(self.session, self.auth, "GetActivityStudent", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
@@ -303,6 +308,7 @@ def get_courses(self, semester: str):
def get_marks(self, semester: str):
"""Lấy bảng điểm theo kỳ."""
+ _validate_semester(semester)
return _authenticated_get(self.session, self.auth, "GetStudentMark", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
@@ -327,26 +333,34 @@ def build_params():
def get_mark_by_course(self, course_id: str):
"""Lấy điểm chi tiết của môn học, gồm dữ liệu HTML."""
+ if not (isinstance(course_id, int) and not isinstance(course_id, bool) and course_id > 0):
+ _validate_text(course_id, "Mã môn học không hợp lệ.")
return _authenticated_get(self.session, self.auth, "GetMarkByCourse", self.auth.mssv,
student=True, params={"CourseId": course_id}, timeout=self.timeout, api_version=self.api_version)
def get_exams(self, semester: str):
"""Lấy lịch thi theo kỳ."""
+ _validate_semester(semester)
return _authenticated_get(self.session, self.auth, "GetScheduleExam", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
def get_schedule_by_week(self, week: int, semester: str, year: int):
"""Lấy lịch học theo tuần."""
+ _validate_semester(semester)
return _authenticated_get(self.session, self.auth, "GetActivityStudentByWeek", self.auth.mssv,
student=True, params={"week": week, "Semester": semester, "year": year}, timeout=self.timeout, api_version=self.api_version)
def get_attendances(self, semester: str):
"""Lấy trạng thái điểm danh tổng quát theo kỳ."""
+ _validate_semester(semester)
return _authenticated_get(self.session, self.auth, "GetStudentAttendances", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
def get_course_attendance(self, semester: str, subject_code: str, class_name: str):
"""Lấy chi tiết điểm danh một môn học."""
+ _validate_semester(semester)
+ _validate_text(subject_code, "Mã môn học và tên lớp không hợp lệ.")
+ _validate_text(class_name, "Mã môn học và tên lớp không hợp lệ.")
return _authenticated_get(self.session, self.auth, "getCourseAttendance", self.auth.mssv,
student=True, params={"Semester": semester, "SubjectCode": subject_code, "ClassName": class_name}, timeout=self.timeout, api_version=self.api_version)
diff --git a/myfap/auth.py b/myfap/auth.py
index 1f81475..3051862 100644
--- a/myfap/auth.py
+++ b/myfap/auth.py
@@ -47,7 +47,11 @@ def create_survey_checksum(username: str) -> str:
def _text(value):
- return isinstance(value, str) and bool(value.strip())
+ return (
+ isinstance(value, str)
+ and bool(value.strip())
+ and not any(ord(character) < 32 or ord(character) == 127 for character in value)
+ )
class MyFapAuth:
@@ -58,12 +62,14 @@ def __init__(self, campus=None, session_file=None, timeout=None, api_version=Non
raise AuthError("API version không hợp lệ.")
if account_type is not None and not _text(account_type):
raise AuthError("Loại tài khoản không hợp lệ.")
+ if session_file is not None and (not isinstance(session_file, (str, Path)) or not _text(str(session_file))):
+ raise AuthError("Đường dẫn file session không hợp lệ. Hãy kiểm tra --config.")
self._requested = (campus, api_version, account_type)
self.campus = campus or "APHL"
self.api_version = api_version or "v1"
self.account_type = account_type or "student"
self.timeout = resolve_timeout(timeout)
- self.session_file = Path(session_file) if session_file else SESSION_FILE
+ self.session_file = Path(session_file) if session_file is not None else SESSION_FILE
self.store = SessionStore(self.session_file)
self.session = requests.Session()
self.session.headers.update({"User-Agent": "okhttp/4.9.2"})
diff --git a/myfap/cli.py b/myfap/cli.py
index 0bb834a..aedb747 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -26,6 +26,11 @@ def _override_common_option(ctx, param, value):
return value
+def _check_non_empty_option(value: Optional[str], hint: str, message: str):
+ if value is not None and (not isinstance(value, str) or not value.strip() or any(ord(c) < 32 or ord(c) == 127 for c in value)):
+ raise typer.BadParameter(message, param_hint=hint)
+
+
def _validate_common_options(callback):
@wraps(callback)
def invoke(*args, **kwargs):
@@ -36,6 +41,11 @@ def invoke(*args, **kwargs):
state["api_version_source"] = "environment"
if state["api_version"] not in (None, "v1", "v2"):
raise typer.BadParameter("Chỉ hỗ trợ v1 hoặc v2.", param_hint="--api-version / MYFAP_API_VER")
+ effective_campus = kwargs.get("campus") if kwargs.get("campus") is not None else state["campus"]
+ _check_non_empty_option(effective_campus, "--campus", "Mã cơ sở không hợp lệ.")
+ _check_non_empty_option(state["config"], "--config", "Đường dẫn file session không hợp lệ.")
+ if "output" in kwargs:
+ _check_non_empty_option(kwargs.get("output"), "--output", "Thư mục xuất không được rỗng.")
try:
state["timeout"] = resolve_timeout(state["timeout"])
except ValueError as error:
@@ -109,7 +119,7 @@ def inherit(command):
err_console = Console(stderr=True)
def get_auth(campus=None):
- c = campus if campus else state["campus"]
+ c = campus if campus is not None else state["campus"]
return MyFapAuth(campus=c, session_file=state.get("config"), timeout=state.get("timeout"), api_version=state.get("api_version"))
def require_auth(operation=None):
@@ -129,7 +139,14 @@ def require_auth(operation=None):
return auth
def require_operation(auth, operation):
- if auth.resolve_api_version() != "v2":
+ version = auth.resolve_api_version()
+ if version == "v1":
+ from .api import READ_OPERATIONS
+ if operation not in READ_OPERATIONS:
+ err_console.print(f"[red]Lỗi: {operation} chỉ có trên proxy API v2; v1 không có route tương ứng.[/red]")
+ raise typer.Exit(code=1)
+ return
+ if version != "v2":
return
from .v2 import OPERATION_ALIASES, SUPPORTED_OPERATIONS
operation = OPERATION_ALIASES.get(operation, operation)
@@ -138,7 +155,7 @@ def require_operation(auth, operation):
raise typer.Exit(code=1)
def resolve_semester(auth, semester_flag):
- if semester_flag:
+ if semester_flag is not None:
return semester_flag
essential = MyFapEssential(auth)
try:
@@ -167,10 +184,14 @@ def save_output(data, default_filename: str, output_dir: Optional[str], stdout:
stream.flush()
return
- out_path = Path(output_dir) if output_dir else Path.cwd()
+ _check_non_empty_option(output_dir, "--output", "Thư mục xuất không được rỗng.")
+ out_path = Path(output_dir) if output_dir is not None else Path.cwd()
out_path.mkdir(parents=True, exist_ok=True)
- # Tên file có thể nhúng dữ liệu server (tên kỳ); thay ký tự đường dẫn để không thoát thư mục xuất.
- safe_filename = default_filename.replace("\\", "_").replace("/", "_").replace("\x00", "_")
+ # Tên file có thể nhúng dữ liệu server (tên kỳ); thay ký tự đường dẫn/cấm trên Windows để không thoát thư mục xuất.
+ safe_filename = "".join(
+ "_" if (ord(ch) < 32 or ord(ch) == 127 or ch in '\\/:*?"<>|') else ch
+ for ch in default_filename
+ )
file_path = out_path / safe_filename
try:
@@ -239,7 +260,7 @@ def login(
force: bool = typer.Option(False, "--force", "-f", help="Bắt buộc đăng nhập lại từ đầu (mở trình duyệt)")
):
"""Đăng nhập vào hệ thống FEID"""
- target_campus = campus if campus else state["campus"]
+ target_campus = campus if campus is not None else state["campus"]
auth = get_auth(target_campus)
try:
@@ -336,6 +357,7 @@ def schedule(
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
"""Xem lịch học"""
+ _check_non_empty_option(semester, "--semester", "Kỳ học không được rỗng.")
auth = require_auth("GetActivityStudent")
client = MyFapClient(auth)
sem = resolve_semester(auth, semester)
@@ -383,8 +405,7 @@ def training(
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
"""Lấy điểm phong trào theo kỳ."""
- if semester is not None and not semester.strip():
- raise typer.BadParameter("Kỳ học không được rỗng.", param_hint="--semester")
+ _check_non_empty_option(semester, "--semester", "Kỳ học không được rỗng.")
auth = require_auth("GetDiemphongtrao")
client = MyFapClient(auth)
sem = resolve_semester(auth, semester)
@@ -403,8 +424,7 @@ def courses(
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
"""Lấy danh sách khóa học theo kỳ."""
- if semester is not None and not semester.strip():
- raise typer.BadParameter("Kỳ học không được rỗng.", param_hint="--semester")
+ _check_non_empty_option(semester, "--semester", "Kỳ học không được rỗng.")
auth = require_auth("GetCourseOfSemester")
client = MyFapClient(auth)
sem = resolve_semester(auth, semester)
@@ -426,6 +446,8 @@ def marks(
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
"""Xem bảng điểm theo kỳ, chi tiết môn hoặc tổng kết."""
+ _check_non_empty_option(semester, "--semester", "Kỳ học không được rỗng.")
+ _check_non_empty_option(courseid, "--courseid", "Mã môn học không được rỗng.")
if summary:
if semester is not None or courseid is not None or pretty:
raise typer.BadParameter("--summary không dùng cùng --semester, --courseid hoặc --pretty.")
@@ -437,20 +459,22 @@ def marks(
err_console.print(f"[red]Lỗi lấy tổng kết: {error}[/red]")
raise typer.Exit(code=1)
return
- if pretty and not courseid:
+ if courseid is not None and semester is not None:
+ raise typer.BadParameter("--courseid không dùng cùng --semester.")
+ if pretty and courseid is None:
err_console.print("[red]Lỗi: --pretty (-p) chỉ được sử dụng khi truyền mã môn --courseid (-cid)[/red]")
raise typer.Exit(code=1)
- auth = require_auth("GetMarkByCourse" if courseid else "GetStudentMark")
+ auth = require_auth("GetMarkByCourse" if courseid is not None else "GetStudentMark")
client = MyFapClient(auth)
- if courseid:
+ if courseid is not None:
try:
with err_console.status(f"[bold green]Đang tải điểm chi tiết môn {courseid}..."):
data = client.get_mark_by_course(courseid)
filename = f"BangDiem_{courseid}.json"
- if pretty and isinstance(data, dict) and 'data' in data and data['data'] and ' str:
"""Chuyển dữ liệu lịch thi JSON thành chuỗi ICS.
- Mặc định (full=False) chỉ đưa thông tin quan trọng (Môn, Ngày công bố);
- ẩn mã slot UUID, phòng thi, ghi chú và các trường phụ.
+ Mặc định (full=False) chỉ đưa thông tin quan trọng (Môn, Phòng thi, Ngày công bố);
+ ẩn mã slot UUID, ghi chú và các trường phụ.
Khi full=True đưa toàn bộ thông tin phụ vào sự kiện lịch.
"""
if not isinstance(data, dict) or not isinstance(data.get("data"), list):
@@ -239,15 +239,24 @@ def convert_schedule_to_ics(data: dict) -> str:
e.begin = start_dt
e.end = end_dt
+ room_no = session.get("roomNo")
+ room_str = room_no if isinstance(room_no, str) else ("" if room_no is None else str(room_no))
+ group_name = session.get("groupName")
+ group_str = group_name if isinstance(group_name, str) else ("" if group_name is None else str(group_name))
+ session_no = session.get("sessionNo")
+ session_str = "" if session_no is None else str(session_no)
+ lecturer = session.get("lecturer")
+ lecturer_str = lecturer if isinstance(lecturer, str) and lecturer else ("N/A" if lecturer is None or lecturer == "" else str(lecturer))
+
# Location
- e.location = session.get("roomNo", "")
-
+ e.location = room_str
+
# Description
desc = []
- desc.append(f"Group: {session.get('groupName', '')}")
- desc.append(f"Session: {session.get('sessionNo', '')}")
- desc.append(f"Lecturer: {session.get('lecturer', 'N/A')}")
- desc.append(f"Room: {session.get('roomNo', '')}")
+ desc.append(f"Group: {group_str}")
+ desc.append(f"Session: {session_str}")
+ desc.append(f"Lecturer: {lecturer_str}")
+ desc.append(f"Room: {room_str}")
if session.get("meetURL"):
desc.append(f"Meet URL: {session.get('meetURL')}")
diff --git a/tests/test_auth_lifecycle.py b/tests/test_auth_lifecycle.py
index f8d8ee2..b82fe4d 100644
--- a/tests/test_auth_lifecycle.py
+++ b/tests/test_auth_lifecycle.py
@@ -379,6 +379,16 @@ def test_handshake_rejects_wrong_account_or_ambiguous_identity(self):
self.auth.session.post.return_value = response({"code": "200", "data": rows})
self.assertFalse(self.refresh())
+ def test_init_rejects_empty_session_file_and_control_characters_in_campus(self):
+ for bad_session in ("", " ", "bad\npath"):
+ with self.subTest(session_file=bad_session):
+ with self.assertRaises(module.AuthError):
+ module.MyFapAuth(session_file=bad_session)
+ for bad_campus in ("HN\nEvil", "HN\x7f"):
+ with self.subTest(campus=bad_campus):
+ with self.assertRaises(module.AuthError):
+ module.MyFapAuth(campus=bad_campus)
+
if __name__ == "__main__":
unittest.main()
diff --git a/tests/test_cli_options.py b/tests/test_cli_options.py
index 5faebf0..e55c998 100644
--- a/tests/test_cli_options.py
+++ b/tests/test_cli_options.py
@@ -131,3 +131,37 @@ def test_common_options_do_not_leak_between_invocations(self):
result = self.runner.invoke(app, ["login", "-f"])
self.assertEqual(result.exit_code, 0, result.output)
self.assertEqual(self.MyFapAuth.call_args.kwargs, {"campus": None, "session_file": None, "api_version": None, "timeout": None})
+
+ def test_empty_or_conflicting_command_options_fail_before_auth(self):
+ cases = (
+ ["--config", "", "login"],
+ ["--campus", "", "campuses", "--api-version", "v2"],
+ ["login", "--campus", ""],
+ ["--campus", "HN", "login", "--campus", ""],
+ ["schedule", "--semester", "", "--stdout"],
+ ["schedule", "--semester", " ", "--stdout"],
+ ["schedule", "--output", ""],
+ ["marks", "--courseid", "", "--stdout"],
+ ["marks", "-cid", "123", "-s", "Fall2026", "--stdout"],
+ ["attendance", "-sc", "", "-cn", "", "--stdout"],
+ ["week-timetable", "--date", "", "--stdout"],
+ ["week-timetable", "--week", "0", "--stdout"],
+ ["week-timetable", "--year", "0", "--stdout"],
+ )
+ for command in cases:
+ with self.subTest(command=command):
+ self.MyFapAuth.reset_mock()
+ self.MyFapEssential.reset_mock()
+ self.MyFapClient.reset_mock()
+ result = self.runner.invoke(app, command)
+ self.assertNotEqual(result.exit_code, 0, result.output)
+ self.assertEqual(result.stdout, "")
+ self.assertNotIn("Traceback", result.stderr)
+ self.MyFapAuth.assert_not_called()
+ self.MyFapEssential.assert_not_called()
+ self.MyFapClient.assert_not_called()
+
+ def test_child_login_campus_overrides_invalid_parent_campus(self):
+ result = self.runner.invoke(app, ["--campus", "", "login", "--campus", "HN", "-f"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(self.MyFapAuth.call_args.kwargs["campus"], "HN")
diff --git a/tests/test_cli_version.py b/tests/test_cli_version.py
index 1dfc167..649e6eb 100644
--- a/tests/test_cli_version.py
+++ b/tests/test_cli_version.py
@@ -56,15 +56,15 @@ def test_invalid_environment_rejected_before_auth(self):
def test_environment_precedence_for_nested_options_and_invocations(self):
cases = (
- ({"MYFAP_API_VER": "v1"}, ["other", "--api-version", "v2", "feedbacks", "--stdout"], "v2"),
- ({"MYFAP_API_VER": "v2"}, ["--api-version", "v1", "other", "feedbacks", "--stdout"], "v1"),
- ({"MYFAP_API_VER": "bad"}, ["other", "feedbacks", "--api-version", "v2", "--stdout"], "v2"),
+ ({"MYFAP_API_VER": "v1"}, ["other", "--api-version", "v2", "balance", "--stdout"], "v2"),
+ ({"MYFAP_API_VER": "v2"}, ["--api-version", "v1", "other", "balance", "--stdout"], "v1"),
+ ({"MYFAP_API_VER": "bad"}, ["other", "balance", "--api-version", "v2", "--stdout"], "v2"),
)
for env, command, expected in cases:
with self.subTest(env=env, command=command), patch("myfap.cli.MyFapAuth") as auth, patch("myfap.cli.MyFapOther") as other:
auth.return_value.resolve_api_version.return_value = expected
auth.return_value.load_session.return_value = True
- other.return_value.get_feedbacks.return_value = {"code": "200", "data": []}
+ other.return_value.get_balance.return_value = {"code": "200", "data": []}
result = self.runner.invoke(app, command, env=env)
self.assertEqual(result.exit_code, 0, result.output)
self.assertEqual(auth.call_args.kwargs["api_version"], expected)
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index bad246f..7498d9d 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -233,6 +233,18 @@ def test_overnight_slot_wraps_end_to_next_day(self):
self.assertEqual(event.end.datetime, datetime(2026, 10, 15, 17, 50, tzinfo=timezone.utc))
self.assertEqual((event.end.datetime - event.begin.datetime).total_seconds(), 80 * 60)
+ def test_null_optional_fields_do_not_render_literal_none(self):
+ data = json.loads((FIXTURES / "schedule_valid.json").read_text(encoding="utf-8"))
+ data["data"][0].update({"roomNo": None, "groupName": None, "sessionNo": None, "lecturer": None, "meetURL": None})
+
+ content = convert_schedule_to_ics(data)
+ event = next(iter(Calendar(content).events))
+
+ self.assertIsNone(event.location)
+ self.assertNotIn("LOCATION:", content)
+ self.assertNotIn("None", event.description)
+ self.assertIn("Lecturer: N/A", event.description)
+
def test_slot_without_separator_raises_clear_message(self):
data = json.loads((FIXTURES / "schedule_valid.json").read_text(encoding="utf-8"))
data["data"][0]["slotTime"] = "7:30"
@@ -344,6 +356,29 @@ def test_server_influenced_filename_stays_inside_output_dir(self):
content = json.loads((Path(temporary) / files[0]).read_text(encoding="utf-8"))
self.assertEqual(content, {"code": 200, "data": []})
+ def test_windows_forbidden_filename_characters_are_sanitized(self):
+ with TemporaryDirectory() as temporary, redirect_stderr(io.StringIO()):
+ save_output({"code": 200, "data": []}, "BangDiem_Fall:2026*?.json", temporary, False)
+ files = sorted(path.name for path in Path(temporary).iterdir())
+ self.assertEqual(files, ["BangDiem_Fall_2026__.json"])
+
+ def test_marks_pretty_parses_uppercase_table_tag(self):
+ from unittest.mock import Mock, patch
+ from typer.testing import CliRunner
+ from myfap.cli import app
+
+ with TemporaryDirectory() as temporary:
+ cfg = Path(temporary) / "session.json"
+ cfg.write_text(json.dumps({
+ "campus": "HN", "api_version": "v2", "account_type": "student",
+ "authen_key": "FAKE_V2_KEY", "mssv": "TEST000", "email": "sample@example.invalid",
+ }), encoding="utf-8")
+ html_upper = ""
+ with patch("requests.Session.request", return_value=Mock(status_code=200, json=Mock(return_value={"code": 200, "data": html_upper}))):
+ result = CliRunner().invoke(app, ["--config", str(cfg), "marks", "-cid", "123", "-p", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout)["data"], [{"category": "", "item": "Q1", "weight": "10%", "value": "9"}])
+
def test_empty_schedule_returns_valid_empty_calendar(self):
data = json.loads((FIXTURES / "schedule_empty.json").read_text(encoding="utf-8"))
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 4d43569..bdf80a6 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -433,12 +433,24 @@ def test_feedbacks_preserves_empty_list(self):
def test_feedbacks_v1_is_rejected_before_http(self):
self.save_session("v1")
- with patch("requests.Session.request") as request:
+ with patch("myfap.auth.MyFapAuth.load_session") as load, patch("requests.Session.request") as request:
result = self.runner.invoke(app, ["--config", str(self.path), "other", "feedbacks", "--stdout"])
self.assertEqual(result.exit_code, 1)
self.assertEqual(result.stdout, "")
self.assertIn("GetStudentFeedbacks", Text.from_ansi(result.stderr).plain)
+ load.assert_not_called()
+ request.assert_not_called()
+
+ def test_feedbacks_v1_on_v2_session_preserves_session_without_handshake(self):
+ self.save_session("v2")
+ before = self.path.read_bytes()
+ with patch("requests.Session.request") as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "--api-version", "v1", "other", "feedbacks", "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertIn("GetStudentFeedbacks", Text.from_ansi(result.stderr).plain)
request.assert_not_called()
+ self.assertEqual(self.path.read_bytes(), before)
class ExamsIcsCommandTests(unittest.TestCase):
| |