AI Assessment Flow — Koperasi (AHU Koperasi / Yii2)

Status: proposal for review · Date: 2026-07-31
Subject codebase: AHU Koperasi (Yii2), master
Note on links: file paths are relative to that repo root.
Method: read-only code survey. Every claim is tagged [CERTAIN] (read directly in a code path that executes) or [VERIFY] (inferred, needs a probe).
Precedents copied: tasks/prd-ptp-ai-transformation.md, docs/specs/apostille-build-plan.md, docs/specs/apostille-extraction-catalog.md

0. Why this flow looks different from PTP and Apostille

Both earlier assessments burned a stage on a question this codebase answers for free.

• PTP: we designed an akta-extraction flow, then discovered PTP has no akta upload anywhere. The document layer was assumed.
• Apostille: the extraction catalog over-claimed code reuse and had to be corrected adversarially before build. Reuse was assumed.

For koperasi, the document layer is not an unknown. It is declared in code, in one class, with types, conditional requirements, size limits and storage paths. That collapses the most expensive stage of the standard assessment from "buy a DB grant and wait for a corpus" into "confirm on samples what the code already tells us."

The headline: koperasi requires a notarial deed (akta) as a mandatory PDF upload on both Pendirian and Perubahan [CERTAIN] — models/TPendirianDokumen.php:46-56. That single fact makes this domain cheaper for us than Apostille was: our akta extractor stack lands directly on the critical path instead of needing a new document family.

The counter-headline, and the reason B0 took longer than expected: the ActiveRecord model for the main table is not a usable schema reference. Its @property docblock and rules() describe a superseded schema generation and disagree with the columns the application actually writes. §2.3 and D5 deal with this. Any read client built from the model class would query columns that are at best unpopulated.

1. The flow in one picture

Effort (one engineer; S ≤ 1 day · M 2–4 days · L 1–2 weeks): B0 done · A0 S, long lead time · A1 M–L · A2 S · A3 M · A4 M · A5 S · A6 M. Total ≈ 2.5–3 weeks of engineering, versus 3–4 for a blind assessment. A0 is mostly waiting on AHU — file it on day one and run A4 (pure in-repo work) while waiting.

Note on the final gate. It is drawn as a decision point, not a gate, deliberately. "Beats the marginal next item in the queue" is only a gate if the existing queue is scored on the same axes. Unless we commit to doing that, this is a product call with a scorecard attached — and calling it a gate would be theatre.

2. B0 — What the code already tells us ✅

2.1 Document taxonomy — complete, from one constant

TPendirianDokumen::TYPE_MAPPING [CERTAIN] — models/TPendirianDokumen.php:21-30:

Conditions are in code, not policy documents [CERTAIN]:
- surat_rekomendasi required when jenis_koperasi == 'jasa tkbm' or pola_pengelolaan == 'syariah' — models/TPendirianDokumen.php:67-69
- hasil_musyawarah_desa required when jenis_koperasi is 'desa merah putih' or 'kelurahan merah putih' — models/TPendirianDokumen.php:81-83

Constraints [CERTAIN]: PDF only, MIME-checked; 5 MB for akta / berita acara / rekomendasi, 10 MB for musyawarah desa; duplicate filenames within one submission rejected (fileUnique, :126-147). Storage: web/uploads/<transaction_id>/<basename>.<ext>; row in kop_t_pendirian_dokumen (transaction_id, type, document_name) — filename only, no path (:149-176).

This is our DocumentType enum, pre-written. No corpus needed to derive it. But see D1 — the stored type value cannot be trusted as a training label.

2.2 Every upload entry point in the app [CERTAIN]

Six flows, and every one has a document layer. Contrast PTP, where the answer was "none."

Two corrections worth carrying, both [CERTAIN]:
- There is no surat_kuasa upload. file_surat_kuasa is a column on kop_pesan_nama read by an admin download action (controllers/AdminController.php:1806-1818); nothing in the app uploads to it. Provenance [VERIFY] — possibly ODS or a retired path.
- kop_t_perbaikan.file_surat_keterangan_domisili is NOT NULL in the DDL (migrations/20250816_insert_kop_t_perbaikan.sql:8) but is hardcoded to an empty string on write (components/helper/PerbaikanDataHelper.php:35). It is a dead column. See D9.

2.3 Pendirian field census — the extraction target set

Source of truth: the assignment block inside savePendirian() — models/forms/PendirianForm.php:794-863 — cross-checked against the raw SQL at models/TransaksiKoperasi.php:591 and the API serialiser at components/ApiHelper.php:105-210.

