Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
# Lịch sử thay đổi

## [0.2.0] - Chưa phát hành
## [0.2.1] - Chưa phát hành

### API và dữ liệu

- Đã cập nhật năm GET proxy v2 theo myFAP Android 2.0.7/build 32: profile, marks summary, applications, kiểm tra feedback và notification bỏ query `Authen`. Credential vẫn nằm trong Bearer/Checksum; header dùng key mới sau refresh. V1 và output giữ nguyên. Cả năm command đã được nghiệm thu trên CLI v2/HN với HTTP/body 200; xem bằng chứng từ app, CLI và các giới hạn tại [báo cáo build 32](docs/discovery/build32-verification.md).

## [0.2.0] - 18/11/2026

### 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 đư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.
- `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 hóa ` `; 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/discovery/endpoint-gap-analysis.md) đối chiếu 82 route của APK với adapter: CLI phủ toàn bộ operation đọc student (ngoại trừ `GetStudentFeedbackForm` đang gate có chủ đích chờ `feedbackId` thực tế); donor/employee, login thay thế và OTA được ghi rõ out of scope.
- Chuyển training và nhóm rating vào `other`: dùng `myfap other training` và `myfap other rating list`, không giữ command root cũ. Endpoint, policy retry và capability từng version không đổi.
Expand Down
4 changes: 3 additions & 1 deletion docs/cli/command-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@ Tài liệu này hợp nhất mapping command → operation → method/URL → c

## Bổ sung Phase 6 đang review

**Cập nhật build 32 (18/11/2026):** năm lệnh `other profile`, `marks --summary`, `applications`, `other feedback`, `other notification` chỉ gửi `CampusCode`, `rollNumber` trong query v2, bỏ `Authen`. V1 giữ nguyên. `marks --summary` gọi `GetSemesterMark`; hai luồng xem điểm còn lại dùng `marks` (`GetStudentMark`) và điểm chi tiết (`GetMarkByCourse`). Cả năm command đã được nghiệm thu trên CLI v2/HN với HTTP/body 200. [Báo cáo build 32](../discovery/build32-verification.md) ghi riêng bằng chứng tĩnh, traffic app qua Fiddler và kết quả chạy CLI.

Mapping theo mốc Phase 5 trong tài liệu này được giữ làm lịch sử. Capability đọc mới, query ngoại lệ, doctor và giới hạn hiện tại nằm tại [coverage Phase 6](../discovery/phase6-coverage.md); đối chiếu toàn bộ 82 route của APK với CLI nằm tại [phân tích khoảng trống endpoint](../discovery/endpoint-gap-analysis.md). Các dòng “chưa tích hợp” ở phần inventory Phase 5 bên dưới cần đọc theo mốc commit ban đầu, không phải trạng thái code Phase 6 mới nhất. Chưa publish Phase 6 hoặc đánh dấu các luồng ghi đã đạt.

## Phạm vi theo kế hoạch

- **Phase 4:** phủ command đọc hiện có, lập coverage và kiểm chứng live. Xem [coverage Phase 4](../discovery/phase4-coverage.md).
- **Phase 5:** chuẩn bị và nghiệm thu pipeline phát hành. Có code và CI xanh chưa đồng nghĩa đã publish `0.2.0`; xem [checklist Phase 5](../discovery/phase5.md).
- **Phase 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.1`; xem [checklist Phase 5](../discovery/phase5.md).
- **Phase 6:** thêm các chức năng/API mới, nghiệm thu trước khi tạo tag/publish theo quyết định ngày 23/10/2026. Không tự mở route chỉ vì có tên trong APK; cần contract, capability, fixture và kiểm chứng riêng.

