mufassall

Konspekt · Biznes jarayonlar

Hujjatning hayot sikli

14 daq · O'rta · mufassall.dtwin.uz/uz/l/document-lifecycle/

← Darsni ochish

Muammo

Ikki kompaniya orasidagi elektron hisob-faktura qoralamadan tasdiqlangan, rad etilgan yoki bekor qilingan holatgacha boradi, yuridik ahamiyatli har qadamni esa tashqi reestr ham tasdiqlashi kerak. Ikki odam bir vaqtda bossa va reestr kech, ikki marta yoki umuman javob bermasa, shu holat mashinasini qanday to'g'ri saqlash.

Nimani o'rganasiz

  • Hujjat holatlari va tarqoq if'lar o'rniga o'tishlar jadvali
  • Optimistik parallellik: version ustuni, 0 qator va 409
  • Reestr callback orqali tasdiqlaguncha kutish holatlari
  • Idempotent callback'lar, holat sinxroni ishi, tarix va outbox
Yakuniy sahna

Diagramma kod sifatida

Darsdagi yakuniy sxemani matn ko'rinishida oling va Jira, GitLab, GitHub, Notion yoki hujjatga qo'ying: Mermaid u yerlarda o'zi chiziladi. D2 va PlantUML (Confluence, IntelliJ) uchun alohida variantlar bor.

Mermaid: sxema

flowchart LR
  n_seller(["Sotuvchi ilovasi"])
  n_buyer(["Xaridor ilovasi"])
  n_api["Hujjat API"]
  n_db[("Hujjatlar bazasi")]
  n_registry>"Reestr"]
  n_worker("Holat sinxroni")
  n_events[["Hodisalar"]]
  n_seller --> n_api
  n_buyer --> n_api
  n_api --> n_db
  n_api --> n_registry
  n_registry --x|"yo'qoldi"| n_api
  n_worker --> n_db
  n_worker --> n_registry
  n_db --> n_events
  n_events --> n_buyer

Mermaid: so'rovlar ketma-ketligi

sequenceDiagram
  participant n_buyer as Xaridor ilovasi
  participant n_api as Hujjat API
  participant n_db as Hujjatlar bazasi
  participant n_seller as Sotuvchi ilovasi
  participant n_registry as Reestr
  participant n_worker as Holat sinxroni
  Note over n_buyer,n_api: Hisob-faktura bu holat mashinasi
  n_buyer->>n_api: GET /documents/inv_5120 HTTP/1.1
  n_api-->>n_buyer: HTTP/1.1 200 OK
  Note over n_api,n_db: Ikki foydalanuvchi bir vaqtda harakat qiladi
  n_api->>n_db: two clicks on inv_5120, 5 ms apart
  Note over n_api,n_db: Faqat o'qilgan versiyani yangilang
  n_api->>n_db: UPDATE documents
  n_db-->>n_api: UPDATE 0
  Note over n_seller,n_api: Yutqazgan 409 oladi, jim ustidan yozish emas
  n_seller->>n_api: POST /documents/inv_5120/cancel HTTP/1.1
  n_api-->>n_seller: HTTP/1.1 409 Conflict
  Note over n_buyer,n_api: Ruxsat etilgan o'tishlar bitta jadvaldan
  n_buyer->>n_api: POST /documents/inv_5120/reject HTTP/1.1
  n_api-->>n_buyer: HTTP/1.1 422 Unprocessable Content
  Note over n_api,n_registry: So'nggi so'z reestrda, u esa keyinroq javob beradi
  n_api->>n_registry: POST /v1/documents/inv_5120/accept HTTP/1.1
  n_registry-->>n_api: HTTP/1.1 202 Accepted
  Note over n_registry,n_api: Reestr tasdiqlaguncha kutish holatida turing
  n_registry->>n_api: POST /registry/callbacks HTTP/1.1
  n_api-->>n_registry: HTTP/1.1 200 OK
  Note over n_registry,n_api: Callback ikki marta keladi yoki umuman kelmaydi
  n_registry-xn_api: callback log, registry -#62; api
  Note over n_api,n_db: Har event ID'ni bir marta ishlang
  n_api->>n_db: INSERT INTO registry_events (event_id, received_at)
  n_db-->>n_api: INSERT 0 0
  Note over n_worker,n_registry: Sinxron ishi qotib qolgan hujjatlarni so'raydi
  n_worker->>n_registry: GET /v1/documents/inv_5133/status HTTP/1.1
  n_registry-->>n_worker: HTTP/1.1 200 OK
  Note over n_api,n_db: Har o'tish tarix va outbox qatorini yozadi
  n_api->>n_db: BEGIN#59;