Why not the docblock. savePendirian() ends in $Trans->save(false) (:864) — validation is skipped, so the model's rules() have never executed in this path and were free to drift. Yii2 derives ActiveRecord attributes from the live table schema and raises UnknownPropertyException on an unknown attribute, so every assignment below is proof the column exists. rules(), attributeLabels() and @property are proof of nothing.

Confidence discipline: the column is [CERTAIN]. The document source is [INFER] — that is the hypothesis A1 measures. A verified column name must not lend borrowed confidence to an unverified source claim.

Columns written on every pendirian that the docblock does not mention [CERTAIN]:

First-pass ratio: ~24 of ~30 substantive scalar fields, plus all three rosters, are document-derived. That is a strong prior for passing G1 — but it is a prior, measured against form structure, not against real akta text. A1 exists to measure it; G1 stops us if it does not hold.

2.4 Roster and child tables — highest-confidence column lists [CERTAIN]

These come from batchInsert() calls, where the column list is written verbatim into the SQL. Strongest evidence available anywhere in this codebase.

kop_data_anggota — officers and supervisors — models/forms/PendirianForm.php:940

t_koperasi_id, m_status_pengurus_id, nama_status, nik, nama,
jenis_kelamin_id, jabatan, npwp, hp

Column is hp, not no_hp (:953). nama_status is stored denormalised beside the FK.

kop_pemilik_manfaat — beneficial owners — models/forms/PendirianForm.php:966

t_koperasi_id, nama, m_jenis_identitas_id, no_identitas, tempat_lahir,
tanggal_lahir, alamat, kewarganegaraan, npwp, hubungan, json_checkbox,
provinsi_id, kabupaten_id, kecamatan_id, kelurahan_id, rt, rw,
negara_asal, is_from_api

Three traps: kewarganegaraan stores the text 'WNI'/'WNA' (:978, confirmed by components/ApiHelper.php:452); the column is negara_asal while the form field is negara_bo (:988); npwp is capped at 16 chars (models/PemilikManfaat.php:55) while a formatted NPWP is 20 — normalise to digits before comparing.

kop_t_aktifitas_usaha — KBLI — models/forms/PendirianForm.php:923

t_koperasi_id, kbli_id, jenis_kbli

jenis_kbli holds 'Utama'/'Pendukung'/'Tambahan', capitalised by ucwords() (:928) and read back with that casing (models/TransaksiKoperasi.php:577). Match case-insensitively.

kop_t_koperasi_sekunder — founding cooperatives — models/forms/PendirianForm.php:901

t_koperasi_id, id_master_sekunder, nik, nama_koperasi, no_sk_koperasi, npwp, file_sk

file_sk is written as an empty string — the copy is commented out (:906-907). The uploaded SK is not persisted by this path.

Where the document attestations actually live. The notary ticks a checkbox group declaring which supporting documents exist. It is not stored as is_minuta / is_surat_bukti / is_rencana_kerja columns — those have no writer anywhere in the application. The list is built by ActionHelper::getListCheckbox('dokumen_form_pendiran') (controllers/PendirianController.php:221), persisted through SaveChkBoxPendirian() → DisclaimerHelper::generateValues(..., 'dokumen_form_pendiran', ...) (models/forms/PendirianForm.php:999-1002), and lands in kop_t_statement_disclaimer (models/StatementDisclaimer.php:23).

Expansion path worth naming in the PRD, not in Phase 1 scope: those attested-but-unfiled documents — minuta, surat bukti setor, rencana kerja — are documents we already extract elsewhere (bukti setor in PP/PT). If AHU ever requires them to be uploaded, our stack is ready the day the policy changes. Inspect kop_t_statement_disclaimer at A0 to see which are actually attested today.

2.5 Validation gaps — the value story [CERTAIN]

Three of the highest-risk tables in the system — the rosters — have no meaningful validation, and the one table that does have rules never runs them. We would be the first validation layer these rosters have ever had. That mirrors work already shipped for PP beneficial owners: cheap for us, highly visible to them.

2.6 Defects found in passing — carry into A5

Additional schema/model mismatch worth flagging in A5: kop_t_perbaikan.status_transaksi_perbaikan has seven enum values in DDL but the model validates only five (migrations/20250816_insert_kop_t_perbaikan.sql:11 vs models/TransaksiPerbaikan.php:63-69). Historical rows may hold values the current workflow never produces.

2.7 Integration surface — [CERTAIN] for existence, [VERIFY] for access

