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
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ jobs:
PY
- name: Publish PyPI, không skip-existing
if: ${{ steps.reconcile.outputs.publish_required == 'true' }}
uses: pypa/gh-action-pypi-publish@106e0b0b7c337fa67ed433972f777c6357f78598 # v1.13.0
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
with:
packages-dir: upload/

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/testpypi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ jobs:
PY
- name: Upload TestPyPI qua publisher riêng
if: ${{ steps.reconcile.outputs.publish_required == 'true' }}
uses: pypa/gh-action-pypi-publish@106e0b0b7c337fa67ed433972f777c6357f78598 # v1.13.0
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
with:
repository-url: https://test.pypi.org/legacy/
packages-dir: upload/
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ __pycache__/
build/
develop-eggs/
dist/
dist-*/
downloads/
eggs/
.eggs/
Expand Down
6 changes: 3 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@
- Thêm `myfap other feedbacks` đọc danh sách feedback student qua `GetStudentFeedbacks`, chỉ có trên proxy API v2; envelope đã kiểm chứng live nhưng item schema chưa có positive (danh sách rỗng trên tài khoản kiểm chứng).
- `transcript --pretty` phân tích HTML bảng điểm toàn khóa thành JSON cấu trúc: mỗi bảng giữ header riêng (bảng chính 10 cột `No`…`Status`, bảng phụ 7 cột) và hàng dữ liệu keyed theo header, chuẩn hoá ` `; không dùng `--pretty` vẫn giữ chuỗi HTML nguyên bản theo contract.
- `doctor --api-version v2 --online` báo thêm `backend_version` qua `GetVersion` POST bootstrap; GET bị proxy từ chối 405 và route v1 đã 404. `myfap version` vẫn chỉ đọc package version offline.
- Thêm [phân tích khoảng trống endpoint](docs/endpoint-gap-analysis.md) đối chiếu 82 route của APK với adapter: CLI phủ toàn bộ operation đọc student (ngoại trừ `GetStudentFeedbackForm` đang gate có chủ đích chờ `feedbackId` thực tế); donor/employee, login thay thế và OTA được ghi rõ out of scope.
- Thêm [phân tích khoảng trống endpoint](docs/discovery/endpoint-gap-analysis.md) đối chiếu 82 route của APK với adapter: CLI phủ toàn bộ operation đọc student (ngoại trừ `GetStudentFeedbackForm` đang gate có chủ đích chờ `feedbackId` thực tế); donor/employee, login thay thế và OTA được ghi rõ out of scope.
- Chuyển training và nhóm rating vào `other`: dùng `myfap other training` và `myfap other rating list`, không giữ command root cũ. Endpoint, policy retry và capability từng version không đổi.

