← Prototype Hub
BACKEND MAP SOURCE · duobao-backend UPDATED · 2026-05-13
BACKEND DIRECTORY · 服务目录树

后端目录树、服务边界与技术架构入口 Backend Tree, Service Boundaries, and Architecture Links

本页把 duobao-backend/ 的真实目录、锁定的 9 个运行时服务、共享模块、兼容入口和服务架构入口放在同一个视图里。 读法是先看整体目录，再点服务卡片进入该服务的功能、目录结构和架构对齐说明。

后端目录树 BACKEND ROOT TREE
运行时架构仍按 9 个服务锁定；额外目录按共享模块、兼容入口或工具入口处理。
duobao-backend/
├── gateway-service/    public ingress, auth, route, rate limit
├── user-service/       account, login, profile, TOS
├── agent-service/      invite relation, refCode, agent flag
├── wallet-service/     ledger, deposit address, withdraw lifecycle
├── game-service/       round, ticket, order, draw, prize
├── chain-service/      chain adapters, broadcast, VRF, BTC path
├── sign-service/       isolated signing and address derivation
├── admin-service/      admin auth, RBAC, audit, ops read models
├── message-service/    inbox + Telegram bot push, port 6678
├── duobao-api/        Feign clients, DTOs, events, errors, enums
├── duobao-common/     shared utilities, money, trace, idempotency
├── risk-service/      compatibility entry, no runtime owner yet
├── task-service/      compatibility entry, maps to game-service
├── scripts/           project-wrapped backend commands
├── docs/              backend catalog, onboarding, gates
├── sql/               SQL entry; service Flyway remains source
├── tools/             ticket bot and backend utilities
└── build.gradle / settings.gradle / gradle/
9-service runtime split 运行时边界锁定为 gateway / user / agent / wallet / game / chain / sign / sms / admin-service。
Shared contracts stay outside services duobao-api 承载 Feign、DTO、事件、错误码；duobao-common 只放纯工具。
Compatibility entries are not new owners risk-service 和 task-service 是兼容入口；业务仍归当前 owner service。
Script-first execution 启动、测试、模式切换、网络切换、钱包检查和机器人都应走 duobao-backend/scripts/。
服务功能卡片 SERVICE RESPONSIBILITY CARDS
点击卡片进入该服务目录结构和架构说明；端口来自后端 service catalog。
gateway-service6661

公网入口。负责 Spring Cloud Gateway 路由、JWT 校验、TG initData 校验、限流、CORS、traceId 注入和内部路径屏蔽。

DBnone
DepsNacos, Redis, downstream services
RuleNo business logic, no signing, no DB access
VIEW ARCHITECTURE→
user-service6671

账号身份服务。负责 TG 一键登录、JWT 签发、uid、profile、安全中心、TOS 和用户状态查询。

DBone_user
DepsMySQL, Redis, Nacos, optional SMS
RuleNo wallet balance, no invite ownership
VIEW ARCHITECTURE→
agent-service6676

邀请与代理边界。负责refCode生成、邀请关系永久绑定、上下级查询和代理 flag；佣金体系(后续开放)。

DBone_agent
DepsMySQL, Nacos, optional user lookup
RuleInvite domain stays out of user-service
VIEW ARCHITECTURE→
wallet-service6673

资金账本权威源。负责账户余额、充值地址分配、充值入账、提现冻结/解冻、对账、treasury 和 BTC 曝险。

DBone_wallet
DepsUser, chain, sign through Feign
RuleBalance truth is ledger, not chain balanceOf
VIEW ARCHITECTURE→
game-service6672

夺宝核心域。负责活动、期次、票号、订单、开奖编排、DrawEngine 路由、中奖发放和实物奖状态机。

DBone_game
DepsWallet, chain, sign through Feign
RuleDraw mode selected by Nacos property
VIEW ARCHITECTURE→
chain-service6674