D2

direction: right

n_seller: "Sotuvchi ilovasi" {
  shape: rectangle
}
n_buyer: "Xaridor ilovasi" {
  shape: rectangle
}
n_api: "Hujjat API" {
  shape: rectangle
}
n_db: "Hujjatlar bazasi" {
  shape: cylinder
}
n_registry: "Reestr" {
  shape: cloud
}
n_worker: "Holat sinxroni" {
  shape: rectangle
  style.multiple: true
}
n_events: "Hodisalar" {
  shape: queue
}

n_seller -> n_api
n_buyer -> n_api
n_api -> n_db
n_api -> n_registry
n_registry -> n_api: "yo'qoldi" {
  style.stroke-dash: 3
  target-arrowhead.shape: cross
}
n_worker -> n_db
n_worker -> n_registry
n_db -> n_events
n_events -> n_buyer

PlantUML: so'rovlar ketma-ketligi

@startuml
participant "Xaridor ilovasi" as n_buyer
participant "Hujjat API" as n_api
database "Hujjatlar bazasi" as n_db
participant "Sotuvchi ilovasi" as n_seller
boundary "Reestr" as n_registry
participant "Holat sinxroni" as n_worker
note over n_buyer, n_api : Hisob-faktura bu holat mashinasi
n_buyer -> n_api : GET /documents/inv_5120 HTTP/1.1
n_api --> n_buyer : HTTP/1.1 200 OK
note over n_api, n_db : Ikki foydalanuvchi bir vaqtda harakat qiladi
n_api -> n_db : [dublikat] two clicks on inv_5120, 5 ms apart
note over n_api, n_db : Faqat o'qilgan versiyani yangilang
n_api -> n_db : UPDATE documents
n_db --> n_api : UPDATE 0
note over n_seller, n_api : Yutqazgan 409 oladi, jim ustidan yozish emas
n_seller -> n_api : POST /documents/inv_5120/cancel HTTP/1.1
n_api --> n_seller : HTTP/1.1 409 Conflict
note over n_buyer, n_api : Ruxsat etilgan o'tishlar bitta jadvaldan
n_buyer -> n_api : POST /documents/inv_5120/reject HTTP/1.1
n_api --> n_buyer : HTTP/1.1 422 Unprocessable Content
note over n_api, n_registry : So'nggi so'z reestrda, u esa keyinroq javob beradi
n_api -> n_registry : POST /v1/documents/inv_5120/accept HTTP/1.1
n_registry --> n_api : HTTP/1.1 202 Accepted
note over n_registry, n_api : Reestr tasdiqlaguncha kutish holatida turing
n_registry -> n_api : POST /registry/callbacks HTTP/1.1
n_api --> n_registry : HTTP/1.1 200 OK
note over n_registry, n_api : Callback ikki marta keladi yoki umuman kelmaydi
n_registry ->x n_api : [yo'qoldi] callback log, registry -> api
note over n_api, n_db : Har event ID'ni bir marta ishlang
n_api -> n_db : INSERT INTO registry_events (event_id, received_at)
n_db --> n_api : INSERT 0 0
note over n_worker, n_registry : Sinxron ishi qotib qolgan hujjatlarni so'raydi
n_worker -> n_registry : GET /v1/documents/inv_5133/status HTTP/1.1
n_registry --> n_worker : HTTP/1.1 200 OK
note over n_api, n_db : Har o'tish tarix va outbox qatorini yozadi
n_api -> n_db : BEGIN;
@enduml

PlantUML: komponentlar

@startuml
left to right direction
agent "Sotuvchi ilovasi" as n_seller
agent "Xaridor ilovasi" as n_buyer
component "Hujjat API" as n_api
database "Hujjatlar bazasi" as n_db
cloud "Reestr" as n_registry
collections "Holat sinxroni" as n_worker
queue "Hodisalar" as n_events
n_seller --> n_api
n_buyer --> n_api
n_api --> n_db
n_api --> n_registry
n_registry -[#c62828,dashed]-> n_api : yo'qoldi
n_worker --> n_db
n_worker --> n_registry
n_db --> n_events
n_events --> n_buyer
@enduml

Xulosa

Reestr bilan sinxronlanadigan hujjatlar uchun besh qoida.

1) Holatlar va o'tishlar bitta o'tishlar jadvalida. 2) Har update version'ni tekshiradi; 0 qator 409 degani. 3) Reestr tasdiqlaguncha hujjat kutish holatida, hech qachon yakuniy emas. 4) Callback'lar event_id bo'yicha takrordan tozalanadi, yo'qolganlarini sinxron ishi topadi. 5) Har o'tish o'sha tranzaksiyada tarix va outbox qatorini yozadi.

