Skip to content

docs: update README with current project state and Neo Feeder API endpoints (DOC-002) #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ffooll-bit merged 1 commit into from
Aug 31, 2026
Merged

docs: update README with current project state and Neo Feeder API endpoints (DOC-002) #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
110 changes: 105 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,17 @@ The name **BASE** (Backbone for Academic Services & Education) reflects that the

## Development Status

Two main features are complete:
The application is functional and covers both authentication and the Neo Feeder data-browsing / administration flows:

1. **Login / Authentication** - Implemented and verified (10/10 E2E passed). The login system uses the Neo Feeder API (`GetToken`) for authentication, with session-based auth via CodeIgniter 4.
1. **Login / Authentication** - The login system uses the Neo Feeder API (`GetToken`) for authentication, with session-based auth via CodeIgniter 4 and an auth filter protecting all routes except the login flow.
2. **AdminLTE 3 → AdminLTE 4 Migration** - The UI layer migrated from AdminLTE 3.2 (Bootstrap 4, jQuery) to AdminLTE 4 (Bootstrap 5, vanilla JS, Font Awesome 7).
3. **Institution & student data pages** - Pages browsing Neo Feeder data read-only through the service layer:
- **Profil Perguruan Tinggi** (`/profil-pt`) - institution profile (identity, contact, address, legalitas).
- **Mahasiswa** (`/mahasiswa`) - student list with edit and read-only detail.
- **Aktivitas Kuliah** (`/aktivitas-kuliah`) - course-activity list with edit.
- **Mahasiswa Lulus / DO** (`/mahasiswa-lulus-do`) - graduated / dropped-out student list.
4. **PISN Graduation wizard** (`/graduation`) - Excel upload of prospective graduates, sequential per-student verification (identity → academic → transcript completeness → PISN eligibility → graduation fields), pre-submit preview, and submission to Neo Feeder via `InsertMahasiswaLulusDO` (`UpdateNilaiPerkuliahanKelas` for missing thesis grades). Progress survives auth-session expiry via a resume cookie + cache-backed store.
5. **Verifikasi IPK** (`/verifikasi-ipk`) - bulk check and correction of last-semester IPK against an Excel file, applying fixes via `UpdatePerkuliahanMahasiswa`.

## Technology Stack

