Doc_chelvyn/Mito/Sfa/Fitur/SFA — Customer Registration.md

392 lines
28 KiB
Markdown
Raw Normal View History

---
judul: SFA — Customer Registration (SFA → CMS → Odoo 18)
proyek: SFA API · SFA CMS · mito_odoo
terkait: Mito · Odoo 18 · SFA Mobile
stack: Node/Express (sfa-api) · Laravel 11 · Filament 3 · MySQL · Odoo 18 (mito_base)
kategori: Fitur
status: Dev 21-10-2026 — CMS b758711 (Jenkins), API 956e8e3 di server (8cd2cd4 di develop belum naik, sengaja ditahan sampai presentasi). Bolu sudah diperbaiki (partner #16810)
tipe: dokumen-internal
tags:
- sfa
- cms
- odoo
- customer-registration
- fitur
diperbarui: 2026-10-20
---
> Index: [[SFA — Index]] · Kategori: **Fitur** · FDD: [[CUSTOMER REGISTRATION]]
>
> Implementasi FDD Customer Registration: sales mendaftarkan **calon customer baru** dari SFA, approver CMS
> memutuskan, CMS langsung membuat customer **Draft** di Odoo, dan customer aktif setelah Finance melengkapi COA AR/AP
> lalu **Validate**. Selama approval & pengiriman ke Odoo data hanya ada di tabel staging **`customer_approval`**;
> baris master `customer` baru dibuat saat Odoo membalas **SYNCED** (§10). Berbeda dengan [[SFA — Self Registration]] (akun untuk customer yang **sudah ada**): customer hasil
> alur ini nantinya bisa melakukan Self Registration setelah ACTIVE.
# SFA — Customer Registration
## Alur Registrasi → Approval → Odoo
```mermaid
flowchart TD
A["Sales SFA: POST /master/customer-registration<br/>(token user internal)"] --> V{"Body valid?<br/>cust_name, cust_type INDIVIDUAL/COMPANY,<br/>employee_id, format email / HP / NPWP"}
V -- tidak --> V1["400"]
V -- ya --> E{"Email (trim + lowercase) dipakai master customer<br/>atau registrasi lain yang masih berjalan?"}
E -- "ya, registrasi sendiri NEEDS_REVISION" --> E1["409 + data.registration_id<br/>perbaiki lewat resubmit"]
E -- "ya, lainnya" --> E2["409 Email sudah terdaftar"]
E -- tidak --> P["Baris customer_approval (staging)<br/>registration_status PENDING_APPROVAL<br/>BELUM masuk tabel customer<br/>+ lonceng approver CMS"]
P --> D{"Approver CMS<br/>(lihat Potential Duplicates)"}
D -- "Request Revision + alasan" --> R["NEEDS_REVISION"]
R --> RS["Sales: PUT /master/customer-registration/:id/resubmit"] --> P
D -- "Reject + alasan" --> X["REJECTED (final)<br/>email boleh dipakai registrasi baru"]
D -- Approve --> C{"Email masih bebas<br/>di CMS? (cek ulang)"}
C -- tidak --> C1["Approve ditolak<br/>minta revisi / reject"]
C -- ya --> Q["APPROVED · sync QUEUED<br/>→ langsung POST /api/v1/customers<br/>(masih di staging)"]
Q --> O{"Hasil Odoo"}
O -- "201 / 200 (retry)" --> S["SYNCED · partner Draft<br/>+ baris customer ACTIVE / REGULAR dibuat<br/>customer_id terisi · odoo_status PENDING_FINANCE"]
O -- "409 duplicate_email / 422" --> F["sync FAILED → otomatis REJECTED<br/>reason 'Rejected by Odoo. …'<br/>+ lonceng admin · tidak masuk tabel customer"]
F -- "can_resubmit: true · sales perbaiki<br/>PUT /master/customer-registration/:id/resubmit" --> P
O -- "timeout / 5xx / 409 registration_in_progress" --> T["RETRY · worker tiap menit<br/>jeda 1, 5, 15, 30, 60 menit"]
T --> O
T -- "gagal sampai retry ke-10" --> F
S --> FN["Finance di Odoo: customer Draft<br/>lengkapi COA AR/AP → Validate"]
FN --> AC["odoo:sync-customers (01:15 / tombol Cek Status Odoo)<br/>activated_at terisi, odoo_status ACTIVE"]
AC -.-> SR["Boleh Self Registration / claim reward"]
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
classDef todo fill:#f3f4f6,stroke:#9ca3af,color:#374151,stroke-dasharray:4 3
class P,Q,S,AC ok
class V1,E1,E2,X,C1,F err
class SR todo
```
Hijau = tersimpan / berhasil · merah = ditolak / gagal · abu putus-putus = di luar alur ini (Self Registration).
### Tiga status terpisah (FDD §6)
```mermaid
stateDiagram-v2
state "registration_status (approval CMS)" as A {
[*] --> PENDING_APPROVAL: submit SFA
PENDING_APPROVAL --> NEEDS_REVISION: Request Revision
NEEDS_REVISION --> PENDING_APPROVAL: resubmit SFA
PENDING_APPROVAL --> REJECTED: Reject
PENDING_APPROVAL --> APPROVED: Approve
APPROVED --> REJECTED: ditolak Odoo / retry habis (SYSTEM)
}
state "odoo_sync_status (integrasi)" as B {
[*] --> QUEUED: Approve
QUEUED --> SENDING
SENDING --> SYNCED: 201 / 200
SENDING --> RETRY: timeout / 5xx
RETRY --> SENDING: worker / Kirim Ulang
SENDING --> FAILED: 422 / duplicate_email / retry ke-10
}
state "Baris customer (master)" as D {
[*] --> BELUM_ADA: submit SFA (staging saja)
BELUM_ADA --> ACTIVE_CMS: SYNCED (dibuat CMS)
}
state "Status Odoo (odoo_status)" as C {
[*] --> PENDING_FINANCE: partner snk_state draft
PENDING_FINANCE --> ACTIVE: Finance Validate + sync (activated_at)
}
```
Gagal **sementara** (timeout / 5xx) tidak mengubah status approval (tetap `APPROVED`, mobile `PROCESSING`). Gagal **permanen**
(`422` / `duplicate_email`, atau retry habis) → sync `FAILED` dan registrasi **otomatis `REJECTED`** (keputusan 21-10-2026,
menyimpang dari FDD §6). Tidak pernah ada baris customer untuk registrasi yang gagal.
> [!warning] Menyimpang dari FDD §5 / §17 (keputusan user 20-10-2026)
> FDD: customer baru Active setelah Finance melengkapi COA AR/AP. Implementasi: customer **dibuat `ACTIVE` / `REGULAR`
> di CMS begitu Odoo membalas SYNCED** (bisa dipakai sales, Self Registration, claim reward). Di Odoo partner tetap **Draft** sampai
> Finance Validate, jadi belum bisa dipilih di Sales Order Odoo. Status Odoo dibaca dari `odoo_status`
> (`PENDING_FINANCE` / `ACTIVE`, berdasarkan `activated_at`), bukan dari `cust_status`.
---
## 1. Keputusan (mengisi TBD FDD §16)
| # | Topik FDD | Keputusan |
|---|---|---|
| 1 | Tempat data | Tabel staging **`customer_approval`** (+ `customer_approval_attachment`). Baris `customer` baru dibuat saat SYNCED (keputusan 20-10-2026, §10). *Sebelumnya: langsung di `customer` PROSPECT / INACTIVE* |
| 2 | Registration ID | `CMS-CR-` + id `customer_approval` 6 digit (`CMS-CR-004711`). Data lama dipindah dengan id yang sama, jadi Registration ID yang sudah ada di Odoo tidak berubah |
| 3 | Email mandatory? | **Opsional** (seperti sebelumnya). Kalau diisi: format email, trim + lowercase |
| 4 | Email uniqueness scope | **Global**: master `customer` + `customer_approval` yang masih berjalan (belum REJECTED, belum jadi customer), dicek saat submit, resubmit, dan approve. Odoo mengecek lagi ke semua `res.partner` (termasuk arsip) |
| 5 | Email dari registrasi REJECTED | **Boleh dipakai lagi** (sama dengan Self Registration) |
| 6 | Exact vs potential duplicate | Email sama = **blocker**. NPWP / no. HP (dinormalisasi `62`↔`0`) / nama sama = **Potential Duplicates** di halaman approval, tidak memblokir |
| 7 | Draft / pending di Odoo | Pakai field yang **sudah ada** `res.partner.snk_state`: `draft` = Pending Finance, `validate` = Active. Customer draft sudah tidak bisa dipilih di Sales Order (domain `partner_id`) dan tidak ditarik CMS |
| 8 | COA AR/AP | Diisi Finance di form partner sebelum klik **Validate**. Belum ada validasi sistem bahwa COA sudah diubah (lihat §7) |
| 9 | Status balik Odoo → CMS/SFA | Lewat `odoo:sync-customers` (harian 01:15, atau tombol **Cek Status Odoo**): partner `validate` dicocokkan lewat `odoo_partner_id` → `activated_at` diisi + riwayat `ACTIVATE` (`PENDING_FINANCE → ACTIVE`). `cust_status` sudah `ACTIVE` sejak approve. SFA membaca `registration.odoo_status` |
| 10 | Retry policy | Approve mengirim **langsung** (realtime). Gagal sementara → `RETRY` jeda 1 / 5 / 15 / 30 / 60 menit, maks 10 kali → `FAILED`. `422` & `duplicate_email` → `FAILED` tanpa retry |
| 11 | Required fields | Sama dengan form lama: `cust_name`, `cust_type` (`INDIVIDUAL`/`COMPANY`), `employee_id` (sales person). Mapping Odoo di §5 |
| 12 | `cust_code` | Nomor CUST, dibuat CMS (`Customer::booted`) saat SYNCED — bukan saat submit lagi. Id partner di `customer.odoo_partner_id` |
| 13 | Kapan customer ACTIVE di CMS | **Saat SYNCED** (baris customer dibuat langsung ACTIVE / REGULAR). Menyimpang dari FDD yang menunggu Finance |
| 14 | Data ditolak Odoo (422, mis. NPWP) / retry habis | **Otomatis `REJECTED`** (riwayat `SYNC_FAILED` + `REJECT` actor SYSTEM), `reason` satu baris bahasa Inggris tanpa kode error (`CustomerOdooService::rejectionReason`): `Rejected by Odoo. The NPWP number 123456789012345 for CV X is invalid. The expected format is 1234567890123456.` / `Rejected by Odoo. The email address x@y.com is already registered to another customer.` / `Could not be sent to Odoo after 10 attempts. …`. Kode error tetap di `odoo_error_code` (CMS). Berbeda dengan reject manual (final), registrasi ini **`can_resubmit: true`**: sales perbaiki lewat resubmit (status sync di-reset, Registration ID sama) → `PENDING_APPROVAL` → approve ulang. Penanda: `REJECTED` + `odoo_sync_status FAILED` + belum ada `customer_id`. Keputusan 21-10-2026; migration `2026_10_21_000001` menyamakan data APPROVED + FAILED lama |
---
## 2. Database (CMS)
> [!warning] Sejak migration `2026_10_20_000005` (§10) kolom registrasi / outbox di bawah ini **pindah ke `customer_approval`**;
> di `customer` tinggal `odoo_partner_id` dan `activated_at`. Riwayat: `customer_approval_history.customer_approval_id`.
Migration `2026_10_20_000001_add_registration_columns_to_customer_table.php` (idempotent, `hasColumn` / `hasTable`):
| Kolom / tabel | Isi |
|---|---|
| `customer.registration_status` | `PENDING_APPROVAL` / `NEEDS_REVISION` / `APPROVED` / `REJECTED` |
| `registration_reason`, `submitted_at`, `reviewed_by`, `reviewed_at` | Alasan revisi / reject terakhir, waktu submit, approver CMS |
| `odoo_partner_id` | id `res.partner` Odoo |
| `odoo_sync_status`, `odoo_error_code`, `odoo_error_message`, `odoo_retry_count`, `odoo_last_sent_at`, `odoo_next_retry_at`, `odoo_synced_at` | Outbox integrasi |
| `activated_at` | Saat partner di-Validate Finance di Odoo (label CMS: **Validated by Finance At**). Bukan saat customer ACTIVE di CMS — itu saat approve |
| `customer_approval_history` | Audit trail: `SUBMIT`, `RESUBMIT`, `APPROVE`, `REVISION`, `REJECT`, `SYNC_SUCCESS`, `SYNC_RETRY`, `SYNC_FAILED`, `ACTIVATE`; `actor_type` `SALES` / `USER` / `SYSTEM` |
Migration `2026_10_20_000002_add_customer_approval_permissions.php`: permission
`{view, view_any, approve, revision, reject, resend}_customer::approval`, otomatis ke `super_admin`.
---
## 3. API Node (`sfa-api`)
> [!note] Endpoint diganti 20-10-2026 (§10)
> `POST /master/customer` dan `PUT /master/customer/:id/resubmit` **dihapus**. `GET /master/customer` tidak lagi punya
> filter `registration_status` dan objek `registration`; isinya hanya customer master.
| Endpoint | Fungsi |
|---|---|
| `POST /master/customer-registration` | Daftar calon customer → `customer_approval` `PENDING_APPROVAL` (tidak masuk `customer`). Response = detail registrasi |
| `GET /master/customer-registration?page&limit&status&search` | Registrasi milik sales login, terbaru dulu |
| `GET /master/customer-registration/:id` | Detail + `attachment[]` + `history[]`. Key data = key body POST (`phone`, `email`, `vat_num`, …). `customer_id` / `cust_code` terisi setelah SYNCED. `odoo_status` `PENDING_FINANCE` / `ACTIVE`. Riwayat tanpa `SYNC_RETRY` / `SYNC_FAILED` |
| `PUT /master/customer-registration/:id/resubmit` | Hanya milik sales login dengan `can_resubmit: true` (`NEEDS_REVISION`, atau `REJECTED` ditolak Odoo). Field opsional + `attachment` + `remove_attachment_ids` (`attachment[].id`) |
| Kondisi | HTTP |
|---|---|
| Field wajib kosong / format salah | 400 |
| Email sudah terdaftar | 409 `Email sudah terdaftar. Silakan periksa kembali atau hubungi administrator…` |
| Email milik registrasi sendiri yang NEEDS_REVISION | 409 + `data.id`, `data.registration_id` |
| Detail / resubmit registrasi sales lain | 403 |
| Resubmit saat status bukan NEEDS_REVISION | 409 |
| Registrasi tidak ada | 404 |
> [!warning] Perubahan kontrak untuk tim mobile
> - `cust_type` sekarang wajib `INDIVIDUAL` / `COMPANY`, `priority` wajib `LOW` / `MIDDLE` / `HIGH`, `expected_revenue` angka.
> - `email` sebelumnya dibatasi 20 karakter tanpa cek format → sekarang maks 60, format email.
> - Lampiran memakai field **`attachment`** (swagger lama menulis `task_attachment`), maks 5 file × 5 MB.
> - Error kini memakai HTTP status asli (400 / 403 / 404 / 409), bukan selalu 500.
> - Field baru: `pic`, `latitude`, `longitude`, `additional_information`.
---
## 4. CMS (Filament)
Menu **Master Sales → Customer Approval** (badge = jumlah `PENDING_APPROVAL`). Model = `CustomerApproval`
(tabel `customer_approval`). "Customer Code" tertaut ke menu **Customers** setelah SYNCED. Data registrasi tidak
diedit di CMS — kalau salah, kembalikan ke sales lewat Request Revision.
| Action | Permission | Muncul saat |
|---|---|---|
| Approve | `approve_customer::approval` | `PENDING_APPROVAL` — kirim ke Odoo; customer dibuat saat SYNCED. Modal menyebut jumlah indikasi duplikat |
| Request Revision | `revision_customer::approval` | `PENDING_APPROVAL`, alasan wajib |
| Reject | `reject_customer::approval` | `PENDING_APPROVAL`, alasan wajib |
| Kirim Ulang ke Odoo | `resend_customer::approval` | `APPROVED` + sync `RETRY` / `QUEUED` (FAILED sudah REJECTED). Payload dari data registrasi apa adanya |
| Cek Status Odoo | `resend_customer::approval` | Sudah SYNCED tapi masih Pending Finance → `odoo:sync-customers --id=<partner>` |
Halaman detail: Registration, Odoo (sync status, partner id, error terakhir, retry), **Potential Duplicates**,
Customer Information, Attachments, History. Lonceng: registrasi baru / dikirim ulang → pemegang `approve_…`;
sync `FAILED` → pemegang `resend_…`.
Scheduler: `odoo:push-customer-registrations` **tiap menit** (`--registration=<id customer_approval>` untuk kirim satu,
termasuk FAILED). Internal endpoint Node → CMS: `POST /api/customer-approvals/{id}/notify` (`verify.internal`).
Penyesuaian kode lama:
- `odoo:sync-customers` mencocokkan juga lewat `odoo_partner_id`, tidak menimpa area / channel / grade / sales dengan
nilai kosong dari Odoo, dan **tidak meng-soft delete customer yang punya `odoo_partner_id`** (partner masih Draft
tidak ikut ditarik). Riwayat `ACTIVATE` ditulis ke `customer_approval` asal customer.
- `CustomerMatcher` (CMS) & `matchCustomer` (Node, Self Registration) memakai semua customer master — registrasi yang
belum SYNCED memang belum ada di tabel `customer`.
- `RewardClaimOdooService::partnerId` memakai `Customer::odooPartnerId()` (`odoo_partner_id`, atau `cust_code` angka).
---
## 5. Odoo (`mito_base`, version `18.0.1.0.3`)
`POST /api/v1/customers` (Swagger `/api/v1/docs`):
```json
{
"registration_id": "CMS-CR-004711",
"source_system": "SFA_CMS",
"approval_status": "approved",
"approved_by": "Admin CMS",
"approved_at": "2026-10-20T14:02:59+07:00",
"customer": {
"name": "Toko Abadi", "is_company": true, "email": "abadi@mail.com", "phone": "+62 812-3456",
"address": "Jl. Merdeka 1", "vat": "12345682901000", "pic": "Budi",
"area_name": "SURABAYA", "channel_code": "OUTL", "channel_name": "OUTLET", "salesperson_name": "ADITIA AYASY",
"latitude": -7.25, "longitude": 112.75, "notes": null
}
}
```
| Response | Arti |
|---|---|
| `201` `created: true` | Partner baru, `snk_state = draft`, `customer_status: pending_finance` |
| `200` `created: false` | Registration ID sudah punya partner (retry) — body lain diabaikan |
| `409 duplicate_email` | Email dipakai partner lain (termasuk arsip), `details.partner_id` |
| `409 registration_in_progress` | Request paralel ID sama, aman di-retry |
| `422 validation_error` | Nama kosong, email salah, NPWP tidak lolos `base_vat` |
- Field baru `res.partner.snk_sfa_registration_ref` (unik) — **hanya di model, tidak ditampilkan**. Aturan project:
tidak ada perubahan / penambahan view. Search filter "Registrasi SFA - Draft" dan field di form partner sempat dibuat
lalu dihapus (`48104b0c`, `55bf7dc5`).
- NPWP: angka dari CMS yang 13–14 digit di-pad `0` jadi 15 digit (0 di depan hilang karena kolom BIGINT).
- `country_id` = Indonesia, `customer_rank` = 1. Area (`snk.master.area.snk_name`, bukan sub area), channel
(`res.partner.category.name`, kode lalu nama), salesperson (`hr.employee.name`) dicocokkan nama persis;
yang tidak ketemu tepat satu dibiarkan kosong dan ditulis di chatter bersama PIC, koordinat, approver.
- Tidak ada migration script: hanya menambah kolom (additive).
---
## 6. Pengujian (lokal, 20-10-2026)
| Lapisan | Hasil |
|---|---|
| Odoo `TestSfaCustomerRegistration` | 12 test lolos (+ 10 test `TestRewardClaimBill` tetap lolos) — `-u mito_base` di `MITO_DEV` |
| Odoo HTTP | 201 create → 200 retry ID sama (partner sama) → 409 `duplicate_email` |
| Node HTTP (port 3999) | submit + lampiran, 409 email sama (beda kapital / master Odoo), 400 email salah, list filter status, 409 resubmit saat PENDING, 403 sales lain, resubmit NEEDS_REVISION, email dari REJECTED boleh dipakai |
| CMS → Odoo lokal | Approve → SYNCED partner Draft; approve kedua ditolak; email hanya ada di Odoo → FAILED + lonceng; Odoo mati → RETRY; partner dibuat lebih dulu (response hilang) → worker SYNCED ke partner yang sama, 1 partner |
| Aktivasi | Validate di Odoo → `odoo:sync-customers --id` → baris yang sama ACTIVE / REGULAR, `cust_code` & area / sales tetap, riwayat `ACTIVATE`; dry-run full sync tidak meng-soft delete customer registrasi |
| Filament (Livewire) | 4 test, 36 assertion: list, status per halaman, Potential Duplicates (NPWP / HP / nama), visibilitas action, 404 customer non-registrasi, 403 tanpa permission |
Data uji tertinggal di DB lokal: customer CMS id 4710–4714, partner Odoo `MITO_DEV` 11369–11372.
---
## 7. Belum Dikerjakan / Keputusan Terbuka
> [!note] Poin 7 (prospect lama) & 8 tidak terdampak refactor §10; poin 5 sekarang lewat `GET /master/customer-registration/:id`.
| # | Hal | Catatan |
|---|---|---|
| 1 | Status Odoo **Finance Review / Pending COA / On Hold** (FDD §6) | Odoo hanya punya `draft` / `validate`; menambah state mengubah workflow partner seluruh perusahaan. Perlu keputusan Finance |
| 2 | Validasi COA AR/AP sebelum Validate | AR/AP Odoo selalu terisi default company, jadi sistem tidak bisa membedakan "sudah diisi Finance". Perlu aturan (mis. akun khusus per customer) |
| 3 | Pembatasan transaksi customer draft | Sekarang hanya domain `partner_id` di Sales Order (UI). Invoice / API lain belum diblokir (FDD §17) |
| 4 | Notifikasi Finance di Odoo | Belum ada activity / email / filter khusus (tidak boleh view baru). Finance memakai Custom Filter Odoo: Status = Draft + SFA Registration ID is set (field tetap bisa dipilih di Custom Filter walau tidak tampil di form), simpan sebagai Favorite |
| 5 | Notifikasi ke sales (approved / revisi / rejected) | Belum ada push; mobile membaca `GET /master/customer/:id` |
| 6 | Unique constraint email di DB | Tidak dibuat (email boleh sama untuk registrasi REJECTED). Dua submit bersamaan bisa lolos, tertahan saat approve / di Odoo |
| 7 | Prospect lama tanpa `registration_status` | Tetap ter-soft delete full sync seperti sebelumnya |
| 8 | Customer Registration dari CMS (bukan SFA) | Belum ada; form Customers CMS tidak masuk alur approval |
---
## 8. File
**sfa-api** — `routes/services/serviceCustomerRegistration.js`, `routes/handler/master/customerRegistration.js`,
`routes/validator/validatorCustomerRegistration.js` (registrasi); `routes/services/serviceCustomer.js`,
`routes/handler/master/customer.js`, `routes/validator/validatorCustomer.js` (master saja); `routes/sfa.js`,
`routes/helpers/enums/customerApproval.js`, `models/McustomerApproval.js`, `McustomerApprovalAttachment.js`,
`McustomerApprovalHistory.js`, `Mcustomer.js`, `routes/services/serviceRegistration.js` (`matchCustomer`),
`app.js` (body 35mb), `swagger/openapi.js`, `docs.md` §10.
**sfa-cms** — migration `2026_10_20_000001`, `000002`, `000004`, **`000005`** (staging); `app/Enums/CustomerApprovalStatusEnum.php`,
`CustomerOdooSyncStatusEnum.php`; `app/Models/Customer.php`, `CustomerApproval.php`, `CustomerApprovalAttachment.php`,
`CustomerApprovalHistory.php`;
`app/Services/CustomerApprovalService.php`, `CustomerOdooService.php`, `CustomerApprovalNotifier.php`,
`CustomerDuplicateFinder.php`, `CustomerMatcher.php`, `RewardClaimOdooService.php`;
`app/Console/Commands/PushCustomerRegistrationsToOdoo.php`, `SyncOdooCustomers.php`;
`app/Filament/Resources/CustomerApprovalResource.php` + `Pages/`; `app/Http/Controllers/CustomerApprovalNotifyController.php`;
`routes/api.php`, `routes/console.php`.
**mito_odoo** — `mito_base/models/base/snk_sfa_customer_registration.py`, `models/base/__init__.py`,
`controllers/api/customers.py`, `tests/test_sfa_customer_registration.py`,
`__manifest__.py` (`18.0.1.0.3`).
## 9. Deploy
### Dev 20-10-2026 (VPS `16.79.56.41`)
| Repo | Commit | Status |
|---|---|---|
| sfa-cms | `d98522a` di `develop` | ✅ Jenkins `sfa-cms deploy --yes`: migration `2026_10_20_000001` `[20] Ran`, `000002` `[21] Ran`, 6 permission, `odoo:push-customer-registrations` tiap menit jalan |
| sfa-api | `b444930` di `develop` | ✅ `/var/www/sfa_api_mito` via `git bundle` + fast-forward (server tidak bisa `git pull`, remote HTTPS tanpa kredensial), `pm2 restart sfa-api-dev`. GET `/` 200, notify CMS `POST /api/customers/{id}/notify` lolos token (404 untuk id tidak ada) |
| mito_odoo | `639721ba` + `48104b0c` + `55bf7dc5` di `cj/api` | ⏳ Di-push, **PR ke `develop` belum** (merge bersih, `cj/api` hanya 1 commit di atas develop). mitodev (`/opt/dev_mito_ho/mito_odoo`, branch `develop`) masih `405` untuk `POST /api/v1/customers` |
Selama Odoo belum naik, Approve di CMS dev → `RETRY [http_405]` lalu `FAILED` setelah 10 percobaan. Setelah Odoo
naik: klik **Kirim Ulang ke Odoo** pada registrasi yang `FAILED`.
Langkah Odoo setelah PR di-merge: di server `cd /opt/dev_mito_ho/mito_odoo && sudo git pull`, backup DB, lalu
`-u mito_base --stop-after-init` di DB `MITO_PRODUCTION_20082026` dan restart container `odoo`.
### Urutan deploy (production)
1. **Odoo**: `docker-compose stop odoo` → backup → `docker-compose run --rm odoo odoo -u mito_base -d <db> --stop-after-init --no-http --max-cron-threads=0` → start.
Jangan upgrade lewat tombol UI / selagi service hidup (lihat §9.1).
2. **CMS**: `php artisan migrate` (`000001`, `000002`, `000004`, `000005`), pastikan cron `schedule:run` jalan, beri permission `…_customer::approval` ke role approver lewat Shield.
3. **Node API**: deploy **bersamaan** dengan migration `000005` (model `Mcustomer` tidak lagi punya kolom registrasi, endpoint
baru butuh tabel `customer_approval`), `pm2 restart`.
4. Kabari tim mobile perubahan kontrak §3 (endpoint `/master/customer-registration`).
### 9.2 Insiden Registration ID bentrok lokal vs dev (21-10-2026)
CMS lokal (`ODOO_URL` = mitodev) dan CMS dev memakai Odoo yang sama, dan Registration ID hanya `CMS-CR-` + id tabel.
Approve lokal id 4715 membuat partner #16802 (`CMS-CR-004715`, "Toko E2E 1792479711"); approve **Bolu** di dev (id
4715 juga) dibalas Odoo "sudah ada" → dev mencatat SYNCED ke #16802 dan membuat `CUSTOMER-0197` → **Bolu tidak ada di
Odoo**. Partner uji lokal lain di mitodev: #16806 (`CMS-CR-004720`), #16805 (`CMS-CR-004723`) — calon bentrok registrasi
dev ke-4720 / ke-4723.
| Perbaikan | Detail |
|---|---|
| Prefix per environment | `CUSTOMER_REGISTRATION_PREFIX` di `.env` CMS **dan** Node (dev / default `CMS-CR`, lokal `LOCAL-CR`) |
| Konflik → REJECTED | Odoo membalas `created: false` dengan nama partner berbeda → `odoo_error_code registration_conflict`, registrasi `REJECTED`, `can_resubmit: false` (kirim ulang akan bentrok lagi), reason `Rejected by Odoo. Registration ID … is already linked to another Odoo customer (…). Please submit a new registration.` |
| **Selesai 21-10-2026** | Partner uji #16802, #16805, #16806 di-archive + Registration ID dikosongkan (Odoo shell, ada catatan di chatter; tidak dihapus supaya bisa dikembalikan). `odoo:relink-customer-registration 4715` → Bolu partner baru **#16810** (`CMS-CR-004715`), `CUSTOMER-0197` tetap, riwayat `SYNC_RESET > SYNC_SUCCESS`. Tidak ada Registration ID dobel di Odoo |
| Data dev (rencana awal) | Hapus partner uji #16802, #16805, #16806 di Odoo mitodev (archive tidak cukup — idempotency mencari termasuk arsip), lalu `php artisan odoo:relink-customer-registration 4715` di dev (lepas #16802, kirim ulang, `CUSTOMER-0197` diisi partner baru; berhenti bila partner lama masih memegang ID) |
### 9.1 Insiden upgrade Odoo dev 20-10-2026
| Gejala | Penyebab | Penanganan |
|---|---|---|
| Tombol Upgrade UI: `UndefinedColumn res_partner.snk_sfa_registration_ref` | Kode baru sudah di-restart sebelum `-u`; registry kenal field, kolom belum ada. `button_upgrade` membaca `res.company → partner` sebelum upgrade jalan | Upgrade lewat CLI |
| CLI `-u` selagi service hidup: error kolom yang sama saat load `ir.cron` | Cron sedang dieksekusi service yang hidup → `_try_lock` gagal → **`cr.rollback()`** membatalkan `ALTER TABLE` upgrade, lalu terjemahan pesan error membaca partner | Stop service dulu, `docker-compose run --rm` (bukan `exec`) |
| `422 validation_error` NPWP dari CMS | NPWP contoh `123456789012345` gagal checksum Luhn `base_vat` (15 digit). SFA hanya cek ≥ 14 digit | Pakai NPWP valid (16 digit tanpa 0 di depan selalu lolos). Validasi checksum di SFA belum dibuat |
---
## 10. Refactor: tabel staging `customer_approval` (20-10-2026)
Permintaan user: data dari submit SFA **jangan masuk tabel `customer`** sebelum di-approve CMS dan diterima Odoo, supaya
master customer hanya berisi data valid.
```mermaid
sequenceDiagram
participant M as SFA Mobile
participant N as Node API
participant DB as DB CMS
participant C as CMS (Filament)
participant O as Odoo mito_base
M->>N: POST /master/customer-registration
N->>DB: INSERT customer_approval (PENDING_APPROVAL)
Note over DB: tabel customer belum disentuh
N-->>M: 200 registration_id CMS-CR-xxxxxx, customer_id null
C->>DB: Approve → APPROVED, sync QUEUED
C->>O: POST /api/v1/customers (registration_id)
alt 201 / 200
O-->>C: odoo_partner_id
C->>DB: INSERT customer ACTIVE / REGULAR + salin lampiran<br/>customer_approval.customer_id, SYNCED
else 422 (mis. NPWP) / duplicate_email
O-->>C: error
C->>DB: FAILED (tanpa baris customer)
C->>DB: Request Revision → NEEDS_REVISION
M->>N: PUT /master/customer-registration/:id/resubmit
end
M->>N: GET /master/customer-registration/:id
N-->>M: odoo_status PENDING_FINANCE / ACTIVE, customer_id, cust_code
```
| Hal | Detail |
|---|---|
| Migration `2026_10_20_000005` | Buat `customer_approval`, `customer_approval_attachment`; rename `customer_approval_history.customer_id` → `customer_approval_id`; pindah registrasi lama dengan **id sama**; SYNCED tetap di `customer` (`customer_id` = id-nya), sisanya + lampirannya di-soft delete dari `customer`; drop kolom registrasi/outbox dari `customer` (sisa `odoo_partner_id`, `activated_at`). Idempotent; `down()` hanya struktur |
| Pembuatan customer | `CustomerOdooService::createCustomer` dalam transaksi bersama update SYNCED. Pakai ulang customer bila registrasi sudah punya `customer_id` atau partner sudah lebih dulu ditarik `odoo:sync-customers` (tidak dobel). Respons Odoo tanpa id partner / gagal buat customer → `RETRY` (aman, Odoo idempotent) |
| Uji lokal | Migration di DB lokal: 3 SYNCED tetap, FAILED / PENDING / REJECTED keluar dari `customer`, riwayat nyambung, `AUTO_INCREMENT` 4716. Alur dengan Odoo palsu: submit (tidak masuk `customer`), 409 email dobel, 403 sales lain, 409 resubmit saat PENDING → approve 422 `FAILED` tanpa customer → Request Revision → resubmit NPWP baru → approve SYNCED → customer `ACTIVE`/`REGULAR` dengan NPWP baru → kirim ulang tidak membuat customer kedua → `odoo:sync-customers --id` → `ACTIVATE`, `odoo_status ACTIVE`. Data uji dihapus |
| Belum | Uji Filament / Livewire §6 belum diulang untuk model baru (halaman hanya dicek lint + route); belum dites di server dev |