• Read: ServiceController::actionGetKoperasi and actionGetKoperasiV2 — controllers/ServiceController.php:69, :201. JWT via auth-jwt: Bearer. Returns only is_active = 1 AND is_finish = 1 (modules/Api/components/TransaksiHelper.php:415-416) — dissolved, merged, blocked and in-progress records, and the entire amendment history, are invisible through the API. Errors fire a Telegram message to an ops group (:97, :193) — do not build bulk polling on this.
• Write: modules/Api/controllers/TransaksiController.php exposes actionInsert (:540), actionUpdate (:353), actionEdit (:747), plus actionDummy and an unauthenticated actionSandbox (:945-947) [VERIFY] whether that route is reachable.
• Access gate: every route, including /api/* and /service/*, passes an application-wide filter resolved against a DB allow-list (config/web.php:197-199; vendor/docotel/yii2-dcms/components/Helper.php:412). [VERIFY] — this decides whether any API integration is possible at all.
• Identity: Dukcapil NIK validation is already wired — components/HelperDukcapil.php:36-76, with a feature flag (CheckIsActiveValidateDukcapil) and an AllowValidation() bypass. Do not duplicate the Dukcapil call — cross-check against it.
• Notary: NotarisNpak::checkNotarisNPAK() — models/NotarisNpak.php:24 — koperasi keeps its own NPAK list keyed on id_notaris. Our notary matching targets SABH PT transactions. [VERIFY] whether id_notaris shares an identifier space — if yes, matching is nearly free; if no, it is net-new.
• Schema: docs/dbml/schema.20250808.dbml exists but covers only 3 tables. The rest needs an information_schema dump (A0).

3. Remaining stages

A0 — Access & corpus (S, long lead time — file day one)

Artifact: koperasi-a0-access-report.md.
Gate G0: DB read live and information_schema returned and corpus delivered with a date. Anything less → park, escalate, no design spend.

A1 — Traceability validation ⭐ (M–L — the stage that decides the product)

Not a discovery stage; a measurement stage. §2.3/§2.4 is the hypothesis, A1 is the experiment.

1. Gold set. Manually key ground truth for 20–30 real bundles. This is the only honest accuracy measure and it is not optional.
2. Silver set — cheap and large. Every corpus file joins through kop_t_pendirian_dokumen.transaction_id to kop_t_koperasi + kop_data_anggota + kop_pemilik_manfaat — i.e. what the notary claimed the akta says. That is automated field-level recall at corpus scale for near-zero extra effort. It is silver, not gold: where extraction and database disagree, either may be wrong — and that ambiguity is itself a finding worth surfacing.
3. Run the existing pipeline unchanged (classifier + akta extractor + KTP/NPWP) over both sets. Output is one number per field, not a narrative.
4. Characterise the corpus: native PDF vs scan vs photo-of-screen; multi-document-per-file; how an akta koperasi differs structurally from the akta PT our extractor was tuned on.
5. Roster shapes: cardinality distribution of pengurus/pengawas and BOs per cooperative, and which document each row is transcribed from.

Artifact: koperasi-extraction-catalog.md, same shape as the Apostille catalog, [CERTAIN]/[INFER] tagged.

Gate G1 — two thresholds, because the two problems are not comparable:

Both thresholds are starting points and should be calibrated in A1 against what the review UI can actually absorb. Failing either → rescope to validation-assist + roster QA, which remains genuinely valuable given §2.5, rather than sell an extraction product we cannot deliver.

A2 — Flow ranking (S)

Score = annual volume (A0.5) × manual fields eliminated (§2.3) × extractability (A1) ÷ build cost (A4), with reviewer-time-saved weighted double — it is the scarce resource.

Note on the rest of the system. Pendirian and Perubahan are notary self-service — the notary calls approvetransaction and the SK is auto-generated with no ministry verifier in the loop (controllers/PendirianController.php:624-690). The only human verification workflow in koperasi is Perbaikan Data. That caps how much "verifier time saved" exists to win, and it should be said out loud in A2 rather than discovered in build.

A3 — Integration decision (M)

Going-in recommendation, to be confirmed not assumed: R1 + R2 for read (R1 for analysis and backfill, R2 as the supported runtime interface), and W1 standalone for Phase 1 — the Apostille decision that de-risked that project by removing an integration dependency from the critical path.

W3 stays red [CERTAIN]. Records written through Api/TransaksiController are flagged is_migrasi / is_ods, and for those records: transaction-number generation is skipped entirely (models/TransaksiKoperasi.php:381), the ODS clone path writes nomor_transaksi = '' (modules/Api/components/TransaksiHelper.php:171), notary identity is nulled (:173-174), is_finish is forced to 1 (:186), and notary validation is skipped downstream (models/MasterTransaction.php:296, :332). Writing through that door means our submissions inherit the exact defect class behind D6 — and leave the legally responsible notary unrecorded.

Probes: confirm A0.6's allow-list result end-to-end with a real service account; obtain a non-paging path for our traffic; get a written answer on who owns the front door. That last one is a product decision, not an engineering one, and it silently determines half the frontend scope — so ask it on day one (§6.7) even though it is decided here.

Artifact: koperasi-integration-decision.md — one page, options, chosen path, signed off by product.

A4 — Reuse ledger (M — run in parallel with A0)

Exit: an adversarial pass whose only job is to refute each ♻️. Every row downgraded here is effort we would otherwise discover mid-build. The Apostille precedent says the first draft of this table over-claims — and this is a first draft.

A5 — Risk register (S)

D1–D9 from §2.6, each tagged design constraint / validator severity / ops ask, carried into the PRD. The five that change architecture:

• D1 + D4 → classify every file by content; treat stored type as a hint, never a label.
• D2 → copy the corpus; never reference files in place; size the loss before promising cross-year coverage.
• D5 → column names come from write paths and raw SQL only; information_schema is the arbiter.
• D6 + D7 + D8 → key on id / id_master. Never on nomor_transaksi, nik, or names.
• Name sanitisation → Helpers::sanitizeHtmlInput strips & / < > " ' from stored values (components/Helpers.php:328-349, applied at controllers/PerubahanController.php:93, :114). Stored names differ from akta text; normalise both sides before comparing, or every name with an ampersand reads as a mismatch that is not one.

Two further items for the register: historical-discrepancy policy — decide, before running cross-validation at scale, what happens when it flags a past registration as not matching its akta; and upload ceilings — if our front door accepts scans larger than the existing 5 MB / 10 MB limits (models/TPendirianDokumen.php:53, :78), handover under W1 can fail at the far end.

A6 — Scope lock (M)

PRD (PTP shape) + phased build plan (Apostille shape). Non-negotiables:

• Phase 0 is scaffold-only — enum + registry entry + route + page shell + rematch wiring; exits when a submission can be created and the shell renders, with no extraction.
• First value phase is identity (KTP → identity block + cross-validation) — cheapest shippable win, the #1 typo field, and it lands on rosters that have no validation today (§2.5).
• All model/OCR egress through the gateway with standard headers and queue semantics (ahu-gpu-manager/docs/CONVENTIONS.md); engine changes dormant until the env flip.
• Phase 1 writes nothing back to AHU_KOPERASI.

4. Gate summary

5. Where this sits in the queue — say it out loud

Standing priority is PP → Apostille/Legalisasi → PT. Koperasi is a fourth domain. What changed with this survey is the price of finding out: the document layer is known, the field census is verified against write paths, the reuse story is legible, and the remaining unknowns are volume, corpus quality, file survival and schema confirmation — all AHU asks with long lead times and near-zero engineering cost while waiting.

Recommended: file the A0 asks now, assess when they land, build when the queue clears.

Be honest about what "assess now" costs: the waiting is free, but A2, A4, A5 and A6 are roughly two to three engineer-weeks of real work. That is small, and it is not nothing.

Starting the build in parallel is not on the table — koperasi needs a net-new read client, a net-new classifier taxonomy and new akta schemas. It is not a configuration of an existing flow.

6. Asks for AHU (file these on day 1)

1. Read-only MySQL grant on AHU_KOPERASI and AHU_BADAN_HUKUM.
2. information_schema dump for all kop_* tables — the committed DBML covers 3, and the model class is unreliable (D5).
3. Document corpus — ≥50 PDFs per type, across years and provinces, copied out, with matching kop_t_pendirian_dokumen rows.
4. File-survival counts: rows versus files present on disk, by year (see D2).
5. Row counts per jenis_transaksi_id per month.
6. SELECT on allowed / group / auth_assignment, kop_setting, and kop_t_statement_disclaimer.
7. A named product owner who can answer the front-door question in A3.
8. Staging instance + service account, if API integration survives A3.
9. Confirmation of who owns the NPAK registry and whether id_notaris shares an identifier space with SABH.

Bugs worth reporting back regardless of whether this project proceeds: D1 (type 7 collision), D2 (document deletion on re-upload, in two flows), D3 (raw SQL with interpolated filenames), D9 (dead NOT NULL column). Worth mentioning separately: the application ships with YII_DEBUG enabled (web/index.php:4-5), and the working tree carries live-looking credentials — treat any koperasi checkout or dump as credential-bearing.