Eminence212 Rawbank Backend
Skills couvrant deux projets Spring Boot Rawbank. Identifier le dépôt avant d'agir.
Usage portable : les fichiers
references/*.mdcontiennent matrice RBAC, endpoints, codes ERR et patterns inline — ne pas dépendre d'un clone repo. Voir references/paths-convention.md.
| Projet | Package | API | Sécurité |
|---|---|---|---|
| GO-PASS | com.rawbank.gopass |
/api/v1/* |
JWT + RBAC @PreAuthorize |
| Digibranch | cd.rawbank.digibranch |
/kiosk/v1/* |
Périmètre kiosk + cookie session |
Vue comparative : references/projects-overview.md
Chemins portables : references/paths-convention.md
GO-PASS
Stack : Spring Boot 3.4 · Java 17 · Oracle · Flyway · JPA · JWT
Artifact : com.rawbank:gopass-api
Flux
Controller (api/) → Service (service/) → Repository → Oracle
↑
*ScopeService (RBAC périmètre)
- DTO records dans
api/dto/— jamais exposer les entités JPA. - Réponses :
ApiResponse.ok()/ApiResponse.paged(). - Erreurs :
BusinessExceptions.badRequest|forbidden|notFound|conflict. - Pagination :
PaginationUtil.createdAtDesc(page, pageSize)(MIN=5, MAX=100).
Contrôleurs (16)
AuthController, HealthController, DashboardController, StockController, SaleController, SupplyOrderController, InventoryController, InventoryLookupController, ReportsController, ExportController, AuditController, AdminUserController, AdminOrganizationController, AdminProductController, AdminThresholdController, InternalJobController
Services scope — ne pas dupliquer RBAC
| Service | Rôle |
|---|---|
OrganizationScopeService |
ECONOMA → REGION → AGENCE → GUICHET |
StockScopeService |
Emplacements stock visibles |
SaleScopeService |
GUICHET = ventes actives ; canCancel exige sale:cancel |
SupplyOrderScopeService |
Appro sortants/entrants par site |
ReportScopeService |
Filtres rapports |
Sécurité IAM
@PreAuthorize("hasAuthority('PERM_stock:read:own')")
@PreAuthorize("hasAnyAuthority('PERM_sale:create', 'PERM_sale:cancel')")
- Permission DB
sale:create→ autorité SpringPERM_sale:create. - Toujours valider le périmètre en service, pas seulement
@PreAuthorize. UserPrincipal:User+ codes permission.
MFA login
POST /auth/login→ selon MFA : JWT direct,/mfachallenge, ou/mfa/enrollTOTPPOST /auth/mfa/verify→ tokens JWT- Parité frontend :
User.requiresTotpEnrollment()↔mfa-requirements.ts
LDAP/LDAPS (livré V30–V31) : bind annuaire remplace BCrypt au login — MFA inchangé. Voir references/gopass-auth-ldap-plan.md.
Migrations Flyway (V1–V29)
| Scripts | Contenu |
|---|---|
| V1–V2 | IAM schéma + seed rôles/permissions |
| V3/V20 | MFA TOTP, challenges |
| V21–V26 | MFA utilisateur, blocage login, email outbox |
| V27–V28 | stock:transfer, stock:receive AGENCE/GUICHET |
| V29 | uk_sales_unit_active — revente série annulée |
Règle : jamais modifier une migration appliquée — créer V{n+1}.
Patterns métier critiques
Ventes : CONFIRMEE → encaissement → RECONCILIEE/ANNULEE. GUICHET liste/détail = CONFIRMEE+ENREGISTREE seulement. Revente : existsByUnit_IdAndStatusNot(unitId, ANNULEE).
Appro : EN_ATTENTE_CONFIRMATION → EN_TRANSIT → CONFIRMEE/REJETEE. Flags canConfirm/canReject = permission + scope + statut.
Stocks : StockMovementWriteService, SerialRangeUtil, SerialValidationUtil.
Checklist nouvel endpoint GO-PASS
- [ ] DTO records + @Valid
- [ ] @Tag / @Operation Swagger
- [ ] @PreAuthorize ou migration V{n}
- [ ] Service @Transactional
- [ ] *ScopeService si données org
- [ ] auditService.write() si sensible
- [ ] Test Mockito (SaleScopeServiceTest, AuthServiceLoginTest)
- [ ] GlobalExceptionHandler si contrainte Oracle
Tests GO-PASS
./mvnw test
./mvnw test -Dtest=SaleScopeServiceTest
Références GO-PASS (autonomes — matrice RBAC inline)
- references/gopass-api-patterns.md
- references/gopass-rbac-scope.md
- references/gopass-migrations-rbac.md
- references/gopass-services-env.md
- references/gopass-auth-ldap-plan.md — LDAP/LDAPS + MFA (plan V30)
- references/paths-convention.md
Digibranch
Stack : Spring Boot 3.3.6 · Java 17 · Oracle 19c · Flyway V1–V7 · Corbanking SIT
Artifact : cd.rawbank:digibranch-api:0.1.0-SNAPSHOT
Flux
Controller (api/) → Service (service/) → Repository / CorbankingClient → Oracle + SIT
↑
KioskSecurityFilter + SessionCookieService + AuthFlowService
Pas de RBAC — sécurité = périmètre kiosk + session Oracle + OTP + audit.
Packages
| Package | Rôle |
|---|---|
api/ |
Controllers, DTOs, ApiExceptionHandler |
api/auth/, accounts/, documents/, downloads/, internal/ |
Domaines REST |
config/ |
KioskProperties, CorbankingProperties, CorsConfig |
corbanking/ |
CorbankingClient, CorbankingHttpClient, DTOs SIT |
domain/ |
AuthException, AuthChallengeState, DocumentKind |
persistence/ |
4 entités + repositories |
security/ |
Filtres périmètre, rate limit, Spring Security |
service/auth/, accounts/, documents/, audit/, retention/ |
Métier |
web/ |
KioskRequestContext, MDC X-Request-Id |
API /kiosk/v1
| Controller | Endpoints clés |
|---|---|
HealthController |
GET /health |
AuthController |
lookup, contact, OTP send/resend/verify, DELETE /pending |
SessionController |
GET /me, DELETE logout |
AccountController |
GET /customers/{code}/accounts, GET /accounts/{id}/activity |
DocumentController |
prepare/finalize RIB, relevés, avis débit/crédit ; DELETE /draft |
DownloadController |
GET /downloads/{signedToken} — public, HMAC |
InternalAuditController |
POST /internal/audit/ping (dev) |
Enveloppe réponse
ActionResult<T> { ok, message, error, code, data }
Erreurs stables ERR-* via AuthException + ApiExceptionHandler. Voir references/digibranch-errors-audit.md.
Sécurité kiosk
| Mécanisme | Classe / config |
|---|---|
| Token BFF | X-Kiosk-Internal-Token → KIOSK_INTERNAL_API_TOKEN |
| Device / agence | X-Kiosk-Device-Id, X-Kiosk-Branch-Id — whitelist |
| Locale | X-Kiosk-Locale |
| Corrélation | X-Request-Id → MDC |
| Session | Cookie digibranch_sid → table KIOSK_SESSION |
| Rate limit | KioskRateLimitFilter par endpoint |
| Download | DownloadTokenSigner HMAC, DOWNLOAD_COUNT = 1 |
| Anomalies | KioskAuditAnomalyDetectionService cron → [SECURITY_ANOMALY] |
Public (sans périmètre) : /health, /actuator/health, GET /downloads/**
KIOSK_AUTH_MODE=mock → MockClientLookupService (tests gates uniquement).
Auth OTP (5 étapes frontend)
- Langue → 2. Méthode → 3. Code client lookup → 4. Contact confirm → 5. OTP verify → session
États Oracle AUTH_CHALLENGE : PENDING_CONTACT → PENDING_OTP. OTP : HMAC-SHA256, TTL 5 min, max 3 tentatives, cooldown resend.
Documents PDF (3 types)
account-statement, rib, debit-credit-notice :
- Prepare — Corbanking → BLOB
DOCUMENT_DOWNLOAD(inactive) - Finalize — OTP lien par canal (SMS/WhatsApp/email)
- Download — URL signée publique, usage unique
Période relevé max : KIOSK_STATEMENT_MAX_PERIOD_MONTHS (6). Date activité : DD/MM/YYYY.
Migrations Flyway V1–V7
| V | Table / colonne |
|---|---|
| V1 | AUTH_AUDIT |
| V2 | DOCUMENT_DOWNLOAD |
| V3 | AUTH_CHALLENGE, KIOSK_SESSION |
| V4 | Index rétention audit |
| V5 | AUTH_CHALLENGE.CLIENT_PROFILE_JSON |
| V6 | KIOSK_SESSION.EMAIL, MASKED_EMAIL |
| V7 | DOCUMENT_DOWNLOAD.DOWNLOAD_COUNT |
Oracle SID : DIGIBRACH (pas service name). hibernate.ddl-auto: validate.
Corbanking (SIT)
CorbankingClient : fetchCustomerDetail, fetchAccountList, fetchAccountActivity, fetchRibStatement, fetchHistoricStatement, fetchDebitCreditNotice.
Secrets backend only : CORBANKING_API_COOKIE. Produits comptes : 001,100,101,102,954.
Tests gates Digibranch
| IT | Gate |
|---|---|
SchemaGateStep1IT |
Flyway V1+V2 |
AuditGateStep2IT |
Audit ping |
AuthGateStep3IT |
OTP mock |
AccountsGateStep4IT |
Session requise |
DocumentsGateStep5IT |
Prepare/finalize |
SecurityGateIT, RateLimitGateIT, DownloadSignatureGateIT |
Sécurité |
./run.sh # ou ./mvnw test
Checklist nouvel endpoint Digibranch
- [ ] DTO record + @Valid
- [ ] ActionResult via KioskResponses
- [ ] Session via SessionCookieService (sauf public download)
- [ ] Audit AUTH_AUDIT si action sensible
- [ ] AuthException + code ERR-* stable
- [ ] Rate limit si endpoint sensible
- [ ] Gate IT ou test unitaire
- [ ] Pas de secret Corbanking exposé
Références Digibranch (autonomes — ERR-* et sécurité inline)
- references/digibranch-security.md
- references/digibranch-api-endpoints.md
- references/digibranch-domain-flows.md
- references/digibranch-errors-audit.md
- references/digibranch-corbanking-env.md
- references/paths-convention.md
Conventions Rawbank partagées
| Convention | GO-PASS | Digibranch |
|---|---|---|
| Java | 17 | 17 |
| Oracle | SID GOPASS | SID DIGIBRACH |
| Flyway | db/migration/V{n}__*.sql |
idem |
| DTO | Java records | Java records |
| OpenAPI | Springdoc | Springdoc /swagger-ui.html |
| Audit | AuditService / AUTH_AUDIT |
AuditService / AUTH_AUDIT |
| Docker | — | backend/Dockerfile multi-stage JRE 17 |
| Logs | — | LOG_FILE, rotation 10MB×14 |
Anti-patterns communs
- Logique métier dans le controller.
- Modifier une migration Flyway déjà déployée.
- Secrets Corbanking ou
KIOSK_INTERNAL_API_TOKENcôté frontend. - Appliquer le pattern JWT/RBAC GO-PASS sur Digibranch (modèle différent).
- Appliquer le pattern kiosk session sur GO-PASS (JWT requis).
- Filtrer ventes GUICHET uniquement côté frontend (GO-PASS).
- Décoder
digibranch_sidcôté client (Digibranch).