Ko'rsatkichlar: boshida va oxirida

Ko'rsatkichBoshidaOxirida
Yo'qolgan yangilanish0/kun0/kun
Reestrdan farqli00
Kutishda qotgan00
Takroriy ta'sir0/kun0/kun

Qadamlar

  1. Holat Hisob-faktura bu holat mashinasi

    Sotuvchi inv_5120 hisob-fakturani draft (qoralama) sifatida yaratadi, imzolaydi (signed) va yuboradi (sent).

  2. Muammo Ikki foydalanuvchi bir vaqtda harakat qiladi

    Xaridor tasdiqlashni bosadi, 5 ms dan keyin sotuvchi bekor qilishni bosadi.

  3. Yechim Faqat o'qilgan versiyani yangilang

    Endi update qaysi versiyaga asoslanganini aytadi.

  4. Holat Yutqazgan 409 oladi, jim ustidan yozish emas

    Mijoz foydalanuvchiga ko'rsatgan versiyani If-Match'da yuboradi.

  5. Yechim Ruxsat etilgan o'tishlar bitta jadvaldan

    Xaridorning ikkinchi xodimida eski tab ochiq qolgan va u allaqachon tasdiqlangan hisob-fakturada yangi versiya bilan rad etishni bosadi.

  6. Muammo So'nggi so'z reestrda, u esa keyinroq javob beradi

    Tasdiqlangan hisob-faktura faqat reestr uni ro'yxatga olgandan keyin kuchga kiradi.

  7. Yechim Reestr tasdiqlaguncha kutish holatida turing

    Jadvalga yangi qatorlar qo'shiladi: delivered + accept -> accept_pending, keyin accept_pending + registered -> accepted va accept_pending + rejected -> delivered.

  8. Muammo Callback ikki marta keladi yoki umuman kelmaydi

    API birinchi callback'ni 12 soniya ishladi, reestr 10 soniyada kutishni to'xtatdi va uni qayta yubordi.

  9. Yechim Har event ID'ni bir marta ishlang

    Handler avval event_id'ni noyob kalitli jadvalga yozadi.

  10. Yechim Sinxron ishi qotib qolgan hujjatlarni so'raydi

    Har 5 daqiqada ish 15 daqiqadan ortiq kutish holatida turgan hujjatlarni tanlaydi va ularning holatini reestrdan so'raydi.

  11. Yechim Har o'tish tarix va outbox qatorini yozadi

    Bitta tranzaksiyada API hujjatni yangilaydi, tarix qatorini (qayerdan, qayerga, kim, nega, qachon) va outbox qatorini qo'shadi.

  12. Xulosa Xulosa

    Reestr bilan sinxronlanadigan hujjatlar uchun besh qoida.

Atamalar

Holat mashinasi
Obyekt faqat o'tishlar jadvalida ruxsat etilgan (holat, amal) juftliklari bo'yicha o'zgaradi. Boshqa har qanday o'tish rad etiladi.
Kutish holati (pending)
Tashqi tizim tasdiqlaguncha hujjat turadigan oraliq holat. Tasdiq kelmaguncha foydalanuvchiga yakuniy natija ko'rsatilmaydi.