链上适配层。负责多链 ChainAdapter、交易广播/查询、充值验证、VRF 记录、nonce 管理和 BTC 本地路径。

DBone_chain
DepsRPC endpoints, sign-service, MySQL
RuleNo private key ownership
VIEW ARCHITECTURE→
sign-service6680

签名隔离边界。负责 EVM/BTC 签名、HD 地址派生、commit signer、operator address 和签名审计。

DBone_sign
DepsKMS/HSM or local signer, MySQL
RuleOnly service allowed to handle key material
VIEW ARCHITECTURE→
admin-service6677

运营后台 BFF。负责 admin auth、RBAC、step-up confirm、audit log、运营只读视图和兼容编排。

DBone_admin + owner read DBs
DepsUser, wallet, game, chain, agent
RuleBusiness writes delegate to owner services
VIEW ARCHITECTURE→
每个服务的目录结构与架构入口 SERVICE DIRECTORY AND ARCHITECTURE ENTRY
目录按当前源码包整理；架构链接优先指向已有 service diagram，缺少 diagram 的服务指向权威架构文档。

gateway-service

唯一公网入口。它只做入口治理，不读取业务库，不持有私钥，不实现业务状态机。
OPEN DIAGRAM
FUNCTIONS
  • Spring Cloud Gateway WebFlux route to backend services through Nacos.
  • JWT verification, Telegram initData validation, route auth and per-user/per-IP rate limit.
  • Blocks /internal/v1/** from public access and injects traceId.
DIRECTORY STRUCTURE
gateway-service/
└── src/main/java/com/chosen/duobao/gateway/
    ├── GatewayServiceApplication.java
    ├── auth/      JWT verification and revocation
    ├── config/    route, JWT, TG initData properties
    ├── error/     JsonResult gateway error envelope
    └── filter/    traceId, internal path, JWT, TG filters
└── src/main/resources/

user-service

身份与账号权威源。invite、wallet、message fan-out 等边界不应继续向 user-service 扩张。
OPEN DIAGRAM
FUNCTIONS
  • TG one-tap login, access token and refresh token lifecycle, user status lookup.
  • 8-digit uid generation with DB uniqueness fallback, profile, TOS.
  • Publishes user.registered when Kafka wiring is enabled; direct invite ownership stays in agent-service.
DIRECTORY STRUCTURE
user-service/
└── src/main/java/com/chosen/duobao/user/
    ├── controller/v1/          public auth/profile/security APIs
    ├── controller/v1/internal/ internal user lookup
    ├── domain/                 user_info, security, token, TOS entities
    ├── id/                     UidGenerator
    ├── jwt/                    JwtIssuer and revocation store
    ├── mapper/                 MyBatis mappers
    ├── service/auth/           TG login strategy + login orchestration
    ├── service/filter/         service token and user header filters
    ├── service/lookup/         internal identity lookup
    ├── service/profile/        profile read/write
    ├── service/registration/   user.registered publisher
    ├── service/tos/            terms agreement
    └── tg/                     initData verifier and TG user
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

agent-service

邀请关系和代理状态服务。v1.0 保持最小集，扩展佣金、阶梯和反刷(后续开放)。
OPEN DIAGRAM
FUNCTIONS
  • Generates and regenerates refCodes with a collision-safe alphabet.
  • Permanently binds inviter/invitee relationships and exposes upline queries.
  • Consumes user.registered when Kafka is enabled; synchronous Feign bind remains a fallback.
DIRECTORY STRUCTURE
agent-service/
└── src/main/java/com/chosen/duobao/agent/
    ├── code/                   RefCodeGenerator
    ├── config/                 service and Kafka properties
    ├── controller/v1/          user-facing invite APIs
    ├── controller/v1/internal/ internal invite APIs
    ├── domain/                 invite, refCode, agent state entities
    ├── event/                  user.registered consumer
    ├── mapper/                 MyBatis mappers
    ├── service/filter/         service token and user header filters
    ├── service/flag/           agent flag state
    └── service/invite/         refCode and relation services
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

wallet-service

余额与资金状态的唯一权威源。链上余额只作为展示或验证输入，不能替代平台账本。
OPEN DIAGRAM
FUNCTIONS
  • Owns USDT/BTC account ledger, wallet transactions, deposit requests and withdraw requests.
  • Allocates HD deposit addresses through sign-service and verifies deposits through chain-service.
  • Freezes, approves and finalizes withdrawals; signing and broadcast remain outside this service.
DIRECTORY STRUCTURE
wallet-service/
└── src/main/java/com/chosen/duobao/wallet/
    ├── controller/v1/           wallet, ledger, whitelist APIs
    ├── controller/v1/internal/  internal callbacks and owner APIs
    ├── domain/                  accounts, txns, deposit, withdraw, treasury
    ├── event/                   chain/game/withdraw consumers
    ├── mapper/                  MyBatis mappers
    ├── service/account/         account query and mutation
    ├── service/bonus/           trial and bonus crediting
    ├── service/deposit/         address, claim, credit flow
    ├── service/filter/          service token and user header filters
    ├── service/ledger/          ledger writes and queries
    ├── service/monitor/         BTC exposure monitor
    ├── service/reconcile/       daily reconciliation
    ├── service/treasury/        hot/warm/cold treasury view
    └── service/withdraw/        withdraw lifecycle and whitelist
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

game-service

游戏域 owner。票号、订单、开奖和奖品状态归这里，余额扣减和链上动作通过 owner service 完成。
OPEN DIAGRAM
FUNCTIONS
  • Creates rounds, manages ticket inventory, buys tickets and recovers pending orders.
  • Routes draw orchestration through DrawEngine: BACKEND, VRF_ONLY or FULL_CHAIN.
  • Settles USDT/BTC/physical prizes through wallet-service and admin-compatible fulfillment flows.
DIRECTORY STRUCTURE
game-service/
└── src/main/java/com/chosen/duobao/game/
    ├── controller/v1/           game and prize APIs
    ├── controller/v1/internal/  internal game owner APIs
    ├── domain/                  lottery, order, ticket, prize, draw result
    ├── event/                   Kafka publisher/consumer
    ├── mapper/                  MyBatis mappers
    ├── service/admin/           admin-compatible game commands
    ├── service/draw/            DrawEngine and implementations
    ├── service/filter/          service token and user header filters
    ├── service/order/           buy, recovery and order query
    ├── service/poll/            deadline polling
    ├── service/prize/           prize distribution and physical prizes
    ├── service/query/           read model queries
    ├── service/round/           round creation
    ├── service/ticket/          Redis ticket pool and assignment
    └── service/unsold/          unsold strategy
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

chain-service

链上交互 owner。它封装 RPC 和合约调用，但不拥有私钥、不拥有余额账本、不决定业务规则。
OPEN ARCH DOC
FUNCTIONS
  • Owns ChainAdapter registry and EVM/stub adapter implementations.
  • Verifies deposits, records VRF requests, manages nonce state and broadcasts signed withdrawals.
  • Calls sign-service for signatures and records broadcast/confirmation state in one_chain.
DIRECTORY STRUCTURE
chain-service/
└── src/main/java/com/chosen/duobao/chain/
    ├── config/                  chain properties and boot validation
    ├── controller/v1/internal/  deposit, withdraw, nonce, chain APIs
    ├── domain/                  broadcast, deposit claim, nonce, VRF records
    ├── mapper/                  MyBatis mappers
    ├── service/adapter/         ChainAdapter, registry, EVM/stub adapters
    ├── service/btc/             local BTC path
    ├── service/deposit/         deposit verification and idempotency
    ├── service/filter/          service token filter
    ├── service/nonce/           nonce manager and gap healer
    ├── service/poll/            broadcast confirmation poller
    ├── service/vrf/             VRF request service
    └── service/withdraw/        withdraw broadcast
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

sign-service

安全最深边界。业务服务不持有私钥，签名只通过 service-token/mTLS 内部 API 进入这里。
OPEN ARCH DOC
FUNCTIONS
  • Signs EVM transactions, BTC PSBTs and backend draw commits; records append-only audit rows.
  • Derives deterministic user deposit addresses from local/KMS-backed HD seed material.
  • Boot guard prevents local-mode signing outside the local profile.
DIRECTORY STRUCTURE
sign-service/
└── src/main/java/com/chosen/duobao/sign/
    ├── config/                  KMS, BTC network, boot validator
    ├── controller/v1/internal/  internal signing APIs
    ├── domain/                  sign audit entity
    ├── mapper/                  SignAuditMapper
    ├── service/audit/           audit writer
    ├── service/auth/            caller auth filter
    ├── service/btc/             BTC derivation, PSBT codec, BTC signer
    ├── service/commit/          commit-reveal signer
    ├── service/derive/          HD derivation and seed providers
    ├── service/evm/             EVM transaction signing
    ├── service/main/            main address lookup
    └── service/signer/          KMS/local signer implementations
└── src/main/resources/db/migration/
└── src/main/resources/mapper/

admin-service

运营后台 BFF 与审计边界。它可以编排 owner service，但不能绕过 owner service 直接成为业务写入源。
OPEN DIAGRAM
FUNCTIONS
  • Admin login, session revocation, RBAC, IP allowlist, step-up confirm and TOTP.
  • Audit ingestion through IAdminService plus local ops read models.
  • Withdraw review and physical prize actions delegate writes to wallet/game owner services.
DIRECTORY STRUCTURE
admin-service/
└── src/main/java/com/chosen/duobao/admin/
    ├── config/                  admin, ops DB and MVC config
    ├── controller/v1/           admin auth, ops and API controllers
    ├── controller/v1/internal/  internal audit/escalation APIs
    ├── domain/                  admin user, session, RBAC, audit entities
    ├── mapper/                  MyBatis mappers
    ├── service/audit/           audit annotation, aspect, writer
    ├── service/auth/            login, token, TOTP, confirm token
    ├── service/filter/          admin auth, IP allowlist, service token
    ├── service/ops/             ops queries and delegated actions
    └── service/rbac/            permissions and confirm annotations
└── src/main/resources/db/migration/
└── src/main/resources/mapper/
整体架构对齐 SYSTEM-WIDE ALIGNMENT CHECK
这些规则把目录树、服务职责、契约、运行时配置和安全边界对齐到同一套项目口径。
One public ingress

只有 gateway-service 暴露公网路由；所有 /internal/v1/** 都是服务间 API。

Contracts in duobao-api

Feign clients、DTO、错误码、事件、枚举先改 duobao-api 和 docs/5-contract，服务不能私自发明契约。

Per-service data ownership

每个服务写自己的 DB；跨服务一致性走 Feign、Kafka、幂等键和补偿，不做跨服务 DB 事务。

Signing stays isolated

私钥材料只进入 sign-service；chain/wallet/game 只能提交签名请求，不能保存或派生密钥。

Chain is adapter-based

chain-service 用 ChainAdapter 隐藏 BSC、ETH、TRON、BTC 差异；env 和 executionChain 保持正交。

Draw mode is pluggable

game-service 通过 DrawEngine 路由 BACKEND、VRF_ONLY、FULL_CHAIN；运行时选择来自 Nacos。

Admin is not SRE

admin-service 是运营 BFF 与审计面；SRE 部署、告警、灾备和事故响应继续看 operations.html。

Compatibility entries need approval

risk-service、task-service 当前只是兼容入口，不能未经架构批准承接新业务代码。

Scripts are the operating interface

构建、测试、启动、Nacos seed、模式切换、网络切换和钱包检查都优先走项目封装脚本。