Ba giai đoạn trên theo mục Phase 4–6 trong `PLAN.md` và `PLAN-PHASES.md` của workspace phân tích. Hai file kế hoạch nằm ngoài repository CLI; không cần đóng gói chúng vào artifact.
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ uv run --locked --group ci python -m unittest discover -s tests -v
uv build --out-dir dist
uv run --locked --group ci python -m twine check --strict dist/*.whl dist/*.tar.gz
uv run --locked --group ci python scripts/check_artifacts.py --dist-dir dist
uv run --locked --group ci python scripts/smoke_install.py --artifact-dir dist --expected-version 0.2.0
uv run --locked --group ci python scripts/smoke_install.py --artifact-dir dist --expected-version 0.2.1
```

Thư mục artifact phải chỉ chứa wheel/sdist của version hiện tại và manifest. Nếu còn file build cũ, copy ra ngoài trước khi chạy
Expand Down
10 changes: 5 additions & 5 deletions docs/cli/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Xem [release notes](../../CHANGELOG.md), [checklist Phase 5](../discovery/phase5

## 1. Quyết định phạm vi trước release

`0.2.0` mặc định v2 khi chưa có session; option `--api-version`, `MYFAP_API_VER` và binding session có thứ tự ưu tiên như [hướng dẫn chọn version](api-versions.md). CLI không fallback im lặng. Trước tag, maintainer phải xác nhận:
Phiên bản chuẩn bị phát hành là `0.2.1`, mặc định v2 khi chưa có session; option `--api-version`, `MYFAP_API_VER` và binding session có thứ tự ưu tiên như [hướng dẫn chọn version](api-versions.md). CLI không fallback im lặng. Trước tag, maintainer phải xác nhận:

- Chấp nhận phạm vi và known issues trong mục `0.2.0` của `CHANGELOG.md`.
- Chấp nhận phạm vi và known issues trong mục `0.2.1` của `CHANGELOG.md`, cùng các giới hạn còn áp dụng từ `0.2.0`.
- 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 (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).
Expand Down Expand Up @@ -38,7 +38,7 @@ Cấu hình sau cần được maintainer kiểm tra trực tiếp; file workflo
## 3. Chuẩn bị commit và tag

1. Kiểm working tree sạch, PR chuẩn bị release đã merge và lấy `main`/tag mới nhất.
2. Đối chiếu `[project].version`, root package trong `uv.lock`, CLI và artifact. Baseline đã là `0.2.0`; không bump lại từ `0.1.8`. Chỉ chạy `uv lock` khi metadata thực sự đổi, không sửa tay lockfile hoặc dùng `--upgrade` cho release thông thường.
2. Đối chiếu `[project].version`, root package trong `uv.lock`, CLI và artifact; tất cả phải là `0.2.1`. Bản `0.2.0` đã có release, không dùng lại tag hoặc version đó cho bản cập nhật này. Chỉ chạy `uv lock` khi metadata thực sự đổi, không sửa tay lockfile hoặc dùng `--upgrade` cho release thông thường.
3. Kiểm PyPI để biết version mục tiêu đã tồn tại hay chưa. Nếu version đã phát hành trước đó mà không phải đang phục hồi cùng release/artifact, dừng và để maintainer chọn version mới.
4. Chạy regression, build, Twine, validator và cài artifact theo [hướng dẫn phát triển](development.md#kiểm-tra-trên-máy-local). Ghi commit, lệnh, exit code và các phần chưa kiểm chứng.
5. Duyệt mục version trong `CHANGELOG.md`, coverage và quyết định phạm vi ở mục 1. Tag phải trỏ tới commit thuộc `origin/main`.
Expand All @@ -51,8 +51,8 @@ git switch main
git pull --ff-only origin main
git status --short --branch
# Xác nhận version, notes, CI và phạm vi trước hai lệnh tiếp theo.
git tag -a v0.2.0 -m "Phát hành myfap 0.2.0"
git push origin v0.2.0
git tag -a v0.2.1 -m "Phát hành myfap 0.2.1"
git push origin v0.2.1
```

Không dùng `--force`, không di chuyển/xóa tag để sửa một release đã upload. Stable pipeline chỉ nhận tag chuẩn `vX.Y.Z`, không nhận prerelease hoặc thành phần số có zero đứng đầu.
Expand Down
18 changes: 11 additions & 7 deletions docs/cli/v2-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Tài liệu này ghi lại adapter v2 và phạm vi các route còn lại. CLI mặc định v2 khi chưa có session; xem [thứ tự chọn version](api-versions.md) và quy tắc tương thích session cũ. Module transport không tự dò phiên bản, refresh session hoặc diễn giải JSON response.

Hợp đồng GET đã được cập nhật theo APK **2.0.7/build 32**; xem [bằng chứng và giới hạn nghiệm thu](../discovery/build32-verification.md). Nguồn `module_599.js` bên dưới thuộc build 31. Ma trận route ghi rõ những query đã đổi.

## Transport và operation đã hỗ trợ

`myfap.v2.request()` trả về `requests.Response` nguyên bản. Lớp gọi phía trên chịu trách nhiệm chạy `read_response`, phân loại `401` và quyết định retry. Transport chỉ dựng request, kiểm tra tham số và che lỗi mạng khỏi thông tin credential.
Expand Down Expand Up @@ -39,13 +41,13 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `AuthenticationByFeIdCode` | `POST` | unsupported | Nhánh code exchange của app đang tắt |
| `GetStudentById` | `GET` | supported | 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 |
| `CheckUpdateProfile` | `GET` | supported | Build 32: query `CampusCode`, `rollNumber`, không `Authen` |
| `GetSemester` | `GET` | supported | Query rỗng |
| `GetSubjets` | `GET` | supported | Query `CampusCode` |
| `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` | supported | Phase 6: query `CampusCode`, `rollNumber`, `Authen`; không query kỳ, reader riêng |
| `GetSemesterMark` | `GET` | supported | Build 32: query `CampusCode`, `rollNumber`, không `Authen`/kỳ; reader riêng; CLI v2/HN đã live 200/200 |
| `GetMarkByCourse` | `GET` | supported | Query `CampusCode`, `CourseId`, `rollNumber` |
| `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 |
Expand All @@ -59,13 +61,13 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea
| `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` | 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 |
| `GetApplication` | `GET` | supported | Build 32: query `CampusCode`, `rollNumber`, không `Authen` |
| `CheckOpenFeedBack` | `GET` | supported | Build 32: query `CampusCode`, `rollNumber`, không `Authen` |
| `AddRate` | `POST` | unsupported | Vẫn giữ query `Authen` theo app |
| `UpdateTokedevices` | `GET` | unsupported | Query `CampusCode`, `Email`, `tokendevice` |
| `GetNotificationByRoll` | `GET` | supported | Vẫn giữ query `Authen` theo app |
| `GetNotificationByRoll` | `GET` | supported | Build 32: query `CampusCode`, `rollNumber`, không `Authen` |
| `UpdateTokenDonor` | `GET` | unsupported | Donor flow |
| `GetNotificationByDonor` | `GET` | unsupported | Vẫn giữ query `Authen` theo app |
| `GetNotificationByDonor` | `GET` | unsupported | Build 32 bỏ query `Authen`; chưa mở donor capability |
| `GetTokenWithEmp` | `GET` | unsupported | Employee flow |
| `GetAllActiveCampus` | `POST` | supported | Body `{}` |
| `GetCampusInfo` | `GET` | supported | Query `CampusCode`, `rollNumber` |
Expand All @@ -80,7 +82,9 @@ Các route trên cùng dùng base URL `https://fap-proxy.fpt.edu.vn/MyFAP/`. Hea

Sau nhóm đọc Phase 6 và đợt mở rộng endpoint 24/10/2026, ma trận có 31 operation được hỗ trợ trong code: 27 operation đọc, 3 bootstrap và 1 handshake. `doctor --api-version v2 --online` gọi `GetApiActive` rồi `GetVersion` bằng bootstrap, không xác nhận session hoặc campus tài khoản. Capability mới chưa đồng nghĩa đã nghiệm thu live; xem [coverage Phase 6](../discovery/phase6-coverage.md). Xem thêm [bảng hợp nhất command/method/URL v1 và v2](command-endpoints.md) để phân biệt capability trong adapter, command thực sự tồn tại và kết quả live.

Bảy route giữ `Authen` trong query của adapter app là `CheckUpdateProfile` (`module_599.js:136`), `GetSemesterMark` (`223`), `GetApplication` (`429`), `CheckOpenFeedBack` (`443`), `AddRate` (`467`), `GetNotificationByRoll` (`491`) và `GetNotificationByDonor` (`532`). Trong số này, CLI đã triển khai năm route `CheckUpdateProfile`, `GetApplication`, `CheckOpenFeedBack`, `GetNotificationByRoll` và `GetSemesterMark`; `AddRate`/`GetNotificationByDonor` vẫn chưa được hỗ trợ. Route điểm danh chi tiết đổi từ `getCourseAttendance` của v1 sang `GetCourseAttendance` ở v2 (`module_599.js:363-364`); wrapper v1 không đủ để ghi nhận capability v2.
Ở build 31, bảy route có query `Authen` là `CheckUpdateProfile`, `GetSemesterMark`, `GetApplication`, `CheckOpenFeedBack`, `AddRate`, `GetNotificationByRoll` và `GetNotificationByDonor` (`module_599.js:136,223,429,443,467,491,532`). Build 32 (`module_604.js`, fn#7514/7538/7594/7598/7614/7622) bỏ trường này ở cả sáu GET; POST `AddRate` giữ nguyên.

CLI áp dụng query mới cho năm GET đã hỗ trợ. FAP key của binding hiện tại vẫn dùng cho Bearer và Checksum; CLI chưa hỗ trợ `AddRate` hoặc donor. Route điểm danh chi tiết tiếp tục dùng alias v2 `GetCourseAttendance`; contract v1 giữ nguyên.

## Giới hạn hiện tại

Expand Down
Loading
Loading