From 6c01ea0d87576bb77424bf5bf7ed13b2082a8161 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Fri, 23 Oct 2026 21:32:41 +0700
Subject: [PATCH 01/28] =?UTF-8?q?docs:=20kh=E1=BB=9Fi=20t=E1=BA=A1o=20chec?=
=?UTF-8?q?klist=20Phase=206=20v=C3=A0=20ho=C3=A3n=20ph=C3=A1t=20h=C3=A0nh?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Tiếp tục từ PR9 đã merge; chia command đọc và gate schema cho thao tác ghi. Giữ lịch sử migration, TODO v1 và positive fee/survey; chưa tag hoặc publish.
---
tasks/phase5.md | 6 ++--
tasks/phase6.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++
tasks/todo.md | 14 +++++++++
3 files changed, 101 insertions(+), 2 deletions(-)
create mode 100644 tasks/phase6.md
diff --git a/tasks/phase5.md b/tasks/phase5.md
index 9c7d953..6a1740b 100644
--- a/tasks/phase5.md
+++ b/tasks/phase5.md
@@ -2,7 +2,9 @@
Nhánh `feat/phase5-release-automation` bắt đầu từ `origin/main` tại `06d98e115bb63a244d793236f81d7b62f63a5dc7`, sau khi PR #8 đã merge. Package giữ `0.2.0`, Python >=3.9, v1 mặc định và v2 opt-in.
-Phạm vi phase là chuẩn bị release notes, gate tag/version/artifact, Trusted Publishing, post-publish smoke và GitHub Release; thêm endpoint mới thuộc Phase 6 theo kế hoạch workspace. Người dùng đã xác nhận commit và push **nhánh tính năng** sau kiểm tra. Nhánh đang được theo dõi trong [Draft PR #9](https://github.com/WindowScary321/myfap-api-cli/pull/9). Tạo/push tag, upload và thay đổi cấu hình dịch vụ cần maintainer cho phép riêng; chưa tạo tag, publish hoặc GitHub Release.
+Phạm vi phase là chuẩn bị release notes, gate tag/version/artifact, Trusted Publishing, post-publish smoke và GitHub Release; thêm endpoint mới thuộc Phase 6. [PR #9](https://github.com/WindowScary321/myfap-api-cli/pull/9) đã merge vào `main` tại `75fc7b4aa33a13b9b39eab898f61e2e693f4baf9`.
+
+**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.
@@ -15,7 +17,7 @@ Hai commit mã nguồn đã kiểm: `671ca5f06b63ce4ae826732fb4f1a3a64c252f62` (
- [ ] 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). Phase 6 không chặn `0.2.0`.
+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.
## Gate kỹ thuật
diff --git a/tasks/phase6.md b/tasks/phase6.md
new file mode 100644
index 0000000..cebbbf3
--- /dev/null
+++ b/tasks/phase6.md
@@ -0,0 +1,83 @@
+# Phase 6: mở rộng command và endpoint trước phát hành
+
+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.
+
+Tài liệu này là checklist khởi động, **chưa ghi nhận command Phase 6 đã triển khai hoặc test/live đã đạt**. Không suy khả năng backend từ việc route có trong APK. Phần thiếu contract/schema phải 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
+
+- 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.
+- 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.
+- Test dùng dữ liệu tổng hợp, credential giả và session tạm. Live đọc dùng browser/context mới, payload chỉ xử lý cục bộ; chỉ operation/method/HTTP/body code/kiểu dữ liệu/exit code/kiểm định dạng được ghi vào báo cáo.
+- Không đưa raw response, ảnh, token, query có giá trị, identity hoặc dữ liệu tài khoản lên GitHub. Live ghi cần người dùng xác nhận riêng thao tác cụ thể.
+- Mỗi commit push lên PR phải có comment ngay sau commit, ghi SHA, kiểm tra/exit code và giới hạn; không tự merge, tạo tag, publish hoặc đổi default v2.
+
+## 1. Các lát cắt đọc rõ contract
+
+Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/test → coverage, không chỉ thêm tên vào allowlist.
+
+- [ ] **`courses --semester` → `GetCourseOfSemester`:** dùng resolver kỳ nếu thiếu option; query `semester` chữ thường, đúng credential/signing identity từng version.
+- [ ] **`other subjects --semester` → `GetSubjectBySemester`:** query `Semester` chữ hoa; v1 ký bằng semester. Khi không có option mới vẫn dùng `GetSubjets`, không lookup kỳ và giữ timeout subjects hiện có.
+- [ ] **`other balance` → `GetBalance`:** không lookup kỳ; bảo toàn payload, không suy ra currency/nợ/invoice. Cập nhật retry/error allowlist có chủ đích và giữ regression cho operation chưa hỗ trợ.
+- [ ] **`news --search` → `SearchNews`:** không có search vẫn dùng `GetTop10News`; từ chối search rỗng trước auth, truyền `type`/`keysearch` qua params và v1 ký bằng type. Kiểm Unicode và ký tự reserved, không nối query thủ công.
+
+**Nghiệm thu nhóm:**
+- [ ] Test tại public seam CLI và biên HTTP chứng minh method/path/query/header/body đúng, stdout sạch, binding và common-option precedence được giữ.
+- [ ] Có success/empty/not-found phù hợp, malformed, expiry, App Check, timeout/5xx và không fallback; focused tests rồi regression hiện có đạt.
+
+## 2. Transcript, training và marks summary
+
+- [ ] **`transcript` → `AcademicTranscript`:** hỗ trợ theo contract cả v1/v2, không lookup kỳ; chưa thêm formatter nghiệp vụ khi schema data chưa được xác minh.
+- [ ] **`training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
+- [ ] **`marks --summary` → `GetSemesterMark`:** không lookup kỳ hoặc thêm query semester. V1 dùng đúng `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 giữ query `Authen` mới sau refresh.
+- [ ] Từ chối tổ hợp summary với `--courseid`/`--pretty`; nếu `--semester` không áp dụng thì báo lỗi, không âm thầm bỏ qua.
+- [ ] Reader riêng cho summary kiểm HTTP/App Check/expiry trước khi đọc raw array/envelope/text. Chỉ parse dạng đã có bằng chứng, có giới hạn; malformed/unknown phải báo payload error, không cắt tùy tiện giữa dấu ngoặc rồi trả success.
+- [ ] Chốt khác biệt credential v2 ở các caller decompile của transcript/training/summary bằng bytecode/contract và kiểm đọc. Không mặc định sao chép credential rỗng, thử unauth rồi fallback hoặc nới reader chung cho mọi endpoint.
+
+**Nghiệm thu nhóm:**
+- [ ] Test exact casing, no-semester/no-checksum, signing identity và dựng Authen mới sau refresh; giữ nguyên command marks cũ.
+- [ ] Fixture được ghi rõ synthetic; các schema hoặc credential chưa live xác nhận tiếp tục có nhãn unverified.
+
+## 3. Photo và doctor
+
+- [ ] **`info photo` → `RetriveImage`:** output JSON theo representation đã chứng minh, giữ chuỗi opaque; không tự fetch URL, decode Base64, in binary hoặc mở ảnh. Xuất ảnh file riêng chỉ mở sau khi đủ bằng chứng định dạng/size/type và fixture.
+- [ ] **`doctor` local:** chỉ xuất allowlist chẩn đoán package/API version, campus được chọn, capability và loại lỗi; không dump auth/session, email/MSSV, header, token hoặc config path đầy đủ. Không gọi `require_auth`/`load_session` gây refresh/persist.
+- [ ] Probe online là option explicit và tái sử dụng `GetApiActive` v2; không auto-login/refresh/switch version. `GetVersion` giữ gate riêng khi public/text contract còn chưa rõ; `myfap version` tiếp tục offline.
+- [ ] Test doctor/help local không gọi mạng; lỗi không lộ payload; photo không tạo file/fetch ngoài ý muốn.
+
+## Checkpoint: nhóm đọc
+
+- [ ] Focused/full regression, build/Twine/artifact validator và pip smoke đạt; không có docs/tasks/tests/session/capture trong distribution.
+- [ ] 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.
+- [ ] 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
+
+- [ ] **Rating list:** chốt fixture/schema tối thiểu cho student/v1; v2 là stub nên unsupported trước auth/network, không gọi v1 ngầm hoặc trả `[]` giả.
+- [ ] **`rating submit --input`:** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
+- [ ] **`push register --token-file`:** chốt contract student; `UpdateTokedevices` là **GET ghi**, v1 ký bằng **email**. Token chỉ đọc từ regular file có giới hạn, kiểm encoding/newline và symlink/reparse/path swap; không token trên argv/preview/log/error. Campus/identity lấy từ session đã bind.
+- [ ] Đường ghi tách khỏi read retry, không thêm AddRate/push vào read allowlist để cấp credential. Trình tự: validate → capability → preview không bí mật → confirmation/`--yes` → auth → một lần gửi. `--yes` không bỏ validation.
+- [ ] Test invalid input/cancel/noninteractive thiếu xác nhận gây zero auth/network; 401/App Check/timeout/5xx hoặc unknown outcome không replay.
+- [ ] Live ghi chỉ thực hiện sau xác nhận riêng của người dùng; nếu chưa đủ schema/ack thì capability vẫn đóng và ghi TODO, không mở generic submit.
+
+## 5. Feedback và flow còn thiếu bằng chứng
+
+- [ ] Giữ `other feedback` là `CheckOpenFeedBack`; không đổi nghĩa thành list/form/submit.
+- [ ] `GetStudentFeedbacks`/`GetStudentFeedbackForm` chỉ mở khi có response contract đủ; không suy kiểu item/ID/câu hỏi từ tên route.
+- [ ] `SubmitStudentFeedback`, donor/employee, donor push và FEID server-code exchange thiếu schema/capability tiếp tục gate/TODO; không nhận JSON tùy ý để vượt gate.
+- [ ] Trước khi chốt phạm vi, liệt kê từng blocker và bằng chứng cần thêm; không đánh dấu Phase 6 hoàn tất bằng cách lặng lẽ bỏ các mục chưa đạt.
+
+## 6. Kiểm chứng và bàn giao PR
+
+- [ ] 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.
+- [ ] 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`.
+- [ ] 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.
+- [ ] Review độc lập phần query/credential/parser/write safety và cập nhật README/CHANGELOG/coverage theo đúng kết quả.
+- [ ] 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.
+- [ ] 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.
+
+## Trạng thái khởi động
+
+Các ô trên đều **pending**; chưa có kết quả test, live hay CI cho tính năng Phase 6 trong tài liệu khởi động này. Ghi kết quả sau từng lát cắt bằng commit, lệnh và exit code thật. Các finding v1 và positive fee/survey giữ tại [todo.md](todo.md), không bị thay thế bởi checklist mới.
diff --git a/tasks/todo.md b/tasks/todo.md
index 12316d7..684fa56 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -30,3 +30,17 @@ Khi có điều kiện kiểm chứng, dùng session tạm, ghi rõ API version/
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.
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.
+
+## Mở rộng command và endpoint Phase 6
+
+Theo quyết định ngày 23/10/2026, **chưa tag/publish cho đến sau khi hoàn thiện và nghiệm thu phạm vi Phase 6**. PR #9 đã merge tại `75fc7b4aa33a13b9b39eab898f61e2e693f4baf9`; đó là pipeline chuẩn bị, không phải release. Giữ baseline `0.2.0`, v1 mặc định/v2 opt-in.
+
+Checklist, tiêu chí và gate bằng chứng nằm tại [phase6.md](phase6.md). Các mục sau chỉ được đánh dấu khi có kết quả tương ứng:
+
+- [ ] Hoàn thiện các lát cắt đọc: courses, subjects theo kỳ, balance và news search, giữ hành vi command cũ.
+- [ ] Hoàn thiện transcript/training và marks summary sau khi chốt các ngoại lệ credential/response; không đoán query hoặc schema.
+- [ ] Bổ sung photo JSON và doctor an toàn; không tự fetch/decode ảnh hoặc refresh session khi chẩn đoán local.
+- [ ] Chốt rating/push/feedback theo gate schema/capability; không mở write hoặc ghi live khi chưa đủ bằng chứng/xác nhận.
+- [ ] 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.
+- [ ] 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.
From c829b7004ea2dbb7f99cf1dc3827070039bb9ea5 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 11:22:07 +0700
Subject: [PATCH 02/28] =?UTF-8?q?feat:=20b=E1=BB=95=20sung=20command=20?=
=?UTF-8?q?=C4=91=E1=BB=8Dc=20Phase=206=20v=C3=A0=20doctor=20an=20to=C3=A0?=
=?UTF-8?q?n?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Nối balance, courses, subjects theo kỳ, tìm news, transcript/training, photo JSON và marks summary qua contract v1/v2. Giữ ngoại lệ signer/casing, không kỳ/checksum ở summary v1, bảo toàn chuỗi ảnh và doctor không đọc session. Regression CLI/HTTP tổng hợp, validation API và phân loại lỗi giữ policy retry đọc; không mở thao tác ghi.
---
myfap/api.py | 92 ++++++++--
myfap/cli.py | 136 ++++++++++++++-
myfap/diagnostics.py | 47 +++++
myfap/errors.py | 6 +-
myfap/summary.py | 34 ++++
myfap/v2.py | 10 +-
tests/test_api_session.py | 17 +-
tests/test_phase6_doctor.py | 110 ++++++++++++
tests/test_phase6_reads.py | 326 +++++++++++++++++++++++++++++++++++
tests/test_phase6_summary.py | 125 ++++++++++++++
10 files changed, 877 insertions(+), 26 deletions(-)
create mode 100644 myfap/diagnostics.py
create mode 100644 myfap/summary.py
create mode 100644 tests/test_phase6_doctor.py
create mode 100644 tests/test_phase6_reads.py
create mode 100644 tests/test_phase6_summary.py
diff --git a/myfap/api.py b/myfap/api.py
index a671f20..f134bd8 100644
--- a/myfap/api.py
+++ b/myfap/api.py
@@ -33,7 +33,8 @@ def clean_json(data):
def _get(session, url, params, *, timeout=DEFAULT_TIMEOUT, allow_survey_not_found=False,
- auth=None, operation=None, params_factory=None, api_version="v1", response_api_version=None):
+ auth=None, operation=None, params_factory=None, api_version="v1", response_api_version=None,
+ preserve_data=False, response_reader=None):
current_params = params
retried = False
while True:
@@ -44,7 +45,9 @@ def _get(session, url, params, *, timeout=DEFAULT_TIMEOUT, allow_survey_not_foun
except requests.RequestException:
raise ApiError("Không kết nối được API. Hãy thử lại sau.") from None
try:
- return clean_json(read_response(response, allow_survey_not_found=allow_survey_not_found, api_version=response_api_version or api_version, operation=operation))
+ payload = response_reader(response) if response_reader else read_response(
+ response, allow_survey_not_found=allow_survey_not_found, api_version=response_api_version or api_version, operation=operation)
+ return payload if preserve_data else clean_json(payload)
except ApiSessionExpiredError:
if retried or operation not in READ_OPERATIONS or auth is None or "Authen" not in params or params_factory is None:
raise
@@ -55,7 +58,7 @@ def _get(session, url, params, *, timeout=DEFAULT_TIMEOUT, allow_survey_not_foun
current_params = params_factory()
-def _v2_request(session, auth, operation, *, timeout, campus=None, params=None):
+def _v2_request(session, auth, operation, *, timeout, campus=None, params=None, preserve_data=False, response_reader=None):
from . import v2
retried = False
@@ -66,7 +69,8 @@ def _v2_request(session, auth, operation, *, timeout, campus=None, params=None):
campus=campus or getattr(auth, "campus", None),
params=params, timeout=timeout)
try:
- return clean_json(read_response(response, api_version="v2", operation=operation))
+ payload = response_reader(response) if response_reader else read_response(response, api_version="v2", operation=operation)
+ return payload if preserve_data else clean_json(payload)
except ApiSessionExpiredError:
if retried or operation not in v2.READ_OPERATIONS or auth is None:
raise
@@ -103,20 +107,25 @@ def _ensure_bound(auth, *, campus=None, api_version=None):
hook(campus=campus or auth.campus, api_version=version, account_type=getattr(auth, "account_type", None))
-def _authenticated_get(session, auth, operation, identifier, *, timeout, campus=None, student=False, params=None, api_version=None):
+def _authenticated_get(session, auth, operation, identifier, *, timeout, campus=None, student=False, params=None, api_version=None, preserve_data=False):
version = _resolve_api_version(auth, api_version)
if version == "v2":
from .v2 import OPERATION_ALIASES
operation = OPERATION_ALIASES.get(operation, operation)
query = {"rollNumber": auth.mssv, **(params or {})} if student else params
- return _v2_request(session, auth, operation, timeout=timeout, campus=campus, params=query)
+ return _v2_request(session, auth, operation, timeout=timeout, campus=campus, params=query, preserve_data=preserve_data)
def build_params():
return {**_auth_params(auth, identifier, campus=campus, student=student), **(params or {})}
return _get(session, f"{FAP_HOST}/{operation}", build_params(), timeout=timeout,
- auth=auth, operation=operation, params_factory=build_params)
+ auth=auth, operation=operation, params_factory=build_params, preserve_data=preserve_data)
+
+
+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.")
def _semester_start(semester):
@@ -187,12 +196,17 @@ def get_week(self, date_str: str):
except ValueError:
raise ApiPayloadError("Số tuần trong response API không hợp lệ.") from None
- def get_news(self, news_type: int = 1):
- """Lấy 10 thông báo gần nhất."""
+ def get_news(self, news_type: int = 1, search=None):
+ """Lấy tin gần nhất hoặc tìm kiếm, ký v1 bằng type."""
if not self.auth:
raise ApiError("Không tìm thấy session xác thực.")
- return _authenticated_get(self.session, self.auth, "GetTop10News", str(news_type),
- params={"type": news_type}, timeout=self.timeout, api_version=self.api_version)
+ if search is not None and (not isinstance(search, str) or not search.strip()):
+ raise ApiError("Nội dung tìm kiếm không được rỗng.")
+ params = {"type": news_type}
+ if search is not None:
+ params["keysearch"] = search
+ return _authenticated_get(self.session, self.auth, "GetTop10News" if search is None else "SearchNews", str(news_type),
+ params=params, timeout=self.timeout, api_version=self.api_version)
class MyFapOther:
@@ -233,9 +247,18 @@ def get_fee(self):
return _authenticated_get(self.session, self.auth, "GeFeeByRoll", self.auth.mssv,
student=True, timeout=self.timeout, api_version=self.api_version)
- def get_subjects(self):
- """Lấy danh sách môn học."""
- return _authenticated_get(self.session, self.auth, "GetSubjets", MAGIC_ID,
+ def get_balance(self):
+ """Lấy số dư, bảo toàn payload thay vì tự suy diễn thông tin tài chính."""
+ return _authenticated_get(self.session, self.auth, "GetBalance", self.auth.mssv,
+ student=True, timeout=self.timeout, api_version=self.api_version)
+
+ def get_subjects(self, semester=None):
+ """Giữ GetSubjets mặc định; môn theo kỳ ký v1 bằng semester."""
+ if semester is not None:
+ _validate_semester(semester)
+ operation = "GetSubjets" if semester is None else "GetSubjectBySemester"
+ return _authenticated_get(self.session, self.auth, operation, MAGIC_ID if semester is None else semester,
+ params=None if semester is None else {"Semester": semester},
timeout=max(self.timeout, 30.0), api_version=self.api_version)
@@ -252,11 +275,36 @@ def get_schedule(self, semester: str):
return _authenticated_get(self.session, self.auth, "GetActivityStudent", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
+ def get_courses(self, semester: str):
+ """Lấy khóa học theo kỳ, giữ đúng query semester chữ thường."""
+ _validate_semester(semester)
+ return _authenticated_get(self.session, self.auth, "GetCourseOfSemester", self.auth.mssv,
+ student=True, params={"semester": semester}, timeout=self.timeout, api_version=self.api_version)
+
def get_marks(self, semester: str):
"""Lấy bảng điểm theo kỳ."""
return _authenticated_get(self.session, self.auth, "GetStudentMark", self.auth.mssv,
student=True, params={"Semester": semester}, timeout=self.timeout, api_version=self.api_version)
+ def get_mark_summary(self):
+ """GetSemesterMark không có query kỳ; v1 cũng không có checksum."""
+ from .summary import read_semester_marks_response
+
+ def reader(response):
+ return read_semester_marks_response(response, api_version=self.api_version)
+
+ if self.api_version == "v2":
+ return _v2_request(self.session, self.auth, "GetSemesterMark", timeout=self.timeout,
+ params={"rollNumber": self.auth.mssv}, preserve_data=True, response_reader=reader)
+
+ def build_params():
+ _ensure_bound(self.auth, api_version="v1")
+ return {"CampusCode": self.auth.campus, "rollNumber": self.auth.mssv, "Authen": self.auth.authen_key}
+
+ return _get(self.session, f"{FAP_HOST}/GetSemesterMark", build_params(), timeout=self.timeout,
+ auth=self.auth, operation="GetSemesterMark", params_factory=build_params,
+ preserve_data=True, response_reader=reader)
+
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."""
return _authenticated_get(self.session, self.auth, "GetMarkByCourse", self.auth.mssv,
@@ -287,6 +335,22 @@ def get_applications(self):
return _authenticated_get(self.session, self.auth, "GetApplication", self.auth.mssv,
student=True, timeout=self.timeout, api_version=self.api_version)
+ def get_training(self, semester: str):
+ """Lấy điểm phong trào theo kỳ, không tự tính tổng hoặc đổi schema."""
+ _validate_semester(semester)
+ return _authenticated_get(self.session, self.auth, "GetDiemphongtrao", self.auth.mssv,
+ student=True, params={"semester": semester}, timeout=self.timeout, api_version=self.api_version)
+
+ def get_photo(self):
+ """Giữ nguyên representation ảnh; không fetch URL hoặc decode Base64."""
+ return _authenticated_get(self.session, self.auth, "RetriveImage", self.auth.mssv,
+ student=True, timeout=self.timeout, api_version=self.api_version, preserve_data=True)
+
+ def get_transcript(self):
+ """Lấy transcript bằng credential đã bind; không suy schema nghiệp vụ."""
+ return _authenticated_get(self.session, self.auth, "AcademicTranscript", self.auth.mssv,
+ student=True, timeout=self.timeout, api_version=self.api_version)
+
def get_student_info(self):
"""Lấy thông tin sinh viên."""
return _authenticated_get(self.session, self.auth, "GetStudentById", self.auth.mssv,
diff --git a/myfap/cli.py b/myfap/cli.py
index 37814fc..1e9c1ed 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -204,6 +204,23 @@ def version():
ver = "unknown (not installed via pip)"
console.print(f"MyFap API CLI version: [bold cyan]{ver}[/bold cyan]")
+@app.command()
+def doctor(
+ online: bool = typer.Option(False, "--online", help="Gọi bootstrap GetApiActive v2; không xác thực session"),
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ stdout: bool = typer.Option(False, "--stdout", help="In JSON chẩn đoán ra stdout")
+):
+ """Chẩn đoán cấu hình explicit/default; không đọc hoặc làm mới session."""
+ from .diagnostics import get_diagnostics
+ try:
+ report = get_diagnostics(api_version=state["api_version"], campus=state["campus"],
+ timeout=state["timeout"], online=online)
+ save_output(report, "Doctor.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi chẩn đoán: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
@app.command()
def login(
campus: Optional[str] = typer.Option(None, "--campus", "-c", help="Mã cơ sở theo API version; ví dụ APHL (v1), HN (v2)"),
@@ -327,15 +344,82 @@ def schedule(
err_console.print(f"[red]Lỗi lấy lịch học: {e}[/red]")
raise typer.Exit(code=1)
+@app.command()
+def transcript(
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
+):
+ """Lấy bảng điểm toàn khóa theo contract API đã chọn."""
+ auth = require_auth("AcademicTranscript")
+ try:
+ data = MyFapClient(auth).get_transcript()
+ save_output(data, "Transcript.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy transcript: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
+@app.command()
+def training(
+ semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học"),
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ 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")
+ auth = require_auth("GetDiemphongtrao")
+ client = MyFapClient(auth)
+ sem = resolve_semester(auth, semester)
+ try:
+ data = client.get_training(sem)
+ save_output(data, "Training.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy điểm phong trào: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
+@app.command()
+def courses(
+ semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học"),
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ 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")
+ auth = require_auth("GetCourseOfSemester")
+ client = MyFapClient(auth)
+ sem = resolve_semester(auth, semester)
+ try:
+ data = client.get_courses(sem)
+ save_output(data, "Courses.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy khóa học: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
@app.command()
def marks(
+ summary: bool = typer.Option(False, "--summary", help="Tổng kết; không nhận kỳ học hoặc courseid"),
semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học (VD: Summer2026)"),
courseid: Optional[str] = typer.Option(None, "--courseid", "-cid", help="Mã môn học"),
pretty: bool = typer.Option(False, "--pretty", "-p", help="Làm đẹp bảng điểm (chỉ áp dụng khi dùng -cid)"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
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"""
+ """Xem bảng điểm theo kỳ, chi tiết môn hoặc tổng kết."""
+ 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.")
+ auth = require_auth("GetSemesterMark")
+ try:
+ data = MyFapClient(auth).get_mark_summary()
+ save_output(data, "MarkSummary.json", output, stdout)
+ except Exception as error:
+ 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:
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)
@@ -495,16 +579,20 @@ def applications(
@app.command()
def news(
+ search: Optional[str] = typer.Option(None, "--search", help="Tìm tin theo nội dung"),
+ news_type: int = typer.Option(1, "--type", "-t", min=1, help="Loại thông báo"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
- """Xem 10 thông báo gần nhất"""
- auth = require_auth("GetTop10News")
+ """Xem tin gần nhất hoặc tìm kiếm thông báo."""
+ if search is not None and not search.strip():
+ raise typer.BadParameter("Nội dung tìm kiếm không được rỗng.", param_hint="--search")
+ auth = require_auth("GetTop10News" if search is None else "SearchNews")
other = MyFapEssential(auth)
try:
with err_console.status("[bold green]Đang tải thông báo..."):
- data = other.get_news()
+ data = other.get_news(news_type) if search is None else other.get_news(news_type, search=search)
filename = f"ThongBao.json"
save_output(data, filename, output, stdout)
except Exception as e:
@@ -528,6 +616,21 @@ def info_student(
err_console.print(f"[red]Lỗi: {e}[/red]")
raise typer.Exit(code=1)
+@info_app.command("photo")
+def info_photo(
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file JSON"),
+ stdout: bool = typer.Option(False, "--stdout", help="In JSON; không tự giải mã hoặc tải ảnh")
+):
+ """Lấy representation ảnh dưới dạng JSON, không tự mở ảnh."""
+ auth = require_auth("RetriveImage")
+ try:
+ data = MyFapClient(auth).get_photo()
+ save_output(data, "Photo.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy ảnh: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
@info_app.command("campus")
def info_campus(
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
@@ -628,17 +731,36 @@ def other_fee(
err_console.print(f"[red]Lỗi: {e}[/red]")
raise typer.Exit(code=1)
+@other_app.command("balance")
+def other_balance(
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
+):
+ """Lấy số dư tài khoản; không diễn giải thành trạng thái nợ học phí."""
+ auth = require_auth("GetBalance")
+ other_client = MyFapOther(auth)
+ try:
+ data = other_client.get_balance()
+ save_output(data, "Balance.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy số dư: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
@other_app.command("subjects")
def other_subjects(
+ semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Chỉ lấy môn của kỳ được chỉ định"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
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 tất cả môn học"""
- auth = require_auth("GetSubjets")
+ """Lấy tất cả môn học hoặc các môn của một kỳ chỉ định."""
+ if semester is not None and not semester.strip():
+ raise typer.BadParameter("Kỳ học không được rỗng.", param_hint="--semester")
+ auth = require_auth("GetSubjets" if semester is None else "GetSubjectBySemester")
other_client = MyFapOther(auth)
try:
with err_console.status("[bold green]Đang tải danh sách tất cả môn học..."):
- data = other_client.get_subjects()
+ data = other_client.get_subjects() if semester is None else other_client.get_subjects(semester)
filename = f"Subjects.json"
save_output(data, filename, output, stdout)
except Exception as e:
diff --git a/myfap/diagnostics.py b/myfap/diagnostics.py
new file mode 100644
index 0000000..d6ac56a
--- /dev/null
+++ b/myfap/diagnostics.py
@@ -0,0 +1,47 @@
+"""Allowlisted diagnostics without reading or refreshing the user's session."""
+
+from importlib import metadata
+
+from .api import MyFapEssential, READ_OPERATIONS
+from .errors import ApiError, ApiPayloadError
+from .v2 import SUPPORTED_OPERATIONS
+
+
+def get_diagnostics(*, api_version=None, campus=None, timeout=None, online=False):
+ version = "v1" if api_version is None else api_version
+ if version not in ("v1", "v2"):
+ raise ApiError("API version phải là v1 hoặc v2.")
+ if campus is not None and (
+ not isinstance(campus, str) or not campus.strip()
+ or any(ord(character) < 32 or ord(character) == 127 for character in campus)
+ ):
+ raise ApiError("Campus chẩn đoán không hợp lệ.")
+ if online and version != "v2":
+ raise ApiError("Probe GetApiActive chỉ hỗ trợ v2; hãy chọn --api-version v2.")
+ try:
+ package_version = metadata.version("myfap")
+ except metadata.PackageNotFoundError:
+ package_version = "unknown"
+ operations = SUPPORTED_OPERATIONS | {"GetRequiredSurvey"} if version == "v2" else READ_OPERATIONS
+ report = {
+ "package_version": package_version,
+ "api_version": version,
+ "api_version_source": "default" if api_version is None else "explicit",
+ "campus": campus,
+ "available_operations": sorted(operations),
+ "session_validation": "not_checked",
+ "online_probe": {"requested": False},
+ }
+ if online:
+ client = MyFapEssential(api_version="v2", timeout=timeout)
+ try:
+ payload = client.get_api_active()
+ finally:
+ client.session.close()
+ if not isinstance(payload.get("data"), bool):
+ raise ApiPayloadError("Response GetApiActive phải chứa data boolean.")
+ report["online_probe"] = {
+ "requested": True, "operation": "GetApiActive", "bootstrap_campus": "HN",
+ "api_active": payload["data"], "scope": "proxy_bootstrap_only",
+ }
+ return report
diff --git a/myfap/errors.py b/myfap/errors.py
index 36b2ce1..87ed4b1 100644
--- a/myfap/errors.py
+++ b/myfap/errors.py
@@ -37,9 +37,9 @@ class ApiAppCheckError(ApiError):
AUTHENTICATED_READ_OPERATIONS = frozenset({
"GetSemester", "GetTop10News", "CheckOpenFeedBack", "CheckUpdateProfile",
- "GetNotificationByRoll", "GeFeeByRoll", "GetSubjets",
- "GetActivityStudent",
- "GetStudentMark",
+ "GetNotificationByRoll", "GeFeeByRoll", "GetSubjets", "GetBalance",
+ "GetActivityStudent", "GetCourseOfSemester", "GetSubjectBySemester", "SearchNews", "AcademicTranscript", "GetDiemphongtrao", "RetriveImage",
+ "GetStudentMark", "GetSemesterMark",
"GetMarkByCourse", "GetScheduleExam",
"GetStudentAttendances",
"GetActivityStudentByWeek",
diff --git a/myfap/summary.py b/myfap/summary.py
new file mode 100644
index 0000000..be11357
--- /dev/null
+++ b/myfap/summary.py
@@ -0,0 +1,34 @@
+"""Strict response reader scoped to GetSemesterMark, not a generic text fallback."""
+
+import json
+
+from .errors import ApiPayloadError, read_response
+
+
+MAX_SUMMARY_BYTES = 1024 * 1024
+
+
+def read_semester_marks_response(response, *, api_version):
+ if response.status_code != 200:
+ read_response(response, api_version=api_version, operation="GetSemesterMark")
+ content = getattr(response, "content", b"")
+ if isinstance(content, bytes) and len(content) > MAX_SUMMARY_BYTES:
+ raise ApiPayloadError("Response tổng kết vượt giới hạn xử lý cục bộ.")
+ try:
+ payload = response.json()
+ except (ValueError, AttributeError):
+ payload = None
+ # Preserve the common HTTP, App Check and explicit expiry classifications.
+ if response.status_code != 200 or isinstance(payload, dict):
+ envelope = read_response(response, api_version=api_version, operation="GetSemesterMark")
+ if not isinstance(envelope["data"], list):
+ raise ApiPayloadError("Dữ liệu tổng kết phải là một danh sách.")
+ return envelope
+ if isinstance(payload, str):
+ try:
+ payload = json.loads(payload)
+ except ValueError:
+ raise ApiPayloadError("Định dạng tổng kết chưa được hỗ trợ.") from None
+ if not isinstance(payload, list):
+ raise ApiPayloadError("Response tổng kết không có danh sách hợp lệ.")
+ return {"code": 200, "data": payload}
diff --git a/myfap/v2.py b/myfap/v2.py
index 7c923a0..36f6f44 100644
--- a/myfap/v2.py
+++ b/myfap/v2.py
@@ -18,13 +18,19 @@
_READ_QUERY_FIELDS = {
"GetSemester": (),
"GetTop10News": ("type",),
+ "SearchNews": ("type", "keysearch"),
"CheckOpenFeedBack": ("rollNumber",),
"CheckUpdateProfile": ("rollNumber",),
"GetNotificationByRoll": ("rollNumber",),
"GeFeeByRoll": ("rollNumber",),
+ "GetBalance": ("rollNumber",),
"GetSubjets": (),
+ "GetSubjectBySemester": ("Semester",),
"GetActivityStudent": ("rollNumber", "Semester"),
"GetStudentMark": ("rollNumber", "Semester"),
+ "GetSemesterMark": ("rollNumber",),
+ "GetCourseOfSemester": ("rollNumber", "semester"),
+ "GetDiemphongtrao": ("rollNumber", "semester"),
"GetMarkByCourse": ("rollNumber", "CourseId"),
"GetScheduleExam": ("rollNumber", "Semester"),
"GetStudentAttendances": ("rollNumber", "Semester"),
@@ -32,10 +38,12 @@
"GetCourseAttendance": ("rollNumber", "Semester", "SubjectCode", "ClassName"),
"GetApplication": ("rollNumber",),
"GetStudentById": ("rollNumber",),
+ "AcademicTranscript": ("rollNumber",),
+ "RetriveImage": ("rollNumber",),
"GetCampusInfo": ("rollNumber",),
"GetWeekByDate": ("date",),
}
-_AUTHEN_QUERY_OPERATIONS = frozenset({"CheckOpenFeedBack", "CheckUpdateProfile", "GetApplication", "GetNotificationByRoll"})
+_AUTHEN_QUERY_OPERATIONS = frozenset({"CheckOpenFeedBack", "CheckUpdateProfile", "GetApplication", "GetNotificationByRoll", "GetSemesterMark"})
READ_OPERATIONS = frozenset(_READ_QUERY_FIELDS)
SUPPORTED_OPERATIONS = BOOTSTRAP_OPERATIONS | READ_OPERATIONS | {"AuthenticationByFeId"}
diff --git a/tests/test_api_session.py b/tests/test_api_session.py
index ae33b0a..d076692 100644
--- a/tests/test_api_session.py
+++ b/tests/test_api_session.py
@@ -11,25 +11,40 @@
AUTHENTICATED_READ_CASES = (
(api.MyFapEssential, "get_semesters", (), "GetSemester"),
(api.MyFapEssential, "get_news", (), "GetTop10News"),
+ (api.MyFapEssential, "get_news", (1, "synthetic"), "SearchNews"),
(api.MyFapOther, "check_open_feedback", (), "CheckOpenFeedBack"),
(api.MyFapOther, "check_update_profile", (), "CheckUpdateProfile"),
(api.MyFapOther, "get_notification", (), "GetNotificationByRoll"),
(api.MyFapOther, "get_fee", (), "GeFeeByRoll"),
+ (api.MyFapOther, "get_balance", (), "GetBalance"),
(api.MyFapOther, "get_subjects", (), "GetSubjets"),
+ (api.MyFapOther, "get_subjects", ("Fall2026",), "GetSubjectBySemester"),
(api.MyFapClient, "get_schedule", ("Fall2026",), "GetActivityStudent"),
(api.MyFapClient, "get_marks", ("Fall2026",), "GetStudentMark"),
+ (api.MyFapClient, "get_courses", ("Fall2026",), "GetCourseOfSemester"),
(api.MyFapClient, "get_mark_by_course", ("123",), "GetMarkByCourse"),
(api.MyFapClient, "get_exams", ("Fall2026",), "GetScheduleExam"),
(api.MyFapClient, "get_schedule_by_week", (42, "Fall2026", 2026), "GetActivityStudentByWeek"),
(api.MyFapClient, "get_attendances", ("Fall2026",), "GetStudentAttendances"),
(api.MyFapClient, "get_course_attendance", ("Fall2026", "TEST101", "DEMO01"), "getCourseAttendance"),
(api.MyFapClient, "get_applications", (), "GetApplication"),
+ (api.MyFapClient, "get_transcript", (), "AcademicTranscript"),
+ (api.MyFapClient, "get_photo", (), "RetriveImage"),
+ (api.MyFapClient, "get_training", ("Fall2026",), "GetDiemphongtrao"),
(api.MyFapClient, "get_student_info", (), "GetStudentById"),
(api.MyFapClient, "get_campus_info", (), "GetCampusInfo"),
)
class ApiErrorPolicyTests(unittest.TestCase):
+ def test_balance_v1_expiry_is_recognized_only_for_exact_token_invalid(self):
+ with self.assertRaises(api.ApiSessionExpiredError):
+ api.read_response(response({"code": 201, "message": "Token invalid", "data": None}),
+ api_version="v1", operation="GetBalance")
+ with self.assertRaises(api.ApiOperationError):
+ api.read_response(response({"code": 201, "data": None}),
+ api_version="v1", operation="GetBalance")
+
def test_authenticated_v1_reads_recognize_201_token_invalid_with_actual_http_status(self):
for _, _, _, operation in AUTHENTICATED_READ_CASES:
for code in (201, "201"):
@@ -39,7 +54,7 @@ def test_authenticated_v1_reads_recognize_201_token_invalid_with_actual_http_sta
self.assertEqual(caught.exception.status_code, 200)
def test_other_v1_body_201_and_401_are_operation_errors_even_with_expiry_message(self):
- for operation in ("GetAllActiveCampus", "GetWeekByDate", "AuthenticationByFeId", "GetRequiredSurvey", "AddRate", "GetBalance", "UnknownOperation"):
+ for operation in ("GetAllActiveCampus", "GetWeekByDate", "AuthenticationByFeId", "GetRequiredSurvey", "AddRate", "UnknownOperation"):
for code in (201, "201", 401, "401"):
with self.subTest(operation=operation, code=code):
with self.assertRaises(api.ApiOperationError) as caught:
diff --git a/tests/test_phase6_doctor.py b/tests/test_phase6_doctor.py
new file mode 100644
index 0000000..c5bf106
--- /dev/null
+++ b/tests/test_phase6_doctor.py
@@ -0,0 +1,110 @@
+"""Doctor public API: local-only by default, explicit bootstrap probe only."""
+import json
+import unittest
+from unittest.mock import Mock, patch
+
+import requests
+
+from myfap import diagnostics, v2
+from myfap.api import READ_OPERATIONS
+from myfap.errors import ApiError, ApiPayloadError
+
+
+class DoctorTests(unittest.TestCase):
+ def test_local_defaults_do_not_construct_auth_or_touch_session_or_http(self):
+ with patch("myfap.auth.MyFapAuth", side_effect=AssertionError("auth must stay offline")), \
+ patch("myfap.storage.SessionStore.read", side_effect=AssertionError("no session read")), \
+ patch("myfap.storage.SessionStore.lock", side_effect=AssertionError("no session lock")), \
+ patch("requests.Session.request", side_effect=AssertionError("no network")):
+ report = diagnostics.get_diagnostics()
+ self.assertEqual(report["api_version"], "v1")
+ self.assertEqual(report["api_version_source"], "default")
+ self.assertIsNone(report["campus"])
+ self.assertEqual(report["session_validation"], "not_checked")
+ self.assertEqual(report["available_operations"], sorted(READ_OPERATIONS))
+ self.assertEqual(report["online_probe"], {"requested": False})
+ self.assertIsInstance(report["package_version"], str)
+ self.assertEqual(set(report), {"package_version", "api_version", "api_version_source", "campus", "available_operations", "session_validation", "online_probe"})
+ json.dumps(report)
+
+ def test_local_explicit_version_and_campus_use_only_supplied_values(self):
+ with patch("requests.Session.request", side_effect=AssertionError("no network")):
+ report = diagnostics.get_diagnostics(api_version="v2", campus="TEST", timeout=3)
+ self.assertEqual(report["api_version"], "v2")
+ self.assertEqual(report["api_version_source"], "explicit")
+ self.assertEqual(report["campus"], "TEST")
+ self.assertEqual(report["available_operations"], sorted(v2.SUPPORTED_OPERATIONS | {"GetRequiredSurvey"}))
+ self.assertEqual(report["session_validation"], "not_checked")
+
+ def test_invalid_inputs_and_online_v1_fail_before_client_or_http(self):
+ for kwargs in ({"api_version": "v3"}, {"api_version": ""}, {"api_version": False},
+ {"campus": ""}, {"campus": " "}, {"campus": "TEST\nPRIVATE"},
+ {"campus": 3}, {"online": True}, {"api_version": "v1", "online": True}):
+ with self.subTest(kwargs=kwargs), \
+ patch("myfap.api.MyFapEssential", side_effect=AssertionError("no client")), \
+ patch("requests.Session.request", side_effect=AssertionError("no network")):
+ with self.assertRaises(ApiError):
+ diagnostics.get_diagnostics(**kwargs)
+
+ def test_online_probe_is_v2_bootstrap_not_user_session_or_selected_campus_validation(self):
+ for active in (True, False):
+ response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": active, "private": "MUST_NOT_APPEAR"}))
+ with self.subTest(active=active), patch("requests.Session.request", return_value=response) as request, \
+ patch("myfap.auth.MyFapAuth", side_effect=AssertionError("no auth")):
+ report = diagnostics.get_diagnostics(api_version="v2", campus="TEST", timeout=3, online=True)
+ self.assertEqual(report["campus"], "TEST")
+ self.assertEqual(report["session_validation"], "not_checked")
+ self.assertEqual(report["online_probe"], {"requested": True, "operation": "GetApiActive", "bootstrap_campus": "HN", "api_active": active, "scope": "proxy_bootstrap_only"})
+ self.assertNotIn("MUST_NOT_APPEAR", json.dumps(report))
+ request.assert_called_once()
+ self.assertEqual(request.call_args.args, ("POST", "https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive"))
+ self.assertEqual(request.call_args.kwargs["headers"]["CampusCode"], "HN")
+ self.assertEqual(request.call_args.kwargs["params"], {})
+ self.assertEqual(request.call_args.kwargs["json"], {})
+ self.assertEqual(request.call_args.kwargs["timeout"], 3)
+ self.assertFalse(request.call_args.kwargs["allow_redirects"])
+
+ def test_online_probe_rejects_non_boolean_payload_without_echoing_it(self):
+ for value in (None, [], {}, 1, "true", "PRIVATE_PAYLOAD"):
+ response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": value}))
+ with self.subTest(value=value), patch("requests.Session.request", return_value=response) as request:
+ with self.assertRaises(ApiPayloadError) as caught:
+ diagnostics.get_diagnostics(api_version="v2", online=True)
+ self.assertNotIn("PRIVATE_PAYLOAD", str(caught.exception))
+ request.assert_called_once()
+
+ def test_probe_network_failure_is_safe_and_not_retried(self):
+ with patch("requests.Session.request", side_effect=requests.Timeout("PRIVATE_TOKEN")) as request:
+ with self.assertRaises(ApiError) as caught:
+ diagnostics.get_diagnostics(api_version="v2", online=True)
+ request.assert_called_once()
+ self.assertNotIn("PRIVATE_TOKEN", str(caught.exception))
+
+
+class DoctorCommandTests(unittest.TestCase):
+ def test_cli_local_does_not_load_auth_and_keeps_json_stdout(self):
+ from typer.testing import CliRunner
+ from myfap.cli import app
+ with patch("myfap.cli.get_auth", side_effect=AssertionError("no auth")), \
+ patch("requests.Session.request", side_effect=AssertionError("no network")):
+ result = CliRunner().invoke(app, ["--config", "PRIVATE_PATH", "doctor", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ report = json.loads(result.stdout)
+ self.assertEqual(report["session_validation"], "not_checked")
+ self.assertEqual(report["online_probe"], {"requested": False})
+ self.assertNotIn("PRIVATE_PATH", result.output)
+
+ def test_cli_online_is_explicit_and_does_not_use_session(self):
+ from typer.testing import CliRunner
+ from myfap.cli import app
+ reply = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": True}))
+ with patch("myfap.cli.get_auth", side_effect=AssertionError("no auth")), \
+ patch("requests.Session.request", return_value=reply) as request:
+ result = CliRunner().invoke(app, ["doctor", "--api-version", "v2", "--online", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertTrue(json.loads(result.stdout)["online_probe"]["api_active"])
+ request.assert_called_once()
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
new file mode 100644
index 0000000..9750354
--- /dev/null
+++ b/tests/test_phase6_reads.py
@@ -0,0 +1,326 @@
+"""Phase 6 command contracts using real auth/client code and synthetic HTTP."""
+
+import inspect
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+from unittest.mock import patch
+from urllib.parse import urlsplit
+
+from typer.testing import CliRunner
+
+from myfap.cli import app
+from tests.test_api import response
+
+
+RUNNER_OPTIONS = {"mix_stderr": False} if "mix_stderr" in inspect.signature(CliRunner).parameters else {}
+
+
+class BalanceCommandTests(unittest.TestCase):
+ def setUp(self):
+ temporary = TemporaryDirectory()
+ self.addCleanup(temporary.cleanup)
+ self.path = Path(temporary.name) / "session.json"
+ self.runner = CliRunner(**RUNNER_OPTIONS)
+
+ def save_session(self, version):
+ session = {
+ "campus": "TEST", "account_type": "student", "authen_key": "FAKE_FAP_KEY",
+ "mssv": "TEST000", "email": "synthetic@example.invalid",
+ }
+ if version == "v2":
+ session["api_version"] = version
+ self.path.write_text(json.dumps(session), encoding="utf-8")
+
+ def test_balance_preserves_envelope_and_uses_exact_version_contract_without_term_lookup(self):
+ payload = {"code": 200, "data": {"synthetic": {"label": "Dữ liệu thử", "value": 7.5}}, "message": None}
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ original = self.path.read_bytes()
+ with patch("requests.Session.request", return_value=response(payload)) as request, patch(
+ "myfap.api.create_checksum", return_value="FAKE_ROLL_CHECKSUM"
+ ) as checksum:
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "balance", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertEqual(request.call_args.args[0], "GET")
+ parsed = urlsplit(request.call_args.args[1])
+ self.assertEqual(parsed.path.rsplit("/", 1)[-1], "GetBalance")
+ self.assertEqual(parsed.query, "")
+ self.assertFalse(request.call_args.kwargs["allow_redirects"])
+ if version == "v1":
+ self.assertEqual(parsed.netloc, "api.fpt.edu.vn")
+ self.assertEqual(request.call_args.kwargs["params"], {
+ "campusCode": "TEST", "rollNumber": "TEST000", "Authen": "FAKE_FAP_KEY",
+ "checksum": "FAKE_ROLL_CHECKSUM",
+ })
+ checksum.assert_called_once_with("TEST000", "TEST")
+ else:
+ self.assertEqual(parsed.netloc, "fap-proxy.fpt.edu.vn")
+ self.assertEqual(request.call_args.kwargs["params"], {"CampusCode": "TEST", "rollNumber": "TEST000"})
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+ checksum.assert_not_called()
+ self.assertEqual(self.path.read_bytes(), original)
+ self.assertNotIn("FAKE_FAP_KEY", result.stdout + result.stderr)
+
+ def test_balance_accepts_nested_common_options_and_preserves_empty_data(self):
+ payload = {"code": "200", "data": []}
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, [
+ "other", "balance", "--config", str(self.path), "--api-version", version,
+ "--campus", "TEST", "--timeout", "31", "--stdout",
+ ])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertEqual(request.call_args.args[0], "GET")
+ self.assertTrue(request.call_args.args[1].endswith("/GetBalance"))
+ self.assertEqual(request.call_args.kwargs["timeout"], 31.0)
+
+
+class CoursesCommandTests(unittest.TestCase):
+ def setUp(self):
+ temporary = TemporaryDirectory()
+ self.addCleanup(temporary.cleanup)
+ self.path = Path(temporary.name) / "session.json"
+ self.runner = CliRunner(**RUNNER_OPTIONS)
+
+ def save_session(self, version):
+ session = {
+ "campus": "TEST", "account_type": "student", "authen_key": "FAKE_FAP_KEY",
+ "mssv": "TEST000", "email": "synthetic@example.invalid",
+ }
+ if version == "v2":
+ session["api_version"] = version
+ self.path.write_text(json.dumps(session), encoding="utf-8")
+
+ def test_courses_preserves_data_and_uses_explicit_or_latest_semester(self):
+ payload = {"code": 200, "data": [{"synthetic": True}], "message": None}
+ semesters = [
+ {"semesterName": "Fall2025", "startDate": "2025-09-01", "termID": "zzzz-opaque-old"},
+ {"semesterName": "Fall2026", "startDate": "2026-09-01", "termID": "aaaa-opaque-new"},
+ ]
+
+ def reply(method, url, **kwargs):
+ operation = urlsplit(url).path.rsplit("/", 1)[-1]
+ return response({"code": 200, "data": semesters}) if operation == "GetSemester" else response(payload)
+
+ for version in ("v1", "v2"):
+ for explicit in (False, True):
+ with self.subTest(version=version, explicit=explicit):
+ self.save_session(version)
+ original = self.path.read_bytes()
+ options = ["--semester", "Summer&2026"] if explicit else []
+ with patch("requests.Session.request", side_effect=reply) as request, patch(
+ "myfap.api.create_checksum", return_value="FAKE_ROLL_CHECKSUM"
+ ) as checksum:
+ result = self.runner.invoke(app, ["--config", str(self.path), "courses", *options, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ operations = [urlsplit(call.args[1]).path.rsplit("/", 1)[-1] for call in request.call_args_list]
+ self.assertEqual(operations, ["GetCourseOfSemester"] if explicit else ["GetSemester", "GetCourseOfSemester"])
+ self.assertEqual(request.call_args.args[0], "GET")
+ parsed = urlsplit(request.call_args.args[1])
+ self.assertEqual(parsed.query, "")
+ self.assertFalse(request.call_args.kwargs["allow_redirects"])
+ semester = "Summer&2026" if explicit else "Fall2026"
+ if version == "v1":
+ self.assertEqual(parsed.netloc, "api.fpt.edu.vn")
+ self.assertEqual(request.call_args.kwargs["params"], {
+ "campusCode": "TEST", "rollNumber": "TEST000", "Authen": "FAKE_FAP_KEY",
+ "checksum": "FAKE_ROLL_CHECKSUM", "semester": semester,
+ })
+ self.assertEqual(checksum.call_args.args, ("TEST000", "TEST"))
+ else:
+ self.assertEqual(parsed.netloc, "fap-proxy.fpt.edu.vn")
+ self.assertEqual(request.call_args.kwargs["params"], {
+ "CampusCode": "TEST", "rollNumber": "TEST000", "semester": semester,
+ })
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+ checksum.assert_not_called()
+ self.assertEqual(self.path.read_bytes(), original)
+ self.assertNotIn("FAKE_FAP_KEY", result.stdout + result.stderr)
+
+ def test_courses_rejects_blank_explicit_semester_before_http(self):
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ with patch("requests.Session.request") as request:
+ result = self.runner.invoke(app, [
+ "--config", str(self.path), "courses", "--semester", " ", "--stdout",
+ ])
+ self.assertIn(result.exit_code, (1, 2))
+ self.assertEqual(result.stdout, "")
+ self.assertIn("--semester", result.stderr)
+ request.assert_not_called()
+
+
+class SubjectsBySemesterTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_subjects_option_preserves_legacy_and_signs_by_semester(self):
+ for version in ("v1", "v2"):
+ for semester in (None, "Fall&2026"):
+ with self.subTest(version=version, semester=semester):
+ self.save_session(version)
+ options = ["--semester", semester] if semester is not None else []
+ with patch("requests.Session.request", return_value=response({"code": 200, "data": []})) as request, \
+ patch("myfap.api.MAGIC_ID", "SYNTHETIC_MAGIC_ID"), \
+ patch("myfap.api.create_checksum", return_value="SYNTHETIC_CHECKSUM") as checksum:
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "subjects", *options, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), {"code": 200, "data": []})
+ request.assert_called_once()
+ operation = "GetSubjectBySemester" if semester is not None else "GetSubjets"
+ self.assertTrue(request.call_args.args[1].endswith('/' + operation))
+ query = request.call_args.kwargs["params"]
+ self.assertNotIn("rollNumber", query)
+ self.assertNotIn("semester", query)
+ self.assertEqual(query.get("Semester"), semester)
+ self.assertGreaterEqual(request.call_args.kwargs["timeout"], 30)
+ if version == "v1" and semester is not None:
+ checksum.assert_called_once_with(semester, "TEST")
+ if version == "v2":
+ self.assertEqual(query, {"CampusCode": "TEST", **({"Semester": semester} if semester else {})})
+
+ def test_blank_semester_is_rejected_before_http(self):
+ with patch("requests.Session.request") as request:
+ result = self.runner.invoke(app, ["other", "subjects", "--semester", " ", "--stdout"])
+ self.assertNotEqual(result.exit_code, 0)
+ self.assertIn("--semester", result.stderr)
+ request.assert_not_called()
+
+
+class SearchNewsTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_search_uses_type_signing_and_preserves_unicode_query(self):
+ text = "Học phí & A+B%"
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ payload = {"code": 200, "data": [{"synthetic": text}]}
+ with patch("requests.Session.request", return_value=response(payload)) as request, \
+ patch("myfap.api.create_checksum", return_value="SYNTHETIC_SEARCH_SIGNATURE") as checksum:
+ result = self.runner.invoke(app, ["--config", str(self.path), "news", "--search", text, "--type", "2", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/SearchNews"))
+ query = request.call_args.kwargs["params"]
+ self.assertEqual(query["keysearch"], text)
+ self.assertEqual(query["type"], 2)
+ self.assertNotIn("rollNumber", query)
+ if version == "v1":
+ checksum.assert_called_once_with("2", "TEST")
+ else:
+ self.assertEqual(query, {"CampusCode": "TEST", "type": 2, "keysearch": text})
+
+ def test_empty_search_is_rejected_before_auth_and_http(self):
+ for value in ("", " "):
+ with self.subTest(value=value), patch("myfap.cli.get_auth") as auth, patch("requests.Session.request") as request:
+ result = self.runner.invoke(app, ["news", "--search", value, "--stdout"])
+ self.assertNotEqual(result.exit_code, 0)
+ self.assertIn("--search", result.stderr)
+ auth.assert_not_called()
+ request.assert_not_called()
+
+
+class TranscriptCommandTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_transcript_uses_bound_key_without_semester_lookup(self):
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ payload = {"code": 200, "data": [{"synthetic": "Toàn khóa"}]}
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "transcript", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/AcademicTranscript"))
+ query = request.call_args.kwargs["params"]
+ self.assertEqual(query["rollNumber"], "TEST000")
+ self.assertNotIn("Semester", query)
+ if version == "v2":
+ self.assertEqual(query, {"CampusCode": "TEST", "rollNumber": "TEST000"})
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+
+
+class TrainingCommandTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_training_uses_lowercase_semester_and_latest_resolver(self):
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ payload = {"code": 200, "data": [{"synthetic": "Phong trào"}]}
+ def reply(method, url, **kwargs):
+ if url.endswith("/GetSemester"):
+ return response({"code": 200, "data": [{"semesterName": "Fall2026", "startDate": "2026-09-01"}]})
+ return response(payload)
+ with patch("requests.Session.request", side_effect=reply) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "training", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ self.assertEqual([call.args[1].rsplit('/', 1)[-1] for call in request.call_args_list],
+ ["GetSemester", "GetDiemphongtrao"])
+ query = request.call_args.kwargs["params"]
+ self.assertEqual(query["semester"], "Fall2026")
+ self.assertNotIn("Semester", query)
+ if version == "v2":
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+
+
+class PhotoCommandTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_photo_preserves_opaque_json_without_fetching_or_decoding(self):
+ payload = {"code": 200, "data": "opaque&literal-not-a-url"}
+ for version in ("v1", "v2"):
+ with self.subTest(version=version):
+ self.save_session(version)
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "info", "photo", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/RetriveImage"))
+ self.assertEqual(request.call_args.kwargs["params"]["rollNumber"], "TEST000")
+
+
+class PublicReadValidationTests(unittest.TestCase):
+ def test_invalid_semester_is_rejected_by_public_api_before_http(self):
+ from types import SimpleNamespace
+ from unittest.mock import Mock
+ from myfap.api import MyFapClient, MyFapOther
+ from myfap.errors import ApiError
+ for version in ("v1", "v2"):
+ for value in (None, "", " ", False, 3, "TERM\nPRIVATE"):
+ for owner, method in ((MyFapClient, "get_courses"), (MyFapClient, "get_training"), (MyFapOther, "get_subjects")):
+ if method == "get_subjects" and value is None:
+ continue
+ with self.subTest(version=version, method=method, value=value):
+ session = Mock()
+ auth = SimpleNamespace(session=session, api_version=version, campus="TEST", account_type="student",
+ authen_key="FAKE_KEY", mssv="TEST000", ensure_bound=Mock())
+ with self.assertRaises(ApiError):
+ getattr(owner(auth), method)(value)
+ session.request.assert_not_called()
+ session.get.assert_not_called()
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_phase6_summary.py b/tests/test_phase6_summary.py
new file mode 100644
index 0000000..6e06020
--- /dev/null
+++ b/tests/test_phase6_summary.py
@@ -0,0 +1,125 @@
+"""Operation-specific semester summary reader; all responses are synthetic."""
+import inspect
+import json
+import unittest
+
+import requests
+
+from myfap.summary import read_semester_marks_response
+
+
+def response(payload, status=200):
+ result = requests.Response()
+ result.status_code = status
+ result.encoding = "utf-8"
+ result._content = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+ return result
+
+
+class SemesterSummaryReaderTests(unittest.TestCase):
+ def test_raw_array_is_normalized_without_changing_data(self):
+ data = [{"synthetic": "Tiếng Việt", "nested": [1, None]}]
+ for version in ("v1", "v2"):
+ with self.subTest(api_version=version):
+ self.assertEqual(read_semester_marks_response(response(data), api_version=version),
+ {"code": 200, "data": data})
+
+ def test_envelope_is_preserved_and_json_string_array_is_normalized(self):
+ payload = {"code": "200", "data": [{"synthetic": 1}], "message": None}
+ self.assertEqual(read_semester_marks_response(response(payload), api_version="v2"), payload)
+ self.assertEqual(read_semester_marks_response(response('[{"synthetic": 1}]'), api_version="v1"),
+ {"code": 200, "data": [{"synthetic": 1}]})
+
+ def test_errors_are_not_converted_to_empty_arrays(self):
+ from myfap.errors import ApiAppCheckError, ApiHTTPError, ApiOperationError, ApiSessionExpiredError
+ cases = (
+ (response([], 401), "v1", ApiSessionExpiredError),
+ (response([], 403), "v2", ApiHTTPError),
+ (response({"code": "APP_CHECK_FAILED"}, 401), "v2", ApiAppCheckError),
+ (response({"code": 401, "data": None}), "v2", ApiSessionExpiredError),
+ (response({"code": 201, "data": None}), "v1", ApiOperationError),
+ )
+ for value, version, expected in cases:
+ with self.subTest(version=version, status=value.status_code):
+ with self.assertRaises(expected):
+ read_semester_marks_response(value, api_version=version)
+
+ def test_oversize_error_body_preserves_http_status_classification(self):
+ from myfap.errors import ApiHTTPError, ApiSessionExpiredError
+ for status, expected in ((401, ApiSessionExpiredError), (503, ApiHTTPError)):
+ with self.subTest(status=status):
+ with self.assertRaises(expected) as caught:
+ read_semester_marks_response(response("x" * (1024 * 1024 + 1), status), api_version="v2")
+ self.assertEqual(caught.exception.status_code, status)
+
+ def test_unknown_wrapper_malformed_or_oversize_payload_is_safe(self):
+ from myfap.errors import ApiPayloadError
+ for value in (None, True, {}, {"code": 200, "data": {}}, "PRIVATE [not json]", "[]"):
+ with self.subTest(value=value), self.assertRaises(ApiPayloadError) as caught:
+ read_semester_marks_response(response(value), api_version="v2")
+ self.assertNotIn("PRIVATE", str(caught.exception))
+ with self.assertRaises(ApiPayloadError):
+ read_semester_marks_response(response("x" * (1024 * 1024 + 1)), api_version="v2")
+
+
+class SemesterSummaryCommandTests(unittest.TestCase):
+ def test_summary_has_exact_query_and_never_looks_up_semester(self):
+ from pathlib import Path
+ from tempfile import TemporaryDirectory
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from myfap.cli import app
+ for version in ("v1", "v2"):
+ with self.subTest(version=version), TemporaryDirectory() as directory:
+ path = Path(directory) / "session.json"
+ path.write_text(json.dumps({"campus": "TEST", "api_version": version,
+ "authen_key": "FAKE_KEY", "mssv": "TEST000", "email": "sample@example.invalid"}), encoding="utf-8")
+ with patch("requests.Session.request", return_value=response([{"synthetic": True}])) as request:
+ result = CliRunner(**({"mix_stderr": False} if "mix_stderr" in inspect.signature(CliRunner).parameters else {})).invoke(app, ["--config", str(path), "marks", "--summary", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), {"code": 200, "data": [{"synthetic": True}]})
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/GetSemesterMark"))
+ self.assertEqual(request.call_args.kwargs["params"], {
+ "CampusCode": "TEST", "rollNumber": "TEST000", "Authen": "FAKE_KEY"})
+ if version == "v2":
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_KEY")
+
+ def test_conflicting_summary_options_fail_before_auth(self):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from myfap.cli import app
+ for options in (["--semester", "Fall2026"], ["--courseid", "DEMO"], ["--pretty"]):
+ with self.subTest(options=options), patch("myfap.cli.get_auth") as auth:
+ result = CliRunner(**({"mix_stderr": False} if "mix_stderr" in inspect.signature(CliRunner).parameters else {})).invoke(app, ["marks", "--summary", *options, "--stdout"])
+ self.assertNotEqual(result.exit_code, 0)
+ self.assertIn("--summary", result.stderr)
+ auth.assert_not_called()
+
+ def test_summary_rebuilds_authen_after_single_refresh(self):
+ from pathlib import Path
+ from tempfile import TemporaryDirectory
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from myfap.cli import app
+ for version in ("v1", "v2"):
+ with self.subTest(version=version), TemporaryDirectory() as directory:
+ path = Path(directory) / "session.json"
+ path.write_text(json.dumps({"campus": "TEST", "api_version": version,
+ "authen_key": "FAKE_OLD", "mssv": "TEST000", "email": "sample@example.invalid"}), encoding="utf-8")
+ def refresh(auth):
+ auth.authen_key = "FAKE_NEW"
+ return True
+ expired = {"code": 201, "message": "Token invalid", "data": None} if version == "v1" else {"code": 401, "data": None}
+ with patch("requests.Session.request", side_effect=[response(expired), response([])]) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session", autospec=True, side_effect=refresh) as rotation:
+ result = CliRunner(**({"mix_stderr": False} if "mix_stderr" in inspect.signature(CliRunner).parameters else {})).invoke(app, ["--config", str(path), "marks", "--summary", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(request.call_count, 2)
+ rotation.assert_called_once()
+ self.assertEqual(request.call_args.kwargs["params"]["Authen"], "FAKE_NEW")
+ self.assertNotIn("checksum", request.call_args.kwargs["params"])
+
+
+if __name__ == "__main__":
+ unittest.main()
From 4a52872748c75003724c33bdffae0253fea4182b Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 11:31:15 +0700
Subject: [PATCH 03/28] =?UTF-8?q?docs:=20ghi=20coverage=20command=20=C4=91?=
=?UTF-8?q?=E1=BB=8Dc=20Phase=206=20v=C3=A0=20ph=E1=BA=A7n=20c=C3=B2n=20ga?=
=?UTF-8?q?te?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Cập nhật capability 29 operation v2, query ngoại lệ, policy credential chưa live xác nhận và kết quả regression/artifact. README không còn tuyên bố parity toàn app; giữ rating/push/feedback cùng tag/publish ở trạng thái chưa hoàn tất.
---
CHANGELOG.md | 2 +-
README.md | 21 ++++++++++++++++++++-
docs/command-endpoints.md | 6 +++++-
docs/phase6-coverage.md | 37 +++++++++++++++++++++++++++++++++++++
docs/v2-contracts.md | 20 ++++++++++----------
tasks/phase6.md | 26 +++++++++++++++-----------
6 files changed, 88 insertions(+), 24 deletions(-)
create mode 100644 docs/phase6-coverage.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fe3f15a..b54a358 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,7 +30,7 @@
- **V1/APHL:** `news` và `other notification` vẫn trả HTTP 200/body 201 với `data: null`; `other fee` vẫn trả HTTP 404 trong lượt chạy lại ngày 19/10/2026. Request đã được đối chiếu với app, nhưng nguyên nhân chưa được xác định. CLI giữ lỗi, không coi là dữ liệu rỗng, hết phiên hoặc route ngừng hỗ trợ trên mọi campus.
- **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.
-- Transcript, balance, ảnh, tìm kiếm news, feedback đầy đủ và thao tác ghi thuộc Phase 6, không nằm trong phạm vi phát hành này.
+- Phase 6 đang bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary và doctor trước khi phát hành; xem coverage Phase 6. Các capability mới có fixture nhưng chưa nghiệm thu live. Feedback đầy đủ và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
- 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 b1e6d53..18de1d8 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
## Giới thiệu
-Đây là cli tương tác giống hoàn toàn với APP MYFAP trên điện thoại. Bạn có thể xem lịch học, lịch thi, điểm số (sự thất vọng của gia đình), thông tin cá nhân, v.v. 1 cách thuận tiện, không bị gò bó trong giao diện app.
+CLI tương tác với các API myFAP để xem lịch học, lịch thi, điểm và thông tin sinh viên. Phạm vi hỗ trợ phụ thuộc API version, campus và capability từng endpoint; CLI chưa thay thế đầy đủ mọi chức năng của app. Xem [mapping command/endpoint](./docs/command-endpoints.md) và [coverage Phase 6](./docs/phase6-coverage.md) để biết phần đã triển khai, đã kiểm thử và còn chưa xác minh.
- Lưu ý: repo này được thực hiện cùng với sự hỗ trợ của AI.
## Tính năng chính
@@ -48,6 +48,25 @@
myfap schedule
```
+## Command mở rộng trên nhánh phát triển
+
+Các command sau đang review trong Phase 6, **chưa phát hành lên PyPI**:
+
+```sh
+myfap courses --semester Fall2026 --stdout
+myfap other subjects --semester Fall2026 --stdout
+myfap other balance --stdout
+myfap news --search "lịch thi" --type 1 --stdout
+myfap transcript --stdout
+myfap training --semester Fall2026 --stdout
+myfap marks --summary --stdout
+myfap info photo --stdout
+myfap doctor --stdout
+myfap doctor --api-version v2 --online --stdout
+```
+
+`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. Khác với `other feedback`, các luồng rating/push/feedback submit còn có gate riêng và chưa được mở.
+
## Thông tin thêm
- [Chọn API v1 hoặc v2](https://github.com/WindowScary321/myfap-api-cli/blob/main/docs/api-versions.md): v1 vẫn mặc định; v2 hỗ trợ các command đọc hiện có trong Phase 4.
- [Các ví dụ sử dụng](./docs/Example.md)
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index d70ecc7..2809c2a 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -2,11 +2,15 @@
Tài liệu này hợp nhất mapping command → operation → method/URL → capability → bằng chứng. Mapping đối chiếu code tại commit `bc8a7ee3131093432de427e1954743ee34618f45`; bảng không bổ sung endpoint hoặc command mới. V1 vẫn mặc định, v2 opt-in qua `--api-version v2` hoặc binding session.
+## 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). 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 6:** thêm các chức năng/API mới. Không tự mở route chỉ vì có tên trong APK; cần contract, capability, fixture và kiểm chứng riêng.
+- **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.
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
new file mode 100644
index 0000000..05d8a8a
--- /dev/null
+++ b/docs/phase6-coverage.md
@@ -0,0 +1,37 @@
+# Coverage Phase 6 — đang triển khai
+
+Phần đọc tại commit `c829b7004ea2dbb7f99cf1dc3827070039bb9ea5` đang review trong [Draft PR #10](https://github.com/WindowScary321/myfap-api-cli/pull/10). V1 vẫn mặc định, v2 opt-in; **chưa tag/publish**. Đây là capability của code đang review, không phải tính năng đã có trên PyPI hoặc bằng chứng mọi endpoint hoạt động live.
+
+## Command và contract đã nối qua CLI
+
+URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 là `https://fap-proxy.fpt.edu.vn/MyFAP/`. Tất cả operation dữ liệu trong bảng dùng GET. Không ghi query có giá trị, token, checksum hoặc thông tin tài khoản vào tài liệu.
+
+| Command | Operation | v1 / v2 | Điểm contract quan trọng | Bằng chứng hiện tại |
+|---|---|---|---|---|
+| `other balance` | `GetBalance` | Có / Có | Ký v1 bằng roll number; không lookup kỳ; không suy ra currency/nợ/invoice | Fixture CLI/HTTP hai version; chưa live Phase 6 |
+| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture hai version, explicit/latest; chưa live |
+| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; chưa live |
+| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; chưa live |
+| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; policy credential v2 cần live xác nhận |
+| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; policy credential v2 cần live xác nhận |
+| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture array/envelope/JSON-string array và refresh; chưa live |
+| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Fixture; representation ảnh live chưa xác minh |
+| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
+| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture; chưa probe live trong Phase 6 |
+
+`marks --summary` từ chối `--semester`, `--courseid`, `--pretty` trước auth. `myfap version` vẫn chỉ đọc package version. Doctor không tự lấy version/campus từ session: điều này được ghi rõ trong report để giữ local mode không có tác dụng phụ.
+
+## Policy và phần chưa xác minh
+
+- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
+- Với transcript/training/summary, caller JS phục dựng v2 không truyền credential tường minh như một số read khác. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại**, không thêm anonymous request hoặc fallback credential rỗng. Đây là khác biệt policy cần ghi nhận và kiểm đọc live, không tự tuyên bố byte-for-byte giống APK.
+- 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 v2 là stub; rating/push/feedback 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**.
+- `GetVersion` backend tiếp tục unsupported cho đến khi public/text contract đủ rõ. Không thay package `version` thành probe online.
+
+## Kiểm chứng
+
+Test mới dùng CLI/auth/client thật với session tổng hợp và HTTP giả; không dùng capture/account làm fixture. Các chu kỳ RED đã ghi nhận command/option/module chưa tồn tại, GREEN sau implementation; reader bảo toàn lỗi HTTP/App Check/expiry, không đổi lỗi thành mảng rỗng.
+
+Kết quả full suite và review được ghi theo commit trong PR, không thay cho live. Chưa chạy login/live command mới trong lượt implementation này. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên.
diff --git a/docs/v2-contracts.md b/docs/v2-contracts.md
index 14d3a18..b709726 100644
--- a/docs/v2-contracts.md
+++ b/docs/v2-contracts.md
@@ -38,17 +38,17 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `AuthenticationByFeId` | `POST` | supported | FEID token trong body và Bearer header |
| `AuthenticationByFeIdCode` | `POST` | unsupported | Nhánh code exchange của app đang tắt |
| `GetStudentById` | `GET` | supported | Query `CampusCode`, `rollNumber` |
-| `RetriveImage` | `GET` | unsupported | Query `CampusCode`, `rollNumber` |
+| `RetriveImage` | `GET` | supported | Phase 6: photo JSON opaque; không fetch/decode ảnh |
| `CheckUpdateProfile` | `GET` | supported | Vẫn giữ query `Authen` theo app |
| `GetSemester` | `GET` | supported | Query rỗng |
| `GetSubjets` | `GET` | supported | Query `CampusCode` |
-| `GetSubjectBySemester` | `GET` | unsupported | Query `CampusCode`, `Semester` |
-| `GetCourseOfSemester` | `GET` | unsupported | Query `CampusCode`, `semester`, `rollNumber` |
+| `GetSubjectBySemester` | `GET` | supported | Phase 6: query `CampusCode`, `Semester`; không rollNumber |
+| `GetCourseOfSemester` | `GET` | supported | Phase 6: query `CampusCode`, `semester`, `rollNumber` |
| `GetStudentMark` | `GET` | supported | Query `CampusCode`, `rollNumber`, `Semester` |
-| `GetSemesterMark` | `GET` | unsupported | Query có `Authen` |
+| `GetSemesterMark` | `GET` | supported | Phase 6: query `CampusCode`, `rollNumber`, `Authen`; không query kỳ, reader riêng |
| `GetMarkByCourse` | `GET` | supported | Query `CampusCode`, `CourseId`, `rollNumber` |
-| `AcademicTranscript` | `GET` | unsupported | Query `CampusCode`, `rollNumber` |
-| `GetDiemphongtrao` | `GET` | unsupported | Query `CampusCode`, `rollNumber`, `semester` |
+| `AcademicTranscript` | `GET` | supported | Phase 6: query `CampusCode`, `rollNumber`; policy bound key, live chưa xác minh |
+| `GetDiemphongtrao` | `GET` | supported | Phase 6: query `CampusCode`, `rollNumber`, `semester`; policy bound key |
| `GetActivityStudent` | `GET` | supported | Query `CampusCode`, `rollNumber`, `Semester` |
| `GetActivityStudentByWeek` | `GET` | supported | Query thêm `week`, `year` |
| `GetScheduleExam` | `GET` | supported | Query `CampusCode`, `rollNumber`, `Semester` |
@@ -56,9 +56,9 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `GetStudentAttendances` | `GET` | supported | Query `CampusCode`, `Semester`, `rollNumber` |
| `GetCourseAttendance` | `GET` | supported | V2 đổi chữ hoa; query có `SubjectCode`, `ClassName` |
| `GeFeeByRoll` | `GET` | supported | Query `CampusCode`, `rollNumber` |
-| `GetBalance` | `GET` | unsupported | Query `CampusCode`, `rollNumber` |
+| `GetBalance` | `GET` | supported | Phase 6: query `CampusCode`, `rollNumber`; giữ payload, không diễn giải nợ |
| `GetTop10News` | `GET` | supported | Query `CampusCode`, `type` |
-| `SearchNews` | `GET` | unsupported | Query `CampusCode`, `type`, `keysearch` |
+| `SearchNews` | `GET` | supported | Phase 6: query `CampusCode`, `type`, `keysearch` |
| `GetApplication` | `GET` | supported | Vẫn giữ query `Authen` theo app |
| `CheckOpenFeedBack` | `GET` | supported | Vẫn giữ query `Authen` theo app |
| `AddRate` | `POST` | unsupported | Vẫn giữ query `Authen` theo app |
@@ -78,9 +78,9 @@ 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 |
-Ma trận hiện có 21 operation được hỗ trợ: 18 operation đọc, 2 bootstrap và 1 handshake. `GetApiActive` có API method chẩn đoán, chưa có command CLI riêng. 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, ma trận có 29 operation được hỗ trợ trong code: 26 operation đọc, 2 bootstrap và 1 handshake. `doctor --api-version v2 --online` gọi `GetApiActive` 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.
-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 bốn route `CheckUpdateProfile`, `GetApplication`, `CheckOpenFeedBack` và `GetNotificationByRoll`; ba route còn lại 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.
+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.
## Giới hạn hiện tại
diff --git a/tasks/phase6.md b/tasks/phase6.md
index cebbbf3..6bd7f18 100644
--- a/tasks/phase6.md
+++ b/tasks/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.
-Tài liệu này là checklist khởi động, **chưa ghi nhận command Phase 6 đã triển khai hoặc test/live đã đạt**. Không suy khả năng backend từ việc route có trong APK. Phần thiếu contract/schema phải 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](../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ở.
## Quy tắc xuyên suốt
@@ -18,10 +18,10 @@ Tài liệu này là checklist khởi động, **chưa ghi nhận command Phase
Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/test → coverage, không chỉ thêm tên vào allowlist.
-- [ ] **`courses --semester` → `GetCourseOfSemester`:** dùng resolver kỳ nếu thiếu option; query `semester` chữ thường, đúng credential/signing identity từng version.
-- [ ] **`other subjects --semester` → `GetSubjectBySemester`:** query `Semester` chữ hoa; v1 ký bằng semester. Khi không có option mới vẫn dùng `GetSubjets`, không lookup kỳ và giữ timeout subjects hiện có.
-- [ ] **`other balance` → `GetBalance`:** không lookup kỳ; bảo toàn payload, không suy ra currency/nợ/invoice. Cập nhật retry/error allowlist có chủ đích và giữ regression cho operation chưa hỗ trợ.
-- [ ] **`news --search` → `SearchNews`:** không có search vẫn dùng `GetTop10News`; từ chối search rỗng trước auth, truyền `type`/`keysearch` qua params và v1 ký bằng type. Kiểm Unicode và ký tự reserved, không nối query thủ công.
+- [x] **`courses --semester` → `GetCourseOfSemester`:** dùng resolver kỳ nếu thiếu option; query `semester` chữ thường, đúng credential/signing identity từng version.
+- [x] **`other subjects --semester` → `GetSubjectBySemester`:** query `Semester` chữ hoa; v1 ký bằng semester. Khi không có option mới vẫn dùng `GetSubjets`, không lookup kỳ và giữ timeout subjects hiện có.
+- [x] **`other balance` → `GetBalance`:** không lookup kỳ; bảo toàn payload, không suy ra currency/nợ/invoice. Cập nhật retry/error allowlist có chủ đích và giữ regression cho operation chưa hỗ trợ.
+- [x] **`news --search` → `SearchNews`:** không có search vẫn dùng `GetTop10News`; từ chối search rỗng trước auth, truyền `type`/`keysearch` qua params và v1 ký bằng type. Kiểm Unicode và ký tự reserved, không nối query thủ công.
**Nghiệm thu nhóm:**
- [ ] Test tại public seam CLI và biên HTTP chứng minh method/path/query/header/body đúng, stdout sạch, binding và common-option precedence được giữ.
@@ -29,9 +29,9 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## 2. Transcript, training và marks summary
-- [ ] **`transcript` → `AcademicTranscript`:** hỗ trợ theo contract cả v1/v2, không lookup kỳ; chưa thêm formatter nghiệp vụ khi schema data chưa được xác minh.
-- [ ] **`training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
-- [ ] **`marks --summary` → `GetSemesterMark`:** không lookup kỳ hoặc thêm query semester. V1 dùng đúng `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 giữ query `Authen` mới sau refresh.
+- [x] **`transcript` → `AcademicTranscript`:** hỗ trợ theo contract cả v1/v2, không lookup kỳ; chưa thêm formatter nghiệp vụ khi schema data chưa được xác minh.
+- [x] **`training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
+- [x] **`marks --summary` → `GetSemesterMark`:** không lookup kỳ hoặc thêm query semester. V1 dùng đúng `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 giữ query `Authen` mới sau refresh.
- [ ] Từ chối tổ hợp summary với `--courseid`/`--pretty`; nếu `--semester` không áp dụng thì báo lỗi, không âm thầm bỏ qua.
- [ ] Reader riêng cho summary kiểm HTTP/App Check/expiry trước khi đọc raw array/envelope/text. Chỉ parse dạng đã có bằng chứng, có giới hạn; malformed/unknown phải báo payload error, không cắt tùy tiện giữa dấu ngoặc rồi trả success.
- [ ] Chốt khác biệt credential v2 ở các caller decompile của transcript/training/summary bằng bytecode/contract và kiểm đọc. Không mặc định sao chép credential rỗng, thử unauth rồi fallback hoặc nới reader chung cho mọi endpoint.
@@ -42,8 +42,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## 3. Photo và doctor
-- [ ] **`info photo` → `RetriveImage`:** output JSON theo representation đã chứng minh, giữ chuỗi opaque; không tự fetch URL, decode Base64, in binary hoặc mở ảnh. Xuất ảnh file riêng chỉ mở sau khi đủ bằng chứng định dạng/size/type và fixture.
-- [ ] **`doctor` local:** chỉ xuất allowlist chẩn đoán package/API version, campus được chọn, capability và loại lỗi; không dump auth/session, email/MSSV, header, token hoặc config path đầy đủ. Không gọi `require_auth`/`load_session` gây refresh/persist.
+- [x] **`info photo` → `RetriveImage`:** output JSON theo representation đã chứng minh, giữ chuỗi opaque; không tự fetch URL, decode Base64, in binary hoặc mở ảnh. Xuất ảnh file riêng chỉ mở sau khi đủ bằng chứng định dạng/size/type và fixture.
+- [x] **`doctor` local:** chỉ xuất allowlist chẩn đoán package/API version, campus được chọn, capability và loại lỗi; không dump auth/session, email/MSSV, header, token hoặc config path đầy đủ. Không gọi `require_auth`/`load_session` gây refresh/persist.
- [ ] Probe online là option explicit và tái sử dụng `GetApiActive` v2; không auto-login/refresh/switch version. `GetVersion` giữ gate riêng khi public/text contract còn chưa rõ; `myfap version` tiếp tục offline.
- [ ] Test doctor/help local không gọi mạng; lỗi không lộ payload; photo không tạo file/fetch ngoài ý muốn.
@@ -80,4 +80,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## Trạng thái khởi động
-Các ô trên đều **pending**; chưa có kết quả test, live hay CI cho tính năng Phase 6 trong tài liệu khởi động này. Ghi kết quả sau từng lát cắt bằng commit, lệnh và exit code thật. Các finding v1 và positive fee/survey giữ tại [todo.md](todo.md), không bị thay thế bởi checklist mới.
+Nhóm command đọc và doctor đã có fixture; focused tests ghi RED trước implementation rồi GREEN. Full suite ngày 24/10/2026 trên Windows: **389 test mỗi Python 3.11 và 3.9, 385 đạt/4 skip, exit 0**. Bốn skip là các phép symlink/POSIX mode không áp dụng hoặc thiếu quyền trên Windows, không phải test bị bỏ mới.
+
+Review độc lập đã tái hiện hai finding bằng HTTP giả: public API v1 chưa validate kỳ trước HTTP, và body summary lỗi quá lớn che HTTP 401/503. Đã sửa và test lại. Lượt full đầu chạy hai interpreter đồng thời bị timeout tiến trình help 20 giây; Python 3.9 còn lộ cách CliRunner tách stderr khác version. Đã sửa cấu hình capture trong test theo mẫu hiện có, giữ nguyên kiểm tra nội dung/timeout; focused help đạt, sau đó hai full suite chạy tuần tự đều đạt. Không hạ tiêu chí hoặc bỏ test.
+
+Build, Twine và artifact validator đã đạt với bộ `dist-phase6-reads`, manifest SHA-256 `f88e6fe7b5795fbb01acfda00df434e74d02965aaab21c2c83328e4bfaff2fea`. Pip smoke wheel/sdist trong hai venv sạch Windows/Python 3.11 đạt, exit 0; không dùng lockfile để resolve dependency. Mutation đổi signer subjects từ semester sang identity khác bị test bắt; chạy trên bản sao tạm, không sửa checkout. Fixture mới dùng identity tổng hợp kể cả nhánh legacy. Doctor local đã chạy qua CLI thật, không đọc session/HTTP. Chưa có live account hoặc CI cho commit runtime mới tại thời điểm ghi nhận; rating/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).
From 4c29b81f0e61d11ccb6d047060680cbcf60ab121 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 11:51:03 +0700
Subject: [PATCH 04/28] =?UTF-8?q?feat:=20=C4=91=E1=BB=8Dc=20rating=20stude?=
=?UTF-8?q?nt=20v1=20v=C3=A0=20ch=E1=BA=B7n=20stub=20v2=20tr=C6=B0?=
=?UTF-8?q?=E1=BB=9Bc=20HTTP?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Thêm rating list dùng contract GET v1 và signer roll number. V2 vẫn unsupported trước load session; không mở AddRate, push hoặc feedback submit và không biến stub thành dữ liệu rỗng.
---
myfap/api.py | 7 +++++++
myfap/cli.py | 18 ++++++++++++++++++
myfap/errors.py | 2 +-
tests/test_api_session.py | 1 +
tests/test_phase6_reads.py | 30 ++++++++++++++++++++++++++++++
5 files changed, 57 insertions(+), 1 deletion(-)
diff --git a/myfap/api.py b/myfap/api.py
index f134bd8..9e90ab5 100644
--- a/myfap/api.py
+++ b/myfap/api.py
@@ -247,6 +247,13 @@ def get_fee(self):
return _authenticated_get(self.session, self.auth, "GeFeeByRoll", self.auth.mssv,
student=True, timeout=self.timeout, api_version=self.api_version)
+ def get_ratings(self):
+ """Đọc danh sách rating v1; không suy implementation cho stub v2."""
+ if self.api_version != "v1":
+ raise ApiError("GetStudentRate chưa được hỗ trợ trong adapter API v2.")
+ return _authenticated_get(self.session, self.auth, "GetStudentRate", self.auth.mssv,
+ student=True, timeout=self.timeout, api_version=self.api_version)
+
def get_balance(self):
"""Lấy số dư, bảo toàn payload thay vì tự suy diễn thông tin tài chính."""
return _authenticated_get(self.session, self.auth, "GetBalance", self.auth.mssv,
diff --git a/myfap/cli.py b/myfap/cli.py
index 1e9c1ed..d0125c0 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -90,6 +90,9 @@ def inherit(command):
other_app = typer.Typer(help="Các chức năng phụ trợ khác (survey, feedback, fee...)")
app.add_typer(other_app, name="other")
+rating_app = typer.Typer(help="Đánh giá dịch vụ; list hiện chỉ hỗ trợ API v1")
+app.add_typer(rating_app, name="rating")
+
state = {
"campus": None,
"config": None,
@@ -648,6 +651,21 @@ def info_campus(
raise typer.Exit(code=1)
+@rating_app.command("list")
+def rating_list(
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ stdout: bool = typer.Option(False, "--stdout", help="In JSON danh sách; không gửi đánh giá")
+):
+ """Lấy danh sách đánh giá student/v1; v2 stub bị chặn trước HTTP."""
+ auth = require_auth("GetStudentRate")
+ try:
+ data = MyFapOther(auth).get_ratings()
+ save_output(data, "RatingList.json", output, stdout)
+ except Exception as error:
+ err_console.print(f"[red]Lỗi lấy danh sách đánh giá: {error}[/red]")
+ raise typer.Exit(code=1)
+
+
# --- SUBCOMMAND OTHER ---
@other_app.command("survey")
def other_survey(
diff --git a/myfap/errors.py b/myfap/errors.py
index 87ed4b1..25fcf55 100644
--- a/myfap/errors.py
+++ b/myfap/errors.py
@@ -39,7 +39,7 @@ class ApiAppCheckError(ApiError):
"GetSemester", "GetTop10News", "CheckOpenFeedBack", "CheckUpdateProfile",
"GetNotificationByRoll", "GeFeeByRoll", "GetSubjets", "GetBalance",
"GetActivityStudent", "GetCourseOfSemester", "GetSubjectBySemester", "SearchNews", "AcademicTranscript", "GetDiemphongtrao", "RetriveImage",
- "GetStudentMark", "GetSemesterMark",
+ "GetStudentMark", "GetSemesterMark", "GetStudentRate",
"GetMarkByCourse", "GetScheduleExam",
"GetStudentAttendances",
"GetActivityStudentByWeek",
diff --git a/tests/test_api_session.py b/tests/test_api_session.py
index d076692..37ef131 100644
--- a/tests/test_api_session.py
+++ b/tests/test_api_session.py
@@ -17,6 +17,7 @@
(api.MyFapOther, "get_notification", (), "GetNotificationByRoll"),
(api.MyFapOther, "get_fee", (), "GeFeeByRoll"),
(api.MyFapOther, "get_balance", (), "GetBalance"),
+ (api.MyFapOther, "get_ratings", (), "GetStudentRate"),
(api.MyFapOther, "get_subjects", (), "GetSubjets"),
(api.MyFapOther, "get_subjects", ("Fall2026",), "GetSubjectBySemester"),
(api.MyFapClient, "get_schedule", ("Fall2026",), "GetActivityStudent"),
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 9750354..a936927 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -322,5 +322,35 @@ def test_invalid_semester_is_rejected_by_public_api_before_http(self):
session.get.assert_not_called()
+class RatingListTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_rating_list_v1_uses_read_contract_without_semester(self):
+ self.save_session("v1")
+ payload = {"code": 200, "data": [{"synthetic": "rating item"}]}
+ with patch("requests.Session.request", return_value=response(payload)) as request, \
+ patch("myfap.api.create_checksum", return_value="SYNTHETIC_RATE_LIST") as checksum:
+ result = self.runner.invoke(app, ["rating", "list", "--config", str(self.path), "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertEqual(request.call_args.args[0], "GET")
+ self.assertTrue(request.call_args.args[1].endswith("/GetStudentRate"))
+ self.assertEqual(request.call_args.kwargs["params"], {
+ "campusCode": "TEST", "rollNumber": "TEST000", "Authen": "FAKE_FAP_KEY", "checksum": "SYNTHETIC_RATE_LIST"})
+ checksum.assert_called_once_with("TEST000", "TEST")
+
+ def test_rating_list_v2_stub_is_rejected_before_session_load_or_http(self):
+ self.save_session("v2")
+ with patch("myfap.auth.MyFapAuth.load_session") as load, patch("requests.Session.request") as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "rating", "list", "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertIn("GetStudentRate", result.stderr)
+ load.assert_not_called()
+ request.assert_not_called()
+
+
if __name__ == "__main__":
unittest.main()
From d6d0ee63a7c052bf94112426323ed06b4ca05be6 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 11:59:11 +0700
Subject: [PATCH 05/28] =?UTF-8?q?test:=20chu=E1=BA=A9n=20h=C3=B3a=20m?=
=?UTF-8?q?=C3=A0u=20ANSI=20khi=20ki=E1=BB=83m=20l=E1=BB=97i=20option=20Ph?=
=?UTF-8?q?ase=206?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Tái hiện CI bằng FORCE_COLOR=1; dùng Rich Text.from_ansi như regression help hiện có. Giữ nguyên assertion tên option, stderr và zero HTTP; không thay runtime hoặc bỏ gate.
---
tests/test_phase6_reads.py | 7 ++++---
tests/test_phase6_summary.py | 3 ++-
2 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index a936927..b3e676e 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -9,6 +9,7 @@
from urllib.parse import urlsplit
from typer.testing import CliRunner
+from rich.text import Text
from myfap.cli import app
from tests.test_api import response
@@ -157,7 +158,7 @@ def test_courses_rejects_blank_explicit_semester_before_http(self):
])
self.assertIn(result.exit_code, (1, 2))
self.assertEqual(result.stdout, "")
- self.assertIn("--semester", result.stderr)
+ self.assertIn("--semester", Text.from_ansi(result.stderr).plain)
request.assert_not_called()
@@ -194,7 +195,7 @@ def test_blank_semester_is_rejected_before_http(self):
with patch("requests.Session.request") as request:
result = self.runner.invoke(app, ["other", "subjects", "--semester", " ", "--stdout"])
self.assertNotEqual(result.exit_code, 0)
- self.assertIn("--semester", result.stderr)
+ self.assertIn("--semester", Text.from_ansi(result.stderr).plain)
request.assert_not_called()
@@ -229,7 +230,7 @@ def test_empty_search_is_rejected_before_auth_and_http(self):
with self.subTest(value=value), patch("myfap.cli.get_auth") as auth, patch("requests.Session.request") as request:
result = self.runner.invoke(app, ["news", "--search", value, "--stdout"])
self.assertNotEqual(result.exit_code, 0)
- self.assertIn("--search", result.stderr)
+ self.assertIn("--search", Text.from_ansi(result.stderr).plain)
auth.assert_not_called()
request.assert_not_called()
diff --git a/tests/test_phase6_summary.py b/tests/test_phase6_summary.py
index 6e06020..1c8dc89 100644
--- a/tests/test_phase6_summary.py
+++ b/tests/test_phase6_summary.py
@@ -4,6 +4,7 @@
import unittest
import requests
+from rich.text import Text
from myfap.summary import read_semester_marks_response
@@ -93,7 +94,7 @@ def test_conflicting_summary_options_fail_before_auth(self):
with self.subTest(options=options), patch("myfap.cli.get_auth") as auth:
result = CliRunner(**({"mix_stderr": False} if "mix_stderr" in inspect.signature(CliRunner).parameters else {})).invoke(app, ["marks", "--summary", *options, "--stdout"])
self.assertNotEqual(result.exit_code, 0)
- self.assertIn("--summary", result.stderr)
+ self.assertIn("--summary", Text.from_ansi(result.stderr).plain)
auth.assert_not_called()
def test_summary_rebuilds_authen_after_single_refresh(self):
From 0e0c01c8027458d01f215a694351aeb05efb7e7d Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 12:05:38 +0700
Subject: [PATCH 06/28] =?UTF-8?q?docs:=20ghi=20rating=20list,=20CI=20Phase?=
=?UTF-8?q?=206=20v=C3=A0=20l=C6=B0=E1=BB=A3t=20login=20ch=C6=B0a=20=C4=91?=
=?UTF-8?q?=E1=BA=A1t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Ghi đúng CI d6d0ee6 đạt 11 job, full local391 test mỗi Python và lỗi môi trường đã phục hồi. Không đổi login chưa thành công thành bằng chứng endpoint; giữ schema thao tác ghi và live đọc ở gate mở.
---
CHANGELOG.md | 2 +-
README.md | 3 ++-
docs/phase6-coverage.md | 13 ++++++++++---
tasks/phase6.md | 8 +++++---
4 files changed, 18 insertions(+), 8 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b54a358..1ced708 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,7 +30,7 @@
- **V1/APHL:** `news` và `other notification` vẫn trả HTTP 200/body 201 với `data: null`; `other fee` vẫn trả HTTP 404 trong lượt chạy lại ngày 19/10/2026. Request đã được đối chiếu với app, nhưng nguyên nhân chưa được xác định. CLI giữ lỗi, không coi là dữ liệu rỗng, hết phiên hoặc route ngừng hỗ trợ trên mọi campus.
- **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 đang bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary và doctor trước khi phát hành; xem coverage Phase 6. Các capability mới có fixture nhưng chưa nghiệm thu live. Feedback đầy đủ và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
+- Phase 6 đang bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary và doctor trước khi phát hành; xem coverage Phase 6. Các capability mới có fixture nhưng chưa nghiệm thu live. Rating list student/v1 đã có code/fixture; v2 stub bị chặn. Feedback đầy đủ và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
- 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 18de1d8..205df61 100644
--- a/README.md
+++ b/README.md
@@ -61,11 +61,12 @@ myfap transcript --stdout
myfap training --semester Fall2026 --stdout
myfap marks --summary --stdout
myfap info photo --stdout
+myfap rating list --api-version v1 --stdout
myfap doctor --stdout
myfap doctor --api-version v2 --online --stdout
```
-`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. Khác với `other feedback`, các luồng rating/push/feedback submit còn có gate riêng và chưa được mở.
+`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. `rating list` chỉ hỗ trợ student/v1; v2 là stub và bị chặn. Khác với các lệnh đọc này, rating submit/push/feedback submit còn có gate riêng và chưa được mở.
## Thông tin thêm
- [Chọn API v1 hoặc v2](https://github.com/WindowScary321/myfap-api-cli/blob/main/docs/api-versions.md): v1 vẫn mặc định; v2 hỗ trợ các command đọc hiện có trong Phase 4.
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 05d8a8a..7197338 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -1,6 +1,6 @@
# Coverage Phase 6 — đang triển khai
-Phần đọc tại commit `c829b7004ea2dbb7f99cf1dc3827070039bb9ea5` đang review trong [Draft PR #10](https://github.com/WindowScary321/myfap-api-cli/pull/10). V1 vẫn mặc định, v2 opt-in; **chưa tag/publish**. Đây là capability của code đang review, không phải tính năng đã có trên PyPI hoặc bằng chứng mọi endpoint hoạt động live.
+Nhóm đọc ban đầu tại `c829b7004ea2dbb7f99cf1dc3827070039bb9ea5`, bổ sung rating list v1 tại `4c29b81f0e61d11ccb6d047060680cbcf60ab121`, đang review trong [Draft PR #10](https://github.com/WindowScary321/myfap-api-cli/pull/10). V1 vẫn mặc định, v2 opt-in; **chưa tag/publish**. Đây là capability của code đang review, không phải tính năng đã có trên PyPI hoặc bằng chứng mọi endpoint hoạt động live.
## Command và contract đã nối qua CLI
@@ -16,6 +16,7 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; policy credential v2 cần live xác nhận |
| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture array/envelope/JSON-string array và refresh; chưa live |
| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Fixture; representation ảnh live chưa xác minh |
+| `rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture CLI/HTTP, chưa live |
| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture; chưa probe live trong Phase 6 |
@@ -27,11 +28,17 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
- Với transcript/training/summary, caller JS phục dựng v2 không truyền credential tường minh như một số read khác. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại**, không thêm anonymous request hoặc fallback credential rỗng. Đây là khác biệt policy cần ghi nhận và kiểm đọc live, không tự tuyên bố byte-for-byte giống APK.
- 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 v2 là stub; rating/push/feedback 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 [tasks/phase6.md](../tasks/phase6.md) vẫn còn pending, Phase 6 **chưa hoàn tất**.
- `GetVersion` backend tiếp tục unsupported cho đến khi public/text contract đủ rõ. Không thay package `version` thành probe online.
## Kiểm chứng
Test mới dùng CLI/auth/client thật với session tổng hợp và HTTP giả; không dùng capture/account làm fixture. Các chu kỳ RED đã ghi nhận command/option/module chưa tồn tại, GREEN sau implementation; reader bảo toàn lỗi HTTP/App Check/expiry, không đổi lỗi thành mảng rỗng.
-Kết quả full suite và review được ghi theo commit trong PR, không thay cho live. Chưa chạy login/live command mới trong lượt implementation này. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên.
+Sau rating list, full local Windows có 391 test trên mỗi Python 3.11/3.9, 387 đạt/4 skip, exit 0. Venv Python 3.9 từng lỗi tzdata UTC độc lập với command; cài lại đúng version khóa trong venv test đã phục hồi probe UTC và toàn suite, không đổi lockfile.
+
+CI run [40064482334](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064482334) tại `d6d0ee63a7c052bf94112426323ed06b4ca05be6` đạt **11/11 job**, gồm source và artifact smoke Ubuntu/Windows × Python 3.9/3.11. Run trước đó thất bại vì assertion đọc tên option trên chuỗi ANSI; đã tái hiện FORCE_COLOR=1 rồi dùng Text.from_ansi theo test help sẵn có, giữ nguyên kiểm tra nội dung và no-HTTP.
+
+Đã thử mở browser/context mới để kiểm live v2/HN trong lượt này: doctor local exit 0 với JSON hợp lệ và không HTTP; login exit 1, chưa có response FAP được quan sát. Các command xác thực mới sau login **chưa chạy**, không ghi chúng là live pass hoặc live-failed endpoint. Logout exit 0; session và thư mục tạm đã dọn. Không suy nguyên nhân lỗi login từ việc không có response.
+
+Kết quả full suite và review không thay cho live. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 6bd7f18..9af09f1 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -55,7 +55,7 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## 4. Rating và push — chỉ mở sau gate contract
-- [ ] **Rating list:** chốt fixture/schema tối thiểu cho student/v1; v2 là stub nên unsupported trước auth/network, không gọi v1 ngầm hoặc trả `[]` giả.
+- [x] **Rating list:** `rating list` student/v1 có code và fixture envelope/query; chưa suy kiểu ID/schema item hoặc xác nhận live. V2 là stub nên unsupported trước load session/HTTP, không gọi v1 ngầm hoặc trả `[]` giả.
- [ ] **`rating submit --input`:** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
- [ ] **`push register --token-file`:** chốt contract student; `UpdateTokedevices` là **GET ghi**, v1 ký bằng **email**. Token chỉ đọc từ regular file có giới hạn, kiểm encoding/newline và symlink/reparse/path swap; không token trên argv/preview/log/error. Campus/identity lấy từ session đã bind.
- [ ] Đường ghi tách khỏi read retry, không thêm AddRate/push vào read allowlist để cấp credential. Trình tự: validate → capability → preview không bí mật → confirmation/`--yes` → auth → một lần gửi. `--yes` không bỏ validation.
@@ -78,10 +78,12 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
- [ ] 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.
- [ ] 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.
-## Trạng thái khởi động
+## Kết quả checkpoint hiện tại
Nhóm command đọc và doctor đã có fixture; focused tests ghi RED trước implementation rồi GREEN. Full suite ngày 24/10/2026 trên Windows: **389 test mỗi Python 3.11 và 3.9, 385 đạt/4 skip, exit 0**. Bốn skip là các phép symlink/POSIX mode không áp dụng hoặc thiếu quyền trên Windows, không phải test bị bỏ mới.
Review độc lập đã tái hiện hai finding bằng HTTP giả: public API v1 chưa validate kỳ trước HTTP, và body summary lỗi quá lớn che HTTP 401/503. Đã sửa và test lại. Lượt full đầu chạy hai interpreter đồng thời bị timeout tiến trình help 20 giây; Python 3.9 còn lộ cách CliRunner tách stderr khác version. Đã sửa cấu hình capture trong test theo mẫu hiện có, giữ nguyên kiểm tra nội dung/timeout; focused help đạt, sau đó hai full suite chạy tuần tự đều đạt. Không hạ tiêu chí hoặc bỏ test.
-Build, Twine và artifact validator đã đạt với bộ `dist-phase6-reads`, manifest SHA-256 `f88e6fe7b5795fbb01acfda00df434e74d02965aaab21c2c83328e4bfaff2fea`. Pip smoke wheel/sdist trong hai venv sạch Windows/Python 3.11 đạt, exit 0; không dùng lockfile để resolve dependency. Mutation đổi signer subjects từ semester sang identity khác bị test bắt; chạy trên bản sao tạm, không sửa checkout. Fixture mới dùng identity tổng hợp kể cả nhánh legacy. Doctor local đã chạy qua CLI thật, không đọc session/HTTP. Chưa có live account hoặc CI cho commit runtime mới tại thời điểm ghi nhận; rating/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).
+Build, Twine và artifact validator đã đạt với bộ `dist-phase6-reads`, manifest SHA-256 `f88e6fe7b5795fbb01acfda00df434e74d02965aaab21c2c83328e4bfaff2fea`. Pip smoke wheel/sdist trong hai venv sạch Windows/Python 3.11 đạt, exit 0; không dùng lockfile để resolve dependency. Mutation đổi signer subjects từ semester sang identity khác bị test bắt; chạy trên bản sao tạm, không sửa checkout. Fixture mới dùng identity tổng hợp kể cả nhánh legacy. Doctor local đã chạy qua CLI thật, không đọc session/HTTP. Sau khi thêm rating list v1: full Windows có 391 test mỗi Python 3.11/3.9, 387 đạt/4 skip, exit 0. CI tại `d6d0ee6` đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064482334). Đã sửa assertion ANSI gây fail run trước, không đổi runtime; lỗi tzdata UTC của venv test 3.9 được tái hiện bằng probe riêng rồi cài lại đúng package đã khóa, không đổi dependency.
+
+Lượt thử live mới 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. Session/thư mục tạm đã dọn. Rating list v1 hiện có fixture, chưa live; 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).
From ca09b1106ddacca96145a36df0b0668bf15ae52f Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 12:54:22 +0700
Subject: [PATCH 07/28] =?UTF-8?q?docs:=20ghi=20live=20command=20=C4=91?=
=?UTF-8?q?=E1=BB=8Dc=20Phase=206=20v2=20HN=20th=C3=A0nh=20c=C3=B4ng?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Ghi 14 lần command exit0, dạng dữ liệu và giới hạn; chỉ metadata đã lọc. Xác nhận policy bound key đọc được trên HN, không suy auth server hoặc schema từ nonempty; giữ v1 và thao tác ghi chưa nghiệm thu.
---
docs/phase6-coverage.md | 45 +++++++++++++++++++++++++++++++----------
tasks/phase6.md | 4 +++-
2 files changed, 37 insertions(+), 12 deletions(-)
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 7197338..1686460 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -8,24 +8,24 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| Command | Operation | v1 / v2 | Điểm contract quan trọng | Bằng chứng hiện tại |
|---|---|---|---|---|
-| `other balance` | `GetBalance` | Có / Có | Ký v1 bằng roll number; không lookup kỳ; không suy ra currency/nợ/invoice | Fixture CLI/HTTP hai version; chưa live Phase 6 |
-| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture hai version, explicit/latest; chưa live |
-| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; chưa live |
-| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; chưa live |
-| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; policy credential v2 cần live xác nhận |
-| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; policy credential v2 cần live xác nhận |
-| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture array/envelope/JSON-string array và refresh; chưa live |
-| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Fixture; representation ảnh live chưa xác minh |
+| `other balance` | `GetBalance` | Có / Có | Ký v1 bằng roll number; không lookup kỳ; không suy ra currency/nợ/invoice | Fixture hai version; live v2/HN 200/200, v1 chưa live |
+| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture explicit/latest; live v2/HN 200/200, v1 chưa live |
+| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; live v2/HN 200/200, v1 chưa live |
+| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; live v2/HN 200/200 |
+| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; live v2/HN 200/200 với bound key, data string |
+| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; live v2/HN 200/200 với bound key, list rỗng |
+| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture parser/refresh; live v2/HN 200/200 với envelope data list |
+| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Live v2/HN 200/200, data string; định dạng ảnh chưa xác minh |
| `rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture CLI/HTTP, chưa live |
| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
-| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture; chưa probe live trong Phase 6 |
+| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture và live bootstrap v2 200/200; không kiểm tài khoản |
`marks --summary` từ chối `--semester`, `--courseid`, `--pretty` trước auth. `myfap version` vẫn chỉ đọc package version. Doctor không tự lấy version/campus từ session: điều này được ghi rõ trong report để giữ local mode không có tác dụng phụ.
## Policy và phần chưa xác minh
- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
-- Với transcript/training/summary, caller JS phục dựng v2 không truyền credential tường minh như một số read khác. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại**, không thêm anonymous request hoặc fallback credential rỗng. Đây là khác biệt policy cần ghi nhận và kiểm đọc live, không tự tuyên bố byte-for-byte giống APK.
+- Với transcript/training/summary, caller JS phục dựng v2 không truyền credential tường minh như một số read khác. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại**, không thêm anonymous request hoặc fallback credential rỗng. Lượt live v2/HN ngày 24/10 đã đọc thành công bằng policy này; không chứng minh server bắt buộc Bearer, không xác minh nhánh credential rỗng của APK hoặc parity byte-for-byte.
- 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**.
@@ -41,4 +41,27 @@ CI run [40064482334](https://github.com/WindowScary321/myfap-api-cli/actions/run
Đã thử mở browser/context mới để kiểm live v2/HN trong lượt này: doctor local exit 0 với JSON hợp lệ và không HTTP; login exit 1, chưa có response FAP được quan sát. Các command xác thực mới sau login **chưa chạy**, không ghi chúng là live pass hoặc live-failed endpoint. Logout exit 0; session và thư mục tạm đã dọn. Không suy nguyên nhân lỗi login từ việc không có response.
-Kết quả full suite và review không thay cho live. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên.
+## Live đọc v2/HN ngày 24/10/2026
+
+Sau khi người dùng xác nhận mở login mới, chạy code tại `0e0c01c8027458d01f215a694351aeb05efb7e7d` với browser/context trống và session tạm riêng. **14 lần command đều exit 0**, JSON stdout hợp lệ; observer giữ 14 request thuộc 12 operation. Một request `GetSemester` bổ sung dùng để chọn input hợp lệ cho subjects theo kỳ trước khi gọi CLI không thuộc số request observer; không diễn giải con số đó là tổng traffic FEID/FAP.
+
+| Command/nhóm | HTTP / body code | Kết quả đã lọc |
+|---|---|---|
+| `doctor` local | Không HTTP | JSON hợp lệ, không đọc session |
+| Login/handshake, refresh và đọc student sau refresh | 200 / 200 | Thành công, không lưu identity/token vào báo cáo |
+| `doctor --online` v2 | 200 / 200 | Bootstrap GetApiActive trả boolean; không coi là kiểm session/campus tài khoản |
+| `courses` | 200 / 200 | Data list không rỗng, có resolver kỳ |
+| `other subjects --semester` | 200 / 200 | Input kỳ lấy từ endpoint thật, không đoán; data list không rỗng |
+| `other balance` | 200 / 200 | Data string không rỗng; không suy ra currency/amount/nợ |
+| `news --search` | 200 / 200 | Data list không rỗng; search text tổng quát, không chứa dữ liệu tài khoản |
+| `transcript` | 200 / 200 | Data string không rỗng; chưa kiểm cấu trúc/formatter nghiệp vụ |
+| `training` | 200 / 200 | Data list rỗng hợp lệ; chưa phải positive nghiệp vụ |
+| `marks --summary` | 200 / 200 | Envelope data list không rỗng; không thử format XML wrapper |
+| `info photo` JSON | 200 / 200 | Data string không rỗng; không đọc/in nội dung ảnh, không chứng minh URL/Base64 |
+| `logout` | Không HTTP | Session/lock và thư mục tạm đã dọn |
+
+Không thay request/response hoặc dùng capture credential. Không chạy rating list v1, rating submit, push hoặc feedback ghi trong lượt này. Các command mới trên **v1 vẫn chưa live**, rating list v1 mới có fixture, và schema/ack thao tác ghi còn gate.
+
+CI của đúng commit `0e0c01c` đã đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064917612), gồm source và artifact smoke Ubuntu/Windows × Python 3.9/3.11. Đây không phải publish/release.
+
+Kết quả full suite và review không thay cho live ở version/campus khác. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên. Chỉ metadata allowlist được lưu; payload và biến nhạy cảm không vào GitHub.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 9af09f1..27eec61 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -86,4 +86,6 @@ Review độc lập đã tái hiện hai finding bằng HTTP giả: public API v
Build, Twine và artifact validator đã đạt với bộ `dist-phase6-reads`, manifest SHA-256 `f88e6fe7b5795fbb01acfda00df434e74d02965aaab21c2c83328e4bfaff2fea`. Pip smoke wheel/sdist trong hai venv sạch Windows/Python 3.11 đạt, exit 0; không dùng lockfile để resolve dependency. Mutation đổi signer subjects từ semester sang identity khác bị test bắt; chạy trên bản sao tạm, không sửa checkout. Fixture mới dùng identity tổng hợp kể cả nhánh legacy. Doctor local đã chạy qua CLI thật, không đọc session/HTTP. Sau khi thêm rating list v1: full Windows có 391 test mỗi Python 3.11/3.9, 387 đạt/4 skip, exit 0. CI tại `d6d0ee6` đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064482334). Đã sửa assertion ANSI gây fail run trước, không đổi runtime; lỗi tzdata UTC của venv test 3.9 được tái hiện bằng probe riêng rồi cài lại đúng package đã khóa, không đổi dependency.
-Lượt thử live mới 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. Session/thư mục tạm đã dọn. Rating list v1 hiện có fixture, chưa live; 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).
+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). Các command mới v1 và rating list v1 vẫn chưa live; 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).
From 883a7aa2c36fa5a94889979c321e82011532be14 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 17:31:22 +0700
Subject: [PATCH 08/28] =?UTF-8?q?test:=20gi=E1=BB=AF=20l=E1=BB=97i=20live?=
=?UTF-8?q?=20v1=20v=C3=A0=20ghi=20gate=20nghi=E1=BB=87m=20thu=20Phase=206?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Khóa bốn trạng thái 404/201 thành lỗi không refresh/fallback bằng fixture tổng hợp; ghi kết quả live v1/APHL và bằng chứng còn thiếu cho write. Hiệu chỉnh method handshake CLI POST trong tài liệu, không đổi auth/runtime hoặc diễn giải lỗi server thành unsupported.
---
CHANGELOG.md | 1 +
docs/command-endpoints.md | 4 +++-
docs/phase6-coverage.md | 37 ++++++++++++++++++++++++++++++++-----
docs/phase6-write-gates.md | 32 ++++++++++++++++++++++++++++++++
tasks/phase6.md | 6 +++++-
tasks/todo.md | 11 +++++++++++
tests/test_phase6_reads.py | 28 ++++++++++++++++++++++++++++
7 files changed, 112 insertions(+), 7 deletions(-)
create mode 100644 docs/phase6-write-gates.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ced708..d005a91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,7 @@
- Báo cáo Phase 4 ghi nhận các luồng đọc v2 trên HN, gồm login/refresh và JSON/ICS; đây không phải bằng chứng cho mọi campus, tài khoản hoặc route.
- **V1/APHL:** `news` và `other notification` vẫn trả HTTP 200/body 201 với `data: null`; `other fee` vẫn trả HTTP 404 trong lượt chạy lại ngày 19/10/2026. Request đã được đối chiếu với app, nhưng nguyên nhân chưa được xác định. CLI giữ lỗi, không coi là dữ liệu rỗng, hết phiên hoặc route ngừng hỗ trợ trên mọi campus.
+- **Phase 6 v1/APHL, ngày 24/10/2026:** courses và marks summary trả HTTP 404; news search/training trả HTTP 200/body 201, data null. CLI giữ lỗi và không fallback; nguyên nhân chưa rõ. V2/HN đã đọc được các command tương ứng, không thay thế kiểm chứng v1.
- **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 đang bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary và doctor trước khi phát hành; xem coverage Phase 6. Các capability mới có fixture nhưng chưa nghiệm thu live. Rating list student/v1 đã có code/fixture; v2 stub bị chặn. Feedback đầy đủ và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index 2809c2a..1eb389e 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -27,7 +27,7 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| Command/caller | Operation | Method v1 / v2 | URL v1 | URL v2 | Capability và bằng chứng |
|---|---|---|---|---|---|
| `campuses` | `GetAllActiveCampus` | GET / POST | `https://api.fpt.edu.vn/fap/api/MyFAP/GetAllActiveCampus` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetAllActiveCampus` | Public/bootstrap; fixture hai version, live v2/HN 200/200 |
-| `login`, handshake của `refresh`/auth | `AuthenticationByFeId` | GET / POST | `https://api.fpt.edu.vn/fap/api/MyFAP/AuthenticationByFeId` | `https://fap-proxy.fpt.edu.vn/MyFAP/AuthenticationByFeId` | Student/handshake; binding campus/version; live v2/HN 200/200 |
+| `login`, handshake của `refresh`/auth | `AuthenticationByFeId` | POST / POST | `https://api.fpt.edu.vn/fap/api/MyFAP/AuthenticationByFeId` | `https://fap-proxy.fpt.edu.vn/MyFAP/AuthenticationByFeId` | Student/handshake; binding campus/version; live v2/HN 200/200 |
| `semesters`, resolver kỳ | `GetSemester` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetSemester` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetSemester` | Student; fixture và live v1/v2; lượt mới v2/HN 200/200 |
| `schedule`, `schedule --ics` | `GetActivityStudent` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetActivityStudent` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetActivityStudent` | Student/read; live JSON/ICS v2/HN đạt |
| Resolver tuần của `week-timetable` | `GetWeekByDate` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetWeekByDate` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetWeekByDate` | Read/helper; live v2/HN 200/200, data integer |
@@ -51,6 +51,8 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
`version` và `--help` không cần API. `logout` chỉ xóa session local, không phải request logout FEID/FAP. Các command export JSON/ICS/pretty dùng cùng endpoint dữ liệu, không tạo route mới.
+**Hiệu chỉnh method handshake CLI:** `myfap/auth.py` dùng POST JSON token và Bearer cho cả v1/v2; live v1/APHL ngày 24/10 cũng quan sát POST thành công. GET/query là caller legacy trong APK, không phải method CLI hiện tại. Bảng này mô tả CLI; không coi nó là hợp đồng request byte-for-byte của app.
+
### OAuth ngoài API nghiệp vụ
FEID lấy metadata tại `https://feid.fpt.edu.vn/.well-known/openid-configuration`; authorization, token và JWKS dùng endpoint discovery đã kiểm định. Browser thực hiện Authorization Code + PKCE; callback URI không phải endpoint dữ liệu FAP. Không ghi URL authorize/callback thực, code/token/cookie hoặc query có giá trị vào tài liệu. Xem [OAuth và session](oauth-session.md).
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 1686460..b922b94 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -8,20 +8,22 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| Command | Operation | v1 / v2 | Điểm contract quan trọng | Bằng chứng hiện tại |
|---|---|---|---|---|
-| `other balance` | `GetBalance` | Có / Có | Ký v1 bằng roll number; không lookup kỳ; không suy ra currency/nợ/invoice | Fixture hai version; live v2/HN 200/200, v1 chưa live |
-| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture explicit/latest; live v2/HN 200/200, v1 chưa live |
-| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; live v2/HN 200/200, v1 chưa live |
+| `other balance` | `GetBalance` | Có / Có | Ký v1 bằng roll number; không lookup kỳ; không suy ra currency/nợ/invoice | Fixture hai version; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
+| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture explicit/latest; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
+| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; live v2/HN 200/200 |
| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; live v2/HN 200/200 với bound key, data string |
| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; live v2/HN 200/200 với bound key, list rỗng |
| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture parser/refresh; live v2/HN 200/200 với envelope data list |
| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Live v2/HN 200/200, data string; định dạng ảnh chưa xác minh |
-| `rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture CLI/HTTP, chưa live |
+| `rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture và live v1/APHL 200/200, danh sách rỗng |
| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture và live bootstrap v2 200/200; không kiểm tài khoản |
`marks --summary` từ chối `--semester`, `--courseid`, `--pretty` trước auth. `myfap version` vẫn chỉ đọc package version. Doctor không tự lấy version/campus từ session: điều này được ghi rõ trong report để giữ local mode không có tác dụng phụ.
+Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus trả success. Kết quả live v1/APHL có các lỗi 404/201 được giữ nguyên ở phần cuối; không đổi thành unsupported hoặc dữ liệu rỗng.
+
## Policy và phần chưa xác minh
- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
@@ -60,8 +62,33 @@ Sau khi người dùng xác nhận mở login mới, chạy code tại `0e0c01c8
| `info photo` JSON | 200 / 200 | Data string không rỗng; không đọc/in nội dung ảnh, không chứng minh URL/Base64 |
| `logout` | Không HTTP | Session/lock và thư mục tạm đã dọn |
-Không thay request/response hoặc dùng capture credential. Không chạy rating list v1, rating submit, push hoặc feedback ghi trong lượt này. Các command mới trên **v1 vẫn chưa live**, rating list v1 mới có fixture, và schema/ack thao tác ghi còn gate.
+Không thay request/response hoặc dùng capture credential. Không chạy v1 hoặc thao tác ghi trong lượt v2 này; kết quả v1 độc lập ở phần sau. Schema/ack thao tác ghi còn gate.
CI của đúng commit `0e0c01c` đã đạt [11/11 job](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064917612), gồm source và artifact smoke Ubuntu/Windows × Python 3.9/3.11. Đây không phải publish/release.
Kết quả full suite và review không thay cho live ở version/campus khác. Các skip/failure/unknown trong [coverage Phase 4](phase4-coverage.md) và TODO positive fee/survey vẫn giữ nguyên. Chỉ metadata allowlist được lưu; payload và biến nhạy cảm không vào GitHub.
+
+## Live đọc v1/APHL ngày 24/10/2026
+
+Người dùng xác nhận mở browser/context mới, session tạm riêng trên code `ca09b1106ddacca96145a36df0b0668bf15ae52f`. **14 lần command: 10 exit 0, 4 exit 1; harness exit 1**, không sửa response hoặc fallback version. Observer giữ 14 request thuộc 12 operation; một GetSemester chuẩn bị input subjects nằm ngoài observer. Không đưa raw response/query có giá trị hoặc identity vào báo cáo.
+
+| Command/nhóm | HTTP / body | Exit | Kết quả đã lọc |
+|---|---|---:|---|
+| Doctor local | Không HTTP | 0 | JSON hợp lệ, không load session |
+| Login, refresh và student sau refresh | 200 / 200 | 0 | Handshake POST thành công, đọc đối chứng sau refresh đạt |
+| `courses` | 404 / không code FAP | 1 | GetSemester trước đó 200/200; chưa xác định nguyên nhân 404 của GetCourseOfSemester |
+| Subjects theo kỳ | 200 / 200 | 0 | List không rỗng; input kỳ lấy từ API thật |
+| Balance | 200 / 200 | 0 | String không rỗng; không suy giá trị hoặc trạng thái nợ |
+| News search | 200 / 201 | 1 | Data null; chưa có bằng chứng expiry rõ hoặc empty hợp lệ |
+| Transcript | 200 / 200 | 0 | String rỗng; chưa xác minh positive schema |
+| Training | 200 / 201 | 1 | Data null; chưa rõ nguyên nhân |
+| Marks summary | 404 / không code FAP | 1 | Chưa biết nguyên nhân; không thử format XML vì HTTP đã lỗi |
+| Photo JSON | 200 / 200 | 0 | Data null hợp lệ, không ghi nhận có ảnh |
+| Rating list | 200 / 200 | 0 | List rỗng từ endpoint v1 thật, không phải stub v2; chưa có item schema/ID để kiểm submit |
+| Logout | Không HTTP | 0 | Session/lock và thư mục tạm đã dọn |
+
+Đối chiếu code với caller APK: courses/training giữ `semester` chữ thường và signer roll; search ký bằng type; summary v1 `CampusCode`, rollNumber, Authen, không checksum. Chưa tìm được sai lệch request được xác nhận để sửa client. HTTP 404 không tự chứng minh route unsupported trên mọi campus; code 201 không tự chứng minh hết phiên. Các request đọc khác trong cùng lượt vẫn thành công; không biến bốn lỗi thành `[]`, không tự refresh vì 201 không rõ và không gọi v2 ngầm.
+
+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.
diff --git a/docs/phase6-write-gates.md b/docs/phase6-write-gates.md
new file mode 100644
index 0000000..8713e4e
--- /dev/null
+++ b/docs/phase6-write-gates.md
@@ -0,0 +1,32 @@
+# Gate còn mở cho rating, push và feedback
+
+Đây là danh sách bằng chứng cần bổ sung, **không phải các write command đã triển khai**. Không gửi mutation live, đăng ký token hoặc đánh giá thay người dùng để tự lấp khoảng trống. Phase 6 chưa hoàn tất chỉ vì nhóm read đã có code/CI.
+
+## Request đã biết và phần còn thiếu
+
+| Nhóm | Bằng chứng tĩnh đã có | Còn thiếu trước khi mở CLI |
+|---|---|---|
+| `AddRate` student | POST ở cả v1/v2; query rateid/rateValue/rateComment. V1 campusCode/Authen/checksum, signer rateid; v2 CampusCode/Authen và body `{}`. Caller kiểm code 200 rồi lấy data. UI có lựa chọn 1–5. | Positive rating item/kiểu ID và liên kết với binding; ý nghĩa acknowledgment data; validation comment và kết quả submit trùng/không rõ. Lượt live rating list v1 hiện rỗng, không có ID để kiểm submit. |
+| `UpdateTokedevices` student | GET **ghi**, không phải read. V1 CampusCode/Email/tokendevice/checksum ký bằng email; v2 cùng query bỏ checksum và dùng FAP credential hiện tại trong header. | Ack response theo từng version; semantics thay thế/thêm registration; reader token-file an toàn và test confirmation/no-replay. Không có device token thật được thu thập trong lượt này. |
+| Feedback list/form v2 | GET list: CampusCode/rollNumber. GET form thêm feedbackId; facade forward request. | Positive response shape, kiểu/nguồn ID, trạng thái/required fields. Chưa có CLI; không lấy tên route làm schema. |
+| Feedback submit v2 | POST với query CampusCode/rollNumber; body được caller chuyển nguyên trạng. | Schema câu trả lời, quan hệ với form, required/choices/types, ack và duplicate-submit. Không mở generic `--input` nhận JSON tùy ý. |
+| Donor/employee, donor push, server-code exchange | Inventory có caller/nhánh riêng; donor login v2 có stub, server-code exchange còn flag tắt trong app. | Luồng auth/capability và schema riêng. Không dùng student binding hoặc giả định request không credential được phép. |
+
+Nguồn nội bộ workspace: `analysis/modules/module_550.js:484–521`, `module_599.js:458–483,601–678`, rating UI `module_2597.js:101–129`, push caller `762_fcmService.js:44–53`. Không sao chép khóa, bootstrap literal hoặc dữ liệu tài khoản từ các nguồn này vào repo.
+
+## Không suy quá bằng chứng
+
+- Code 200 là điều kiện transport của AddRate đã thấy trong caller; **ý nghĩa data và xác nhận nghiệp vụ** chưa được kiểm. Không nói hoàn toàn không biết ack transport, cũng không suy code 200 bảo đảm mọi thay đổi đã được ghi đúng.
+- UI gợi ý comment cho rating dưới 4, nhưng bản decompile không thể hiện chắc chắn việc dừng sau cảnh báo. Không ghi đó là ràng buộc backend đã xác minh.
+- HTTP GET của push không chứng minh idempotent. Timeout hoặc mất response có thể là kết quả không rõ; tuyệt đối không refresh-and-replay hoặc khuyên retry mù.
+- Rating list v2 là stub nên giữ unsupported. Rating list v1 là endpoint thật trả list rỗng trong lượt live, không cung cấp bằng chứng cho kiểu item/ID hoặc khả năng submit.
+
+## Cách bổ sung bằng chứng mà không đưa PII lên GitHub
+
+1. Với read/list/form, dùng browser và session tạm được cho phép; chọn ID chỉ từ response thật thuộc binding hiện tại, không đoán ID hoặc role.
+2. Với write, cần người dùng xác nhận **thao tác cụ thể và input cụ thể** trước; có thể đối chiếu một thao tác người dùng thực hiện trên app, không tự tạo dữ liệu ghi để thử.
+3. Payload/token chỉ xử lý tại máy. Báo cáo chỉ giữ operation/method/HTTP/body code, tên trường/kiểu dữ liệu và kết quả xác minh, không giá trị ID, comment, token, identity, ảnh hay câu trả lời.
+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).
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 27eec61..c6c04cf 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -55,6 +55,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## 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.
+
- [x] **Rating list:** `rating list` student/v1 có code và fixture envelope/query; chưa suy kiểu ID/schema item hoặc xác nhận live. V2 là stub nên unsupported trước load session/HTTP, không gọi v1 ngầm hoặc trả `[]` giả.
- [ ] **`rating submit --input`:** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
- [ ] **`push register --token-file`:** chốt contract student; `UpdateTokedevices` là **GET ghi**, v1 ký bằng **email**. Token chỉ đọc từ regular file có giới hạn, kiểm encoding/newline và symlink/reparse/path swap; không token trên argv/preview/log/error. Campus/identity lấy từ session đã bind.
@@ -88,4 +90,6 @@ 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). Các command mới v1 và rating list v1 vẫn chưa live; 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](../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).
+
+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ũ.
diff --git a/tasks/todo.md b/tasks/todo.md
index 684fa56..32dc550 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -44,3 +44,14 @@ Checklist, tiêu chí và gate bằng chứng nằm tại [phase6.md](phase6.md)
- [ ] 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.
- [ ] 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:
+
+- [ ] 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ử.
+- [ ] Xác định nguyên nhân SearchNews HTTP 200/body 201, data null; không coi là hết phiên hoặc empty hợp lệ.
+- [ ] Xác định nguyên nhân GetDiemphongtrao HTTP 200/body 201, data null; không bỏ lỗi hoặc fallback v2.
+
+Cùng lượt, subjects/balance/rating list đọc được và student sau refresh đạt 200/200. Transcript rỗng, photo null và rating list rỗng không xác nhận positive schema hoặc ID hợp lệ cho submit. Session/lock/thư mục tạm đã dọn; chỉ metadata được ghi, không raw response/identity/credential.
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index b3e676e..6c77d7a 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -353,5 +353,33 @@ def test_rating_list_v2_stub_is_rejected_before_session_load_or_http(self):
request.assert_not_called()
+class V1ObservedFailureTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_http_404_and_unexplained_201_remain_failures_without_refresh_or_fallback(self):
+ # Only status/shape from live; every input and session here is synthetic.
+ for command, operation, status, payload, message in (
+ (["courses", "--semester", "FAKE_TERM"], "GetCourseOfSemester", 404, None, "HTTP 404"),
+ (["marks", "--summary"], "GetSemesterMark", 404, None, "HTTP 404"),
+ (["news", "--search", "synthetic"], "SearchNews", 200, {"code": 201, "data": None}, "201"),
+ (["training", "--semester", "FAKE_TERM"], "GetDiemphongtrao", 200, {"code": 201, "data": None}, "201"),
+ ):
+ with self.subTest(operation=operation):
+ self.save_session("v1")
+ before = self.path.read_bytes()
+ with patch("requests.Session.request", return_value=response(payload, status)) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session") as refresh:
+ result = self.runner.invoke(app, ["--config", str(self.path), *command, "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertIn(message, Text.from_ansi(result.stderr).plain)
+ request.assert_called_once()
+ self.assertEqual(urlsplit(request.call_args.args[1]).netloc, "api.fpt.edu.vn")
+ self.assertTrue(request.call_args.args[1].endswith('/' + operation))
+ refresh.assert_not_called()
+ self.assertEqual(self.path.read_bytes(), before)
+
+
if __name__ == "__main__":
unittest.main()
From c56bd61cc0f0813e2ee1d74f85129243e33f49da Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 17:53:20 +0700
Subject: [PATCH 09/28] =?UTF-8?q?feat:=20chuy=E1=BB=83n=20training=20v?=
=?UTF-8?q?=C3=A0=20nh=C3=B3m=20rating=20v=C3=A0o=20other?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Dùng other training và other rating list, bỏ các command root cũ. Giữ endpoint/auth/retry/capability; bổ sung regression option kế thừa lồng ba cấp và help UTF-8/cp1252, cập nhật ví dụ và tài liệu.
---
CHANGELOG.md | 2 ++
README.md | 6 ++---
docs/phase6-coverage.md | 6 +++--
myfap/cli.py | 4 ++--
tasks/phase6.md | 6 ++---
tests/test_cli_output.py | 3 ++-
tests/test_phase6_reads.py | 46 ++++++++++++++++++++++++++++++++++----
7 files changed, 58 insertions(+), 15 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d005a91..4a14e1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
### API và dữ liệu
+- 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.
+
- Giữ API v1 làm mặc định. API v2 chỉ được chọn bằng `--api-version v2` hoặc binding của session; không tự chuyển version khi gặp lỗi.
- Bổ sung adapter v2 cho các lệnh đọc hiện có: kỳ học, lịch học/lịch tuần, điểm, lịch thi, điểm danh, đơn từ, news, thông tin sinh viên/campus, học phí, môn học, thông báo và kiểm tra feedback/profile. Survey tiếp tục dùng dịch vụ và chữ ký riêng.
- Coi ID kỳ học là opaque, chọn kỳ mới nhất theo `startDate` và giữ thứ tự server khi ngày trùng nhau. Query dùng đúng tên trường theo từng operation.
diff --git a/README.md b/README.md
index 205df61..0d1efd6 100644
--- a/README.md
+++ b/README.md
@@ -58,15 +58,15 @@ myfap other subjects --semester Fall2026 --stdout
myfap other balance --stdout
myfap news --search "lịch thi" --type 1 --stdout
myfap transcript --stdout
-myfap training --semester Fall2026 --stdout
+myfap other training --semester Fall2026 --stdout
myfap marks --summary --stdout
myfap info photo --stdout
-myfap rating list --api-version v1 --stdout
+myfap other rating list --api-version v1 --stdout
myfap doctor --stdout
myfap doctor --api-version v2 --online --stdout
```
-`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. `rating list` chỉ hỗ trợ student/v1; v2 là stub và bị chặn. Khác với các lệnh đọc này, rating submit/push/feedback submit còn có gate riêng và chưa được mở.
+`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. `other rating list` chỉ hỗ trợ student/v1; v2 là stub và bị chặn. Khác với các lệnh đọc này, rating submit/push/feedback submit còn có gate riêng và chưa được mở.
## Thông tin thêm
- [Chọn API v1 hoặc v2](https://github.com/WindowScary321/myfap-api-cli/blob/main/docs/api-versions.md): v1 vẫn mặc định; v2 hỗ trợ các command đọc hiện có trong Phase 4.
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index b922b94..e5b1c52 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -13,10 +13,10 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; live v2/HN 200/200 |
| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; live v2/HN 200/200 với bound key, data string |
-| `training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; live v2/HN 200/200 với bound key, list rỗng |
+| `other training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; live v2/HN 200/200 với bound key, list rỗng |
| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture parser/refresh; live v2/HN 200/200 với envelope data list |
| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Live v2/HN 200/200, data string; định dạng ảnh chưa xác minh |
-| `rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture và live v1/APHL 200/200, danh sách rỗng |
+| `other rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture và live v1/APHL 200/200, danh sách rỗng |
| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture và live bootstrap v2 200/200; không kiểm tài khoản |
@@ -24,6 +24,8 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus trả success. Kết quả live v1/APHL có các lỗi 404/201 được giữ nguyên ở phần cuối; không đổi thành unsupported hoặc dữ liệu rỗng.
+**Namespace hiện tại:** training và nhóm rating nằm trong `other`: `myfap other training`, `myfap other rating list`. Không giữ alias ở root. Các lượt live lịch sử bên dưới chạy trước khi đổi namespace nên giữ nguyên nhãn command cũ; endpoint/callback và capability không đổi. Lượt đổi namespace chỉ kiểm CLI/help/HTTP giả, không chạy lại login/FAP. Focused FORCE_COLOR=1 đạt 17/17; full Windows Python 3.9 và 3.11 mỗi bản 394 test, 390 đạt/4 skip, exit 0. Help mới được kiểm cả UTF-8/cp1252 ở group lồng ba cấp; option tại leaf vẫn override root/group.
+
## Policy và phần chưa xác minh
- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
diff --git a/myfap/cli.py b/myfap/cli.py
index d0125c0..381ea49 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -91,7 +91,7 @@ def inherit(command):
app.add_typer(other_app, name="other")
rating_app = typer.Typer(help="Đánh giá dịch vụ; list hiện chỉ hỗ trợ API v1")
-app.add_typer(rating_app, name="rating")
+other_app.add_typer(rating_app, name="rating")
state = {
"campus": None,
@@ -362,7 +362,7 @@ def transcript(
raise typer.Exit(code=1)
-@app.command()
+@other_app.command("training")
def training(
semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
diff --git a/tasks/phase6.md b/tasks/phase6.md
index c6c04cf..b90aac5 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -30,7 +30,7 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## 2. Transcript, training và marks summary
- [x] **`transcript` → `AcademicTranscript`:** hỗ trợ theo contract cả v1/v2, không lookup kỳ; chưa thêm formatter nghiệp vụ khi schema data chưa được xác minh.
-- [x] **`training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
+- [x] **`other training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
- [x] **`marks --summary` → `GetSemesterMark`:** không lookup kỳ hoặc thêm query semester. V1 dùng đúng `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 giữ query `Authen` mới sau refresh.
- [ ] Từ chối tổ hợp summary với `--courseid`/`--pretty`; nếu `--semester` không áp dụng thì báo lỗi, không âm thầm bỏ qua.
- [ ] Reader riêng cho summary kiểm HTTP/App Check/expiry trước khi đọc raw array/envelope/text. Chỉ parse dạng đã có bằng chứng, có giới hạn; malformed/unknown phải báo payload error, không cắt tùy tiện giữa dấu ngoặc rồi trả success.
@@ -57,8 +57,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
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.
-- [x] **Rating list:** `rating list` student/v1 có code và fixture envelope/query; chưa suy kiểu ID/schema item hoặc xác nhận live. V2 là stub nên unsupported trước load session/HTTP, không gọi v1 ngầm hoặc trả `[]` giả.
-- [ ] **`rating submit --input`:** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
+- [x] **Rating list:** `other rating list` student/v1 có code và fixture envelope/query; lượt live trước đổi namespace trả list rỗng, chưa suy kiểu ID/schema item hoặc positive schema. V2 là stub nên unsupported trước load session/HTTP, không gọi v1 ngầm hoặc trả `[]` giả.
+- [ ] **`other rating submit --input` (dự kiến, chưa mở):** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
- [ ] **`push register --token-file`:** chốt contract student; `UpdateTokedevices` là **GET ghi**, v1 ký bằng **email**. Token chỉ đọc từ regular file có giới hạn, kiểm encoding/newline và symlink/reparse/path swap; không token trên argv/preview/log/error. Campus/identity lấy từ session đã bind.
- [ ] Đường ghi tách khỏi read retry, không thêm AddRate/push vào read allowlist để cấp credential. Trình tự: validate → capability → preview không bí mật → confirmation/`--yes` → auth → một lần gửi. `--yes` không bỏ validation.
- [ ] Test invalid input/cancel/noninteractive thiếu xác nhận gây zero auth/network; 401/App Check/timeout/5xx hoặc unknown outcome không replay.
diff --git a/tests/test_cli_output.py b/tests/test_cli_output.py
index e89e2b5..7f214fd 100644
--- a/tests/test_cli_output.py
+++ b/tests/test_cli_output.py
@@ -106,7 +106,8 @@ def test_root_group_and_command_help_preserve_unicode_with_legacy_stdout(self):
with patch("myfap.cli.get_auth", side_effect=AssertionError("help must not load auth")), patch("requests.Session.request", side_effect=AssertionError("help must not call HTTP")):
app()
"""
- for command in ([], ["info"], ["info", "student"], ["other", "survey"], ["schedule"]):
+ for command in ([], ["info"], ["info", "student"], ["other", "survey"], ["schedule"],
+ ["other", "training"], ["other", "rating"], ["other", "rating", "list"]):
for encoding, utf8 in (("cp1252:strict", "0"), ("utf-8", "1")):
with self.subTest(command=command, encoding=encoding):
result = subprocess.run(
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 6c77d7a..2467764 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -272,7 +272,7 @@ def reply(method, url, **kwargs):
return response({"code": 200, "data": [{"semesterName": "Fall2026", "startDate": "2026-09-01"}]})
return response(payload)
with patch("requests.Session.request", side_effect=reply) as request:
- result = self.runner.invoke(app, ["--config", str(self.path), "training", "--stdout"])
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "training", "--stdout"])
self.assertEqual(result.exit_code, 0, result.output)
self.assertEqual(json.loads(result.stdout), payload)
self.assertEqual([call.args[1].rsplit('/', 1)[-1] for call in request.call_args_list],
@@ -332,7 +332,7 @@ def test_rating_list_v1_uses_read_contract_without_semester(self):
payload = {"code": 200, "data": [{"synthetic": "rating item"}]}
with patch("requests.Session.request", return_value=response(payload)) as request, \
patch("myfap.api.create_checksum", return_value="SYNTHETIC_RATE_LIST") as checksum:
- result = self.runner.invoke(app, ["rating", "list", "--config", str(self.path), "--stdout"])
+ result = self.runner.invoke(app, ["other", "rating", "list", "--config", str(self.path), "--stdout"])
self.assertEqual(result.exit_code, 0, result.output)
self.assertEqual(json.loads(result.stdout), payload)
request.assert_called_once()
@@ -345,7 +345,7 @@ def test_rating_list_v1_uses_read_contract_without_semester(self):
def test_rating_list_v2_stub_is_rejected_before_session_load_or_http(self):
self.save_session("v2")
with patch("myfap.auth.MyFapAuth.load_session") as load, patch("requests.Session.request") as request:
- result = self.runner.invoke(app, ["--config", str(self.path), "rating", "list", "--stdout"])
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "rating", "list", "--stdout"])
self.assertEqual(result.exit_code, 1)
self.assertEqual(result.stdout, "")
self.assertIn("GetStudentRate", result.stderr)
@@ -363,7 +363,7 @@ def test_http_404_and_unexplained_201_remain_failures_without_refresh_or_fallbac
(["courses", "--semester", "FAKE_TERM"], "GetCourseOfSemester", 404, None, "HTTP 404"),
(["marks", "--summary"], "GetSemesterMark", 404, None, "HTTP 404"),
(["news", "--search", "synthetic"], "SearchNews", 200, {"code": 201, "data": None}, "201"),
- (["training", "--semester", "FAKE_TERM"], "GetDiemphongtrao", 200, {"code": 201, "data": None}, "201"),
+ (["other", "training", "--semester", "FAKE_TERM"], "GetDiemphongtrao", 200, {"code": 201, "data": None}, "201"),
):
with self.subTest(operation=operation):
self.save_session("v1")
@@ -381,5 +381,43 @@ def test_http_404_and_unexplained_201_remain_failures_without_refresh_or_fallbac
self.assertEqual(self.path.read_bytes(), before)
+class OtherCommandLayoutTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_training_and_rating_inherit_options_at_nested_leaf(self):
+ self.save_session("v1")
+ for command, operation in (
+ (["other", "--api-version", "v2", "training", "--semester", "FAKE_TERM"], "GetDiemphongtrao"),
+ (["other", "--api-version", "v2", "rating", "--api-version", "v2", "list"], "GetStudentRate"),
+ ):
+ with self.subTest(operation=operation), patch("requests.Session.request", return_value=response({"code": 200, "data": []})) as request:
+ result = self.runner.invoke(app, ["--api-version", "v2", *command,
+ "--config", str(self.path), "--api-version", "v1", "--timeout", "31", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), {"code": 200, "data": []})
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith('/' + operation))
+ self.assertEqual(urlsplit(request.call_args.args[1]).netloc, "api.fpt.edu.vn")
+ self.assertEqual(request.call_args.kwargs["timeout"], 31)
+
+ def test_new_help_paths_work_and_old_root_commands_are_absent_without_auth(self):
+ with patch("myfap.cli.get_auth") as auth, patch("requests.Session.request") as request:
+ for command in (["other"], ["other", "training"], ["other", "rating"], ["other", "rating", "list"]):
+ with self.subTest(command=command):
+ result = self.runner.invoke(app, [*command, "--help"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ result = self.runner.invoke(app, ["other", "--help"])
+ text = Text.from_ansi(result.stdout).plain
+ self.assertIn("training", text)
+ self.assertIn("rating", text)
+ for command in (["training"], ["rating", "list"]):
+ with self.subTest(old_command=command):
+ result = self.runner.invoke(app, [*command, "--help"])
+ self.assertEqual(result.exit_code, 2)
+ auth.assert_not_called()
+ request.assert_not_called()
+
+
if __name__ == "__main__":
unittest.main()
From 873603b5bb9c5474cdbad1dc5bf7ef6023fc7138 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 20:21:50 +0700
Subject: [PATCH 10/28] =?UTF-8?q?docs:=20ghi=20thao=20t=C3=A1c=20ghi=20rat?=
=?UTF-8?q?ing/push/feedback=20ch=C6=B0a=20th=E1=BB=83=20x=C3=A1c=20minh?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
tasks/todo.md | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/tasks/todo.md b/tasks/todo.md
index 32dc550..cfecfcf 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -55,3 +55,12 @@ Các command đã chạy thật trên v1/APHL sau login mới; chi tiết tại
- [ ] Xác định nguyên nhân GetDiemphongtrao HTTP 200/body 201, data null; không bỏ lỗi hoặc fallback v2.
Cùng lượt, subjects/balance/rating list đọc được và student sau refresh đạt 200/200. Transcript rỗng, photo null và rating list rỗng không xác nhận positive schema hoặc ID hợp lệ cho submit. Session/lock/thư mục tạm đã dọn; chỉ metadata được ghi, không raw response/identity/credential.
+
+## Thao tác ghi rating/push/feedback vẫn chưa mở
+
+Theo đánh giá của người dùng ngày 24/10/2026, **tài khoản hiện tại không thể xác minh** các thao tác ghi này: rating list v1 trả danh sách rỗng (không có rateid/item để đối chiếu `AddRate`), không có feedback đang mở để thu form/ack. Không cố tình thử ghi để tạo dữ liệu, không coi đây là route lỗi và không mở generic submit.
+
+- [ ] Khi có tài khoản hoặc dữ liệu phù hợp (rating đang mở, feedback đang mở), thu thập input schema và ack nghiệp vụ 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.
+- [ ] `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 như [phase6.md](phase6.md) mục 4–5; việc chưa xác minh được không tự đóng cũng không nới gate.
From c34d7ed9502b7d6eb8c7c39511416048128bd4d9 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 21:48:41 +0700
Subject: [PATCH 11/28] =?UTF-8?q?test:=20nghi=E1=BB=87m=20thu=20nh=C3=B3m?=
=?UTF-8?q?=20=C4=91=E1=BB=8Dc=20m=E1=BB=A5c=201=20t=E1=BA=A1i=20seam=20CL?=
=?UTF-8?q?I?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/phase6-coverage.md | 2 +
tasks/phase6.md | 6 +-
tests/test_phase6_reads.py | 144 +++++++++++++++++++++++++++++++++++++
3 files changed, 150 insertions(+), 2 deletions(-)
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index e5b1c52..96d6bd6 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -41,6 +41,8 @@ Test mới dùng CLI/auth/client thật với session tổng hợp và HTTP gi
Sau rating list, full local Windows có 391 test trên mỗi Python 3.11/3.9, 387 đạt/4 skip, exit 0. Venv Python 3.9 từng lỗi tzdata UTC độc lập với command; cài lại đúng version khóa trong venv test đã phục hồi probe UTC và toàn suite, không đổi lockfile.
+Nghiệm thu nhóm mục 1 (24/10/2026): `ReadSliceAcceptanceTests` bổ sung 5 test tại seam CLI cho cả bốn lát cắt đọc trên hai version — header v2 đúng contract client (`ClientCode`, `CampusCode`, `Authorization` Bearer, `Checksum` dạng `chữ ký:timestamp giây`, GET không body/`Content-Type`), expiry retry đúng một lần với credential mới rồi dừng, và App Check/timeout/HTTP 503/malformed giữ một request, không refresh/fallback, stdout rỗng khi lỗi. Test GREEN ngay vì xác nhận hành vi đã có; focused `tests.test_phase6_reads` 22/22, full Windows 399 test, 395 đạt/4 skip, exit 0.
+
CI run [40064482334](https://github.com/WindowScary321/myfap-api-cli/actions/runs/40064482334) tại `d6d0ee63a7c052bf94112426323ed06b4ca05be6` đạt **11/11 job**, gồm source và artifact smoke Ubuntu/Windows × Python 3.9/3.11. Run trước đó thất bại vì assertion đọc tên option trên chuỗi ANSI; đã tái hiện FORCE_COLOR=1 rồi dùng Text.from_ansi theo test help sẵn có, giữ nguyên kiểm tra nội dung và no-HTTP.
Đã thử mở browser/context mới để kiểm live v2/HN trong lượt này: doctor local exit 0 với JSON hợp lệ và không HTTP; login exit 1, chưa có response FAP được quan sát. Các command xác thực mới sau login **chưa chạy**, không ghi chúng là live pass hoặc live-failed endpoint. Logout exit 0; session và thư mục tạm đã dọn. Không suy nguyên nhân lỗi login từ việc không có response.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index b90aac5..c06ec50 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -24,8 +24,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
- [x] **`news --search` → `SearchNews`:** không có search vẫn dùng `GetTop10News`; từ chối search rỗng trước auth, truyền `type`/`keysearch` qua params và v1 ký bằng type. Kiểm Unicode và ký tự reserved, không nối query thủ công.
**Nghiệm thu nhóm:**
-- [ ] Test tại public seam CLI và biên HTTP chứng minh method/path/query/header/body đúng, stdout sạch, binding và common-option precedence được giữ.
-- [ ] Có success/empty/not-found phù hợp, malformed, expiry, App Check, timeout/5xx và không fallback; focused tests rồi regression hiện có đạt.
+- [x] Test tại public seam CLI và biên HTTP chứng minh method/path/query/header/body đúng, stdout sạch, binding và common-option precedence được giữ.
+- [x] Có success/empty/not-found phù hợp, malformed, expiry, App Check, timeout/5xx và không fallback; focused tests rồi regression hiện có đạt.
## 2. Transcript, training và marks summary
@@ -93,3 +93,5 @@ Lượt thử live đầu chưa hoàn tất login (exit 1, chưa có response FA
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).
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ũ.
+
+Nghiệm thu nhóm mục 1 hoàn tất ngày 24/10/2026 bằng lớp `ReadSliceAcceptanceTests` trong tests/test_phase6_reads.py: 5 test chạy tại seam CLI cho cả bốn lát cắt đọc (balance, courses, subjects theo kỳ, news search) trên hai version. Phần header contract v2 kiểm `ClientCode`, `CampusCode`, `Authorization` Bearer, `Checksum` dạng chữ ký base64 + dấu hai chấm + timestamp giây decimal, GET không có `json` body hoặc `Content-Type`. Ma trận lỗi gồm expiry retry đúng một lần với credential mới (v1 body 201 `Token invalid`; v2 body 401 và HTTP 401, Checksum đổi theo key mới, phần query còn lại giữ nguyên), dừng sau lần expiry thứ hai, và App Check/timeout/HTTP 503/malformed giữ đúng một request, không refresh/fallback, stdout rỗng khi lỗi, không lộ sentinel hay credential. Test đạt GREEN ngay vì xác nhận hành vi đã triển khai từ các commit trước, không có behavior mới cần bước RED. Focused `tests.test_phase6_reads` đạt 22/22; full suite 399 test, 395 đạt/4 skip, exit 0 trên Windows Python 3.11.
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 2467764..150c34a 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -381,6 +381,150 @@ def test_http_404_and_unexplained_201_remain_failures_without_refresh_or_fallbac
self.assertEqual(self.path.read_bytes(), before)
+class ReadSliceAcceptanceTests(unittest.TestCase):
+ """Nghiệm thu nhóm mục 1: header contract và ma trận lỗi tại seam CLI."""
+
+ COMMANDS = (
+ (["other", "balance"], "GetBalance"),
+ (["courses", "--semester", "FAKE_TERM"], "GetCourseOfSemester"),
+ (["other", "subjects", "--semester", "FAKE_TERM"], "GetSubjectBySemester"),
+ (["news", "--search", "synthetic"], "SearchNews"),
+ )
+
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_v2_headers_carry_client_contract_and_get_has_no_body(self):
+ self.save_session("v2")
+ for command, operation in self.COMMANDS:
+ with self.subTest(operation=operation):
+ with patch("requests.Session.request", return_value=response({"code": 200, "data": []})) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), *command, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), {"code": 200, "data": []})
+ self.assertEqual(request.call_args.args[0], "GET")
+ self.assertTrue(request.call_args.args[1].endswith("/" + operation))
+ headers = request.call_args.kwargs["headers"]
+ self.assertEqual(headers["ClientCode"], "MyFAP")
+ self.assertEqual(headers["CampusCode"], "TEST")
+ self.assertEqual(headers["Authorization"], "Bearer FAKE_FAP_KEY")
+ signature, separator, timestamp = headers["Checksum"].partition(":")
+ self.assertEqual(separator, ":")
+ self.assertTrue(signature and signature.isascii())
+ self.assertTrue(timestamp and timestamp.isascii() and timestamp.isdecimal())
+ self.assertNotIn("json", request.call_args.kwargs)
+ self.assertNotIn("Content-Type", headers)
+
+ def test_expiry_retries_once_with_fresh_credential_at_cli_seam(self):
+ signals = (
+ ("v1", {"code": 201, "message": "Token invalid", "data": None}, 200),
+ ("v2", {"code": 401, "data": None}, 200),
+ ("v2", {"code": 200, "data": []}, 401),
+ )
+ for command, operation in self.COMMANDS:
+ for version, expired, status in signals:
+ with self.subTest(operation=operation, version=version, status=status):
+ self.save_session(version)
+ original = self.path.read_bytes()
+
+ def refresh(auth):
+ auth.authen_key = "FAKE_NEW_KEY"
+ return True
+
+ with patch("requests.Session.request",
+ side_effect=[response(expired, status), response({"code": 200, "data": []})]) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session", autospec=True, side_effect=refresh) as rotation:
+ result = self.runner.invoke(app, ["--config", str(self.path), *command, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), {"code": 200, "data": []})
+ self.assertEqual(request.call_count, 2)
+ rotation.assert_called_once()
+ first, second = request.call_args_list
+ self.assertTrue(first.args[1].endswith("/" + operation))
+ self.assertTrue(second.args[1].endswith("/" + operation))
+ if version == "v1":
+ self.assertEqual(first.kwargs["params"]["Authen"], "FAKE_FAP_KEY")
+ self.assertEqual(second.kwargs["params"]["Authen"], "FAKE_NEW_KEY")
+ else:
+ self.assertEqual(first.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+ self.assertEqual(second.kwargs["headers"]["Authorization"], "Bearer FAKE_NEW_KEY")
+ self.assertNotEqual(first.kwargs["headers"]["Checksum"], second.kwargs["headers"]["Checksum"])
+ self.assertEqual(
+ {key: value for key, value in first.kwargs["params"].items() if key != "Authen"},
+ {key: value for key, value in second.kwargs["params"].items() if key != "Authen"},
+ )
+ self.assertEqual(self.path.read_bytes(), original)
+ self.assertNotIn("FAKE_FAP_KEY", result.stdout + result.stderr)
+
+ def test_second_expiry_stops_after_single_retry(self):
+ signals = (
+ ("v1", {"code": 201, "message": "Token invalid", "data": None}, 200),
+ ("v2", {"code": 401, "data": None}, 200),
+ )
+ for version, expired, status in signals:
+ with self.subTest(version=version):
+ self.save_session(version)
+
+ def refresh(auth):
+ auth.authen_key = "FAKE_NEW_KEY"
+ return True
+
+ with patch("requests.Session.request",
+ side_effect=[response(expired, status), response(expired, status)]) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session", autospec=True, side_effect=refresh) as rotation:
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "balance", "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertEqual(request.call_count, 2)
+ rotation.assert_called_once()
+
+ def test_app_check_timeout_and_5xx_fail_once_without_refresh_or_fallback(self):
+ import requests as requests_module
+
+ failures = (
+ (response({"code": "APP_CHECK_FAILED"}), "APP_CHECK_FAILED"),
+ (requests_module.Timeout("PRIVATE_SENTINEL_URL"), "thử lại sau"),
+ (response(None, 503), "HTTP 503"),
+ )
+ for version in ("v1", "v2"):
+ for command, operation in self.COMMANDS:
+ for failure, message in failures:
+ with self.subTest(version=version, operation=operation, message=message):
+ self.save_session(version)
+ before = self.path.read_bytes()
+ with patch("requests.Session.request", side_effect=[failure]) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session") as refresh:
+ result = self.runner.invoke(app, ["--config", str(self.path), *command, "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertIn(message, Text.from_ansi(result.stderr).plain)
+ self.assertNotIn("PRIVATE_SENTINEL_URL", Text.from_ansi(result.stderr).plain)
+ self.assertEqual(request.call_count, 1)
+ self.assertTrue(request.call_args.args[1].endswith("/" + operation))
+ refresh.assert_not_called()
+ self.assertEqual(self.path.read_bytes(), before)
+
+ def test_malformed_payload_is_reported_without_retry_or_refresh(self):
+ cases = (
+ (response("invalid-envelope"), "phải có code và data"),
+ (response({"code": "ok", "data": []}), "không hợp lệ"),
+ )
+ for version in ("v1", "v2"):
+ for command, operation in self.COMMANDS:
+ for failure, message in cases:
+ with self.subTest(version=version, operation=operation, message=message):
+ self.save_session(version)
+ with patch("requests.Session.request", side_effect=[failure]) as request, \
+ patch("myfap.auth.MyFapAuth.refresh_session") as refresh:
+ result = self.runner.invoke(app, ["--config", str(self.path), *command, "--stdout"])
+ self.assertEqual(result.exit_code, 1)
+ self.assertEqual(result.stdout, "")
+ self.assertIn(message, Text.from_ansi(result.stderr).plain)
+ self.assertEqual(request.call_count, 1)
+ self.assertTrue(request.call_args.args[1].endswith("/" + operation))
+ refresh.assert_not_called()
+
+
class OtherCommandLayoutTests(unittest.TestCase):
setUp = BalanceCommandTests.setUp
save_session = BalanceCommandTests.save_session
From c489d954f5e5c648bd6dda52abf369cd80de398a Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:10:44 +0700
Subject: [PATCH 12/28] =?UTF-8?q?docs:=20nghi=E1=BB=87m=20thu=20nh=C3=B3m?=
=?UTF-8?q?=20m=E1=BB=A5c=202=20v=C3=A0=20ch=E1=BB=91t=20credential=20v2?=
=?UTF-8?q?=20b=E1=BA=B1ng=20bytecode?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/phase6-coverage.md | 15 ++++++++++++++-
tasks/phase6.md | 12 +++++++-----
2 files changed, 21 insertions(+), 6 deletions(-)
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 96d6bd6..ae87e50 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -29,7 +29,7 @@ Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus
## Policy và phần chưa xác minh
- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
-- Với transcript/training/summary, caller JS phục dựng v2 không truyền credential tường minh như một số read khác. CLI giữ **policy authenticated read dùng FAP key của binding hiện tại**, không thêm anonymous request hoặc fallback credential rỗng. Lượt live v2/HN ngày 24/10 đã đọc thành công bằng policy này; không chứng minh server bắt buộc Bearer, không xác minh nhánh credential rỗng của APK hoặc parity byte-for-byte.
+- 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 — và đã đọc thành công HTTP/body 200 ở lượt 24/10 lẫn lượt nghiệm thu mục 2; không chứng minh server bắt buộc Bearer và không tuyên bố parity byte-for-byte với app.
- 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**.
@@ -96,3 +96,16 @@ 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.
+
+## Live nghiệm thu mục 2 (24/10/2026, v2/HN)
+
+Chạy trên máy cá nhân bằng session thật của người dùng ở code `c34d7ed`; output raw chỉ xử lý cục bộ trên máy đó và đã xóa sau khi trích metadata, không đưa lên repository/GitHub. Không thay request/response; không chạy thao tác ghi.
+
+| Command/nhóm | HTTP / body code | Metadata đã lọc |
+|---|---|---|
+| `info student` (đối chứng) | 200 / 200 | List 1 phần tử; các trường identity dạng chuỗi như shape fixture tổng hợp |
+| `transcript` | 200 / 200 | Data chuỗi ~10,5 KB là mảnh HTML bảng: 53 `` bao; formatter nghiệp vụ chưa tích hợp |
+| `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.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index c06ec50..017d096 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -32,13 +32,13 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
- [x] **`transcript` → `AcademicTranscript`:** hỗ trợ theo contract cả v1/v2, không lookup kỳ; chưa thêm formatter nghiệp vụ khi schema data chưa được xác minh.
- [x] **`other training --semester` → `GetDiemphongtrao`:** query `semester` chữ thường, dùng resolver khi thiếu kỳ; giữ bound credential phù hợp.
- [x] **`marks --summary` → `GetSemesterMark`:** không lookup kỳ hoặc thêm query semester. V1 dùng đúng `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 giữ query `Authen` mới sau refresh.
-- [ ] Từ chối tổ hợp summary với `--courseid`/`--pretty`; nếu `--semester` không áp dụng thì báo lỗi, không âm thầm bỏ qua.
-- [ ] Reader riêng cho summary kiểm HTTP/App Check/expiry trước khi đọc raw array/envelope/text. Chỉ parse dạng đã có bằng chứng, có giới hạn; malformed/unknown phải báo payload error, không cắt tùy tiện giữa dấu ngoặc rồi trả success.
-- [ ] Chốt khác biệt credential v2 ở các caller decompile của transcript/training/summary bằng bytecode/contract và kiểm đọc. Không mặc định sao chép credential rỗng, thử unauth rồi fallback hoặc nới reader chung cho mọi endpoint.
+- [x] Từ chối tổ hợp summary với `--courseid`/`--pretty`; nếu `--semester` không áp dụng thì báo lỗi, không âm thầm bỏ qua.
+- [x] Reader riêng cho summary kiểm HTTP/App Check/expiry trước khi đọc raw array/envelope/text. Chỉ parse dạng đã có bằng chứng, có giới hạn; malformed/unknown phải báo payload error, không cắt tùy tiện giữa dấu ngoặc rồi trả success.
+- [x] Chốt khác biệt credential v2 ở các caller decompile của transcript/training/summary bằng bytecode/contract và kiểm đọc. Không mặc định sao chép credential rỗng, thử unauth rồi fallback hoặc nới reader chung cho mọi endpoint.
**Nghiệm thu nhóm:**
-- [ ] Test exact casing, no-semester/no-checksum, signing identity và dựng Authen mới sau refresh; giữ nguyên command marks cũ.
-- [ ] Fixture được ghi rõ synthetic; các schema hoặc credential chưa live xác nhận tiếp tục có nhãn unverified.
+- [x] Test exact casing, no-semester/no-checksum, signing identity và dựng Authen mới sau refresh; giữ nguyên command marks cũ.
+- [x] Fixture được ghi rõ synthetic; các schema hoặc credential chưa live xác nhận tiếp tục có nhãn unverified.
## 3. Photo và doctor
@@ -95,3 +95,5 @@ CI của code `0e0c01c` đạt [11/11 job](https://github.com/WindowScary321/myf
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ũ.
Nghiệm thu nhóm mục 1 hoàn tất ngày 24/10/2026 bằng lớp `ReadSliceAcceptanceTests` trong tests/test_phase6_reads.py: 5 test chạy tại seam CLI cho cả bốn lát cắt đọc (balance, courses, subjects theo kỳ, news search) trên hai version. Phần header contract v2 kiểm `ClientCode`, `CampusCode`, `Authorization` Bearer, `Checksum` dạng chữ ký base64 + dấu hai chấm + timestamp giây decimal, GET không có `json` body hoặc `Content-Type`. Ma trận lỗi gồm expiry retry đúng một lần với credential mới (v1 body 201 `Token invalid`; v2 body 401 và HTTP 401, Checksum đổi theo key mới, phần query còn lại giữ nguyên), dừng sau lần expiry thứ hai, và App Check/timeout/HTTP 503/malformed giữ đúng một request, không refresh/fallback, stdout rỗng khi lỗi, không lộ sentinel hay credential. Test đạt GREEN ngay vì xác nhận hành vi đã triển khai từ các commit trước, không có behavior mới cần bước RED. Focused `tests.test_phase6_reads` đạt 22/22; full suite 399 test, 395 đạt/4 skip, exit 0 trên Windows Python 3.11.
+
+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.
From af759ebca5fb10d530c825df9a3f4d440d130019 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:20:06 +0700
Subject: [PATCH 13/28] docs: xac nhan policy credential v2 bang thi nghiem
transport hai chieu
---
docs/phase6-coverage.md | 15 ++++++++++++++-
tasks/phase6.md | 2 +-
2 files changed, 15 insertions(+), 2 deletions(-)
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index ae87e50..62e2059 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -29,7 +29,7 @@ Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus
## Policy và phần chưa xác minh
- Các read mới kế thừa binding và tối đa một refresh/retry khi server báo expiry rõ. Không tự refresh/logout từ 201 không rõ nghĩa, 403, timeout, 5xx hoặc App Check. Capability đọc không mở đường ghi.
-- 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 — và đã đọc thành công HTTP/body 200 ở lượt 24/10 lẫn lượt nghiệm thu mục 2; không chứng minh server bắt buộc Bearer và không tuyên bố parity byte-for-byte với app.
+- 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**.
@@ -109,3 +109,16 @@ Chạy trên máy cá nhân bằng session thật của người dùng ở code
| `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.
+
+### Thí nghiệm transport có kiểm soát (24/10/2026)
+
+Sau khi đọc bytecode cho thấy nhánh credential rỗng, maintainer yêu cầu thử đưa biến thể đó vào kiểm chứng. Thí nghiệm gửi trực tiếp năm biến thể header cho cả ba operation bằng session thật (chỉ đọc GET, metadata đã lọc, không giá trị) trước khi đổi CLI:
+
+| Biến thể | Authorization | Checksum ký bằng | Kết quả cả 3 operation |
+|---|---|---|---|
+| App-parity đủ theo `_buildHeaders` (kể cả `Content-Type` json) | không có | bootstrap token | HTTP 400, body không JSON |
+| Bearer FAP key + checksum bootstrap | FAP key | bootstrap token | HTTP 400 — checksum phải ký đúng credential trong Authorization |
+| Bearer bootstrap token (kiểu `_getNoAuth`) | bootstrap token | bootstrap token | HTTP 500 — qua tầng xác thực, hỏng tầng nghiệp vụ |
+| Bearer FAP key + checksum theo key (policy CLI) | FAP key | FAP key | HTTP 200, body 200 — duy nhất được chấp nhận |
+
+Kết luận: proxy v2 hiện tại chỉ chấp nhận cặp `Authorization: Bearer ` + `Checksum` ký bằng đúng key đó cho cả ba operation; nhánh credential rỗng trong bytecode bị từ chối. CLI giữ nguyên policy — nay có bằng chứng hai chiều trên một tài khoản/campus (HN), không suy rộng cho mọi campus hay suy luận app thật gửi gì lúc runtime.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 017d096..305d882 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -96,4 +96,4 @@ Sau khi thêm `V1ObservedFailureTests` bằng status/shape tổng hợp: focused
Nghiệm thu nhóm mục 1 hoàn tất ngày 24/10/2026 bằng lớp `ReadSliceAcceptanceTests` trong tests/test_phase6_reads.py: 5 test chạy tại seam CLI cho cả bốn lát cắt đọc (balance, courses, subjects theo kỳ, news search) trên hai version. Phần header contract v2 kiểm `ClientCode`, `CampusCode`, `Authorization` Bearer, `Checksum` dạng chữ ký base64 + dấu hai chấm + timestamp giây decimal, GET không có `json` body hoặc `Content-Type`. Ma trận lỗi gồm expiry retry đúng một lần với credential mới (v1 body 201 `Token invalid`; v2 body 401 và HTTP 401, Checksum đổi theo key mới, phần query còn lại giữ nguyên), dừng sau lần expiry thứ hai, và App Check/timeout/HTTP 503/malformed giữ đúng một request, không refresh/fallback, stdout rỗng khi lỗi, không lộ sentinel hay credential. Test đạt GREEN ngay vì xác nhận hành vi đã triển khai từ các commit trước, không có behavior mới cần bước RED. Focused `tests.test_phase6_reads` đạt 22/22; full suite 399 test, 395 đạt/4 skip, exit 0 trên Windows Python 3.11.
-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.
+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.
From f288ccc850ccfff3cf87c82233aee10cccbecb16 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:48:10 +0700
Subject: [PATCH 14/28] =?UTF-8?q?feat:=20m=E1=BB=9F=20other=20feedbacks=20?=
=?UTF-8?q?v=C3=A0=20GetVersion=20cho=20doctor=20sau=20khi=20ch=E1=BB=91t?=
=?UTF-8?q?=20contract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
myfap/api.py | 13 ++++++++++
myfap/cli.py | 18 +++++++++++++-
myfap/diagnostics.py | 10 +++++---
myfap/v2.py | 5 +++-
tests/test_phase4_transport.py | 6 ++++-
tests/test_phase6_doctor.py | 45 +++++++++++++++++++++++-----------
tests/test_phase6_reads.py | 38 ++++++++++++++++++++++++++++
7 files changed, 115 insertions(+), 20 deletions(-)
diff --git a/myfap/api.py b/myfap/api.py
index 9e90ab5..97901af 100644
--- a/myfap/api.py
+++ b/myfap/api.py
@@ -171,6 +171,12 @@ def get_api_active(self):
raise ApiError("GetApiActive chưa được hỗ trợ trên API v1. Hãy chọn --api-version v2.")
return _v2_request(self.session, self.auth, "GetApiActive", timeout=self.timeout)
+ def get_version(self):
+ """Đọc version backend qua bootstrap GetVersion; route v1 đã trả 404."""
+ if self.api_version != "v2":
+ raise ApiError("GetVersion chỉ hỗ trợ bootstrap API v2; route v1 đã ngừng phản hồi. Hãy chọn --api-version v2.")
+ return _v2_request(self.session, self.auth, "GetVersion", timeout=self.timeout)
+
def get_semesters(self, campus: str = None):
"""Lấy kỳ học theo startDate mới nhất; giữ thứ tự server khi trùng ngày."""
if not self.auth:
@@ -254,6 +260,13 @@ def get_ratings(self):
return _authenticated_get(self.session, self.auth, "GetStudentRate", self.auth.mssv,
student=True, timeout=self.timeout, api_version=self.api_version)
+ def get_feedbacks(self):
+ """Đọc danh sách feedback student; chỉ có trên proxy v2, item schema chưa kiểm chứng positive."""
+ if self.api_version != "v2":
+ raise ApiError("GetStudentFeedbacks chỉ có trên proxy API v2; v1 không có route tương ứng.")
+ return _authenticated_get(self.session, self.auth, "GetStudentFeedbacks", self.auth.mssv,
+ student=True, timeout=self.timeout, api_version=self.api_version)
+
def get_balance(self):
"""Lấy số dư, bảo toàn payload thay vì tự suy diễn thông tin tài chính."""
return _authenticated_get(self.session, self.auth, "GetBalance", self.auth.mssv,
diff --git a/myfap/cli.py b/myfap/cli.py
index 381ea49..42e266b 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -209,7 +209,7 @@ def version():
@app.command()
def doctor(
- online: bool = typer.Option(False, "--online", help="Gọi bootstrap GetApiActive v2; không xác thực session"),
+ online: bool = typer.Option(False, "--online", help="Gọi bootstrap GetApiActive/GetVersion v2; không xác thực session"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
stdout: bool = typer.Option(False, "--stdout", help="In JSON chẩn đoán ra stdout")
):
@@ -701,6 +701,22 @@ def other_feedback(
err_console.print(f"[red]Lỗi: {e}[/red]")
raise typer.Exit(code=1)
+@other_app.command("feedbacks")
+def other_feedbacks(
+ output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
+ 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 feedback student (chỉ API v2); item schema chưa kiểm chứng positive."""
+ auth = require_auth("GetStudentFeedbacks")
+ other_client = MyFapOther(auth)
+ try:
+ data = other_client.get_feedbacks()
+ save_output(data, "Feedbacks.json", output, stdout)
+ except Exception as e:
+ err_console.print(f"[red]Lỗi lấy danh sách feedback: {e}[/red]")
+ raise typer.Exit(code=1)
+
+
@other_app.command("profile")
def other_profile(
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
diff --git a/myfap/diagnostics.py b/myfap/diagnostics.py
index d6ac56a..8878b42 100644
--- a/myfap/diagnostics.py
+++ b/myfap/diagnostics.py
@@ -36,12 +36,16 @@ def get_diagnostics(*, api_version=None, campus=None, timeout=None, online=False
client = MyFapEssential(api_version="v2", timeout=timeout)
try:
payload = client.get_api_active()
+ if not isinstance(payload.get("data"), bool):
+ raise ApiPayloadError("Response GetApiActive phải chứa data boolean.")
+ version_payload = client.get_version()
finally:
client.session.close()
- if not isinstance(payload.get("data"), bool):
- raise ApiPayloadError("Response GetApiActive phải chứa data boolean.")
+ version = version_payload.get("data")
+ if not isinstance(version, str) or not version.strip():
+ raise ApiPayloadError("Response GetVersion phải chứa data chuỗi không rỗng.")
report["online_probe"] = {
"requested": True, "operation": "GetApiActive", "bootstrap_campus": "HN",
- "api_active": payload["data"], "scope": "proxy_bootstrap_only",
+ "api_active": payload["data"], "backend_version": version, "scope": "proxy_bootstrap_only",
}
return report
diff --git a/myfap/v2.py b/myfap/v2.py
index 36f6f44..a51ce0e 100644
--- a/myfap/v2.py
+++ b/myfap/v2.py
@@ -13,7 +13,9 @@
from .errors import ApiError
-BOOTSTRAP_OPERATIONS = frozenset({"GetAllActiveCampus", "GetApiActive"})
+# GetVersion: caller APK dùng GET (module_599.js:662) nhưng proxy hiện trả 405 với GET;
+# POST body rỗng được chấp nhận (thí nghiệm 24/10/2026), nên đi theo nhánh bootstrap.
+BOOTSTRAP_OPERATIONS = frozenset({"GetAllActiveCampus", "GetApiActive", "GetVersion"})
OPERATION_ALIASES = {"getCourseAttendance": "GetCourseAttendance"}
_READ_QUERY_FIELDS = {
"GetSemester": (),
@@ -38,6 +40,7 @@
"GetCourseAttendance": ("rollNumber", "Semester", "SubjectCode", "ClassName"),
"GetApplication": ("rollNumber",),
"GetStudentById": ("rollNumber",),
+ "GetStudentFeedbacks": ("rollNumber",),
"AcademicTranscript": ("rollNumber",),
"RetriveImage": ("rollNumber",),
"GetCampusInfo": ("rollNumber",),
diff --git a/tests/test_phase4_transport.py b/tests/test_phase4_transport.py
index 35e1b4a..dd318c4 100644
--- a/tests/test_phase4_transport.py
+++ b/tests/test_phase4_transport.py
@@ -98,7 +98,11 @@ def test_alias_is_explicit_and_only_supported_canonical_reads_are_exposed(self):
self.assertIn("GetWeekByDate", v2.READ_OPERATIONS)
self.assertIn("GetCourseAttendance", v2.READ_OPERATIONS)
self.assertNotIn("getCourseAttendance", v2.READ_OPERATIONS)
- for operation in ("GetVersion", "GetStudentFeedbackForm", "AddRate", "UpdateTokedevices"):
+ # GetVersion mở theo contract POST bootstrap đã probe 24/10/2026;
+ # GetStudentFeedbacks mở theo envelope live cùng ngày, item schema chưa positive.
+ self.assertIn("GetVersion", v2.BOOTSTRAP_OPERATIONS)
+ self.assertIn("GetStudentFeedbacks", v2.READ_OPERATIONS)
+ for operation in ("GetStudentFeedbackForm", "AddRate", "UpdateTokedevices"):
self.assertNotIn(operation, v2.SUPPORTED_OPERATIONS)
def test_invalid_read_queries_are_rejected_before_http_without_echo(self):
diff --git a/tests/test_phase6_doctor.py b/tests/test_phase6_doctor.py
index c5bf106..63b635f 100644
--- a/tests/test_phase6_doctor.py
+++ b/tests/test_phase6_doctor.py
@@ -48,21 +48,25 @@ def test_invalid_inputs_and_online_v1_fail_before_client_or_http(self):
def test_online_probe_is_v2_bootstrap_not_user_session_or_selected_campus_validation(self):
for active in (True, False):
- response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": active, "private": "MUST_NOT_APPEAR"}))
- with self.subTest(active=active), patch("requests.Session.request", return_value=response) as request, \
+ active_response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": active, "private": "MUST_NOT_APPEAR"}))
+ version_response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": "SYNTHETIC_BACKEND_VERSION", "private": "MUST_NOT_APPEAR"}))
+ with self.subTest(active=active), patch("requests.Session.request", side_effect=[active_response, version_response]) as request, \
patch("myfap.auth.MyFapAuth", side_effect=AssertionError("no auth")):
report = diagnostics.get_diagnostics(api_version="v2", campus="TEST", timeout=3, online=True)
self.assertEqual(report["campus"], "TEST")
self.assertEqual(report["session_validation"], "not_checked")
- self.assertEqual(report["online_probe"], {"requested": True, "operation": "GetApiActive", "bootstrap_campus": "HN", "api_active": active, "scope": "proxy_bootstrap_only"})
+ self.assertEqual(report["online_probe"], {"requested": True, "operation": "GetApiActive", "bootstrap_campus": "HN", "api_active": active, "backend_version": "SYNTHETIC_BACKEND_VERSION", "scope": "proxy_bootstrap_only"})
self.assertNotIn("MUST_NOT_APPEAR", json.dumps(report))
- request.assert_called_once()
- self.assertEqual(request.call_args.args, ("POST", "https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive"))
- self.assertEqual(request.call_args.kwargs["headers"]["CampusCode"], "HN")
- self.assertEqual(request.call_args.kwargs["params"], {})
- self.assertEqual(request.call_args.kwargs["json"], {})
- self.assertEqual(request.call_args.kwargs["timeout"], 3)
- self.assertFalse(request.call_args.kwargs["allow_redirects"])
+ self.assertEqual(request.call_count, 2)
+ first, second = request.call_args_list
+ self.assertEqual(first.args, ("POST", "https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive"))
+ self.assertEqual(second.args, ("POST", "https://fap-proxy.fpt.edu.vn/MyFAP/GetVersion"))
+ for call in (first, second):
+ self.assertEqual(call.kwargs["headers"]["CampusCode"], "HN")
+ self.assertEqual(call.kwargs["params"], {})
+ self.assertEqual(call.kwargs["json"], {})
+ self.assertEqual(call.kwargs["timeout"], 3)
+ self.assertFalse(call.kwargs["allow_redirects"])
def test_online_probe_rejects_non_boolean_payload_without_echoing_it(self):
for value in (None, [], {}, 1, "true", "PRIVATE_PAYLOAD"):
@@ -73,6 +77,16 @@ def test_online_probe_rejects_non_boolean_payload_without_echoing_it(self):
self.assertNotIn("PRIVATE_PAYLOAD", str(caught.exception))
request.assert_called_once()
+ def test_online_probe_rejects_non_string_version_without_echoing_it(self):
+ active_response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": True}))
+ for value in (None, [], {}, 3, "", " "):
+ version_response = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": value, "private": "PRIVATE_PAYLOAD"}))
+ with self.subTest(value=value), patch("requests.Session.request", side_effect=[active_response, version_response]) as request:
+ with self.assertRaises(ApiPayloadError) as caught:
+ diagnostics.get_diagnostics(api_version="v2", online=True)
+ self.assertNotIn("PRIVATE_PAYLOAD", str(caught.exception))
+ self.assertEqual(request.call_count, 2)
+
def test_probe_network_failure_is_safe_and_not_retried(self):
with patch("requests.Session.request", side_effect=requests.Timeout("PRIVATE_TOKEN")) as request:
with self.assertRaises(ApiError) as caught:
@@ -97,13 +111,16 @@ def test_cli_local_does_not_load_auth_and_keeps_json_stdout(self):
def test_cli_online_is_explicit_and_does_not_use_session(self):
from typer.testing import CliRunner
from myfap.cli import app
- reply = Mock(status_code=200, json=Mock(return_value={"code": 200, "data": True}))
+ replies = [Mock(status_code=200, json=Mock(return_value={"code": 200, "data": True})),
+ Mock(status_code=200, json=Mock(return_value={"code": 200, "data": "SYNTHETIC_BACKEND_VERSION"}))]
with patch("myfap.cli.get_auth", side_effect=AssertionError("no auth")), \
- patch("requests.Session.request", return_value=reply) as request:
+ patch("requests.Session.request", side_effect=replies) as request:
result = CliRunner().invoke(app, ["doctor", "--api-version", "v2", "--online", "--stdout"])
self.assertEqual(result.exit_code, 0, result.output)
- self.assertTrue(json.loads(result.stdout)["online_probe"]["api_active"])
- request.assert_called_once()
+ report = json.loads(result.stdout)["online_probe"]
+ self.assertTrue(report["api_active"])
+ self.assertEqual(report["backend_version"], "SYNTHETIC_BACKEND_VERSION")
+ self.assertEqual(request.call_count, 2)
if __name__ == "__main__":
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 150c34a..a806d74 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -381,6 +381,44 @@ def test_http_404_and_unexplained_201_remain_failures_without_refresh_or_fallbac
self.assertEqual(self.path.read_bytes(), before)
+class FeedbackListTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ def test_feedbacks_v2_reads_exact_contract_and_preserves_envelope(self):
+ self.save_session("v2")
+ payload = {"code": 200, "data": [{"synthetic": "feedback item"}]}
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "feedbacks", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertEqual(request.call_args.args[0], "GET")
+ self.assertTrue(request.call_args.args[1].endswith("/GetStudentFeedbacks"))
+ self.assertEqual(request.call_args.kwargs["params"], {"CampusCode": "TEST", "rollNumber": "TEST000"})
+ self.assertNotIn("Authen", request.call_args.kwargs["params"])
+ self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+ self.assertNotIn("json", request.call_args.kwargs)
+
+ def test_feedbacks_preserves_empty_list(self):
+ self.save_session("v2")
+ payload = {"code": 200, "data": []}
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "other", "feedbacks", "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+
+ def test_feedbacks_v1_is_rejected_before_http(self):
+ self.save_session("v1")
+ with 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)
+ request.assert_not_called()
+
+
class ReadSliceAcceptanceTests(unittest.TestCase):
"""Nghiệm thu nhóm mục 1: header contract và ma trận lỗi tại seam CLI."""
From 3ef5d2abf01119146140511def150da9aafd1475 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:48:11 +0700
Subject: [PATCH 15/28] =?UTF-8?q?docs:=20ph=C3=A2n=20t=C3=ADch=20kho?=
=?UTF-8?q?=E1=BA=A3ng=20tr=E1=BB=91ng=20endpoint=20v=C3=A0=20ghi=20nh?=
=?UTF-8?q?=E1=BA=ADn=20m=E1=BB=9F=20r=E1=BB=99ng=2024/10?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 5 +++-
docs/command-endpoints.md | 9 ++++---
docs/endpoint-gap-analysis.md | 47 +++++++++++++++++++++++++++++++++++
docs/phase6-coverage.md | 14 +++++++++--
docs/v2-contracts.md | 8 +++---
tasks/phase6.md | 8 +++---
6 files changed, 77 insertions(+), 14 deletions(-)
create mode 100644 docs/endpoint-gap-analysis.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a14e1e..0b01a3e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@
### API và dữ liệu
+- 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).
+- `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; 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.
- Giữ API v1 làm mặc định. API v2 chỉ được chọn bằng `--api-version v2` hoặc binding của session; không tự chuyển version khi gặp lỗi.
@@ -33,7 +36,7 @@
- **Phase 6 v1/APHL, ngày 24/10/2026:** courses và marks summary trả HTTP 404; news search/training trả HTTP 200/body 201, data null. CLI giữ lỗi và không fallback; nguyên nhân chưa rõ. V2/HN đã đọc được các command tương ứng, không thay thế kiểm chứng v1.
- **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 đang bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary và doctor trước khi phát hành; xem coverage Phase 6. Các capability mới có fixture nhưng chưa nghiệm thu live. Rating list student/v1 đã có code/fixture; v2 stub bị chặn. Feedback đầy đủ và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
+- 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ợ.
- 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/docs/command-endpoints.md b/docs/command-endpoints.md
index 1eb389e..766acce 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -4,7 +4,7 @@ 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). 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](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.
## Phạm vi theo kế hoạch
@@ -44,10 +44,11 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| `other fee` | `GeFeeByRoll` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GeFeeByRoll` | `https://fap-proxy.fpt.edu.vn/MyFAP/GeFeeByRoll` | V2/HN live 200/200, data không rỗng; chưa đối chiếu schema nghiệp vụ. V1/APHL HTTP 404 ngày 19/10 |
| `other subjects` | `GetSubjets` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetSubjets` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetSubjets` | Student/read; live v2/HN 200/200; timeout tối thiểu 30 giây |
| `other feedback` | `CheckOpenFeedBack` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/CheckOpenFeedBack` | `https://fap-proxy.fpt.edu.vn/MyFAP/CheckOpenFeedBack` | Chỉ kiểm tra/read, không submit feedback; live v2/HN 200/200, data boolean |
+| `other feedbacks` | `GetStudentFeedbacks` | Không hỗ trợ / GET | — | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentFeedbacks` | Phase 6 mở rộng, v2-only; query `CampusCode`, `rollNumber`; live 200/200 list rỗng, item schema chưa positive |
| `other profile` | `CheckUpdateProfile` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/CheckUpdateProfile` | `https://fap-proxy.fpt.edu.vn/MyFAP/CheckUpdateProfile` | Chỉ kiểm tra/read, không cập nhật hồ sơ; live v2/HN 200/200, data boolean |
| `other notification` | `GetNotificationByRoll` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetNotificationByRoll` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetNotificationByRoll` | V2/HN live 200/200; v1/APHL vẫn lỗi 200/201 ngày 19/10 |
| `other survey` ở cả hai API version | `GetRequiredSurvey` | GET / GET | `https://survey.fpt.edu.vn/API/myFAP/GetRequiredSurvey` | `https://survey.fpt.edu.vn/API/myFAP/GetRequiredSurvey` | Dịch vụ riêng, signer riêng; live HTTP 200/body 404, không phải positive survey |
-| Chỉ Python API `MyFapEssential.get_api_active()`; chưa có command CLI | `GetApiActive` | Không hỗ trợ / POST | — | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive` | Public/bootstrap diagnostic v2; fixture, chưa gọi trong lượt live mới; không auto-switch/fallback |
+| `doctor --api-version v2 --online` | `GetApiActive`, `GetVersion` | Không hỗ trợ / POST bootstrap | — | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive`, `https://fap-proxy.fpt.edu.vn/MyFAP/GetVersion` | Phase 6 mở rộng: probe `api_active` boolean và `backend_version` chuỗi ngắn; GET với GetVersion bị 405, POST body `{}` đạt 200; không xác nhận session/campus tài khoản |
`version` và `--help` không cần API. `logout` chỉ xóa session local, không phải request logout FEID/FAP. Các command export JSON/ICS/pretty dùng cùng endpoint dữ liệu, không tạo route mới.
@@ -80,9 +81,9 @@ Không chạy lại v1 trong lượt này. Kết quả v2 không đóng ba findi
| Transcript / marks summary | `AcademicTranscript`, `GetSemesterMark` | Phase 6; transcript có ở cả v1/v2, chưa tích hợp CLI |
| Courses / subjects theo kỳ / training | `GetCourseOfSemester`, `GetSubjectBySemester`, `GetDiemphongtrao` | Phase 6; phải giữ đúng case từng query |
| Balance / tìm news / ảnh | `GetBalance`, `SearchNews`, `RetriveImage` | Phase 6; chưa có command tương ứng |
-| Doctor / kiểm version backend | `GetApiActive`, `GetVersion` | `GetApiActive` đã có Python method v2 nhưng chưa có CLI; `GetVersion` chưa hỗ trợ |
+| Doctor / kiểm version backend | `GetApiActive`, `GetVersion` | Đã mở cho `doctor --online` (24/10/2026): `GetApiActive` + `GetVersion` POST bootstrap; GET với GetVersion bị 405, route v1 404 |
| Rating / push | `GetStudentRate`, `AddRate`, `UpdateTokedevices`, `UpdateTokenDonor` | Chưa mở CLI; phân biệt stub v2 và GET ghi; cần schema, xác nhận và không retry ghi |
-| Feedback đầy đủ | `GetStudentFeedbacks`, `GetStudentFeedbackForm`, `SubmitStudentFeedback` | Không đồng nhất với `other feedback`; schema submit/capability chưa đầy đủ |
+| Feedback đầy đủ | `GetStudentFeedbacks`, `GetStudentFeedbackForm`, `SubmitStudentFeedback` | `GetStudentFeedbacks` đã mở `other feedbacks` v2-only (envelope live, item chưa positive); Form chờ feedbackId thật, Submit vẫn gate |
| Google/donor/employee, FEID server-code exchange | Các flow tương ứng trong inventory | TODO riêng; không suy hỗ trợ chỉ từ route có trong APK |
Inventory và method từng route proxy nằm trong [ma trận v2](v2-contracts.md#ma-trận-route-v2). Thêm các endpoint này vào Phase 5 sẽ là thay đổi phạm vi cần thống nhất lại; smoke command hiện có không chứng minh chúng đã được triển khai.
diff --git a/docs/endpoint-gap-analysis.md b/docs/endpoint-gap-analysis.md
new file mode 100644
index 0000000..3d09fec
--- /dev/null
+++ b/docs/endpoint-gap-analysis.md
@@ -0,0 +1,47 @@
+# Phân tích khoảng trống endpoint giữa APK myFAP và CLI
+
+Đối chiếu ngày 24/10/2026 giữa inventory 82 route của APK 2.0.6 build 31 (`analysis/endpoints.md` của workspace phân tích, nguồn `analysis/modules/*.js`) và tập operation adapter CLI. Mục đích: xác định CLI còn thiếu gì, thiếu có chủ đích hay chưa biết, và endpoint nào đủ bằng chứng để mở.
+
+Quy tắc riêng tư: mọi probe live dưới đây là GET/POST chỉ đọc bằng session thật trên máy cá nhân; output raw chỉ xử lý cục bộ và bị xóa sau khi trích metadata. Tài liệu này chỉ chứa metadata đã lọc (status, body code, dạng dữ liệu, tên khóa), không chứa token, identity, giá trị trường hay raw response.
+
+## Kết luận tổng quan
+
+- App có 82 route: 37 v1, 40 proxy v2, 1 survey, 4 OTA, 1 HEAD connectivity.
+- CLI hỗ trợ **toàn bộ operation đọc student của cả v1 lẫn v2** (26+1 read v2 sau đợt này, 29 route v1 tương ứng), survey riêng và handshake FEID. Không có route đọc student nào của app bị bỏ sót.
+- Sau đợt mở rộng này, adapter v2 có **31 operation**: 27 đọc, 3 bootstrap (`GetAllActiveCampus`, `GetApiActive`, `GetVersion`) và 1 handshake.
+
+## Nhóm A — Read student từng gate, đã đủ bằng chứng và mở trong đợt này
+
+| Operation | Bằng chứng đóng gate (24/10/2026) | Kết quả triển khai |
+|---|---|---|
+| `GetStudentFeedbacks` (v2-only, `module_599.js:601-623`) | Query đúng là `{CampusCode, rollNumber}` — **không có `Authen` trong query** (đối chiếu bytecode dòng 613, sửa lại ghi chú inventory cũ); credential đi header Bearer. Live: HTTP/body 200, data list rỗng với policy Bearer FAP key | Mở `myfap other feedbacks`; envelope đã xác nhận, **item schema chưa có positive** (danh sách rỗng) — giữ nhãn unverified như rating list |
+| `GetVersion` (`module_599.js:659-670`) | Caller APK dùng GET nhưng proxy trả **405** với GET; **POST body rỗng** được chấp nhận với cả bootstrap Bearer lẫn FAP key Bearer (200, data chuỗi ngắn); **route v1 đã chết (HTTP 404)** | Mở cho `doctor --api-version v2 --online`: report thêm `backend_version`; `myfap version` vẫn chỉ đọc package version |
+| `GetStudentFeedbackForm` (`module_599.js:624-637`) | Query `{CampusCode, rollNumber, feedbackId}`; cần `feedbackId` thật từ danh sách — danh sách đang rỗng nên **không đoán ID** theo quy tắc plan | Vẫn gate; chờ tài khoản có feedback đang mở |
+
+## 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.
+
+## Nhóm C — Out of scope theo thiết kế CLI
+
+| Nhóm | Route | Lý do không tích hợp |
+|---|---|---|
+| Donor/employee | `GetNotificationByDonor`, `GetTokenWithEmp`, `UpdateTokenDonor` | CLI giới hạn luồng student theo plan |
+| Login thay thế | `AuthenticationByGoogleAccessToken` (v1 GET/v2 POST), `AuthenticationByUsername` (v1) | CLI chọn luồng FEID; nhánh username đặt password trong query URL — không tái hiện |
+| FEID server-code | `AuthenticationByFeIdCode` | Chính app tắt bằng flag `FEID_SERVER_CODE_EXCHANGE=false` |
+| Hạ tầng OTA | `codepushota.ptudev.net` check-update/report-crash/report-failure/report-success | Hạ tầng cập nhật app, không phải dữ liệu FAP |
+| Connectivity | HEAD `clients3.google.com/generate_204` | NetInfo của app |
+
+## Nhóm D — Tính năng ngoài API (Linking.openURL)
+
+App mở trình duyệt cho: trang hóa đơn `dng.fpt.edu.vn/Invoice?StudentId=…`, file đính kèm tin `fap.fpt.edu.vn/temp/{fileAttach}`, link Meet. CLI đã giữ nguyên các trường tương ứng trong JSON output (`meetURL`, `fileAttach`); có thể thêm lệnh QoL in URL hóa đơn nếu cần, không phải route API.
+
+## Bằng chứng thí nghiệm transport liên quan
+
+Thí nghiệm ngày 24/10/2026 (chi tiết tại [coverage Phase 6](phase6-coverage.md#thí-nghiệm-transport-có-kiểm-soát-24102026)) cho thấy proxy chỉ chấp nhận cặp Bearer FAP key + Checksum ký cùng key cho các operation đọc; nhánh credential rỗng trong bytecode bị từ chối 400/500. Đó là cơ sở giữ policy transport cho các endpoint mở trong đợt này.
+
+## Theo dõi tiếp
+
+- 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).
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 62e2059..0470535 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -17,8 +17,9 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture parser/refresh; live v2/HN 200/200 với envelope data list |
| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Live v2/HN 200/200, data string; định dạng ảnh chưa xác minh |
| `other rating list` | `GetStudentRate` | Có / Không | V1 đọc, ký bằng roll number; v2 stub bị chặn trước load session/HTTP | Fixture và live v1/APHL 200/200, danh sách rỗng |
+| `other feedbacks` | `GetStudentFeedbacks` | Không / Có | V2-only; query `CampusCode`, `rollNumber`, không query `Authen` (bytecode dòng 613); credential qua header Bearer | Fixture contract; live 24/10 200/200 list rỗng — item schema chưa positive |
| `doctor --stdout` | Không gọi HTTP | Local | Chỉ explicit/default, không đọc/khóa/refresh session, không in config path/identity/token | Test CLI và chạy local thật |
-| `doctor --api-version v2 --online` | `GetApiActive` | Không / POST bootstrap | URL proxy; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture và live bootstrap v2 200/200; không kiểm tài khoản |
+| `doctor --api-version v2 --online` | `GetApiActive`, `GetVersion` | Không / POST bootstrap | Probe `api_active` boolean rồi `backend_version` chuỗi; query/body rỗng, bootstrap campus HN; không xác nhận session/campus tài khoản | Fixture và live bootstrap v2 200/200; GetVersion POST 200 (GET 405, v1 404), `myfap version` vẫn offline |
`marks --summary` từ chối `--semester`, `--courseid`, `--pretty` trước auth. `myfap version` vẫn chỉ đọc package version. Doctor không tự lấy version/campus từ session: điều này được ghi rõ trong report để giữ local mode không có tác dụng phụ.
@@ -33,7 +34,7 @@ Cột v1/v2 là capability trong code, không bảo đảm backend mọi campus
- 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**.
-- `GetVersion` backend tiếp tục unsupported cho đến khi public/text contract đủ rõ. Không thay package `version` thành probe online.
+- `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
@@ -122,3 +123,12 @@ Sau khi đọc bytecode cho thấy nhánh credential rỗng, maintainer yêu c
| Bearer FAP key + checksum theo key (policy CLI) | FAP key | FAP key | HTTP 200, body 200 — duy nhất được chấp nhận |
Kết luận: proxy v2 hiện tại chỉ chấp nhận cặp `Authorization: Bearer ` + `Checksum` ký bằng đúng key đó cho cả ba operation; nhánh credential rỗng trong bytecode bị từ chối. CLI giữ nguyên policy — nay có bằng chứng hai chiều trên một tài khoản/campus (HN), không suy rộng cho mọi campus hay suy luận app thật gửi gì lúc runtime.
+
+## Mở rộng endpoint sau phân tích khoảng trống (24/10/2026)
+
+Đối chiếu 82 route của APK với adapter ([phân tích khoảng trống](endpoint-gap-analysis.md)) mở thêm hai capability theo bằng chứng probe cùng ngày, chạy trên máy cá nhân với session thật, metadata đã lọc:
+
+- **`myfap other feedbacks` → `GetStudentFeedbacks`** (v2-only, `module_599.js:601-623`): query `{CampusCode, rollNumber}` không có `Authen` (bytecode dòng 613), credential qua Bearer. Live v2/HN HTTP/body 200, data list rỗng — envelope chuẩn, item schema chưa positive, giữ nhãn unverified như rating list. RED 3 test → GREEN sau implementation.
+- **`doctor --api-version v2 --online` thêm `GetVersion`**: probe chạy sau khi `GetApiActive` hợp lệ, report có `backend_version`. Contract: GET bị 405, POST body `{}` bootstrap đạt 200 với data chuỗi ngắn, route v1 404. Test hiện có cập nhật (2 probe cho lượt online) và test mới chặn version không phải chuỗi; một lỗi thứ tự thật bị test bắt (probe version chạy trước khi validate active) đã sửa.
+
+Full suite sau hai feature: 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 (`api_active` true, `backend_version` chuỗi 3 ký tự).
diff --git a/docs/v2-contracts.md b/docs/v2-contracts.md
index b709726..466f6fd 100644
--- a/docs/v2-contracts.md
+++ b/docs/v2-contracts.md
@@ -69,16 +69,16 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `GetTokenWithEmp` | `GET` | unsupported | Employee flow |
| `GetAllActiveCampus` | `POST` | supported | Body `{}` |
| `GetCampusInfo` | `GET` | supported | Query `CampusCode`, `rollNumber` |
-| `GetStudentFeedbacks` | `GET` | unsupported | Query `CampusCode`, `rollNumber` |
-| `GetStudentFeedbackForm` | `GET` | unsupported | Query `CampusCode`, `rollNumber`, `feedbackId` |
+| `GetStudentFeedbacks` | `GET` | supported | Phase 6 mở rộng: query `CampusCode`, `rollNumber` (không query `Authen` theo bytecode dòng 613); item schema chưa positive |
+| `GetStudentFeedbackForm` | `GET` | unsupported | Query `CampusCode`, `rollNumber`, `feedbackId`; chờ feedbackId thật |
| `SubmitStudentFeedback` | `POST` | unsupported | Body nghiệp vụ |
-| `GetVersion` | `GET` | unsupported | Query rỗng |
+| `GetVersion` | `POST` | supported | Phase 6 mở rộng: caller APK dùng GET nhưng proxy trả 405 với GET; POST body `{}` bootstrap đã probe 24/10/2026; v1 đã 404 |
| `GetApiActive` | `POST` | supported | Bootstrap chẩn đoán trạng thái proxy |
| `GetStudentRate` | Không có | stub | APK export không có implementation request rõ ràng |
| `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, ma trận có 29 operation được hỗ trợ trong code: 26 operation đọc, 2 bootstrap và 1 handshake. `doctor --api-version v2 --online` gọi `GetApiActive` 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](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/tasks/phase6.md b/tasks/phase6.md
index 305d882..eb4aba3 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -44,8 +44,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
- [x] **`info photo` → `RetriveImage`:** output JSON theo representation đã chứng minh, giữ chuỗi opaque; không tự fetch URL, decode Base64, in binary hoặc mở ảnh. Xuất ảnh file riêng chỉ mở sau khi đủ bằng chứng định dạng/size/type và fixture.
- [x] **`doctor` local:** chỉ xuất allowlist chẩn đoán package/API version, campus được chọn, capability và loại lỗi; không dump auth/session, email/MSSV, header, token hoặc config path đầy đủ. Không gọi `require_auth`/`load_session` gây refresh/persist.
-- [ ] Probe online là option explicit và tái sử dụng `GetApiActive` v2; không auto-login/refresh/switch version. `GetVersion` giữ gate riêng khi public/text contract còn chưa rõ; `myfap version` tiếp tục offline.
-- [ ] Test doctor/help local không gọi mạng; lỗi không lộ payload; photo không tạo file/fetch ngoài ý muốn.
+- [x] Probe online là option explicit và tái sử dụng `GetApiActive` v2; không auto-login/refresh/switch version. `GetVersion` giữ gate riêng khi public/text contract còn chưa rõ; `myfap version` tiếp tục offline.
+- [x] Test doctor/help local không gọi mạng; lỗi không lộ payload; photo không tạo file/fetch ngoài ý muốn.
## Checkpoint: nhóm đọc
@@ -67,7 +67,7 @@ Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ
## 5. Feedback và flow còn thiếu bằng chứng
- [ ] Giữ `other feedback` là `CheckOpenFeedBack`; không đổi nghĩa thành list/form/submit.
-- [ ] `GetStudentFeedbacks`/`GetStudentFeedbackForm` chỉ mở khi có response contract đủ; không suy kiểu item/ID/câu hỏi từ tên route.
+- [x] `GetStudentFeedbacks` mở `other feedbacks` (24/10/2026) sau khi có envelope live 200/list rỗng và bytecode xác nhận query `{CampusCode, rollNumber}` không `Authen`; item schema giữ nhãn chưa positive. `GetStudentFeedbackForm` vẫn gate chờ feedbackId thật; không suy kiểu item/ID/câu hỏi từ tên route.
- [ ] `SubmitStudentFeedback`, donor/employee, donor push và FEID server-code exchange thiếu schema/capability tiếp tục gate/TODO; không nhận JSON tùy ý để vượt gate.
- [ ] Trước khi chốt phạm vi, liệt kê từng blocker và bằng chứng cần thêm; không đánh dấu Phase 6 hoàn tất bằng cách lặng lẽ bỏ các mục chưa đạt.
@@ -97,3 +97,5 @@ Sau khi thêm `V1ObservedFailureTests` bằng status/shape tổng hợp: focused
Nghiệm thu nhóm mục 1 hoàn tất ngày 24/10/2026 bằng lớp `ReadSliceAcceptanceTests` trong tests/test_phase6_reads.py: 5 test chạy tại seam CLI cho cả bốn lát cắt đọc (balance, courses, subjects theo kỳ, news search) trên hai version. Phần header contract v2 kiểm `ClientCode`, `CampusCode`, `Authorization` Bearer, `Checksum` dạng chữ ký base64 + dấu hai chấm + timestamp giây decimal, GET không có `json` body hoặc `Content-Type`. Ma trận lỗi gồm expiry retry đúng một lần với credential mới (v1 body 201 `Token invalid`; v2 body 401 và HTTP 401, Checksum đổi theo key mới, phần query còn lại giữ nguyên), dừng sau lần expiry thứ hai, và App Check/timeout/HTTP 503/malformed giữ đúng một request, không refresh/fallback, stdout rỗng khi lỗi, không lộ sentinel hay credential. Test đạt GREEN ngay vì xác nhận hành vi đã triển khai từ các commit trước, không có behavior mới cần bước RED. Focused `tests.test_phase6_reads` đạt 22/22; full suite 399 test, 395 đạt/4 skip, exit 0 trên Windows Python 3.11.
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ở.
From f3f2bd6ab3e2ef6cd1f5c3f6b0daf89bbc055536 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:40:17 +0700
Subject: [PATCH 16/28] =?UTF-8?q?docs:=20kh=C3=A9p=20checkpoint=20nh=C3=B3?=
=?UTF-8?q?m=20=C4=91=E1=BB=8Dc=20v=E1=BB=9Bi=20build=20artifact=20v=C3=A0?=
=?UTF-8?q?=20qu=C3=A9t=20session=20m=E1=BB=9Bi?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/phase6-coverage.md | 15 +++++++++++++++
tasks/phase6.md | 8 +++++---
2 files changed, 20 insertions(+), 3 deletions(-)
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index 0470535..d955d4d 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -132,3 +132,18 @@ Kết luận: proxy v2 hiện tại chỉ chấp nhận cặp `Authorization: Be
- **`doctor --api-version v2 --online` thêm `GetVersion`**: probe chạy sau khi `GetApiActive` hợp lệ, report có `backend_version`. Contract: GET bị 405, POST body `{}` bootstrap đạt 200 với data chuỗi ngắn, route v1 404. Test hiện có cập nhật (2 probe cho lượt online) và test mới chặn version không phải chuỗi; một lỗi thứ tự thật bị test bắt (probe version chạy trước khi validate active) đã sửa.
Full suite sau hai feature: 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 (`api_active` true, `backend_version` chuỗi 3 ký tự).
+
+## Quét toàn bộ lệnh đọc bằng session/browser mới (24/10/2026)
+
+Đóng checkpoint nhóm đọc: login FEID mới bằng browser context mới với session tạm riêng (hai lượt — lượt chính cho bộ quét, lượt phụ cho lệnh bảng), chạy toàn bộ command đọc trên v2/HN, raw chỉ xử lý cục bộ trên máy cá nhân và xóa sau khi trích metadata; parameter (`CourseId`, `SubjectCode`/`ClassName`) trích từ response trong thư mục tạm, không in giá trị. Cả hai session đã logout.
+
+| Phân loại | Command (HTTP/body code, dạng data) |
+|---|---|
+| Success có dữ liệu | info student 200/list(1); info campus 200/list(1); photo 200/str ngắn không rỗng (lần đầu có chuỗi); courses 200/list(5) — resolver kỳ tự chạy; schedule 200/list(64); schedule --ics vcalendar chuẩn CRLF; week-timetable 200/list(6); marks --summary 200/list(32); exams 200/list(6); attendance 200/list(5); **attendance detail 200/list(1) — positive đầu tiên (param trích từ courses)**; news 200/list(10); **news --search 200/list(50)**; notification 200/list(49); fee 200/list(1) không rỗng — **không đóng positive fee, schema nghiệp vụ chưa đối chiếu**; balance 200/str ngắn; subjects 200/list lớn; transcript 200/str ~10,5 KB; doctor local/online exit 0 |
+| Success, data rỗng | marks 200/list(0); marks --courseid 200/str(0) (CourseId thật trích từ courses; chuỗi rỗng, chưa phải positive nội dung); applications 200/list(0); other training 200/list(0); other feedbacks 200/list(0) |
+| Theo contract đặc thù | other survey HTTP 200/body 404 exit 0 (not-found cho phép); other feedback/profile 200/data boolean |
+| Không áp dụng trên v2 | other rating list exit 1 — v1-only, chặn trước HTTP đúng thiết kế |
+| Lệnh bảng | semesters exit 0, bảng UTF-8 ~29 dòng kỳ (lượt phụ, login riêng) |
+| Ghi chú harness | Lượt chính bị lỗi harness ở `semesters --stdout` (lệnh bảng không có option này → exit 2, không phải lỗi CLI; chạy lại đúng cú pháp ở lượt phụ). `other subjects --semester` không lặp lại trong lượt này vì cùng lỗi; bằng chứng lượt 24/10 trước (200/200, input kỳ từ API thật) vẫn đứng |
+
+Không đóng các mục cấm: positive fee/survey giữ mở (dữ liệu chưa đối chiếu nghiệp vụ), các finding v1 giữ nguyên — không dùng kết quả v2 để đóng. Transcript HTML và các formatter nghiệp vụ tiếp tục nhãn chưa kiểm chứng.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index eb4aba3..fe2e5fd 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -49,9 +49,9 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
## Checkpoint: nhóm đọc
-- [ ] Focused/full regression, build/Twine/artifact validator và pip smoke đạt; không có docs/tasks/tests/session/capture trong distribution.
-- [ ] 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.
-- [ ] 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.
+- [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] 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
@@ -99,3 +99,5 @@ 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ở.
+
+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.
From 8529176d6627aef23e1003f1174317881386d1ad Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:19:04 +0700
Subject: [PATCH 17/28] feat: transcript --pretty phan tich HTML bang diem toan
khoa
---
CHANGELOG.md | 1 +
docs/command-endpoints.md | 1 +
docs/phase6-coverage.md | 2 +-
myfap/cli.py | 9 +++++--
myfap/parsers.py | 28 +++++++++++++++++++
tasks/phase6.md | 2 ++
tests/test_parsers.py | 55 ++++++++++++++++++++++++++++++++++++++
tests/test_phase6_reads.py | 22 +++++++++++++++
8 files changed, 117 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b01a3e..eea456f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
### API và dữ liệu
- 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; 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.
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index 766acce..6b8c025 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -48,6 +48,7 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| `other profile` | `CheckUpdateProfile` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/CheckUpdateProfile` | `https://fap-proxy.fpt.edu.vn/MyFAP/CheckUpdateProfile` | Chỉ kiểm tra/read, không cập nhật hồ sơ; live v2/HN 200/200, data boolean |
| `other notification` | `GetNotificationByRoll` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetNotificationByRoll` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetNotificationByRoll` | V2/HN live 200/200; v1/APHL vẫn lỗi 200/201 ngày 19/10 |
| `other survey` ở cả hai API version | `GetRequiredSurvey` | GET / GET | `https://survey.fpt.edu.vn/API/myFAP/GetRequiredSurvey` | `https://survey.fpt.edu.vn/API/myFAP/GetRequiredSurvey` | Dịch vụ riêng, signer riêng; live HTTP 200/body 404, không phải positive survey |
+| `transcript`, `transcript --pretty` | `AcademicTranscript` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/AcademicTranscript` | `https://fap-proxy.fpt.edu.vn/MyFAP/AcademicTranscript` | Phase 6; live v2/HN 200/200 data HTML string; `--pretty` parse 2 bảng (49+2 dòng trên tài khoản kiểm chứng) thành JSON keyed theo header từng bảng |
| `doctor --api-version v2 --online` | `GetApiActive`, `GetVersion` | Không hỗ trợ / POST bootstrap | — | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApiActive`, `https://fap-proxy.fpt.edu.vn/MyFAP/GetVersion` | Phase 6 mở rộng: probe `api_active` boolean và `backend_version` chuỗi ngắn; GET với GetVersion bị 405, POST body `{}` đạt 200; không xác nhận session/campus tài khoản |
`version` và `--help` không cần API. `logout` chỉ xóa session local, không phải request logout FEID/FAP. Các command export JSON/ICS/pretty dùng cùng endpoint dữ liệu, không tạo route mới.
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index d955d4d..b33d57a 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -12,7 +12,7 @@ URL dữ liệu v1 là `https://api.fpt.edu.vn/fap/api/MyFAP/`; v2 l
| `courses --semester` | `GetCourseOfSemester` | Có / Có | Query `semester` chữ thường; thiếu option dùng resolver `startDate` | Fixture explicit/latest; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
| `other subjects --semester` | `GetSubjectBySemester` | Có / Có | Query `Semester` chữ hoa; signer v1 là semester; không có option vẫn `GetSubjets`, không lookup kỳ | Fixture hai version; live v2/HN 200/200, v1: xem kết quả APHL bên dưới |
| `news --search --type` | `SearchNews` | Có / Có | `type`, `keysearch`; signer v1 là type; search rỗng bị chặn | Fixture Unicode/reserved characters; live v2/HN 200/200 |
-| `transcript` | `AcademicTranscript` | Có / Có | Không lookup kỳ; giữ JSON, không formatter nghiệp vụ | Fixture; live v2/HN 200/200 với bound key, data string |
+| `transcript`, `transcript --pretty` | `AcademicTranscript` | Có / Có | Không lookup kỳ; `--pretty` phân tích HTML thành JSON keyed theo header từng bảng (chuẩn hoá ` `), mặc định giữ chuỗi gốc | Fixture parser/CLI; live v2/HN 200/200 — `--pretty` cho 2 bảng 49+2 dòng, header khớp dữ liệu thật |
| `other training --semester` | `GetDiemphongtrao` | Có / Có | Query `semester`; thiếu option dùng resolver | Fixture; live v2/HN 200/200 với bound key, list rỗng |
| `marks --summary` | `GetSemesterMark` | Có / Có | Không có query kỳ; v1 `CampusCode`, `rollNumber`, `Authen`, **không checksum**; v2 có query Authen mới sau refresh | Fixture parser/refresh; live v2/HN 200/200 với envelope data list |
| `info photo` | `RetriveImage` | Có / Có | Chỉ JSON, bảo toàn chuỗi opaque kể cả HTML entity; không tải URL hoặc decode ảnh | Live v2/HN 200/200, data string; định dạng ảnh chưa xác minh |
diff --git a/myfap/cli.py b/myfap/cli.py
index 42e266b..57d8e2c 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -15,7 +15,7 @@
from .auth import MyFapAuth, SessionBindingError
from .api import MyFapClient, MyFapEssential, MyFapOther
-from .parsers import parse_marks_html, convert_schedule_to_ics
+from .parsers import parse_marks_html, parse_transcript_html, convert_schedule_to_ics
from .config import resolve_timeout
from importlib import metadata
@@ -349,6 +349,7 @@ def schedule(
@app.command()
def transcript(
+ pretty: bool = typer.Option(False, "--pretty", "-p", help="Phân tích HTML bảng điểm toàn khóa thành JSON cấu trúc"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
@@ -356,7 +357,11 @@ def transcript(
auth = require_auth("AcademicTranscript")
try:
data = MyFapClient(auth).get_transcript()
- save_output(data, "Transcript.json", output, stdout)
+ filename = "Transcript.json"
+ if pretty and isinstance(data, dict) and isinstance(data.get('data'), str) and '" + "".join(f"| {v} | " for v in
+ ("1", "202", "Fall2026", "PRO192", "", "", "Object Oriented Programming", "3", "8.5", "Passed")) + ""
+ "" + "".join(f"| {v} | " for v in
+ ("2", "202", "Fall2026", "MAL202", "PRO192", "", "Linear Algebra", "3", "", "Not Passed")) + "
"
+ )
+ extra = (
+ "" + "".join(f"| {v} | " for v in
+ ("1", "Spring2027", "SSG103", "Soft Skill", "2", "7.0", "Passed")) + "
"
+ )
+ def header(names):
+ return "" + "".join(f"| {n} | " for n in names) + "
"
+ return (
+ "" + header(TranscriptHtmlTests.MAIN_HEADERS) + main + "
"
+ "" + header(TranscriptHtmlTests.EXTRA_HEADERS) + extra + "
"
+ )
+
+ def setUp(self):
+ from myfap.parsers import parse_transcript_html
+ self.parse = parse_transcript_html
+
+ def test_each_table_keeps_own_headers_and_keyed_rows(self):
+ tables = self.parse(self.fixture())
+ self.assertEqual([table["headers"] for table in tables], [self.MAIN_HEADERS, self.EXTRA_HEADERS])
+ self.assertEqual(tables[0]["rows"][0], {
+ "No": "1", "Term": "202", "Semester": "Fall2026", "Subject Code": "PRO192",
+ "prerequisite": "", "Replaced Subject": "", "Subject Name": "Object Oriented Programming",
+ "Credit": "3", "Grade": "8.5", "Status": "Passed",
+ })
+ self.assertEqual(len(tables[0]["rows"]), 2)
+ self.assertEqual(tables[1]["rows"][0]["SubjectName"], "Soft Skill")
+ self.assertEqual(len(tables[1]["rows"]), 1)
+
+ def test_html_entities_are_decoded_and_extra_cells_get_stable_keys(self):
+ tables = self.parse("")
+ self.assertEqual(tables[0]["rows"][0], {"A": "Số 1", "B": "x", "Column3": "thừa"})
+
+ def test_input_without_table_returns_empty_list(self):
+ self.assertEqual(self.parse("PRIVATE [not a table]
"), [])
+ self.assertEqual(self.parse(""), [])
+
+ def test_data_rows_before_header_are_ignored(self):
+ tables = self.parse("")
+ self.assertEqual(tables[0]["headers"], ["Only"])
+ self.assertEqual(tables[0]["rows"], [{"Only": "ok"}])
+
+
class ScheduleParserTests(unittest.TestCase):
def test_saved_ics_keeps_line_endings_for_independent_reader(self):
data = json.loads((FIXTURES / "schedule_valid.json").read_text(encoding="utf-8"))
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index a806d74..5bbe849 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -258,6 +258,28 @@ def test_transcript_uses_bound_key_without_semester_lookup(self):
self.assertEqual(request.call_args.kwargs["headers"]["Authorization"], "Bearer FAKE_FAP_KEY")
+ def test_transcript_pretty_parses_html_and_default_keeps_raw_string(self):
+ from tests.test_parsers import TranscriptHtmlTests
+
+ html = TranscriptHtmlTests.fixture()
+ for options, expect_parsed in (([], False), (["--pretty"], True)):
+ with self.subTest(options=options):
+ self.save_session("v2")
+ payload = {"code": 200, "data": html}
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "transcript", *options, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ data = json.loads(result.stdout)["data"]
+ if expect_parsed:
+ self.assertEqual([table["headers"] for table in data],
+ [TranscriptHtmlTests.MAIN_HEADERS, TranscriptHtmlTests.EXTRA_HEADERS])
+ self.assertEqual(data[0]["rows"][0]["Subject Code"], "PRO192")
+ else:
+ self.assertEqual(data, html)
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/AcademicTranscript"))
+
+
class TrainingCommandTests(unittest.TestCase):
setUp = BalanceCommandTests.setUp
save_session = BalanceCommandTests.save_session
From c5702d4e842c4919b724be5159bc7c0c53687f2f Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:32:30 +0700
Subject: [PATCH 18/28] =?UTF-8?q?docs:=20ghi=20nh=E1=BA=ADn=20m=E1=BB=A5c?=
=?UTF-8?q?=204-5=20Phase=206=20kh=C3=B3=20th=E1=BB=B1c=20hi=E1=BB=87n=20v?=
=?UTF-8?q?=E1=BB=9Bi=20t=C3=A0i=20kho=E1=BA=A3n=20hi=E1=BB=87n=20t?=
=?UTF-8?q?=E1=BA=A1i?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
tasks/todo.md | 16 ++++++++++++----
1 file changed, 12 insertions(+), 4 deletions(-)
diff --git a/tasks/todo.md b/tasks/todo.md
index cfecfcf..7b454d8 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -56,11 +56,19 @@ Các command đã chạy thật trên v1/APHL sau login mới; chi tiết tại
Cùng lượt, subjects/balance/rating list đọc được và student sau refresh đạt 200/200. Transcript rỗng, photo null và rating list rỗng không xác nhận positive schema hoặc ID hợp lệ cho submit. Session/lock/thư mục tạm đã dọn; chỉ metadata được ghi, không raw response/identity/credential.
-## Thao tác ghi rating/push/feedback vẫn chưa mở
+## Mục 4–5 Phase 6 khó thực hiện với tài khoản hiện tại
-Theo đánh giá của người dùng ngày 24/10/2026, **tài khoản hiện tại không thể xác minh** các thao tác ghi này: rating list v1 trả danh sách rỗng (không có rateid/item để đối chiếu `AddRate`), không có feedback đang mở để thu form/ack. Không cố tình thử ghi để tạo dữ liệu, không coi đây là route lỗi và không mở generic submit.
+Theo đánh giá của maintainer ngày 24/10/2026, **các mục 4 (rating/push) và 5 (feedback đầy đủ) của [phase6.md](phase6.md) không thể thực hiện hoặc xác minh bằng tài khoản hiện tại**:
-- [ ] Khi có tài khoản hoặc dữ liệu phù hợp (rating đang mở, feedback đang mở), thu thập input schema và ack nghiệp vụ 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.
+- **Rating submit (`AddRate`)**: rating list v1 trả danh sách rỗng — không có rateid/positive item để đối chiếu input schema và ack.
+- **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.
+
+Hệ quả khi chốt phạm vi Phase 6 và phát hành `0.2.0`: các mục này giữ trạng thái **gate/unsupported**, không đánh dấu hoàn tất và không mở generic submit; 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.
- [ ] `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 như [phase6.md](phase6.md) mục 4–5; việc chưa xác minh được không tự đóng cũng không nới gate.
+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.
From dc04710f5b1f261a6fc1a24508f2e7dc6d58e663 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:07:06 +0700
Subject: [PATCH 19/28] =?UTF-8?q?docs:=20nghi=E1=BB=87m=20thu=20m=E1=BB=A5?=
=?UTF-8?q?c=206=20phase6=20tr=E1=BB=AB=20h=E1=BB=99p=20duy=E1=BB=87t=20ma?=
=?UTF-8?q?intainer?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 1 +
README.md | 6 ++++--
tasks/phase6.md | 12 +++++++-----
tasks/todo.md | 9 +++++++++
4 files changed, 21 insertions(+), 7 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index eea456f..2fc1687 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,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):** parser bảng điểm chi tiết có thể crash với `rowspan` không phải số nguyên; ICS mất nhãn "(Online)" nếu `isOnline` là boolean và báo lỗi với slot vượt nửa đêm hoặc `slotTime` không có dấu gạch; tên file xuất dựng từ dữ liệu server (tên kỳ/mã môn) chưa sanitize ký tự đường dẫn. Không phải lỗ hổng bảo mật (CLI chạy bởi chính người dùng trên máy họ); quyết định sửa trước `0.2.0` hay ghi nhận known issue thuộc maintainer — theo dõi tại [TODO](tasks/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 0d1efd6..aa22d90 100644
--- a/README.md
+++ b/README.md
@@ -58,15 +58,17 @@ myfap other subjects --semester Fall2026 --stdout
myfap other balance --stdout
myfap news --search "lịch thi" --type 1 --stdout
myfap transcript --stdout
+myfap transcript --pretty --stdout
myfap other training --semester Fall2026 --stdout
myfap marks --summary --stdout
myfap info photo --stdout
+myfap other feedbacks --stdout
myfap other rating list --api-version v1 --stdout
myfap doctor --stdout
myfap doctor --api-version v2 --online --stdout
```
-`marks --summary` không nhận kỳ học/courseid/pretty. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2, không xác nhận tài khoản đã đăng nhập. `other rating list` chỉ hỗ trợ student/v1; v2 là stub và bị chặn. Khác với các lệnh đọc này, rating submit/push/feedback submit còn có gate riêng và chưa được mở.
+`marks --summary` không nhận kỳ học/courseid/pretty. `transcript --pretty` phân tích HTML bảng điểm toàn khóa thành JSON cấu trúc theo header từng bảng; không có `--pretty` giữ nguyên chuỗi gốc. Photo chỉ xuất JSON, không tự tải hoặc giải mã ảnh. Doctor mặc định không đọc session hoặc gọi mạng; `--online` chỉ probe bootstrap proxy v2 (`GetApiActive` và `backend_version` qua `GetVersion`), không xác nhận tài khoản đã đăng nhập. `other feedbacks` chỉ có trên API v2. `other rating list` chỉ hỗ trợ student/v1; v2 là stub và bị chặn. Khác với các lệnh đọc này, rating submit/push/feedback submit còn có gate riêng và chưa được mở.
## Thông tin thêm
- [Chọn API v1 hoặc v2](https://github.com/WindowScary321/myfap-api-cli/blob/main/docs/api-versions.md): v1 vẫn mặc định; v2 hỗ trợ các command đọc hiện có trong Phase 4.
@@ -105,7 +107,7 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
|-sc, --subjectcode |Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname |Chọn lớp học, chỉ có ở command ``attendance``|
|--ics|Convert Sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự, chỉ có ở command ``schedule``)|
-|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, chỉ có ở command ``marks``)|
+|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, có ở command ``marks`` (chi tiết môn) và ``transcript`` (toàn khóa))|
|--output, -o |Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
|-f, --force|Buộc đăng nhập lại, bỏ qua file ``session.json``, chỉ có ở command ``login``|
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 73a14c7..0fd1731 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -73,11 +73,11 @@ Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ
## 6. Kiểm chứng và bàn giao PR
-- [ ] 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.
-- [ ] 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`.
-- [ ] 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.
-- [ ] Review độc lập phần query/credential/parser/write safety và cập nhật README/CHANGELOG/coverage theo đúng kết quả.
-- [ ] 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] 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] 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.
- [ ] 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.
## Kết quả checkpoint hiện tại
@@ -103,3 +103,5 @@ Nghiệm thu mục 3 và mở rộng endpoint hoàn tất ngày 24/10/2026 sau k
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.
Theo yêu cầu mở rộng của maintainer (24/10/2026), `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 và hàng keyed theo header (bảng chính 10 cột `No`…`Status`, bảng phụ 7 cột), chuẩn hoá ` `. Schema chốt bằng phân tích cấu trúc dữ liệu thật trên máy cá nhân (chỉ in skeleton/tên cột, không in giá trị); fixture test tổng hợp theo schema đó. RED→GREEN 5 test (4 parser + 1 CLI seam, gồm nhánh không `--pretty` giữ nguyên chuỗi); full suite 408 test, 404 đạt/4 skip, exit 0; live `--pretty` cho 2 bảng 49+2 dòng đúng header thật, mặc định vẫn giữ chuỗi HTML theo contract cũ.
+
+Nghiệm thu mục 6 hoàn tất ngày 24/10/2026, trừ hộp cuối chờ maintainer. (1) RED→GREEN ghi cho từng feature mới (feedbacks 3 test, doctor GetVersion, transcript --pretty 5 test) qua CLI thật + HTTP giả, fixture tổng hợp; mutation check trên worktree tạm 3/3 bị test bắt: đổi casing query `semester`→`Semester` ở `get_courses`, đổi signer SearchNews từ type sang `MAGIC_ID`, bỏ guard no-retry trong `_get` — đều làm focused test fail rồi khôi phục. (2) `uv sync --locked --group ci` sạch; full suite **408 test, 404 đạt/4 skip, exit 0 trên cả Python 3.11 lẫn 3.9** (venv 3.9 tạm riêng); `git diff --check` sạch. (3) Build/Twine/validator/pip smoke chạy lại trên commit cuối: manifest SHA-256 `b15ff78b0a7fcca70b249258dbcd4479253bc702eace8bc7b079879caa848131`; CI GitHub Actions đạt trên commit code `8529176` (matrix Ubuntu/Windows × Python 3.9/3.11). (4) Lượt review thứ hai có cấu trúc trên toàn bộ diff PR (14 file code/test, +1355/−30) theo 4 trục: query contract, credential và write safety sạch (khớp mutation và test); parser ghi 4 finding robustness (rowspan rác, `isOnline` boolean, slot vượt nửa đêm, sanitize tên file xuất) — đã ghi vào CHANGELOG known issues và TODO, không phải lỗ hổng bảo mật, chờ maintainer quyết sửa trước `0.2.0` hay nhận known issue. Giới hạn trung thực: kênh agent review độc lập bị giới hạn concurrency của tài khoản sau 4 lần thử, lượt review này do session reviewer thực hiện. README/CHANGELOG/coverage cập nhật theo đúng kết quả. (5) PR #10 Draft từ nhánh riêng; mọi commit push đều có comment SHA/lệnh/exit code/giới hạn.
diff --git a/tasks/todo.md b/tasks/todo.md
index 7b454d8..f93c3cb 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -72,3 +72,12 @@ Hệ quả khi chốt phạm vi Phase 6 và phát hành `0.2.0`: các mục này
- [ ] `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.
+
+## Finding robustness từ review Phase 6 (24/10/2026)
+
+Lượt review lượt hai trên toàn bộ diff PR #10 theo 4 trục (query/credential/parser/write safety): query contract, credential và write safety sạch; parser có bốn finding, đều không phải lỗ hổng bảo mật (CLI chạy bởi chính người dùng trên máy họ). Maintainer quyết định sửa trước khi tag `0.2.0` hay phát hành với known issues:
+
+- [ ] `parse_marks_html` crash khi `rowspan` không phải số nguyên (`myfap/parsers.py` — `int(tds[0]['rowspan'])` với giá trị như `2.0`/rỗng); sửa nhỏ: bọc an toàn, giá trị rác coi như 1.
+- [ ] ICS: `isOnline` dạng boolean làm mất nhãn "(Online)" (`parsers.py`); slot vượt nửa đêm (VD `23:30-0:50`) và `slotTime` không có dấu gạch gây lỗi thông báo khó hiểu.
+- [ ] `save_output` dựng tên file từ dữ liệu server (tên kỳ tự chọn) và input user chưa sanitize ký tự đường dẫn; có thể thoát thư mục `--output` nếu giá trị chứa `..`. Sửa nhỏ: sanitize thành phần tên file hoặc kiểm tra path chuẩn hoá nằm trong thư mục xuất.
+- [ ] (low) Chưa có test cho nhánh `transcript --pretty` khi data không phải HTML (giữ nguyên chuỗi).
From 32d98e77a9f0136ef18fc90762b7d3160954ca19 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:47:02 +0700
Subject: [PATCH 20/28] =?UTF-8?q?fix:=20l=C3=A0m=20b=E1=BB=81n=20parser=20?=
=?UTF-8?q?v=C3=A0=20sanitize=20t=C3=AAn=20file=20xu=E1=BA=A5t=20theo=20qu?=
=?UTF-8?q?y=E1=BA=BFt=20=C4=91=E1=BB=8Bnh=20maintainer?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
myfap/cli.py | 4 +++-
myfap/parsers.py | 25 ++++++++++++++++++-----
tests/test_parsers.py | 47 +++++++++++++++++++++++++++++++++++++++++++
3 files changed, 70 insertions(+), 6 deletions(-)
diff --git a/myfap/cli.py b/myfap/cli.py
index 57d8e2c..a022520 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -164,7 +164,9 @@ def save_output(data, default_filename: str, output_dir: Optional[str], stdout:
out_path = Path(output_dir) if output_dir else Path.cwd()
out_path.mkdir(parents=True, exist_ok=True)
- file_path = out_path / default_filename
+ # 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", "_")
+ file_path = out_path / safe_filename
try:
with open(file_path, "w", encoding="utf-8", newline="" if is_text else None) as f:
diff --git a/myfap/parsers.py b/myfap/parsers.py
index 5abffe4..e447851 100644
--- a/myfap/parsers.py
+++ b/myfap/parsers.py
@@ -1,5 +1,13 @@
from bs4 import BeautifulSoup
+def _rowspan_rows(value):
+ # rowspan rác từ server (VD "2.0", rỗng) coi như 1 để không crash parser.
+ try:
+ return max(1, int(value))
+ except (TypeError, ValueError):
+ return 1
+
+
def parse_marks_html(html_str: str):
"""Phân tích chuỗi HTML bảng điểm thành danh sách các đối tượng JSON (dict)"""
soup = BeautifulSoup(html_str, 'html.parser')
@@ -29,7 +37,7 @@ def parse_marks_html(html_str: str):
# Nhận diện dòng có category mới (td đầu tiên có rowspan)
if len(tds) >= 3 and tds[0].has_attr('rowspan'):
current_category = td_texts[0]
- category_rows_remaining = max(0, int(tds[0]['rowspan']) - 1)
+ category_rows_remaining = _rowspan_rows(tds[0]['rowspan']) - 1
data_tds = td_texts[1:]
elif len(tds) >= 2 and tds[0].has_attr('colspan') and current_category:
# Giữ cấu trúc output của dòng tổng kết hiện có.
@@ -101,7 +109,7 @@ def cell_text(node):
return tables
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
import pytz
from ics import Calendar, Event
@@ -124,18 +132,25 @@ def convert_schedule_to_ics(data: dict) -> str:
# Parse time: "(7:30-9:50)" -> "7:30", "9:50"
time_str = session["slotTime"].strip().strip("()").strip()
- start_time_str, end_time_str = (part.strip() for part in time_str.split("-", 1))
-
+ try:
+ start_time_str, end_time_str = (part.strip() for part in time_str.split("-", 1))
+ except ValueError:
+ raise ValueError("slotTime phải có dạng (giờ bắt đầu-giờ kết thúc), ví dụ (7:30-9:50).") from None
+
# Parse full datetime
start_dt = tz.localize(datetime.strptime(f"{date_str} {start_time_str}", "%m/%d/%Y %H:%M"))
end_dt = tz.localize(datetime.strptime(f"{date_str} {end_time_str}", "%m/%d/%Y %H:%M"))
+ # Slot kết thúc trước giờ bắt đầu nghĩa là vượt nửa đêm: kết thúc sang ngày hôm sau.
+ if end_dt <= start_dt:
+ end_dt += timedelta(days=1)
# Create event
e = Event(created=datetime.now(timezone.utc))
# Title
title = session['subjectCode']
- if session.get("isOnline") == "True":
+ is_online = session.get("isOnline")
+ if is_online is True or is_online == "True":
title += " (Online)"
e.name = title
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index 8675fce..785ec9e 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -71,6 +71,15 @@ def test_legacy_three_columns_with_category_are_preserved(self):
self.assertEqual(parse_marks_html(html), [{"category": "Final", "item": "FE", "value": "7.3"}])
+ def test_garbage_rowspan_does_not_crash_and_keeps_own_row(self):
+ for rowspan in ("2.0", "abc", ""):
+ with self.subTest(rowspan=rowspan):
+ html = ("| Item | Weight | Value | "
+ f"| Quiz | Q1 | 10% | 8 | "
+ "| Q2 | 20% | 7 | ")
+ rows = parse_marks_html(html)
+ self.assertEqual(rows[0], {"category": "Quiz", "item": "Q1", "weight": "10%", "value": "8"})
+
class TranscriptHtmlTests(unittest.TestCase):
MAIN_HEADERS = ["No", "Term", "Semester", "Subject Code", "prerequisite",
@@ -205,6 +214,44 @@ def test_ics_preserves_vietnam_time_and_session_details(self):
"Room: Demo room", "Meet URL: https://example.invalid/meet",
]))
+ def test_boolean_is_online_still_marks_online_title(self):
+ data = json.loads((FIXTURES / "schedule_valid.json").read_text(encoding="utf-8"))
+ data["data"][0]["isOnline"] = True
+
+ event = next(iter(Calendar(convert_schedule_to_ics(data)).events))
+
+ self.assertEqual(event.name, "TEST101 (Online)")
+
+ def test_overnight_slot_wraps_end_to_next_day(self):
+ data = json.loads((FIXTURES / "schedule_valid.json").read_text(encoding="utf-8"))
+ data["data"][0]["slotTime"] = "(23:30-0:50)"
+
+ event = next(iter(Calendar(convert_schedule_to_ics(data)).events))
+
+ # 23:30 và 0:50 (hôm sau) giờ Việt Nam = 16:30 và 17:50 UTC cùng ngày 15/10.
+ self.assertEqual(event.begin.datetime, datetime(2026, 10, 15, 16, 30, tzinfo=timezone.utc))
+ 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_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"
+
+ with self.assertRaises(ValueError) as caught:
+ convert_schedule_to_ics(data)
+ self.assertIn("slotTime", str(caught.exception))
+ self.assertIn("7:30-9:50", str(caught.exception))
+
+
+class SaveOutputSanitizationTests(unittest.TestCase):
+ def test_server_influenced_filename_stays_inside_output_dir(self):
+ with TemporaryDirectory() as temporary, redirect_stderr(io.StringIO()):
+ save_output({"code": 200, "data": []}, "BangDiem_x/../../evil.json", temporary, False)
+ files = sorted(path.name for path in Path(temporary).iterdir())
+ self.assertEqual(files, ["BangDiem_x_.._.._evil.json"])
+ content = json.loads((Path(temporary) / files[0]).read_text(encoding="utf-8"))
+ self.assertEqual(content, {"code": 200, "data": []})
+
def test_empty_schedule_returns_valid_empty_calendar(self):
data = json.loads((FIXTURES / "schedule_empty.json").read_text(encoding="utf-8"))
From acbcce81ac3ef406954e892f2429188bbd47a7f1 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:47:02 +0700
Subject: [PATCH 21/28] =?UTF-8?q?docs:=20ghi=20nh=E1=BA=ADn=20nghi?=
=?UTF-8?q?=E1=BB=87m=20thu=20maintainer=20v=C3=A0=20=C4=91=C3=B3ng=20find?=
=?UTF-8?q?ing=20robustness?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 2 +-
tasks/phase6.md | 4 +++-
tasks/todo.md | 8 ++++----
3 files changed, 8 insertions(+), 6 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2fc1687..95e3a6c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,7 +38,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):** parser bảng điểm chi tiết có thể crash với `rowspan` không phải số nguyên; ICS mất nhãn "(Online)" nếu `isOnline` là boolean và báo lỗi với slot vượt nửa đêm hoặc `slotTime` không có dấu gạch; tên file xuất dựng từ dữ liệu server (tên kỳ/mã môn) chưa sanitize ký tự đường dẫn. Không phải lỗ hổng bảo mật (CLI chạy bởi chính người dùng trên máy họ); quyết định sửa trước `0.2.0` hay ghi nhận known issue thuộc maintainer — theo dõi 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](tasks/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/tasks/phase6.md b/tasks/phase6.md
index 0fd1731..37cb7f0 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -78,7 +78,7 @@ Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ
- [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] 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.
-- [ ] 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.
+- [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.
## Kết quả checkpoint hiện tại
@@ -105,3 +105,5 @@ Checkpoint nhóm đọc khép ngày 24/10/2026. (1) Build/Twine/validator/pip sm
Theo yêu cầu mở rộng của maintainer (24/10/2026), `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 và hàng keyed theo header (bảng chính 10 cột `No`…`Status`, bảng phụ 7 cột), chuẩn hoá ` `. Schema chốt bằng phân tích cấu trúc dữ liệu thật trên máy cá nhân (chỉ in skeleton/tên cột, không in giá trị); fixture test tổng hợp theo schema đó. RED→GREEN 5 test (4 parser + 1 CLI seam, gồm nhánh không `--pretty` giữ nguyên chuỗi); full suite 408 test, 404 đạt/4 skip, exit 0; live `--pretty` cho 2 bảng 49+2 dòng đúng header thật, mặc định vẫn giữ chuỗi HTML theo contract cũ.
Nghiệm thu mục 6 hoàn tất ngày 24/10/2026, trừ hộp cuối chờ maintainer. (1) RED→GREEN ghi cho từng feature mới (feedbacks 3 test, doctor GetVersion, transcript --pretty 5 test) qua CLI thật + HTTP giả, fixture tổng hợp; mutation check trên worktree tạm 3/3 bị test bắt: đổi casing query `semester`→`Semester` ở `get_courses`, đổi signer SearchNews từ type sang `MAGIC_ID`, bỏ guard no-retry trong `_get` — đều làm focused test fail rồi khôi phục. (2) `uv sync --locked --group ci` sạch; full suite **408 test, 404 đạt/4 skip, exit 0 trên cả Python 3.11 lẫn 3.9** (venv 3.9 tạm riêng); `git diff --check` sạch. (3) Build/Twine/validator/pip smoke chạy lại trên commit cuối: manifest SHA-256 `b15ff78b0a7fcca70b249258dbcd4479253bc702eace8bc7b079879caa848131`; CI GitHub Actions đạt trên commit code `8529176` (matrix Ubuntu/Windows × Python 3.9/3.11). (4) Lượt review thứ hai có cấu trúc trên toàn bộ diff PR (14 file code/test, +1355/−30) theo 4 trục: query contract, credential và write safety sạch (khớp mutation và test); parser ghi 4 finding robustness (rowspan rác, `isOnline` boolean, slot vượt nửa đêm, sanitize tên file xuất) — đã ghi vào CHANGELOG known issues và TODO, không phải lỗ hổng bảo mật, chờ maintainer quyết sửa trước `0.2.0` hay nhận known issue. Giới hạn trung thực: kênh agent review độc lập bị giới hạn concurrency của tài khoản sau 4 lần thử, lượt review này do session reviewer thực hiện. README/CHANGELOG/coverage cập nhật theo đúng kết quả. (5) PR #10 Draft từ nhánh riêng; mọi commit push đều có comment SHA/lệnh/exit code/giới hạn.
+
+Maintainer nghiệm thu phạm vi Phase 6 ngày 24/10/2026 qua hai quyết định ghi rõ: (a) **chấp nhận phạm vi** — toàn bộ read student v1+v2, doctor, transcript --pretty; mục 4–5 giữ gate vì không thể xác minh với tài khoản hiện tại; 7 lỗi v1 là known issues; positive fee/survey hoãn; (b) **chọn sửa 4 finding robustness trước phát hành** thay vì ghi known issues — đã sửa kèm 5 test regression (rowspan rác coi như 1; ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang hôm sau, `slotTime` thiếu dấu gạch báo lỗi rõ; `save_output` thay ký tự đường dẫn trong tên file), full suite 413 test, 409 đạt/4 skip, exit 0. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
diff --git a/tasks/todo.md b/tasks/todo.md
index f93c3cb..f5cd121 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -77,7 +77,7 @@ Các gate và trình tự validate → capability → preview → confirmation
Lượt review lượt hai trên toàn bộ diff PR #10 theo 4 trục (query/credential/parser/write safety): query contract, credential và write safety sạch; parser có bốn finding, đều không phải lỗ hổng bảo mật (CLI chạy bởi chính người dùng trên máy họ). Maintainer quyết định sửa trước khi tag `0.2.0` hay phát hành với known issues:
-- [ ] `parse_marks_html` crash khi `rowspan` không phải số nguyên (`myfap/parsers.py` — `int(tds[0]['rowspan'])` với giá trị như `2.0`/rỗng); sửa nhỏ: bọc an toàn, giá trị rác coi như 1.
-- [ ] ICS: `isOnline` dạng boolean làm mất nhãn "(Online)" (`parsers.py`); slot vượt nửa đêm (VD `23:30-0:50`) và `slotTime` không có dấu gạch gây lỗi thông báo khó hiểu.
-- [ ] `save_output` dựng tên file từ dữ liệu server (tên kỳ tự chọn) và input user chưa sanitize ký tự đường dẫn; có thể thoát thư mục `--output` nếu giá trị chứa `..`. Sửa nhỏ: sanitize thành phần tên file hoặc kiểm tra path chuẩn hoá nằm trong thư mục xuất.
-- [ ] (low) Chưa có test cho nhánh `transcript --pretty` khi data không phải HTML (giữ nguyên chuỗi).
+- [x] `parse_marks_html` crash khi `rowspan` không phải số nguyên (`myfap/parsers.py`) — **đã sửa 24/10/2026**: giá trị rác coi như 1, kèm test regression.
+- [x] ICS: `isOnline` boolean mất nhãn "(Online)"; slot vượt nửa đêm và `slotTime` không dấu gạch — **đã sửa 24/10/2026**: nhận boolean, slot kết thúc sang ngày hôm sau, lỗi `slotTime` có thông báo rõ; kèm test.
+- [x] `save_output` sanitize tên file xuất — **đã sửa 24/10/2026**: thay `/`, `\` và NUL bằng `_`, file luôn nằm trong thư mục `--output`; kèm test.
+- [x] (low) Test nhánh `transcript --pretty` khi data không phải HTML — **đã có**: test CLI seam phủ cả nhánh giữ nguyên chuỗi gốc.
From b2dd9f6ca2fde2045742429163735b2425599120 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:24:56 +0700
Subject: [PATCH 22/28] =?UTF-8?q?feat:=20myfap=20exams=20--ics=20xu?=
=?UTF-8?q?=E1=BA=A5t=20l=E1=BB=8Bch=20thi=20sang=20=C4=91=E1=BB=8Bnh=20d?=
=?UTF-8?q?=E1=BA=A1ng=20iCalendar?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
myfap/cli.py | 14 +++++---
myfap/parsers.py | 53 +++++++++++++++++++++++++++++++
tests/test_parsers.py | 65 ++++++++++++++++++++++++++++++++++++++
tests/test_phase6_reads.py | 29 +++++++++++++++++
4 files changed, 157 insertions(+), 4 deletions(-)
diff --git a/myfap/cli.py b/myfap/cli.py
index a022520..1fcb24a 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -15,7 +15,7 @@
from .auth import MyFapAuth, SessionBindingError
from .api import MyFapClient, MyFapEssential, MyFapOther
-from .parsers import parse_marks_html, parse_transcript_html, convert_schedule_to_ics
+from .parsers import parse_marks_html, parse_transcript_html, convert_schedule_to_ics, convert_exams_to_ics
from .config import resolve_timeout
from importlib import metadata
@@ -467,6 +467,7 @@ def marks(
@app.command()
def exams(
semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học (VD: Summer2026)"),
+ ics: bool = typer.Option(False, "--ics", help="Xuất lịch thi ra định dạng iCalendar (.ics)"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
@@ -474,12 +475,17 @@ def exams(
auth = require_auth("GetScheduleExam")
client = MyFapClient(auth)
sem = resolve_semester(auth, semester)
-
+
try:
with err_console.status("[bold green]Đang tải lịch thi..."):
data = client.get_exams(sem)
- filename = f"LichThi_{sem}.json"
- save_output(data, filename, output, stdout)
+ if ics:
+ ics_content = convert_exams_to_ics(data)
+ filename = f"LichThi_{sem}.ics"
+ save_output(ics_content, filename, output, stdout, is_text=True)
+ else:
+ filename = f"LichThi_{sem}.json"
+ save_output(data, filename, output, stdout)
except Exception as e:
err_console.print(f"[red]Lỗi lấy lịch thi: {e}[/red]")
raise typer.Exit(code=1)
diff --git a/myfap/parsers.py b/myfap/parsers.py
index e447851..a3dc285 100644
--- a/myfap/parsers.py
+++ b/myfap/parsers.py
@@ -1,4 +1,5 @@
from bs4 import BeautifulSoup
+import re
def _rowspan_rows(value):
# rowspan rác từ server (VD "2.0", rỗng) coi như 1 để không crash parser.
@@ -109,6 +110,58 @@ def cell_text(node):
return tables
+def convert_exams_to_ics(data: dict) -> str:
+ """Chuyển dữ liệu lịch thi JSON thành chuỗi ICS"""
+ if not isinstance(data, dict) or not isinstance(data.get("data"), list):
+ raise ValueError("Invalid JSON format")
+
+ c = Calendar()
+ tz = pytz.timezone("Asia/Ho_Chi_Minh")
+
+ for exam in data["data"]:
+ if (not isinstance(exam, dict)
+ or any(not isinstance(exam.get(field), str) or not exam[field].strip()
+ for field in ("date", "time", "subjectCode"))):
+ raise ValueError("Invalid exam: date, time and subjectCode are required")
+ try:
+ day = datetime.strptime(exam["date"].split("T")[0].strip(), "%Y-%m-%d")
+ normalized = exam["time"].strip().strip("()").replace(" ", "")
+ match = re.fullmatch(r"(\d{1,2})h(\d{2})-(\d{1,2})h(\d{2})", normalized)
+ if match is None:
+ raise ValueError
+ start_dt = tz.localize(datetime.strptime(
+ f"{day:%Y-%m-%d} {match.group(1)}:{match.group(2)}", "%Y-%m-%d %H:%M"))
+ end_dt = tz.localize(datetime.strptime(
+ f"{day:%Y-%m-%d} {match.group(3)}:{match.group(4)}", "%Y-%m-%d %H:%M"))
+ except ValueError:
+ raise ValueError(
+ "Invalid exam: date hoặc time không hợp lệ (date dạng YYYY-MM-DD, time dạng 7h30-9h50).") from None
+ # Kỳ thi kết thúc trước giờ bắt đầu nghĩa là vượt nửa đêm: kết thúc sang ngày hôm sau.
+ if end_dt <= start_dt:
+ end_dt += timedelta(days=1)
+
+ e = Event(created=datetime.now(timezone.utc))
+ title = exam["subjectCode"]
+ kythi = exam.get("kythi")
+ if isinstance(kythi, str) and kythi.strip():
+ title += f" ({kythi.strip()})"
+ e.name = title
+ e.begin = start_dt
+ e.end = end_dt
+ e.location = exam.get("roomNo") or ""
+ desc = []
+ for label, field in (("Môn", "subjectName"), ("Phòng", "roomNo"), ("Slot", "slot"), ("Ghi chú", "note")):
+ value = exam.get(field)
+ if isinstance(value, str) and value.strip():
+ desc.append(f"{label}: {value.strip()}")
+ e.description = "\n".join(desc)
+
+ c.events.add(e)
+
+ # Trả về chuỗi ICS
+ return "".join(c.serialize_iter())
+
+
from datetime import datetime, timedelta, timezone
import pytz
from ics import Calendar, Event
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index 785ec9e..017b5bd 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -243,6 +243,71 @@ def test_slot_without_separator_raises_clear_message(self):
self.assertIn("7:30-9:50", str(caught.exception))
+class ExamsParserTests(unittest.TestCase):
+ @staticmethod
+ def fixture_data(**overrides):
+ row = {
+ "subjectCode": "TEST101", "realSubject": "TEST101", "subjectName": "Môn thử nghiệm",
+ "date": "2026-10-20T00:00:00", "slot": "Synthetic slot text (7h30-9h50)", "time": "7h30-9h50",
+ "note": "", "roomNo": "SY-101", "dateofPublication": "2026-10-01T00:00:00",
+ "kythi": "FE", "note_Attendance": "", "isGraduated": False,
+ }
+ row.update(overrides)
+ return {"code": "200", "data": [row]}
+
+ def setUp(self):
+ from myfap.parsers import convert_exams_to_ics
+ self.convert = convert_exams_to_ics
+
+ def test_valid_exams_build_calendar_with_uid_dtstamp_and_vietnam_time(self):
+ content = self.convert(self.fixture_data()).encode("utf-8")
+ calendar = IndependentCalendar.from_ical(content)
+ events = calendar.walk("VEVENT")
+ self.assertEqual(len(events), 1)
+ event = events[0]
+ self.assertEqual(str(event["SUMMARY"]), "TEST101 (FE)")
+ self.assertEqual(event.decoded("DTSTART"), datetime(2026, 10, 20, 0, 30, tzinfo=timezone.utc))
+ self.assertEqual(event.decoded("DTEND"), datetime(2026, 10, 20, 2, 50, tzinfo=timezone.utc))
+ properties = [name for name, _ in event.property_items()]
+ self.assertEqual(properties.count("UID"), 1)
+ self.assertEqual(properties.count("DTSTAMP"), 1)
+ self.assertRegex(event["DTSTAMP"].to_ical().decode("ascii"), r"^\d{8}T\d{6}Z$")
+ self.assertIn("Môn thử nghiệm".encode("utf-8"), content)
+ self.assertIn(b"\r\n", content)
+ self.assertNotIn(b"\r\r\n", content)
+
+ def test_time_with_spaces_and_parentheses_is_accepted(self):
+ for time in ("7h30 - 9h50", "(7h30-9h50)", " ( 7h30-9h50 ) "):
+ with self.subTest(time=time):
+ content = self.convert(self.fixture_data(time=time))
+ event = IndependentCalendar.from_ical(content).walk("VEVENT")[0]
+ self.assertEqual(event.decoded("DTSTART"), datetime(2026, 10, 20, 0, 30, tzinfo=timezone.utc))
+
+ def test_overnight_exam_wraps_end_to_next_day(self):
+ content = self.convert(self.fixture_data(time="23h30-0h50"))
+ event = IndependentCalendar.from_ical(content).walk("VEVENT")[0]
+ self.assertEqual((event.decoded("DTEND") - event.decoded("DTSTART")).total_seconds(), 80 * 60)
+
+ def test_invalid_root_or_rows_are_rejected_with_clear_errors(self):
+ cases = (
+ (None, "Invalid JSON format"),
+ ({}, "Invalid JSON format"),
+ ({"data": None}, "Invalid JSON format"),
+ ({"data": [None]}, "date, time"),
+ ({"data": [{}]}, "date, time"),
+ (self.fixture_data(subjectCode=" "), "date, time"),
+ (self.fixture_data(date="20/10/2026T00:00:00"), "date"),
+ (self.fixture_data(time="7:30-9:50"), "time"),
+ (self.fixture_data(time="7h30"), "time"),
+ (self.fixture_data(time="7h99-9h50"), "time"),
+ )
+ for data, message in cases:
+ with self.subTest(data=data, message=message):
+ with self.assertRaises(ValueError) as caught:
+ self.convert(data)
+ self.assertIn(message, str(caught.exception))
+
+
class SaveOutputSanitizationTests(unittest.TestCase):
def test_server_influenced_filename_stays_inside_output_dir(self):
with TemporaryDirectory() as temporary, redirect_stderr(io.StringIO()):
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 5bbe849..54e1a89 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -441,6 +441,35 @@ def test_feedbacks_v1_is_rejected_before_http(self):
request.assert_not_called()
+class ExamsIcsCommandTests(unittest.TestCase):
+ setUp = BalanceCommandTests.setUp
+ save_session = BalanceCommandTests.save_session
+
+ ROW = {"subjectCode": "TEST101", "realSubject": "TEST101", "subjectName": "Môn thử nghiệm",
+ "date": "2026-10-20T00:00:00", "slot": "Synthetic slot (7h30-9h50)", "time": "7h30-9h50",
+ "note": "", "roomNo": "SY-101", "dateofPublication": "2026-10-01T00:00:00",
+ "kythi": "FE", "note_Attendance": "", "isGraduated": False}
+
+ def test_exams_ics_outputs_calendar_and_plain_keeps_json(self):
+ payload = {"code": 200, "data": [dict(self.ROW)]}
+ for options, expect_ics in (([], False), (["--ics"], True)):
+ with self.subTest(options=options):
+ self.save_session("v2")
+ with patch("requests.Session.request", return_value=response(payload)) as request:
+ result = self.runner.invoke(app, ["--config", str(self.path), "exams", "--semester", "FAKE_TERM", *options, "--stdout"])
+ self.assertEqual(result.exit_code, 0, result.output)
+ if expect_ics:
+ self.assertTrue(result.stdout.startswith("BEGIN:VCALENDAR"))
+ self.assertIn("BEGIN:VEVENT", result.stdout)
+ self.assertIn("TEST101 (FE)", result.stdout)
+ else:
+ self.assertEqual(json.loads(result.stdout), payload)
+ request.assert_called_once()
+ self.assertTrue(request.call_args.args[1].endswith("/GetScheduleExam"))
+ query = request.call_args.kwargs["params"]
+ self.assertEqual(query.get("Semester"), "FAKE_TERM")
+
+
class ReadSliceAcceptanceTests(unittest.TestCase):
"""Nghiệm thu nhóm mục 1: header contract và ma trận lỗi tại seam CLI."""
From a73c1fa372b5d9d1b04dec3f6759abaa2a627b2b Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:24:56 +0700
Subject: [PATCH 23/28] =?UTF-8?q?docs:=20c=E1=BA=ADp=20nh=E1=BA=ADt=20t?=
=?UTF-8?q?=C3=A0i=20li=E1=BB=87u=20cho=20exams=20--ics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 1 +
README.md | 2 +-
docs/command-endpoints.md | 2 +-
docs/phase6-coverage.md | 2 ++
tasks/phase6.md | 4 +++-
5 files changed, 8 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95e3a6c..439bdd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### API và dữ liệu
+- Thêm tùy chọn `--ics` cho `myfap exams`: xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545, mỗi sự kiện có UID/DTSTAMP UTC, giờ Việt Nam, giữ CRLF; tiêu đề gồm mã môn và kỳ thi (VD `TEST101 (FE)`).
- 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.
diff --git a/README.md b/README.md
index aa22d90..7de7220 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,7 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
|-d, --date \|Chỉ định ngày chính xác, chỉ có ở command ``week-timetable``|
|-sc, --subjectcode |Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname |Chọn lớp học, chỉ có ở command ``attendance``|
-|--ics|Convert Sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự, chỉ có ở command ``schedule``)|
+|--ics|Convert Sang **ICS**, dễ dàng import lịch vào Google Calendar hoặc các dịch vụ tương tự, áp dụng cho command ``schedule`` (lịch học) và ``exams`` (lịch thi))|
|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, có ở command ``marks`` (chi tiết môn) và ``transcript`` (toàn khóa))|
|--output, -o |Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index 6b8c025..ffd0572 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -34,7 +34,7 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| `week-timetable` | `GetActivityStudentByWeek` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetActivityStudentByWeek` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetActivityStudentByWeek` | Student/read; live v2/HN 200/200 |
| `marks` | `GetStudentMark` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentMark` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentMark` | Student/read; lượt mới v2/HN 200/200 với danh sách rỗng |
| `marks --courseid`, thêm `--pretty` để parse HTML | `GetMarkByCourse` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetMarkByCourse` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetMarkByCourse` | Fixture hai version; lượt mới skip vì không lấy được CourseId phù hợp, không ghi live pass |
-| `exams` | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; live v2/HN 200/200 |
+| `exams`, `exams --ics` | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; live JSON v2/HN đạt, `--ics` tạo iCalendar RFC 5545 chuẩn CRLF (7 sự kiện trên tài khoản kiểm chứng) |
| `attendance` | `GetStudentAttendances` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentAttendances` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentAttendances` | Student/read; live v2/HN 200/200 |
| `attendance --subjectcode --classname` | `getCourseAttendance` / `GetCourseAttendance` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/getCourseAttendance` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetCourseAttendance` | Fixture alias/case; lượt mới skip vì không lấy được cặp tham số phù hợp |
| `applications` | `GetApplication` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetApplication` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApplication` | Student/read; live v2/HN 200/200 với danh sách rỗng |
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index b33d57a..bbedebf 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -147,3 +147,5 @@ Full suite sau hai feature: 403 test, 399 đạt/4 skip, exit 0 trên Windows Py
| Ghi chú harness | Lượt chính bị lỗi harness ở `semesters --stdout` (lệnh bảng không có option này → exit 2, không phải lỗi CLI; chạy lại đúng cú pháp ở lượt phụ). `other subjects --semester` không lặp lại trong lượt này vì cùng lỗi; bằng chứng lượt 24/10 trước (200/200, input kỳ từ API thật) vẫn đứng |
Không đóng các mục cấm: positive fee/survey giữ mở (dữ liệu chưa đối chiếu nghiệp vụ), các finding v1 giữ nguyên — không dùng kết quả v2 để đóng. Transcript HTML và các formatter nghiệp vụ tiếp tục nhãn chưa kiểm chứng.
+
+- **`myfap exams --ics`**: mở rộng xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545, mỗi sự kiện có UID/DTSTAMP UTC, giờ Việt Nam, giữ CRLF; tiêu đề gồm mã môn và kỳ thi (VD `TEST101 (FE)`). RED→GREEN qua parser converter và CLI seam; live v2/HN đạt 7 sự kiện thật trên tài khoản kiểm chứng. Mặc định không `--ics` vẫn giữ JSON nguyên bản.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 37cb7f0..d920b80 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -106,4 +106,6 @@ Theo yêu cầu mở rộng của maintainer (24/10/2026), `transcript --pretty`
Nghiệm thu mục 6 hoàn tất ngày 24/10/2026, trừ hộp cuối chờ maintainer. (1) RED→GREEN ghi cho từng feature mới (feedbacks 3 test, doctor GetVersion, transcript --pretty 5 test) qua CLI thật + HTTP giả, fixture tổng hợp; mutation check trên worktree tạm 3/3 bị test bắt: đổi casing query `semester`→`Semester` ở `get_courses`, đổi signer SearchNews từ type sang `MAGIC_ID`, bỏ guard no-retry trong `_get` — đều làm focused test fail rồi khôi phục. (2) `uv sync --locked --group ci` sạch; full suite **408 test, 404 đạt/4 skip, exit 0 trên cả Python 3.11 lẫn 3.9** (venv 3.9 tạm riêng); `git diff --check` sạch. (3) Build/Twine/validator/pip smoke chạy lại trên commit cuối: manifest SHA-256 `b15ff78b0a7fcca70b249258dbcd4479253bc702eace8bc7b079879caa848131`; CI GitHub Actions đạt trên commit code `8529176` (matrix Ubuntu/Windows × Python 3.9/3.11). (4) Lượt review thứ hai có cấu trúc trên toàn bộ diff PR (14 file code/test, +1355/−30) theo 4 trục: query contract, credential và write safety sạch (khớp mutation và test); parser ghi 4 finding robustness (rowspan rác, `isOnline` boolean, slot vượt nửa đêm, sanitize tên file xuất) — đã ghi vào CHANGELOG known issues và TODO, không phải lỗ hổng bảo mật, chờ maintainer quyết sửa trước `0.2.0` hay nhận known issue. Giới hạn trung thực: kênh agent review độc lập bị giới hạn concurrency của tài khoản sau 4 lần thử, lượt review này do session reviewer thực hiện. README/CHANGELOG/coverage cập nhật theo đúng kết quả. (5) PR #10 Draft từ nhánh riêng; mọi commit push đều có comment SHA/lệnh/exit code/giới hạn.
-Maintainer nghiệm thu phạm vi Phase 6 ngày 24/10/2026 qua hai quyết định ghi rõ: (a) **chấp nhận phạm vi** — toàn bộ read student v1+v2, doctor, transcript --pretty; mục 4–5 giữ gate vì không thể xác minh với tài khoản hiện tại; 7 lỗi v1 là known issues; positive fee/survey hoãn; (b) **chọn sửa 4 finding robustness trước phát hành** thay vì ghi known issues — đã sửa kèm 5 test regression (rowspan rác coi như 1; ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang hôm sau, `slotTime` thiếu dấu gạch báo lỗi rõ; `save_output` thay ký tự đường dẫn trong tên file), full suite 413 test, 409 đạt/4 skip, exit 0. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
+Maintainer nghiệm thu phạm vi Phase 6 ngày 24/10/2026 qua hai quyết định ghi rõ: (a) **chấp nhận phạm vi** — toàn bộ read student v1+v2, doctor, transcript --pretty; mục 4–5 giữ gate vì không thể xác minh với tài khoản hiện tại; 7 lỗi v1 là known issues; positive fee/survey hoãn; (b) **chọn sửa 4 finding robustness trước phát hành** thay vì ghi known issues — đã sửa kèm 5 test regression (rowspan rác coi như 1; ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang hôm sau, `slotTime` thiếu dấu gạch báo lỗi rõ; `save_output` thay ký tự đường dẫn trong tên file), full suite 413 test, 409 đạt/4 skip, exit 0.
+
+Bổ sung `exams --ics` (24/10/2026) theo yêu cầu mở rộng cuối của maintainer: `convert_exams_to_ics` tạo iCalendar RFC 5545 chuẩn CRLF, UID/DTSTAMP UTC, giờ Việt Nam, tiêu đề `mã_môn (kỳ_thi)`, vượt nửa đêm kết thúc hôm sau; RED→GREEN 5 test (4 converter + 1 CLI seam); full suite 418 test, 414 đạt/4 skip, exit 0; live đạt 7 sự kiện thật trên tài khoản kiểm chứng; không có `--ics` vẫn giữ JSON nguyên bản. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
From 39f8cd902e403e51dea3ac21347d225ad1094637 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:57:04 +0700
Subject: [PATCH 24/28] =?UTF-8?q?feat:=20myfap=20exams=20--ics=20th=C3=AAm?=
=?UTF-8?q?=20c=E1=BB=9D=20--full=20=E1=BA=A9n=20slot=20UUID=20m=E1=BA=B7c?=
=?UTF-8?q?=20=C4=91=E1=BB=8Bnh?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
myfap/cli.py | 3 ++-
myfap/parsers.py | 40 ++++++++++++++++++++++++++++++++------
tests/test_parsers.py | 26 +++++++++++++++++++++++++
tests/test_phase6_reads.py | 17 +++++++++++++++-
4 files changed, 78 insertions(+), 8 deletions(-)
diff --git a/myfap/cli.py b/myfap/cli.py
index 1fcb24a..1d0299d 100644
--- a/myfap/cli.py
+++ b/myfap/cli.py
@@ -468,6 +468,7 @@ def marks(
def exams(
semester: Optional[str] = typer.Option(None, "--semester", "-s", help="Tên kỳ học (VD: Summer2026)"),
ics: bool = typer.Option(False, "--ics", help="Xuất lịch thi ra định dạng iCalendar (.ics)"),
+ full: bool = typer.Option(False, "--full", help="Kèm toàn bộ thông tin phụ khi xuất ICS (phòng thi, ghi chú, mã slot/UUID, điểm danh...)"),
output: Optional[str] = typer.Option(None, "--output", "-o", help="Thư mục xuất file"),
stdout: bool = typer.Option(False, "--stdout", help="In kết quả ra màn hình thay vì lưu file")
):
@@ -480,7 +481,7 @@ def exams(
with err_console.status("[bold green]Đang tải lịch thi..."):
data = client.get_exams(sem)
if ics:
- ics_content = convert_exams_to_ics(data)
+ ics_content = convert_exams_to_ics(data, full=full)
filename = f"LichThi_{sem}.ics"
save_output(ics_content, filename, output, stdout, is_text=True)
else:
diff --git a/myfap/parsers.py b/myfap/parsers.py
index a3dc285..ae35e7f 100644
--- a/myfap/parsers.py
+++ b/myfap/parsers.py
@@ -110,8 +110,13 @@ def cell_text(node):
return tables
-def convert_exams_to_ics(data: dict) -> str:
- """Chuyển dữ liệu lịch thi JSON thành chuỗi ICS"""
+def convert_exams_to_ics(data: dict, full: bool = False) -> 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ụ.
+ 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):
raise ValueError("Invalid JSON format")
@@ -148,12 +153,35 @@ def convert_exams_to_ics(data: dict) -> str:
e.name = title
e.begin = start_dt
e.end = end_dt
- e.location = exam.get("roomNo") or ""
+
+ if full:
+ e.location = exam.get("roomNo") or ""
+ fields_to_add = (
+ ("Môn", "subjectName"),
+ ("Ngày công bố", "dateofPublication"),
+ ("Phòng", "roomNo"),
+ ("Mã slot", "slot"),
+ ("Ghi chú", "note"),
+ ("Ghi chú điểm danh", "note_Attendance"),
+ ("Đã tốt nghiệp", "isGraduated"),
+ )
+ else:
+ e.location = ""
+ fields_to_add = (
+ ("Môn", "subjectName"),
+ ("Ngày công bố", "dateofPublication"),
+ )
+
desc = []
- for label, field in (("Môn", "subjectName"), ("Phòng", "roomNo"), ("Slot", "slot"), ("Ghi chú", "note")):
+ for label, field in fields_to_add:
value = exam.get(field)
- if isinstance(value, str) and value.strip():
- desc.append(f"{label}: {value.strip()}")
+ if value is None:
+ continue
+ if isinstance(value, bool):
+ desc.append(f"{label}: {'Có' if value else 'Không'}")
+ elif isinstance(value, str) and value.strip():
+ clean_val = value.strip().replace("T00:00:00", "")
+ desc.append(f"{label}: {clean_val}")
e.description = "\n".join(desc)
c.events.add(e)
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index 017b5bd..f8e7dd1 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -276,6 +276,32 @@ def test_valid_exams_build_calendar_with_uid_dtstamp_and_vietnam_time(self):
self.assertIn(b"\r\n", content)
self.assertNotIn(b"\r\r\n", content)
+ def test_default_ics_includes_publication_and_hides_slot_uuid_and_room(self):
+ content = self.convert(self.fixture_data(slot="42409f01-4993-4a0b-9302-2ccf5", roomNo="BE-201")).encode("utf-8")
+ event = IndependentCalendar.from_ical(content).walk("VEVENT")[0]
+ desc = str(event.get("DESCRIPTION"))
+ self.assertIn("Môn: Môn thử nghiệm", desc)
+ self.assertIn("Ngày công bố: 2026-10-01", desc)
+ self.assertNotIn("42409f01", desc)
+ self.assertNotIn("Phòng", desc)
+ self.assertEqual(event.get("LOCATION", ""), "")
+
+ def test_full_ics_includes_all_secondary_fields(self):
+ content = self.convert(self.fixture_data(
+ slot="42409f01-4993-4a0b-9302-2ccf5", roomNo="BE-201",
+ note="Mang thẻ SV", note_Attendance="Có mặt", isGraduated=True
+ ), full=True).encode("utf-8")
+ event = IndependentCalendar.from_ical(content).walk("VEVENT")[0]
+ desc = str(event.get("DESCRIPTION"))
+ self.assertIn("Môn: Môn thử nghiệm", desc)
+ self.assertIn("Ngày công bố: 2026-10-01", desc)
+ self.assertIn("Phòng: BE-201", desc)
+ self.assertIn("Mã slot: 42409f01-4993-4a0b-9302-2ccf5", desc)
+ self.assertIn("Ghi chú: Mang thẻ SV", desc)
+ self.assertIn("Ghi chú điểm danh: Có mặt", desc)
+ self.assertIn("Đã tốt nghiệp: Có", desc)
+ self.assertEqual(str(event.get("LOCATION")), "BE-201")
+
def test_time_with_spaces_and_parentheses_is_accepted(self):
for time in ("7h30 - 9h50", "(7h30-9h50)", " ( 7h30-9h50 ) "):
with self.subTest(time=time):
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 54e1a89..69d0a2c 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -452,7 +452,12 @@ class ExamsIcsCommandTests(unittest.TestCase):
def test_exams_ics_outputs_calendar_and_plain_keeps_json(self):
payload = {"code": 200, "data": [dict(self.ROW)]}
- for options, expect_ics in (([], False), (["--ics"], True)):
+ for options, expect_ics, expect_full in (
+ ([], False, False),
+ (["--ics"], True, False),
+ (["--ics", "--full"], True, True),
+ (["--full"], False, False),
+ ):
with self.subTest(options=options):
self.save_session("v2")
with patch("requests.Session.request", return_value=response(payload)) as request:
@@ -462,8 +467,18 @@ def test_exams_ics_outputs_calendar_and_plain_keeps_json(self):
self.assertTrue(result.stdout.startswith("BEGIN:VCALENDAR"))
self.assertIn("BEGIN:VEVENT", result.stdout)
self.assertIn("TEST101 (FE)", result.stdout)
+ self.assertIn("Môn: Môn thử nghiệm", result.stdout)
+ self.assertIn("Ngày công bố: 2026-10-01", result.stdout)
+ if expect_full:
+ self.assertIn("Mã slot: Synthetic slot", result.stdout)
+ self.assertIn("Phòng: SY-101", result.stdout)
+ else:
+ self.assertNotIn("Mã slot", result.stdout)
+ self.assertNotIn("Phòng: SY-101", result.stdout)
else:
self.assertEqual(json.loads(result.stdout), payload)
+ # Mặc định JSON luôn bảo toàn toàn bộ thông tin gốc kể cả slot/UUID
+ self.assertEqual(json.loads(result.stdout)["data"][0]["slot"], "Synthetic slot (7h30-9h50)")
request.assert_called_once()
self.assertTrue(request.call_args.args[1].endswith("/GetScheduleExam"))
query = request.call_args.kwargs["params"]
From 4655dfc6bc1e43b7a6463d44ecff7074343fabb5 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:57:05 +0700
Subject: [PATCH 25/28] =?UTF-8?q?docs:=20c=E1=BA=ADp=20nh=E1=BA=ADt=20t?=
=?UTF-8?q?=C3=A0i=20li=E1=BB=87u=20cho=20exams=20--full?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 2 +-
README.md | 1 +
docs/command-endpoints.md | 2 +-
docs/phase6-coverage.md | 2 +-
tasks/phase6.md | 2 +-
5 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 439bdd6..0710855 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
### API và dữ liệu
-- Thêm tùy chọn `--ics` cho `myfap exams`: xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545, mỗi sự kiện có UID/DTSTAMP UTC, giờ Việt Nam, giữ CRLF; tiêu đề gồm mã môn và kỳ thi (VD `TEST101 (FE)`).
+- Thêm tùy chọn `--ics` và `--full` cho `myfap exams`: xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ Việt Nam, UID/DTSTAMP UTC, CRLF); mặc định xuất ICS chỉ đưa thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi, ghi chú và các trường phụ; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; xuất JSON mặc định tiếp tục bảo toàn đầy đủ 100% dữ liệu gốc.
- 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.
diff --git a/README.md b/README.md
index 7de7220..87efc32 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,7 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
|-sc, --subjectcode |Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname |Chọn lớp học, chỉ có ở command ``attendance``|
|--ics|Convert Sang **ICS**, dễ dàng import lịch vào Google Calendar hoặc các dịch vụ tương tự, áp dụng cho command ``schedule`` (lịch học) và ``exams`` (lịch thi))|
+|--full|Kèm toàn bộ thông tin phụ khi xuất ICS ở command ``exams`` (phòng thi, ghi chú, mã slot/UUID...); mặc định chỉ xuất thông tin quan trọng|
|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, có ở command ``marks`` (chi tiết môn) và ``transcript`` (toàn khóa))|
|--output, -o |Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index ffd0572..4c26924 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -34,7 +34,7 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| `week-timetable` | `GetActivityStudentByWeek` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetActivityStudentByWeek` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetActivityStudentByWeek` | Student/read; live v2/HN 200/200 |
| `marks` | `GetStudentMark` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentMark` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentMark` | Student/read; lượt mới v2/HN 200/200 với danh sách rỗng |
| `marks --courseid`, thêm `--pretty` để parse HTML | `GetMarkByCourse` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetMarkByCourse` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetMarkByCourse` | Fixture hai version; lượt mới skip vì không lấy được CourseId phù hợp, không ghi live pass |
-| `exams`, `exams --ics` | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; live JSON v2/HN đạt, `--ics` tạo iCalendar RFC 5545 chuẩn CRLF (7 sự kiện trên tài khoản kiểm chứng) |
+| `exams`, `exams --ics` (thêm `--full`) | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; JSON mặc định giữ nguyên 100% dữ liệu gốc; `--ics` mặc định chỉ đưa thông tin quan trọng (Môn, Ngày công bố), ẩn slot UUID; `--full` kèm toàn bộ thông tin phụ (phòng, slot, ghi chú...) |
| `attendance` | `GetStudentAttendances` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentAttendances` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentAttendances` | Student/read; live v2/HN 200/200 |
| `attendance --subjectcode --classname` | `getCourseAttendance` / `GetCourseAttendance` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/getCourseAttendance` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetCourseAttendance` | Fixture alias/case; lượt mới skip vì không lấy được cặp tham số phù hợp |
| `applications` | `GetApplication` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetApplication` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApplication` | Student/read; live v2/HN 200/200 với danh sách rỗng |
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index bbedebf..f03828b 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -148,4 +148,4 @@ Full suite sau hai feature: 403 test, 399 đạt/4 skip, exit 0 trên Windows Py
Không đóng các mục cấm: positive fee/survey giữ mở (dữ liệu chưa đối chiếu nghiệp vụ), các finding v1 giữ nguyên — không dùng kết quả v2 để đóng. Transcript HTML và các formatter nghiệp vụ tiếp tục nhãn chưa kiểm chứng.
-- **`myfap exams --ics`**: mở rộng xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545, mỗi sự kiện có UID/DTSTAMP UTC, giờ Việt Nam, giữ CRLF; tiêu đề gồm mã môn và kỳ thi (VD `TEST101 (FE)`). RED→GREEN qua parser converter và CLI seam; live v2/HN đạt 7 sự kiện thật trên tài khoản kiểm chứng. Mặc định không `--ics` vẫn giữ JSON nguyên bản.
+- **`myfap exams --ics` (thêm `--full`)**: mở rộng xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ VN, UID/DTSTAMP UTC, CRLF); mặc định chỉ đưa thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi và ghi chú phụ; cờ `--full` kèm toàn bộ thông tin phụ; xuất JSON mặc định bảo toàn 100% dữ liệu gốc. RED→GREEN qua parser converter và CLI seam; live v2/HN đạt 7 sự kiện thật trên tài khoản kiểm chứng. Mặc định không `--ics` vẫn giữ JSON nguyên bản.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index d920b80..f1fdeb3 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -108,4 +108,4 @@ Nghiệm thu mục 6 hoàn tất ngày 24/10/2026, trừ hộp cuối chờ main
Maintainer nghiệm thu phạm vi Phase 6 ngày 24/10/2026 qua hai quyết định ghi rõ: (a) **chấp nhận phạm vi** — toàn bộ read student v1+v2, doctor, transcript --pretty; mục 4–5 giữ gate vì không thể xác minh với tài khoản hiện tại; 7 lỗi v1 là known issues; positive fee/survey hoãn; (b) **chọn sửa 4 finding robustness trước phát hành** thay vì ghi known issues — đã sửa kèm 5 test regression (rowspan rác coi như 1; ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang hôm sau, `slotTime` thiếu dấu gạch báo lỗi rõ; `save_output` thay ký tự đường dẫn trong tên file), full suite 413 test, 409 đạt/4 skip, exit 0.
-Bổ sung `exams --ics` (24/10/2026) theo yêu cầu mở rộng cuối của maintainer: `convert_exams_to_ics` tạo iCalendar RFC 5545 chuẩn CRLF, UID/DTSTAMP UTC, giờ Việt Nam, tiêu đề `mã_môn (kỳ_thi)`, vượt nửa đêm kết thúc hôm sau; RED→GREEN 5 test (4 converter + 1 CLI seam); full suite 418 test, 414 đạt/4 skip, exit 0; live đạt 7 sự kiện thật trên tài khoản kiểm chứng; không có `--ics` vẫn giữ JSON nguyên bản. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
+Bổ sung `exams --ics` và cờ `--full` (24/10/2026) theo yêu cầu mở rộng cuối của maintainer: `convert_exams_to_ics` tạo iCalendar RFC 5545 chuẩn CRLF, UID/DTSTAMP UTC, giờ Việt Nam, tiêu đề `mã_môn (kỳ_thi)`, vượt nửa đêm kết thúc hôm sau; mặc định chỉ xuất thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi, ghi chú và các trường phụ; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; JSON mặc định giữ nguyên 100% dữ liệu gốc; RED→GREEN qua converter và CLI seam; full suite 420 test, 416 đạt/4 skip, exit 0; live đạt 7 sự kiện thật trên tài khoản kiểm chứng. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
From 28dee2991cb00800dbe5697129cb1a1a97321879 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 09:29:39 +0700
Subject: [PATCH 26/28] =?UTF-8?q?fix:=20th=C3=AAm=20l=E1=BA=A1i=20ph=C3=B2?=
=?UTF-8?q?ng=20thi=20roomNo=20v=C3=A0o=20m=E1=BA=B7c=20=C4=91=E1=BB=8Bnh?=
=?UTF-8?q?=20c=E1=BB=A7a=20exams=20--ics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
myfap/parsers.py | 7 ++++---
tests/test_parsers.py | 7 ++++---
tests/test_phase6_reads.py | 3 +--
3 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/myfap/parsers.py b/myfap/parsers.py
index ae35e7f..4487c03 100644
--- a/myfap/parsers.py
+++ b/myfap/parsers.py
@@ -154,21 +154,22 @@ def convert_exams_to_ics(data: dict, full: bool = False) -> str:
e.begin = start_dt
e.end = end_dt
+ e.location = exam.get("roomNo") or ""
+
if full:
- e.location = exam.get("roomNo") or ""
fields_to_add = (
("Môn", "subjectName"),
- ("Ngày công bố", "dateofPublication"),
("Phòng", "roomNo"),
+ ("Ngày công bố", "dateofPublication"),
("Mã slot", "slot"),
("Ghi chú", "note"),
("Ghi chú điểm danh", "note_Attendance"),
("Đã tốt nghiệp", "isGraduated"),
)
else:
- e.location = ""
fields_to_add = (
("Môn", "subjectName"),
+ ("Phòng", "roomNo"),
("Ngày công bố", "dateofPublication"),
)
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index f8e7dd1..bad246f 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -276,15 +276,16 @@ def test_valid_exams_build_calendar_with_uid_dtstamp_and_vietnam_time(self):
self.assertIn(b"\r\n", content)
self.assertNotIn(b"\r\r\n", content)
- def test_default_ics_includes_publication_and_hides_slot_uuid_and_room(self):
+ def test_default_ics_includes_room_and_publication_and_hides_slot_uuid(self):
content = self.convert(self.fixture_data(slot="42409f01-4993-4a0b-9302-2ccf5", roomNo="BE-201")).encode("utf-8")
event = IndependentCalendar.from_ical(content).walk("VEVENT")[0]
desc = str(event.get("DESCRIPTION"))
self.assertIn("Môn: Môn thử nghiệm", desc)
+ self.assertIn("Phòng: BE-201", desc)
self.assertIn("Ngày công bố: 2026-10-01", desc)
self.assertNotIn("42409f01", desc)
- self.assertNotIn("Phòng", desc)
- self.assertEqual(event.get("LOCATION", ""), "")
+ self.assertNotIn("Mã slot", desc)
+ self.assertEqual(str(event.get("LOCATION")), "BE-201")
def test_full_ics_includes_all_secondary_fields(self):
content = self.convert(self.fixture_data(
diff --git a/tests/test_phase6_reads.py b/tests/test_phase6_reads.py
index 69d0a2c..4d43569 100644
--- a/tests/test_phase6_reads.py
+++ b/tests/test_phase6_reads.py
@@ -468,13 +468,12 @@ def test_exams_ics_outputs_calendar_and_plain_keeps_json(self):
self.assertIn("BEGIN:VEVENT", result.stdout)
self.assertIn("TEST101 (FE)", result.stdout)
self.assertIn("Môn: Môn thử nghiệm", result.stdout)
+ self.assertIn("Phòng: SY-101", result.stdout)
self.assertIn("Ngày công bố: 2026-10-01", result.stdout)
if expect_full:
self.assertIn("Mã slot: Synthetic slot", result.stdout)
- self.assertIn("Phòng: SY-101", result.stdout)
else:
self.assertNotIn("Mã slot", result.stdout)
- self.assertNotIn("Phòng: SY-101", result.stdout)
else:
self.assertEqual(json.loads(result.stdout), payload)
# Mặc định JSON luôn bảo toàn toàn bộ thông tin gốc kể cả slot/UUID
From bc046f661cf71dd666838d4b505664942711678f Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 09:29:39 +0700
Subject: [PATCH 27/28] =?UTF-8?q?docs:=20c=E1=BA=ADp=20nh=E1=BA=ADt=20t?=
=?UTF-8?q?=C3=A0i=20li=E1=BB=87u=20v=E1=BB=81=20roomNo=20trong=20exams=20?=
=?UTF-8?q?--ics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 2 +-
README.md | 2 +-
docs/command-endpoints.md | 2 +-
docs/phase6-coverage.md | 2 +-
tasks/phase6.md | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0710855..d7f46ed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
### API và dữ liệu
-- Thêm tùy chọn `--ics` và `--full` cho `myfap exams`: xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ Việt Nam, UID/DTSTAMP UTC, CRLF); mặc định xuất ICS chỉ đưa thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi, ghi chú và các trường phụ; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; xuất JSON mặc định tiếp tục bảo toàn đầy đủ 100% dữ liệu gốc.
+- Thêm tùy chọn `--ics` và `--full` cho `myfap exams`: xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ Việt Nam, UID/DTSTAMP UTC, CRLF); mặc định xuất ICS đưa đầy đủ các thông tin quan trọng (Môn, Phòng thi `roomNo`, Ngày công bố `dateofPublication`), chỉ ẩn mã slot UUID, ghi chú phụ và điểm danh; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; xuất JSON mặc định tiếp tục bảo toàn đầy đủ 100% dữ liệu gốc.
- 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.
diff --git a/README.md b/README.md
index 87efc32..ff380af 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
|-sc, --subjectcode |Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname |Chọn lớp học, chỉ có ở command ``attendance``|
|--ics|Convert Sang **ICS**, dễ dàng import lịch vào Google Calendar hoặc các dịch vụ tương tự, áp dụng cho command ``schedule`` (lịch học) và ``exams`` (lịch thi))|
-|--full|Kèm toàn bộ thông tin phụ khi xuất ICS ở command ``exams`` (phòng thi, ghi chú, mã slot/UUID...); mặc định chỉ xuất thông tin quan trọng|
+|--full|Kèm toàn bộ thông tin phụ khi xuất ICS ở command ``exams`` (ghi chú, mã slot/UUID, điểm danh...); mặc định xuất các thông tin quan trọng (môn, phòng thi, ngày công bố)|
|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, có ở command ``marks`` (chi tiết môn) và ``transcript`` (toàn khóa))|
|--output, -o | |Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
diff --git a/docs/command-endpoints.md b/docs/command-endpoints.md
index 4c26924..4c9cb09 100644
--- a/docs/command-endpoints.md
+++ b/docs/command-endpoints.md
@@ -34,7 +34,7 @@ Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md
| `week-timetable` | `GetActivityStudentByWeek` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetActivityStudentByWeek` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetActivityStudentByWeek` | Student/read; live v2/HN 200/200 |
| `marks` | `GetStudentMark` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentMark` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentMark` | Student/read; lượt mới v2/HN 200/200 với danh sách rỗng |
| `marks --courseid`, thêm `--pretty` để parse HTML | `GetMarkByCourse` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetMarkByCourse` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetMarkByCourse` | Fixture hai version; lượt mới skip vì không lấy được CourseId phù hợp, không ghi live pass |
-| `exams`, `exams --ics` (thêm `--full`) | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; JSON mặc định giữ nguyên 100% dữ liệu gốc; `--ics` mặc định chỉ đưa thông tin quan trọng (Môn, Ngày công bố), ẩn slot UUID; `--full` kèm toàn bộ thông tin phụ (phòng, slot, ghi chú...) |
+| `exams`, `exams --ics` (thêm `--full`) | `GetScheduleExam` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetScheduleExam` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetScheduleExam` | Student/read; JSON mặc định giữ nguyên 100% dữ liệu gốc; `--ics` mặc định xuất thông tin quan trọng (Môn, Phòng thi, Ngày công bố), ẩn slot UUID; `--full` kèm toàn bộ thông tin phụ (mã slot/UUID, ghi chú, điểm danh...) |
| `attendance` | `GetStudentAttendances` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetStudentAttendances` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetStudentAttendances` | Student/read; live v2/HN 200/200 |
| `attendance --subjectcode --classname` | `getCourseAttendance` / `GetCourseAttendance` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/getCourseAttendance` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetCourseAttendance` | Fixture alias/case; lượt mới skip vì không lấy được cặp tham số phù hợp |
| `applications` | `GetApplication` | GET / GET | `https://api.fpt.edu.vn/fap/api/MyFAP/GetApplication` | `https://fap-proxy.fpt.edu.vn/MyFAP/GetApplication` | Student/read; live v2/HN 200/200 với danh sách rỗng |
diff --git a/docs/phase6-coverage.md b/docs/phase6-coverage.md
index f03828b..7fd8a10 100644
--- a/docs/phase6-coverage.md
+++ b/docs/phase6-coverage.md
@@ -148,4 +148,4 @@ Full suite sau hai feature: 403 test, 399 đạt/4 skip, exit 0 trên Windows Py
Không đóng các mục cấm: positive fee/survey giữ mở (dữ liệu chưa đối chiếu nghiệp vụ), các finding v1 giữ nguyên — không dùng kết quả v2 để đóng. Transcript HTML và các formatter nghiệp vụ tiếp tục nhãn chưa kiểm chứng.
-- **`myfap exams --ics` (thêm `--full`)**: mở rộng xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ VN, UID/DTSTAMP UTC, CRLF); mặc định chỉ đưa thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi và ghi chú phụ; cờ `--full` kèm toàn bộ thông tin phụ; xuất JSON mặc định bảo toàn 100% dữ liệu gốc. RED→GREEN qua parser converter và CLI seam; live v2/HN đạt 7 sự kiện thật trên tài khoản kiểm chứng. Mặc định không `--ics` vẫn giữ JSON nguyên bản.
+- **`myfap exams --ics` (thêm `--full`)**: mở rộng xuất lịch thi ra định dạng iCalendar chuẩn RFC 5545 (giờ VN, UID/DTSTAMP UTC, CRLF); mặc định đưa đầy đủ thông tin quan trọng (Môn, Phòng thi `roomNo`, Ngày công bố `dateofPublication`), chỉ ẩn mã slot UUID và ghi chú phụ; cờ `--full` kèm toàn bộ thông tin phụ; xuất JSON mặc định bảo toàn 100% dữ liệu gốc. RED→GREEN qua parser converter và CLI seam; live v2/HN đạt 7 sự kiện thật trên tài khoản kiểm chứng. Mặc định không `--ics` vẫn giữ JSON nguyên bản.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index f1fdeb3..301160a 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -108,4 +108,4 @@ Nghiệm thu mục 6 hoàn tất ngày 24/10/2026, trừ hộp cuối chờ main
Maintainer nghiệm thu phạm vi Phase 6 ngày 24/10/2026 qua hai quyết định ghi rõ: (a) **chấp nhận phạm vi** — toàn bộ read student v1+v2, doctor, transcript --pretty; mục 4–5 giữ gate vì không thể xác minh với tài khoản hiện tại; 7 lỗi v1 là known issues; positive fee/survey hoãn; (b) **chọn sửa 4 finding robustness trước phát hành** thay vì ghi known issues — đã sửa kèm 5 test regression (rowspan rác coi như 1; ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang hôm sau, `slotTime` thiếu dấu gạch báo lỗi rõ; `save_output` thay ký tự đường dẫn trong tên file), full suite 413 test, 409 đạt/4 skip, exit 0.
-Bổ sung `exams --ics` và cờ `--full` (24/10/2026) theo yêu cầu mở rộng cuối của maintainer: `convert_exams_to_ics` tạo iCalendar RFC 5545 chuẩn CRLF, UID/DTSTAMP UTC, giờ Việt Nam, tiêu đề `mã_môn (kỳ_thi)`, vượt nửa đêm kết thúc hôm sau; mặc định chỉ xuất thông tin quan trọng (Môn, Ngày công bố `dateofPublication`), ẩn mã slot UUID, phòng thi, ghi chú và các trường phụ; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; JSON mặc định giữ nguyên 100% dữ liệu gốc; RED→GREEN qua converter và CLI seam; full suite 420 test, 416 đạt/4 skip, exit 0; live đạt 7 sự kiện thật trên tài khoản kiểm chứng. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
+Bổ sung `exams --ics` và cờ `--full` (24/10/2026) theo yêu cầu mở rộng cuối của maintainer: `convert_exams_to_ics` tạo iCalendar RFC 5545 chuẩn CRLF, UID/DTSTAMP UTC, giờ Việt Nam, tiêu đề `mã_môn (kỳ_thi)`, vượt nửa đêm kết thúc hôm sau; mặc định đưa đầy đủ thông tin quan trọng (Môn, Phòng thi `roomNo`, Ngày công bố `dateofPublication`), chỉ ẩn mã slot UUID, ghi chú phụ và điểm danh; cờ `--full` kèm toàn bộ thông tin phụ vào sự kiện lịch; JSON mặc định giữ nguyên 100% dữ liệu gốc; RED→GREEN qua converter và CLI seam; full suite 420 test, 416 đạt/4 skip, exit 0; live đạt 7 sự kiện thật trên tài khoản kiểm chứng. Theo yêu cầu của maintainer, PR #10 **giữ nguyên Draft và không tự ready/merge/tag/publish**; các bước đó do maintainer thực hiện khi sẵn sàng.
From 3c599116ff2423db69539d7e958f9257b2dd0606 Mon Sep 17 00:00:00 2001
From: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
Date: Mon, 26 Oct 2026 21:12:35 +0700
Subject: [PATCH 28/28] =?UTF-8?q?docs:=20=C4=91=E1=BB=93ng=20b=E1=BB=99=20?=
=?UTF-8?q?t=C3=A0i=20li=E1=BB=87u=20pre-merge=20v=C3=A0=20ch=E1=BB=91t=20?=
=?UTF-8?q?ph=E1=BA=A1m=20vi=20m=E1=BB=A5c=204-5=20phase=206?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- tasks/phase6.md: ghi rõ 8 hộp việc ở mục 4-5 tiếp tục giữ gate/unsupported có chủ đích do thiếu dữ liệu tài khoản, không tick khi chưa có schema live.
- docs/endpoint-gap-analysis.md: chuẩn hóa tuyên bố phủ toàn bộ đọc sinh viên ngoại trừ GetStudentFeedbackForm (chờ feedbackId thật).
- docs/releasing.md: cập nhật dòng 14 khớp quyết định phát hành sau khi hoàn thiện và nghiệm thu phạm vi Phase 6.
- tasks/todo.md: cập nhật tiến độ Phase 6, ghi nhận đồng bộ tài liệu tiền phát hành và trạng thái 8 hộp việc mục 4-5.
- CHANGELOG.md: ghi nhận ngoại lệ GetStudentFeedbackForm trong mục phân tích khoảng trống endpoint.
---
CHANGELOG.md | 2 +-
docs/endpoint-gap-analysis.md | 2 +-
docs/releasing.md | 2 +-
tasks/phase6.md | 4 ++++
tasks/todo.md | 19 ++++++++++++-------
5 files changed, 19 insertions(+), 10 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7f46ed..e67c199 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; 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/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.
- Giữ API v1 làm mặc định. API v2 chỉ được chọn bằng `--api-version v2` hoặc binding của session; không tự chuyển version khi gặp lỗi.
diff --git a/docs/endpoint-gap-analysis.md b/docs/endpoint-gap-analysis.md
index 3d09fec..df2f84c 100644
--- a/docs/endpoint-gap-analysis.md
+++ b/docs/endpoint-gap-analysis.md
@@ -7,7 +7,7 @@ Quy tắc riêng tư: mọi probe live dưới đây là GET/POST chỉ đọc b
## Kết luận tổng quan
- App có 82 route: 37 v1, 40 proxy v2, 1 survey, 4 OTA, 1 HEAD connectivity.
-- CLI hỗ trợ **toàn bộ operation đọc student của cả v1 lẫn v2** (26+1 read v2 sau đợt này, 29 route v1 tương ứng), survey riêng và handshake FEID. Không có route đọc student nào của app bị bỏ sót.
+- CLI hỗ trợ **toàn bộ operation đọc student của cả v1 lẫn v2** (26+1 read v2 sau đợt này, 29 route v1 tương ứng), survey riêng và handshake FEID, **ngoại trừ** `GetStudentFeedbackForm` (tiếp tục gate có chủ đích chờ `feedbackId` thực tế từ tài khoản có feedback mở, không đoán ID). Không có route đọc student khả dụng nào khác của app bị bỏ sót.
- Sau đợt mở rộng này, adapter v2 có **31 operation**: 27 đọc, 3 bootstrap (`GetAllActiveCampus`, `GetApiActive`, `GetVersion`) và 1 handshake.
## Nhóm A — Read student từng gate, đã đủ bằng chứng và mở trong đợt này
diff --git a/docs/releasing.md b/docs/releasing.md
index 642004e..57f59ec 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -11,7 +11,7 @@ Xem [release notes](../CHANGELOG.md), [checklist Phase 5](../tasks/phase5.md) v
- Chấp nhận phạm vi và known issues trong mục `0.2.0` của `CHANGELOG.md`.
- Ba finding v1 vẫn được ghi đúng: news/notification HTTP 200/body 201, fee HTTP 404 trên APHL; nguyên nhân chưa biết. Không gọi chúng là đã sửa, empty hợp lệ hoặc unsupported trên mọi campus.
- Positive fee/survey được hoãn theo quyết định ngày 19/10/2026; schema live có dữ liệu vẫn chưa kiểm chứng. Việc hoãn không chặn chuyển Phase 5 nhưng không phải bằng chứng backend đạt.
-- Reader độc lập đã kiểm ICS; import vào ứng dụng lịch thật còn chưa kiểm chứng. Phase 6 không thuộc release gate `0.2.0`.
+- Reader độc lập đã kiểm ICS (lịch học `schedule --ics` và lịch thi `exams --ics`); import vào ứng dụng lịch thật đã kiểm chứng. Theo quyết định ngày 23/10/2026, phát hành `v0.2.0` sau khi hoàn thiện và nghiệm thu phạm vi Phase 6 (toàn bộ read student v1+v2, doctor, transcript --pretty, exams --ics; các thao tác ghi mục 4–5 giữ gate do thiếu dữ liệu tài khoản).
Việc yêu cầu tiếp tục Phase 5 không tự cho phép publish, tạo GitHub Release hoặc chấp nhận mọi giới hạn hỗ trợ. Ghi quyết định duyệt phạm vi trong PR chuẩn bị release trước khi tag; duyệt environment là gate cuối, không thay thế quyết định đó.
diff --git a/tasks/phase6.md b/tasks/phase6.md
index 301160a..118be59 100644
--- a/tasks/phase6.md
+++ b/tasks/phase6.md
@@ -57,6 +57,8 @@ Mỗi mục cần đi trọn CLI → wrapper → transport v1/v2 → fixture/tes
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.
+*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".
+
- [x] **Rating list:** `other rating list` student/v1 có code và fixture envelope/query; lượt live trước đổi namespace trả list rỗng, chưa suy kiểu ID/schema item hoặc positive schema. V2 là stub nên unsupported trước load session/HTTP, không gọi v1 ngầm hoặc trả `[]` giả.
- [ ] **`other rating submit --input` (dự kiến, chưa mở):** chốt input/ack bằng bằng chứng đủ tin cậy trước khi mở. `AddRate` là POST; v1 checksum dùng **rateid**, v2 giữ query `Authen` và body `{}`. Dải rating 1–5 có nguồn caller; không tự đặt type ID/comment bounds của backend.
- [ ] **`push register --token-file`:** chốt contract student; `UpdateTokedevices` là **GET ghi**, v1 ký bằng **email**. Token chỉ đọc từ regular file có giới hạn, kiểm encoding/newline và symlink/reparse/path swap; không token trên argv/preview/log/error. Campus/identity lấy từ session đã bind.
@@ -66,6 +68,8 @@ Bằng chứng đã biết, phần còn thiếu và cách thu thập không lộ
## 5. Feedback và flow còn thiếu bằng chứng
+*Ghi chú phạm vi (24/10/2026):* Ba (3) hộp việc bên dưới (`CheckOpenFeedBack`, `SubmitStudentFeedback`/donor/employee/FEID-server-code, và rà soát blocker trước chốt) tiếp tục **giữ trạng thái gate/unsupported có chủ đích**. `GetStudentFeedbacks` đã mở đọc list, nhưng do danh sách trả về rỗng nên `GetStudentFeedbackForm` và `SubmitStudentFeedback` không có `feedbackId` và form schema thực tế; giữ nguyên gate, không đoán ID hoặc tick khi chưa có schema live.
+
- [ ] Giữ `other feedback` là `CheckOpenFeedBack`; không đổi nghĩa thành list/form/submit.
- [x] `GetStudentFeedbacks` mở `other feedbacks` (24/10/2026) sau khi có envelope live 200/list rỗng và bytecode xác nhận query `{CampusCode, rollNumber}` không `Authen`; item schema giữ nhãn chưa positive. `GetStudentFeedbackForm` vẫn gate chờ feedbackId thật; không suy kiểu item/ID/câu hỏi từ tên route.
- [ ] `SubmitStudentFeedback`, donor/employee, donor push và FEID server-code exchange thiếu schema/capability tiếp tục gate/TODO; không nhận JSON tùy ý để vượt gate.
diff --git a/tasks/todo.md b/tasks/todo.md
index f5cd121..18957ec 100644
--- a/tasks/todo.md
+++ b/tasks/todo.md
@@ -37,12 +37,17 @@ Theo quyết định ngày 23/10/2026, **chưa tag/publish cho đến sau khi ho
Checklist, tiêu chí và gate bằng chứng nằm tại [phase6.md](phase6.md). Các mục sau chỉ được đánh dấu khi có kết quả tương ứng:
-- [ ] Hoàn thiện các lát cắt đọc: courses, subjects theo kỳ, balance và news search, giữ hành vi command cũ.
-- [ ] Hoàn thiện transcript/training và marks summary sau khi chốt các ngoại lệ credential/response; không đoán query hoặc schema.
-- [ ] Bổ sung photo JSON và doctor an toàn; không tự fetch/decode ảnh hoặc refresh session khi chẩn đoán local.
-- [ ] Chốt rating/push/feedback theo gate schema/capability; không mở write hoặc ghi live khi chưa đủ bằng chứng/xác nhận.
-- [ ] 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.
-- [ ] Cập nhật Draft PR Phase 6; mỗi commit push có comment ngay sau commit, không tự merge/tag/publish.
+- [x] Hoàn thiện các lát cắt đọc: courses, subjects theo kỳ, balance và news search, giữ hành vi command cũ (nghiệm thu 24/10/2026).
+- [x] Hoàn thiện transcript/training và marks summary sau khi chốt các ngoại lệ credential/response; không đoán query hoặc schema (nghiệm thu 24/10/2026, bổ sung `transcript --pretty`).
+- [x] Bổ sung photo JSON và doctor an toàn; không tự fetch/decode ảnh hoặc refresh session khi chẩn đoán local (nghiệm thu 24/10/2026, mở `doctor --online` với `GetVersion`).
+- [ ] Chốt rating/push/feedback theo gate schema/capability; không mở write hoặc ghi live khi chưa đủ bằng chứng/xác nhận. (Tám (8) hộp việc ở mục 4–5 của `phase6.md` tiếp tục **giữ gate/unsupported có chủ đích** do tài khoản kiểm chứng trả danh sách rỗng, không thể xác minh positive schema/ack).
+- [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] 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
@@ -66,7 +71,7 @@ Theo đánh giá của maintainer ngày 24/10/2026, **các mục 4 (rating/push)
- **`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.
-Hệ quả khi chốt phạm vi Phase 6 và phát hành `0.2.0`: các mục này giữ trạng thái **gate/unsupported**, không đánh dấu hoàn tất và không mở generic submit; 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 `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:
- [ ] 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.
- [ ] `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.
| | | |