Expand All @@ -34,13 +41,15 @@ Two main features are complete:
BASE/
|-- app/
| |-- Config/ # Configuration (Routes, Filters, NeoFeeder, Services, etc.)
| |-- Controllers/ # Login, Dashboard, Home, BaseController
| |-- Controllers/ # Home, Login, Dashboard, ProfilPT, Mahasiswa, AktivitasKuliah,
| | # MahasiswaLulusDo, Graduation, VerifikasiIpk, BaseController
| |-- Database/ # Migrations & Seeds
| |-- Filters/ # AuthFilter (route protection middleware)
| |-- Helpers/ # Helper functions
| |-- Libraries/ # Auth.php, NeoFeeder.php (service layer)
| |-- Libraries/ # Auth, NeoFeeder, PisnService, WizardProgress, VerifikasiIpkStore (service layer)
| |-- Models/ # Database models
| |-- Views/ # login/, dashboard/, layout/, errors/
| |-- Views/ # login/, layout/, dashboard/, profil_pt/, mahasiswa/,
| | # aktivitas_kuliah/, mahasiswa_lulus_do/, graduation/, verifikasi_ipk/, errors/
|-- docs/ # Project documentation (with docs/archived/ for archives)
|-- public/ # Document root (index.php)
| |-- adminlte/ # AdminLTE 4 CSS/JS (from npm build)
Expand Down Expand Up @@ -79,6 +88,97 @@ The API base URL is configured via `neofeeder.apiBaseUrl` in `.env` (see the `en
}
```

### Request / Response envelope

Every WS call answers with a standard envelope:

```json
{
"error_code": 0,
"error_desc": "",
"data": null
}
```

`error_code` is `0` on success (with `data` populated for list/`Get*` calls). Negative values are produced by the app itself for connection failure (`-1`) and malformed responses (`-2`); `100`/`-2` from the API mean the session/token is invalid.

All API calls are server-side (PHP via CI4 `CURLRequest`) using the token from `session('auth.token')` — the token never reaches the browser. Payload keys are limited to `act`, `token`, `filter`, `order`, `limit`, `offset` (plus `record`/`key` for mutations).

### List / Get endpoints

These use the `{ act, token, filter?, order?, limit?, offset? }` shape. `filter` is a SQL-style WHERE string (e.g. `"nim='202010087'"`), not a JSON object. `order` is a column name, optionally `DESC`.

| WS act | Purpose |
|---------|---------|
| `GetProfilPT` | Institution (PT) profile |
| `GetListMahasiswa` | Student list (biodata) |
| `GetAktivitasKuliahMahasiswa` | Per-semester course-activity summary (IPK, IPS, sks, status) |
| `GetListRiwayatPendidikanMahasiswa` | Study-history list; carries `id_pembiayaan` needed for `UpdatePerkuliahanMahasiswa` |
| `GetStatusMahasiswa` | Reference list of student statuses |
| `GetJenisKeluar` | Reference list of graduation exit reasons |
| `GetSemester` | Reference list of semesters |
| `GetListMahasiswaLulusDO` | Graduated / dropped-out student list |
| `GetCountMahasiswa` | Total student row count (for pagination) |
| `GetCountAktivitasKuliahMahasiswa` | Total activity row count (rejects `nim`/`id_mahasiswa` filters) |
| `GetCountMahasiswaLulusDO` | Total graduated/dropped-out row count |
| `GetTranskripMahasiswa` | Student transcript grade rows |
| `GetBiodataMahasiswa` | Single student biodata (`filter`: `id_mahasiswa='...'`) |
| `GetDetailPerkuliahanMahasiswa` | Single course-activity record (`filter`: `id_registrasi_mahasiswa='...' AND id_semester='...'`) |

### Mutation endpoints

These use the `{ act, token, key?, record? }` shape — `key` holds the primary key for Update/Delete, `record` holds the fields for Insert/Update.

| WS act | `key` | Notes |
|--------|-------|-------|
| `InsertMahasiswaLulusDO` | — | Graduated/dropped-out record |
| `InsertBiodataMahasiswa` / `UpdateBiodataMahasiswa` / `DeleteBiodataMahasiswa` | `id_mahasiswa` (Update/Delete) | Student biodata |
| `InsertPerkuliahanMahasiswa` / `UpdatePerkuliahanMahasiswa` / `DeletePerkuliahanMahasiswa` | `id_registrasi_mahasiswa` + `id_semester` | Course-activity record |
| `UpdateNilaiPerkuliahanKelas` | `id_registrasi_mahasiswa` + `id_kelas_kuliah` | Class grade (e.g. `nilai_huruf`) |

Mutations require a complete record: Neo Feeder rejects partial updates, so every NOT-NULL field (plus fields such as `biaya_kuliah_smt` and `id_pembiayaan` from `GetListRiwayatPendidikanMahasiswa`) must be present.

### Cloud REST endpoints

The transcript-check feature (`getCekTranskripMahasiswa`) calls two cloud REST endpoints under the same API base host instead of a WS `act`. They authenticate with `Authorization: Bearer <token>` (the same token issued by `GetToken`).

| Endpoint | Query | Purpose |
|----------|-------|---------|
| `/ws/transkrip/cari_mahasiswa` | `nm_pd=<nim>` | Find a student |
| `/ws/transkrip/nilai_mahasiswa` | `mahasiswa=<json>` | Transcript grade rows for one student |

Query one student at a time; multi-student queries can overflow the URL length (HTTP 414).

### GetDictionary (schema inspection)

`GetDictionary` inspects the actual `key`/`record` schema of any WS function at runtime — useful before implementing a new endpoint, so the schema is not guessed. In this project it is called ad-hoc as a schema-inspection tool (development-time), not as part of the application's runtime request path.

**Request:**
```json
{
"act": "GetDictionary",
"token": "...",
"fungsi": "<NamaFungsi>"
}
```

**Response (simplified)** — the schema of the requested function:
```json
{
"error_code": 0,
"error_desc": "",
"data": {
"nama": "UpdatePerkuliahanMahasiswa",
"key": ["id_registrasi_mahasiswa", "id_semester"],
"record": [
{ "name": "id_status_mahasiswa", "mandatory": true },
{ "name": "ips", "mandatory": false },
{ "name": "ipk", "mandatory": false }
]
}
}
```

## Setup

1. Clone this repository into your web server directory.
Expand Down
8 changes: 4 additions & 4 deletions docs/IMPROVEMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,12 +231,12 @@ The label is encoded directly in the ID prefix. When a valid item becomes a GitH
- **Changes:** `ARCHITECTURE.md` and `STRUCTURE.md` no longer drift from the code — the pending documentation of the merged PISN features (routes/controllers, libraries, wizard flow, resume cookie) is now committed and tracked in git.

### DOC-002 — Update README to reflect the current project state, including a record of the Neo Feeder API endpoints used (focus GetDictionary)
- **Status:** `verified`
- **Status:** `implemented`
- **Issue:** #120
- **Recorded:** 2026-08-31 15:42
- **Implemented:** —
- **Implemented:** 2026-08-31 16:17
- **Problem:** `README.md` does not yet reflect the current project state (menus/features: Mahasiswa, AktivitasKuliah, MahasiswaLulusDo, the PISN Graduation wizard, Verifikasi IPK; updated dependencies), and its API section documents only `GetToken`. The other Neo Feeder endpoints the project consumes are not recorded, so adding a new feature later requires re-testing endpoints that are already in use, and the `GetDictionary` endpoint (whose `fungsi` parameter reveals the actual `key`/`record` schema of a WS function, and which we already use to inspect schemas) is not captured.
- **Possible Fix:** Extend `README.md` — (1) align the feature/status summary and directory structure with the current state; (2) add a record of the Neo Feeder endpoints the project actually uses: per endpoint the request (act/token/params) and the response, including a dedicated `GetDictionary` subsection (payload `{'act':'GetDictionary','token':...,'fungsi':'<Fungsi>'}` with an example schema response) so new endpoints can be vetted without re-testing existing ones.
- **Actual Fix:** In `README.md`: (1) update the feature/status summary and Development Status to reflect the current menus (Mahasiswa, AktivitasKuliah, MahasiswaLulusDo, PISN Graduation wizard, Verifikasi IPK) and dependencies; (2) replace the current minimal API section with a record of the Neo Feeder endpoints the project actually consumes, per endpoint noting the WS act (or cloud path), request params (act/token and, where used, filter/order/key/record), and a concise response summary (error_code/data). Include a dedicated `GetDictionary` subsection documenting it as a schema-inspection tool called ad-hoc (not part of the app's runtime request path): payload `{'act':'GetDictionary','token':...,'fungsi':'<NamaFungsi>'}` and a short example schema response; the endpoint list is derived from the methods in `app/Libraries/NeoFeeder.php` (WS acts: GetToken, GetProfilPT, GetListMahasiswa, GetAktivitasKuliahMahasiswa, GetListRiwayatPendidikanMahasiswa, GetStatusMahasiswa, GetJenisKeluar, GetSemester, GetListMahasiswaLulusDO, GetCountMahasiswa, GetCountAktivitasKuliahMahasiswa, GetCountMahasiswaLulusDO, GetTranskripMahasiswa, GetBiodataMahasiswa, GetDetailPerkuliahanMahasiswa, InsertMahasiswaLulusDO, Insert/Update/Delete BiodataMahasiswa, Insert/Update/Delete PerkuliahanMahasiswa, UpdateNilaiPerkuliahanKelas; plus cloud REST `/ws/transkrip/cari_mahasiswa` + `/ws/transkrip/nilai_mahasiswa`). Schema facts are summarized from prior live-verified test results (already recorded in the tracker), not re-tested.
- **Actual Implemented:** —
- **Changes:** —
- **Actual Implemented:** Rewrote `README.md` on branch `docs/readme-api-endpoints` from `main`: (1) Development Status now lists the current features (Login/Auth, AdminLTE 4, Profil PT, Mahasiswa, Aktivitas Kuliah, Mahasiswa Lulus/DO, PISN Graduation wizard, Verifikasi IPK); (2) Directory Structure updated with the actual Controllers/Libraries/Views; (3) the Neo Feeder API section now documents the standard request/response envelope, List/Get endpoints table, Mutation endpoints table (with `key` and the complete-record requirement), the two cloud REST transcript endpoints, and a dedicated GetDictionary schema-inspection subsection. Markdown verified LF-only + no-BOM (CI markdown checks pass).
- **Changes:** `README.md` now reflects the current project state and records every Neo Feeder endpoint the project consumes (WS acts, mutations, cloud REST, and GetDictionary schema inspection), so new features no longer require re-testing endpoints already in use.