awcms-profile-identity

name

awcms-profile-identity

description

SEBAGIAN BACAAN SAJA — hanya fondasi (Issue 2.2: profile CRUD, identifier, entity link, `sql/003`) yang ada di repo ini; seluruh lapis Issue #748 yang dijelaskan di bawah (merge workflow, relasi party-to-party, deteksi duplikat, merge history) ADA DI awcms-mini dan BELUM di-port ke sini. Gunakan saat mengubah profile CRUD/identifier/masking/cross-tenant guard, ATAU saat mem-port lapis #748 dari mini — bagian #748 di skill ini adalah spesifikasi target, bukan deskripsi kode yang bisa dipanggil hari ini.

AWCMS — Profile Identity Module

profile_identity (src/modules/profile-identity) adalah siklus hidup party (person/organization) KANONIK. Baca src/modules/profile-identity/README.md untuk keadaan repo ini yang sebenarnya; skill ini merangkum invariant keamanan (cross-tenant guard, self-approval, field-conflict snapshot) yang WAJIB dipertahankan.

STATUS — baca duluan, dua lapis dengan realitas BERBEDA

Lapis	Di repo ini
Fondasi (Issue 2.2, sql/003) — awcms_profiles, awcms_profile_identifiers, awcms_profile_entity_links, masking, resolve	ADA — kode nyata, boleh dijadikan acuan implementasi.
Issue #748 (epic platform-evolution #738 Wave 2) — merge workflow, profile_relationships, profile_duplicate_candidates, profile_merge_requests/_history, channel/alamat effective-dated	TIDAK ADA — ada di awcms-mini (migrasi 059 di sana), belum di-port. Tabel, endpoint, domain/merge.ts, domain/relationship.ts yang disebut di bawah tidak ada file-nya di sini.