- 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.
- Đặt API v2 làm mặc định khi chưa có session. Thứ tự chọn version: option `--api-version`, biến môi trường `MYFAP_API_VER`, binding session, rồi v2; session cũ thiếu trường version vẫn được hiểu là v1. Không tự chuyển version khi gặp lỗi.
- 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.
- Giữ stdout JSON/ICS tách khỏi log và lỗi trên stderr; xuất tiếng Việt an toàn hơn trên Windows, kể cả bảng Rich và help.
Expand Down Expand Up @@ -39,7 +39,7 @@
- **Fee/survey positive:** theo quyết định ngày 19/10/2026, chờ dữ liệu nghiệp vụ phù hợp và không chặn chuyển sang Phase 5. Schema live có dữ liệu vẫn **chưa kiểm chứng**; fee HTTP/body 200 hoặc survey not-found không đủ để đóng các mục này.
- ICS đã được đọc bằng reader độc lập `icalendar`; chưa xác nhận import vào Google Calendar/Outlook. Reader `ics` hiện có giới hạn recursion với lịch lớn.
- Phase 6 đã bổ sung transcript, balance, courses/training, subjects theo kỳ, tìm news, ảnh JSON, marks summary, doctor và (24/10/2026) `other feedbacks` cùng `backend_version` cho doctor online; xem coverage Phase 6 và phân tích khoảng trống endpoint. Rating list student/v1 đã có code/fixture; v2 stub bị chặn. Feedback form/submit và thao tác ghi vẫn còn gate contract/schema, không được coi là đã hỗ trợ.
- **Finding robustness từ review Phase 6 (24/10/2026) — đã sửa theo quyết định maintainer trước khi phát hành:** `rowspan` không phải số nguyên không còn làm parser bảng điểm chi tiết crash (coi như 1); ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang ngày hôm sau và `slotTime` thiếu dấu gạch báo lỗi rõ ràng; tên file xuất thay ký tự đường dẫn để không thoát thư mục `--output`. Chi tiết tại [TODO](tasks/todo.md).
- **Finding robustness từ review Phase 6 (24/10/2026) — đã sửa theo quyết định maintainer trước khi phát hành:** `rowspan` không phải số nguyên không còn làm parser bảng điểm chi tiết crash (coi như 1); ICS nhận `isOnline` boolean, slot vượt nửa đêm kết thúc sang ngày hôm sau và `slotTime` thiếu dấu gạch báo lỗi rõ ràng; tên file xuất thay ký tự đường dẫn để không thoát thư mục `--output`. Chi tiết tại [TODO](docs/discovery/todo.md).
- Maintainer phải chấp nhận rõ phạm vi hỗ trợ và các lỗi v1 còn mở trước khi tạo tag. CI xanh không thay thế nghiệm thu API thật hoặc quyết định này.

## [0.1.8] - Mốc trước 0.2.0
Expand Down
127 changes: 70 additions & 57 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,18 @@

## Giới thiệu

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. <br>
- Lưu ý: repo này được thực hiện cùng với sự hỗ trợ của AI.
Unofficial CLI tương tác với các API internal của ứng dụng myFAP giúp xem lịch học, lịch thi, điểm số (sự thất vọng của gia đình) và thông tin sinh viên

## Tính năng chính
- Hỗ trợ đa nền tảng.
- Login thông qua FEID hoặc Google OAuth.
- Xem lịch học (từng tuần hoặc cả Kỳ).
- Xem điểm (từng môn hoặc cả Kỳ).
- Check điểm danh (từng môn hoặc cả Kỳ).
- Check tình trạng đơn từ.
- Xem thông báo của trường.
- Check Info của sinh viên hoặc phòng dvsv.
- Convert lịch học Kỳ sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự.
- Hỗ trợ đa nền tảng
- Login thông qua FEID hoặc Google OAuth
- Xem lịch học (từng tuần hoặc cả Kỳ)
- Xem điểm (từng môn hoặc cả Kỳ)
- Check điểm danh (từng môn hoặc cả Kỳ)
- Check tình trạng đơn từ
- Xem thông báo của trường
- Check Info của sinh viên hoặc phòng dvsv
- Convert lịch học Kỳ sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự
- Và nhiều hơn nữa ...

