docs(refactor): complete final verification and handoff

2026-09-01 14:34:12 +03:30
parent 7d2008772e
commit a504dc2b03
6 changed files with 222 additions and 15 deletions
@@ -0,0 +1,108 @@
+# Darano refactoring final migration report
+
+Date: 2026-09-01  
+Branch: `feat/refactor-v1`  
+Authoritative tracker: `REFACTORING-TODO.md`
+
+## Outcome
+
+The planned refactoring is complete. There are no `TODO`, `STARTED`, or `FAILED`
+tasks in the actionable tracker. Historical `CHANGED` entries preserve explicit
+scope decisions and completed task splits.
+
+Active repositories are API, Auth, Wallet, AdminPanel, Proto, and GL. UI, Docs,
+and DevOps were excluded from the architecture refactor by scope decision and were
+not modified during the final phase.
+
+## Delivered architecture
+
+- API owns the public HTTP boundary under `interface/http`, depends on an
+  application upstream port, and uses explicitly composed lazy gRPC clients.
+- Auth configuration is injected; domain/application boundaries cover OTP,
+  session/JWT, identity, periodic identity validation, and permissions; persistence
+  and provider implementations are infrastructure-owned.
+- Wallet uses exact scale-7 domain money, application-owned wallet/transaction,
+  market, alert, stream, locking, and asset-administration workflows, explicit
+  process composition, durable transaction/ledger outboxes, and interface-owned
+  adapters.
+- GL is an independent immutable double-entry service with scale-18 audit amounts,
+  idempotent append/reversal, reconciliation, recovery, explorer, and load coverage.
+- Publisher-backed ICO settlement and all transaction-type event routes use the
+  owning Wallet/Market workflows with durable, idempotent delivery.
+- Federation coupling and wallet creation by federation were removed; ownership is
+  `user_id -> identity_id -> wallet_id`, with wallets remaining asset-scoped.
+- AdminPanel retains direct SQL reads for projections. Unmanaged projections fail
+  closed for writes; Assets alone use authenticated typed Wallet upsert/deactivate
+  commands. Duplicate Django wallet policy and secondary persistence signals are gone.
+- Proto changes are additive where compatibility was required, and active generated
+  consumers are committed and reproducible.
+
+## Shared-type decision
+
+`SHARED-TYPES-EVALUATION.md` concludes that no new shared source package is safe:
+
+- Wallet uses scale 7 with Stellar and `numeric(23,7)` semantics.
+- GL uses precision 38/scale 18 with canonical immutable-journal semantics.
+- deployed IDs mix signed database keys, unsigned legacy contract fields, Auth-owned
+  regulated identifiers, and opaque GL strings.
+
+The approved boundary remains canonical base-10 decimal strings plus explicit
+adapter conversions. Services do not import another service's domain package.
+
+## Final corrections found by verification
+
+- API commit `0074e91` regenerates its Wallet contract consumer.
+- Auth commit `2c8a0b1` regenerates its Wallet contract consumer.
+- Wallet commit `3b898e1` makes the duplicate-event integration assertion wait for
+  the first inbox success transition. The previous test could publish its duplicate
+  before the first handler completed; 20 race-enabled repetitions and the full race
+  suite pass after the correction.
+
+These changes are scoped to generated outputs or test synchronization. No unrelated
+working-tree changes were absorbed.
+
+## Final verification
+
+| Repository | Verification |
+|---|---|
+| Proto | Buf lint, build, and breaking check against the prior commit pass. |
+| API | Proto and Swagger generation; `go test ./...`; race tests; vet; build; whitespace checks pass. |
+| Auth | Proto generation; `go test ./...`; race tests; vet; build; whitespace checks pass. |
+| Wallet | Proto generation; normal and race tests; vet; build; focused duplicate-event race test repeated 20 times; whitespace checks pass. |
+| GL | Templ/proto generation; normal and race tests; vet; build pass. The localhost `httptest` case required normal socket permission rather than the restricted sandbox. |
+| AdminPanel | Local BetterProto generation; 13 focused boundary tests; Django system checks; Python compilation; whitespace checks pass. |
+
+API/Auth/Wallet/GL/AdminPanel/Proto are clean on `feat/refactor-v1` after their final
+commits. The coordination repository contains only this final documentation change
+until its handoff commit is created.
+
+## Required deployment configuration
+
+Asset administration is fail-closed. Configure matching secrets:
+
+- AdminPanel: `WALLET_ADMIN_GRPC_TOKEN`
+- Internal Wallet: `[admin-assets].token`
+
+Optional AdminPanel settings:
+
+- `WALLET_ADMIN_GRPC_ADDRESS` (default `127.0.0.1:8500`)
+- `WALLET_ADMIN_GRPC_TIMEOUT` (default 5 seconds)
+
+The internal Wallet schedule/config files remain environment-owned and ignored where
+previously established; deploy secrets through the existing configuration mechanism.
+
+## Known external/baseline conditions
+
+- The Darano Go proxy previously returned long `504` responses during cold Docker
+  dependency downloads for API/Auth/Wallet. Native generation, tests, vet, and builds
+  pass; the final phase did not alter registry policy or add a public fallback.
+- Django deploy checks still depend on production-provided secret, TLS redirect,
+  secure cookie, CSRF, HSTS, and DEBUG settings. Normal system checks pass.
+- Legacy public Wallet/Market protobuf money remains `double` for compatibility.
+  New exact internal financial boundaries must use canonical decimal strings.
+
+## Handoff
+
+Use `REFACTORING-TODO.md`, `REFACTORING-AUDIT.md`, this report, and `MEMORY.md` as
+the continuation sources. All implementation tasks are complete; future work should
+be opened as a new scoped task rather than reopening the finished migration tracker.