agent-service Architecture

duobao backend — invite relations (permanent), refCodes, agent flag; v1.1+ commission settlement

agent-service (schema: one_agent, port 6676) v1.0: thin — 2 tables + invite lookup. v1.1+: commission, ladder, anti-fraud gateway-service upstream router + JWT upstream AUTHENTICATED (JWT) /api/v1/agent/* GET /api/v1/agent/me (my refCode / upline / count) GET /api/v1/agent/invitees (paged direct invitees list) POST /api/v1/agent/code/regen (rate-limited) v1.0 done INTERNAL FEIGN /internal/v1/agent/* POST /invite/bind (user-service on register) GET /upline?uid= (wallet-service, v1.1+ commission) GET /invite/resolve?code= (user-service pre-register) GET /{uid}/me GET /{uid}/invitees POST /flag (admin toggle) POST /{uid}/ref-code/regen ServiceTokenAuthFilter UserHeaderVerifyFilter v1.0 done SERVLET FILTERS ServiceTokenAuthFilter internal Feign auth UserHeaderVerifyFilter HMAC X-User-Id from gateway CONTROLLERS AgentController /api/v1/agent/* — authenticated user endpoints AgentInternalController /internal/v1/agent/* — Feign from user/wallet/admin SERVICES (business logic) InviteRelationSvc bind (permanent, 1-write-only) getUpline, resolve inviter RefCodeSvc generate on register regenerate (rate-limited) RefCodeGenerator Base62 random 8-char collision retry loop v1.1+ DEFERRED SERVICES (not yet wired) CommissionCalc ladder + anti-fraud AgentFlagSvc admin toggle + audit log EVENT CONSUMER UserRegisteredConsumer @KafkaListener("user.registered") — writes user_invite row if inviterUid non-null; idempotent by inviteeUid v1.1+ DEFERRED PRODUCER agent.commission.settled (v1.1+ only, not produced in v1.0) daily settlement job output — partition key: agentUid MYBATIS MAPPERS UserInviteMapper user_invite (permanent relation, UNIQUE on invitee) UserRefCodeMapper user_ref_code (one code per uid, UNIQUE on both uid and code) v1.0 done — 2 mappers + flyway_schema_history (V1 migration) v1.1+ tables: agent_commission_pending / agent_commission_settled / agent_ladder_volume / agent_ladder_headcount MySQL 8 schema: one_agent • user_invite UNIQUE(invitee_uid) — permanent inviter_uid, ref_code_used • user_ref_code UNIQUE(uid), UNIQUE(code) v1.1+ tables deferred: agent_commission_pending agent_commission_settled agent_ladder_volume/headcount v1.0 done Kafka broker kafka:29092 (compose) • consumes: user.registered • produces: (v1.1+) commission Kafka Events — agent-service CONSUMES user.registered partition keyuid consumer groupagent-service actionwrite user_invite if inviterUid != null idempotencyUNIQUE(invitee_uid) on insert PRODUCES (v1.1+ only — not wired in v1.0) agent.commission.settled partition keyagentUid triggerdaily settlement job (v1.1+) consumed by (v1.1+)wallet · agent · admin v1.0: produces 0 topics v1.0: consumes 1 topic (user.registered) v1.0 done · v1.1 commission wire deferred LEGEND Controllers Services / sibling svc Auth filters DB / Mappers Events / channels External services Helpers / lanes Service boundary Cache / limiter line Kafka consume v1.1 deferred path v1.0 done v1.1 deferred

What agent-service owns

  • • Permanent invite relation binding — one write per invitee, never changes
  • • One refCode per user — generated on registration, optionally regenerated (rate-limited)
  • • RefCode resolution (pre-register validation)
  • • Agent flag toggle — admin-only, audited (v1.0 flag stored in user_invite; v1.1+ dedicated log table)
  • • Upline chain query (getUpline) — used by wallet-service v1.1+ for commission calculation
  • • v1.1+: commission calculation, ladder amplification, anti-fraud, daily settlement job

Kafka events produced + consumed

  • v1.0 Consumes: user.registered — binds invite relation if inviterUid is non-null
  • v1.0 Produces: none
  • v1.1+ Produces: agent.commission.settled — daily settlement job output (partition key: agentUid)
  • v1.1+ also consumes: game.draw.completed, wallet.deposit.credited for commission triggers

External dependencies

  • • MySQL one_agent — 2 tables in v1.0 (user_invite, user_ref_code), V1 migration
  • • Kafka — consumes user.registered; produces nothing in v1.0
  • • Feign callee: IAdminService (audit log), IUserService (lookup — if needed)
  • • No Redis, no chain-service, no SMS dependency in v1.0
  • • v1.1+: commission tables + ladder + anti-fraud added here, not polluting other services