## Cách sử dụng
Expand All @@ -31,88 +30,102 @@ CLI tương tác với các API myFAP để xem lịch học, lịch thi, điể
myfap campuses
```

- Login vào feid (chỉ cần làm 1 lần, mặc định chọn Hola)
- Login vào myFAP api thông qua FEID
```
myfap login
myfap login --campus HN
```
Sau khi hoàn thành login, phiên đăng nhập sẽ dc lưu ở ``~/.myfap-api-cli/session.json`` <br>
Sau khi hoàn thành login, phiên đăng nhập sẽ được lưu ở ``~/.myfap-api-cli/session.json``

- Login cho cơ sở Xavalo
```
myfap login -c HCM
```

- Lấy Lịch học *(tự động lấy kỳ mới nhất)*.
- Lấy Lịch học *(tự động lấy kỳ mới nhất)*

```
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 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. `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.
- [Các ví dụ sử dụng](./docs/Example.md)
- [Tạo môi trường dev bằng uv](./docs/development.md)
- [CI và kiểm tra artifact](./docs/development.md#ci-và-kiểm-tra-artifact)
## Danh sách các Command

| Command | Tác dụng |
|:--|:--|
| `version` | Hiển thị phiên bản CLI |
| `doctor` | Kiểm tra cấu hình; thêm `--online` để kiểm tra kết nối bootstrap v2. |
| `login` | Đăng nhập hoặc dùng session hiện có; thêm `--force` để đăng nhập lại |
| `logout` | Xóa session trên máy |
| `refresh` | Làm mới token và session |
| `campuses` | Liệt kê các cơ sở của API đang chọn |
| `semesters` | Liệt kê các kỳ học |
| `schedule` | Xem lịch học theo kỳ; dùng `--ics` để xuất lịch **ICS** |
| `week-timetable` | Xem lịch học theo tuần hoặc ngày |
| `exams` | Xem lịch thi; dùng `--ics` để xuất lịch, thêm `--full` để kèm thông tin phụ |
| `courses` | Xem danh sách khóa học theo kỳ |
| `marks` | Xem điểm theo kỳ, chi tiết theo môn hoặc tổng kết với `--summary` |
| `transcript` | Xem bảng điểm toàn khóa; `--pretty` phân tích dữ liệu bảng HTML sang JSON |
| `attendance` | Xem điểm danh theo kỳ hoặc theo môn và lớp |
| `applications` | Xem danh sách đơn đã gửi |
| `news` | Xem hoặc tìm kiếm tin tức |
| `info student` | Xem thông tin sinh viên |
| `info photo` | Lấy dữ liệu ảnh sinh viên ở dạng JSON |
| `info campus` | Xem thông tin phòng dịch vụ sinh viên |
| `other training` | Xem điểm phong trào theo kỳ |
| `other survey` | Kiểm tra khảo sát cần làm |
| `other feedback` | Kiểm tra feedback đang mở |
| `other feedbacks` | Xem danh sách feedback của sinh viên; chỉ hỗ trợ v2 |
| `other profile` | Kiểm tra yêu cầu cập nhật hồ sơ |
| `other notification` | Xem thông báo của sinh viên |
| `other fee` | Xem các khoản học phí và trạng thái thanh toán |
| `other balance` | Xem số dư tài khoản |
| `other subjects` | Xem danh sách môn; có thể lọc theo kỳ |
| `other rating list` | Xem danh sách đánh giá; chỉ hỗ trợ v1 |

## Biến môi trường
Gồm 2 biến mặc định
- ``MYFAP_TIMEOUT``: thay đổi thời gian timeout mặc định (mặc định: 10s), danh sách môn timeout 30s
- ``MYFAP_API_VER``: overide phiên bản api (mặc định: v2)

## Lưu ý
Khi thiếu `--semester`, cli chọn kỳ theo `startDate` gần đây. Với lịch tuần, `--date` quyết định năm nếu bạn không truyền `--year` <br>

Khi thiếu `--semester`, cli chọn kỳ theo `startDate` gần đây. Với lịch tuần, `--date` quyết định năm nếu bạn không truyền `--year`

## Các Options

Các option chung `--campus` (`-c`), `--config`, `--timeout` và `--api-version` có thể đặt trước hoặc sau command, kể cả giữa nhóm lệnh và lệnh con. Option của riêng từng command vẫn đặt sau command đó.

Ví dụ:
```sh
myfap --api-version v2 --campus HN schedule --ics
myfap schedule --ics --api-version v2 --campus HN
myfap info student --timeout 20 --stdout
```

Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con được ưu tiên; lặp trong cùng cấp thì dùng giá trị cuối.
Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con được ưu tiên; lặp trong cùng cấp thì dùng giá trị cuối

|Option|Chú thích|
|:-|:-|
|--help|Hiển thị bảng Commands và Options|
|--config <đường dẫn>|Đường dẫn tới file cấu hình session tùy chỉnh (mặc định: ~/.myfap-api-cli/session.json)|
|--timeout <giây>|Timeout HTTP; ưu tiên hơn biến `MYFAP_TIMEOUT`|
|--api-version <v1 hoặc v2>|Chọn API; ưu tiên option, session, rồi v1. V2 hỗ trợ các command đọc hiện có trong Phase 4.|
|-c, --campus <cơ sở>|Mã cơ sở; ưu tiên option rồi session. APHL chỉ mặc định cho v1; v2 cần chọn campus nếu chưa có mã phù hợp trong session.|
|-s, --semester <kỳ học>|Tên kỳ học (VD: Summer2026)|
|--timeout <giây>|Tăng hoặc giảm thời gian chờ dữ liệu gửi về từ server, có thể dùng biến môi trường ``MYFAP_TIMEOUT``|
|--api-version <v1 hoặc v2>|Chọn API; ưu tiên option, biến môi trường `MYFAP_API_VER`, version trong session, rồi mặc định v2. Session cũ thiếu version vẫn là v1|
|-c, --campus <cơ sở>|Mã cơ sở; ưu tiên option rồi session. APHL chỉ mặc định cho v1; v2 cần chọn campus nếu chưa có mã phù hợp trong session|
|-s, --semester <kỳ học>|Tên kỳ học (VD: ``Fall2026``)|
|-cid, --courseid <mã môn>|Chọn mã môn, chỉ có ở command ``marks``. (VD: 82934, lấy từ bảng điểm của kỳ, ko phải mã môn như PRO192, SWE201c, ...)|
|-w, --week <số tuần>|Chọn tuần, chỉ có ở command ``week-timetable``|
|-y, --year <số năm>|Chọn năm học, chỉ có ở command ``week-timetable``|
|-d, --date \<YYYY-MM-DD\>|Chỉ định ngày chính xác, chỉ có ở command ``week-timetable``|
|-sc, --subjectcode <mã môn>|Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname <mã lớp>|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`` (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))|
|--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``, 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, chỉ có ở command ``marks`` và ``transcript``|
|--output, -o <thư mục>|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``|
|--timeout <giây>|Tăng hoặc giảm thời gian chờ dữ liệu gửi về từ server, có thể dùng biến môi trường ``MYFAP_TIMEOUT``|


## Thông tin thêm
- [Chọn API v1 hoặc v2](./docs/cli/api-versions.md): v2 là mặc định khi chưa có session; xem thứ tự ưu tiên và cách dùng v1
- [Các ví dụ sử dụng](./docs/cli/Example.md)
- [Tạo môi trường dev bằng uv](./docs/cli/development.md)
- [CI và kiểm tra artifact](./docs/cli/development.md#ci-và-kiểm-tra-artifact)

## Ghi công
- Api đã dc reverse engineered từ [myFAP android](https://play.google.com/store/apps/details?id=com.fuct): phiên bản *2.0.6*, versionCode: *31*
Expand All @@ -122,4 +135,4 @@ Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con đư
- [Playwright](https://playwright.dev/): chịu trắch nhiệm chính trong quy trình login
- [Typer](https://typer.tiangolo.com/) & [Rich](https://rich.readthedocs.io/): nền tảng giao diện cli của repo này
- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/): bóc tách và xử lý dữ liệu html
- [ics.py](https://icspy.readthedocs.io/): tạo và chuẩn hóa định dạng iCalendar giúp dễ dàng import vào các ứng dụng lịch
- [ics.py](https://icspy.readthedocs.io/): tạo và chuẩn hóa định dạng iCalendar giúp dễ dàng import vào các ứng dụng lịch
Loading
Loading