user-service Architecture

Diagram pending re-render after v1.0 scope cleanup. Authoritative details live in docs/ARCH/backend.md section 3.2. Components currently in the codebase:

Inbound

• PUBLIC /auth/v1/*: POST /auth/v1/tg/login, /auth/v1/refresh, /auth/v1/logout
• AUTHENTICATED /api/v1/user/*: profile, messages, shipping-addr, tos, security/sessions
• INTERNAL FEIGN /internal/v1/user/*: lookup by uid / batch / status / by-tg-id / shipping-addresses / notify

Servlet filters

• ServiceTokenAuthFilter — internal Feign auth
• UserHeaderVerifyFilter — HMAC X-User-Id from gateway

Controllers

• AuthController, UserProfileController, UserMessageController, ShippingAddressController, TosController, SecurityController, UserInternalController

Services (business logic)

• LoginOrchestrator — JWT + refresh + security upsert + user.registered publish
• TgLoginStrategy — initData HMAC verify + auto-register
• RefreshTokenService — opaque token rotate + replay detection
• UserProfileSvc, UserLookupSvc, UserMessageSvc, ShippingAddrSvc, TosService

Outbound Feign

• INotifyService → message-service POST /notify (Inbox + TG push fan-out)

Domain helpers

• JwtIssuer (HS256 + jti), JwtRevocationStore (Redis jti blacklist), UidGenerator (8-char SecureRandom), TgInitDataVerifier (HMAC + expiry)

Event publishers

• KafkaUserRegisteredEventPublisher — @ConditionalOnProperty duobao.kafka.enabled=true
• LoggingUserRegisteredEventPublisher — fallback when Kafka disabled

MyBatis mappers + MySQL one_user

• UserInfoMapper → user_info (+ vip_level)
• UserSecurityMapper → user_security
• UserTosAgreementMapper → user_tos_agreement
• RefreshTokenMapper → refresh_token
• UserShippingAddrMapper → user_shipping_address
• flyway_schema_history — single squashed migration V1__init.sql

External

• MySQL 8 — schema one_user
• Redis 7 — jwt:revoked:{jti} blacklist
• Kafka — user.registered producer (consumed by agent-service, wallet-service)
• message-service — outbound Feign target for notification dispatch
• gateway-service (sibling) — JWT verify + header inject