Konsekuensinya, jangan: (1) memanggil/mengimpor domain/merge.ts, domain/relationship.ts, application/merge-workflow.ts, duplicate-candidate-directory.ts, atau _shared/ports/party-directory-port.ts — tidak ada di repo ini; (2) SELECT dari tabel merge/relationship/duplicate-candidate; (3) mengklaim ke user bahwa merge workflow "sudah ada". README.md modul ini menyebut mereka di §"Belum tersedia" — itulah yang akurat. Bagian sisa skill ini berguna sebagai spesifikasi target port (invariant apa yang WAJIB ikut saat lapis #748 di-port dari mini) — bukan peta kode.

Kapan pakai skill ini vs skill generik

Melengkapi awcms-sensitive-data (normalize/hash/mask identifier — domain/identifier.ts di modul ini adalah CONTOH implementasi pola itu), awcms-abac-guard (self-approval guard dipakai ulang di sini), awcms-idempotency. Skill ini menyediakan konteks merge-workflow dan cross-tenant guard spesifik modul ini.

Tabel (sql/003 fondasi = ADA; tabel bertanda [#748 — mini] = BELUM ADA di sini)

• awcms_profiles — profile kanonik, soft delete, merged_into_profile_id untuk hasil merge, status (active/inactive/merged — merged HANYA di-set oleh eksekusi merge, tidak bisa lewat PATCH).
• awcms_profile_identifiers — identifier sensitif (email/phone/ whatsapp/national_id/tax_id/external_code), dedup lewat value_hash (unique parsial per tenant+type selama belum soft-deleted), masked_value untuk tampilan aman. Kolom provenance/verified_at/ verified_by/valid_from/valid_until = [#748 — mini], tidak ada di sql/003 repo ini.
• [#748 — mini] awcms_profile_channels — preferensi channel, mengacu ke profile_identifiers (TIDAK menduplikasi nilai sensitif); is_default = flag "preferred channel per type".
• [#748 — mini] awcms_profile_addresses — alamat per profile, effective-dated.
• awcms_profile_entity_links — tautan profile ke entity modul lain (module_key/entity_type/entity_id), unique per entity — SET REFERENSI yang direpoint saat merge dieksekusi.
• [#748 — mini] awcms_profile_relationships — relasi party-to-party effective-dated, GENERIK: relationship_type teks bebas snake_case, TIDAK ADA CHECK enum peran bisnis (customer/supplier/employee). Authorized representative hanyalah baris relasi is_authorized_representative = true.
• [#748 — mini] awcms_profile_duplicate_candidates — kandidat duplikat: match_basis/match_score/match_reasons (jsonb, SELALU explainable), status (pending/confirmed_duplicate/not_duplicate). Pasangan disimpan terurut (profile_id_a < profile_id_b).
• [#748 — mini] awcms_profile_merge_requests — source(loser)/target(survivor), source_profile_id <> target_profile_id (constraint DB + domain/merge.ts), requires_approval, field_conflict_snapshot, reference_impact_snapshot. Permission profile_identity.profile_management.restore sudah diseed sql/005 di sini tapi belum punya konsumen — jangan simpulkan dari keberadaan permission bahwa endpoint/tabelnya ada.
• [#748 — mini] awcms_profile_merge_history — append-only, immutable, TERPISAH dari merge_requests yang statusnya mutable. Dasar untuk operator menalar/memulihkan efek merge yang keliru.
• awcms_profile_audit_logs — tidak ada di repo ini sama sekali (di mini ia dead schema: dideklarasikan tapi tak pernah ditulis kode; di sini sql/003 tidak mendeklarasikannya). Audit high-risk lewat logging module's recordAuditEvent/awcms_audit_events. Jangan buat ulang tabel ini "karena skill menyebutnya".

Tabel tenant-scoped sql/003 mendapat ENABLE+FORCE ROW LEVEL SECURITY lewat sql/017_awcms_enforce_rls_force.sql (Issue #139 — sebelum itu hanya ENABLE, yang inert selama app connect sebagai owner tabel). Kalau menyelidiki "kapan RLS FORCE mulai berlaku untuk tabel profile" di repo INI, jawabannya sql/017 — bukan migration 013 (nomor itu penomoran mini untuk enforce_rls_least_privilege; di sini 013 adalah workflow approval). Catatan FORCE saja belum cukup: superuser/BYPASSRLS tetap melewatinya — lihat header sql/019_awcms_db_role_separation.sql (Issue #141) untuk role awcms_app yang membuat policy ini benar-benar dievaluasi.

[#748 — mini] Merge workflow — 3 langkah, approval WAJIB di setiap merge

Seluruh §ini mendeskripsikan kode di awcms-mini. Di repo ini belum ada satu pun endpoint/fungsi merge. Baca sebagai kontrak yang WAJIB dipertahankan saat mem-port, bukan sebagai API yang bisa dipanggil.

1. Create (profile_merge.create) — sourceProfileId (loser) + targetProfileId (survivor) + reason. Menghitung dan menyimpan snapshot field_conflict_snapshot (field yang berbeda antar profile — HANYA untuk review, base ini TIDAK punya UI pick-and-choose per field; nilai SURVIVOR yang selalu bertahan) dan reference_impact_snapshot (jumlah profile_entity_links per module/entity type yang akan direpoint).
2. Approval (profile_merge.approve) — SETIAP merge di base ini wajib approval (computeRequiresApproval() SELALU true — superset ketat "hanya merge high-risk butuh approval", menghindari heuristik risiko yang bisa keliru). Guard self-approval generik (identity-access/domain/access-control.ts) mencegah requester menyetujui request-nya sendiri.
3. Execute (profile_merge.merge, action ABAC terpisah dari .approve) — high-risk: Idempotency-Key wajib, PLUS row lock (SELECT ... FOR UPDATE) pada merge_requests yang menyerialisasi eksekusi konkuren KEDUA (idempotency key BEDA sekalipun) sehingga panggilan kedua melihat status = 'completed' dan mengembalikan hasil yang sudah ada, bukan mengeksekusi ulang. Tenant loser & survivor divalidasi ULANG tepat di titik eksekusi (assertSameTenant), tidak pernah mempercayai apa pun yang tersimpan di request — lihat §Cross-tenant guard di bawah.

Efek eksekusi: profile_entity_links milik loser direpoint ke survivor (baris yang bentrok dengan link survivor yang sudah ada dihapus sebagai duplikat murni), loser di-soft-delete dengan status = 'merged' + merged_into_profile_id, baris profile_merge_history immutable ditulis, event domain awcms.profile-identity.profile.merged dipublikasikan.

Strategi pemulihan merge — TIDAK ADA tombol "undo"

Merge tidak hard-delete — loser tetap ada sebagai baris soft-deleted dengan merged_into_profile_id. Un-merge OTOMATIS penuh tidak disediakan — pemulihan butuh: (1) baca profile_merge_history untuk survivor/loser + snapshot; (2) profile_entity_links yang direpoint masih teridentifikasi lewat module_key/entity_type/entity_id yang sama (profile_id-nya sudah berubah); (3) menulis ulang link + memulihkan loser secara MANUAL/terarah — jejak audit di atas adalah yang dibutuhkan operator, bukan mekanisme otomatis. Jangan janjikan/bangun tombol "undo merge" satu-klik tanpa issue baru eksplisit.

[#748 — mini] CRITICAL — cross-tenant guard, DUA lapis, keduanya wajib

Cross-tenant matching/merge DILARANG KERAS. Ditegakkan di mini lewat dua lapis independen — kontrak WAJIB yang harus ikut saat lapis #748 di-port ke sini, bukan kode yang sudah berjalan di repo ini:

1. RLS (FORCE ROW LEVEL SECURITY) — koneksi role aplikasi biasa tidak akan pernah melihat baris tenant lain sama sekali.
2. domain/merge.ts's assertSameTenant/CrossTenantMergeError — dipanggil ULANG di application/merge-workflow.ts's createMergeRequest DAN executeMergeRequest, terhadap baris yang di-fetch ULANG di dalam transaksi yang sama, tidak pernah mempercayai tenant id yang dibawa objek lama. fetchPartyForMerge SENGAJA TIDAK memfilter tenant_id di WHERE-nya (mengandalkan RLS untuk jalur normal) justru supaya lapis kedua ini GENUINELY teruji lewat test terhadap koneksi privileged (bypass RLS) — di mini: tests/integration/profile-identity.integration.test.ts's test "application-layer guard: assertSameTenant/CrossTenantMergeError fires even when RLS is bypassed". Repo ini belum punya tests/integration/ sama sekali (Issue #154) — port lapis #748 tanpa mem-port test itu berarti guard kedua tidak terverifikasi. Endpoint merge/match baru wajib memanggil assertSameTenant di titik eksekusi, jangan andalkan RLS saja — RLS adalah lapis pertama, bukan satu-satunya.

duplicate-candidate-directory.ts's scan juga selalu ter-scope tenant_id yang sama pada kedua sisi query — tidak ada jalur yang membandingkan profile lintas tenant.

Business role BUKAN hardcoded (persyaratan eksplisit Issue #748)

Berlaku untuk KEDUA lapis. Tidak ada tabel/kolom/enum di modul ini yang mengenkode peran bisnis kontekstual (customer/supplier/employee/donor/ merchant/student/patient). [#748 — mini] relationship_type teks bebas tervalidasi FORMAT saja; domain/relationship.ts (mini) bahkan MENOLAK eksplisit beberapa kata peran bisnis sebagai guard defensif terhadap regresi. Aplikasi turunan bebas membangun semantik domain-spesifik DI ATAS relasi generik ini — jangan tambah CHECK constraint/enum peran bisnis apa pun ke modul base ini.

Kontrak proyeksi (domain/projection.ts)

Di repo ini domain/projection.ts mengekspor satu kontrak: PartyMaskedAdminDTO (API admin — TANPA tenantId/actor id) + toPartyMaskedAdminDTO. Endpoint/response baru wajib memakainya secara eksplisit — jangan bikin bentuk DTO ad-hoc baru yang membocorkan field internal.

[#748 — mini] PartyFullDTO (internal) dan PartyPublicSafeDTO (3 field saja: id/profileType/displayName, null untuk profile soft-deleted/merged/inactive) belum ada di sini — kalau butuh proyeksi public-safe, port PartyPublicSafeDTO dari mini apa adanya, jangan bikin varian baru.

[#748 — mini] Capability port — BELUM ADA di repo ini

_shared/ports/ di sini hanya berisi workflow-condition-port.ts dan workflow-notification-port.ts. party-directory-port.ts (PartyDirectoryPort — exists/resolveSummary/resolveMergeSurvivor mengikuti rantai merged_into_profile_id/resolvePublicSafeSummary), adapter-nya, dan legal-hold-guard-port.ts yang disebut sebagai preseden semuanya ada di mini saja. Jangan import salah satunya di repo ini — port dulu kalau memang dibutuhkan.

Pitfall umum

1. Jangan set status: merged lewat PATCH — hanya eksekusi merge yang boleh set field itu (domain/party-validation.ts menolaknya).
2. Jangan tambah endpoint reveal identifier mentah — belum ada di scope manapun, masked_value adalah satu-satunya bentuk baca yang diizinkan hari ini.
3. Jangan asumsikan awcms_profile_audit_logs adalah sumber audit trail — tabelnya tidak ada di sini sama sekali; gunakan recordAuditEvent/awcms_audit_events.
4. Jangan bikin merge/match tanpa memanggil assertSameTenant ulang di titik eksekusi, meski RLS "seharusnya" sudah mencegahnya.
5. Jangan tambah CHECK enum peran bisnis ke relationship_type atau tabel lain di modul ini.
6. Kalau menelusuri "kapan RLS FORCE mulai berlaku" untuk tabel sql/003 di repo ini, jawabannya sql/017 (Issue #139). Nomor 013/059 yang beredar di dokumen warisan adalah penomoran awcms-mini.
7. Jangan perlakukan §bertanda [#748 — mini] sebagai kode yang ada. Verifikasi ke src/modules/profile-identity/ + sql/003 dulu sebelum memanggil/mengklaim apa pun dari sana.

Verifikasi

Repo ini belum punya tests/integration/ sama sekali (Issue #154) — termasuk profile-identity.integration.test.ts yang disebut di atas; itu milik mini. Yang ada di sini: unit test tests/*.test.ts (jalankan bun test). Saat mem-port lapis #748, test cross-tenant guard yang sengaja bypass RLS (koneksi privileged) adalah bagian WAJIB dari port — bukan opsional — karena itulah satu-satunya yang membuktikan lapis kedua independen dari RLS.

Belum tersedia di repo ini

Seluruh lapis #748 (lihat §STATUS), plus — di mini pun sengaja di luar scope — endpoint reveal identifier mentah (raw value), un-merge otomatis, pencarian full-text (masih substring ILIKE), dan business role/entitas domain (customer/supplier/dll.).