hy/hyapp-server

Fork 0

zhx 679d068a82 feat: remove generic USD wallet balance

2026-06-03 00:02:19 +08:00

15 KiB

Raw Permalink Blame History

币商进货与金币补偿架构设计

目标

币商管理列表增加“加金币”按钮。运营点击后打开“币商进货”弹窗，给币商的专用金币账户 COIN_SELLER_COIN 增加库存。

表单字段：

充值金币：增加到币商库存的金币数量，必填。
类型：USDT进货 / 金币补偿，必填。
充值金额：币商线下支付给平台的 USDT 金额，仅 USDT进货 必填。

业务口径：

USDT进货：平台收到币商线下 USDT 后，后台给币商发放 COIN_SELLER_COIN 库存；这笔记录计入币商进货/充值统计。
金币补偿：平台因为异常、活动、人工修正等原因给币商补库存；没有充值金额，不计入币商进货/充值统计。
两种类型都不能给币商发放 HOST_SALARY_USD, AGENCY_SALARY_USD, BD_SALARY_USD, ADMIN_SALARY_USD，也不能直接影响玩家普通 COIN。

服务边界

模块	职责
`server/admin`	币商列表、按钮权限、弹窗表单、后台审计、调用 user-service 校验币商身份、调用 wallet-service 发放库存
`user-service`	保存 `coin_seller_profiles` 身份事实，判断目标用户是否是有效币商
`wallet-service`	拥有 `COIN_SELLER_COIN` 账户、钱包流水、币商进货记录、幂等和 outbox
`gateway-service`	不参与后台币商进货；App 币商给玩家转金币仍走现有 `/api/v1/wallet/coin-seller/transfer`

边界规则：

server/admin 不能直接改 wallet_accounts。
user-service 不能保存币商余额。
wallet-service 不判断后台菜单权限，但必须保存完整账务流水和进货记录。
币商库存入账必须走钱包命令，不能用通用 SQL 修余额。

后台交互

币商列表

现有币商列表继续展示：

用户 ID / 短号
昵称 / 头像
区域
币商状态
币商库存余额 merchantBalance
创建时间 / 更新时间

新增行操作：

按钮	权限	状态
`加金币`	`coin-seller:stock-credit`	仅 active 币商可点击；disabled 币商按钮置灰

如果后续产品要求 disabled 币商也能补偿库存，必须新增单独权限或二次确认，不在首版默认放开。

弹窗表单

弹窗标题：币商进货

只读信息：

币商用户 ID
币商短号
昵称
当前库存余额
区域

可编辑字段：

字段	类型	规则
`type`	单选	`usdt_purchase` / `coin_compensation`
`coin_amount`	正整数	两种类型都必填，表示增加的 `COIN_SELLER_COIN`
`recharge_amount`	金额	仅 `usdt_purchase` 展示并必填；`coin_compensation` 不展示也不提交
`payment_ref`	文本	`usdt_purchase` 必填，建议填链上 tx hash、收款单号或财务凭证号
`evidence_ref`	文本	凭证附件或后台上传后的文件 ID；首版建议两种类型都必填
`reason`	文本	必填，写清楚进货或补偿原因
`command_id`	文本	操作端前端按单次授信动作生成，同一动作重试必须复用

金额存储规则：

recharge_amount 前端可以展示小数，例如 120.50。
服务端统一转成 paid_amount_micro，USDT 按 6 位精度保存。
coin_compensation 必须满足 paid_currency_code='' 且 paid_amount_micro=0，如果客户端传了金额，服务端直接拒绝。

账务模型

币商库存仍然是钱包资产：

资产类型：COIN_SELLER_COIN
账户表：wallet_accounts
流水表：wallet_transactions
分录表：wallet_entries
事件表：wallet_outbox

新增专门的币商进货明细表，避免从通用钱包 metadata 里做统计。

coin_seller_stock_records(
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  stock_id VARCHAR(96) NOT NULL,
  transaction_id VARCHAR(96) NOT NULL,
  command_id VARCHAR(128) NOT NULL,
  seller_user_id BIGINT NOT NULL,
  stock_type VARCHAR(32) NOT NULL,
  counts_as_seller_recharge BOOLEAN NOT NULL,
  coin_amount BIGINT NOT NULL,
  paid_currency_code VARCHAR(8) NOT NULL DEFAULT '',
  paid_amount_micro BIGINT NOT NULL DEFAULT 0,
  payment_ref VARCHAR(128) NULL,
  evidence_ref VARCHAR(256) NOT NULL DEFAULT '',
  operator_user_id BIGINT NOT NULL,
  reason VARCHAR(512) NOT NULL DEFAULT '',
  balance_after BIGINT NOT NULL,
  metadata_json JSON NULL,
  created_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, stock_id),
  UNIQUE KEY uk_coin_seller_stock_command (app_code, command_id),
  UNIQUE KEY uk_coin_seller_stock_payment_ref (app_code, stock_type, payment_ref),
  KEY idx_coin_seller_stock_seller_time (app_code, seller_user_id, created_at_ms),
  KEY idx_coin_seller_stock_type_time (app_code, stock_type, created_at_ms)
);

字段语义：

stock_type='usdt_purchase'：counts_as_seller_recharge=true，paid_currency_code='USDT'，paid_amount_micro>0。
stock_type='coin_compensation'：counts_as_seller_recharge=false，paid_currency_code=''，paid_amount_micro=0。
coin_amount 是发给币商的库存金币，不是玩家充值金币。
payment_ref 对 USDT 进货必须唯一，防止同一笔线下收款重复入账。
balance_after 保存账后币商库存，后台详情不用再回放钱包分录。

注意：这张表不是 wallet_recharge_records。wallet_recharge_records 只记录币商给玩家转金币后形成的“玩家充值事实”。币商自己进货应该单独统计，不能混到玩家充值记录里。

业务类型

钱包交易 biz_type 建议拆成两个值：

`biz_type`	说明	是否计入币商充值统计
`coin_seller_stock_purchase`	USDT 进货，平台收到币商付款后发放库存	是
`coin_seller_coin_compensation`	人工金币补偿、异常修复、活动补库存	否

不要复用 manual_credit，因为通用后台入账无法表达：

是否是币商库存
是否是 USDT 进货
是否计入币商充值统计
线下付款凭证是否唯一
金币补偿没有充值金额这个约束

主链路

sequenceDiagram
    autonumber
    participant Admin as Admin Web
    participant AdminSrv as server/admin
    participant User as user-service
    participant Wallet as wallet-service
    participant DB as wallet MySQL
    participant Audit as admin_operation_logs

    Admin->>AdminSrv: POST /admin/coin-sellers/{user_id}/stock-credits
    AdminSrv->>AdminSrv: 校验 coin-seller:stock-credit 权限和表单
    AdminSrv->>User: GetCoinSellerProfile(user_id)
    User-->>AdminSrv: active coin_seller profile
    AdminSrv->>Wallet: AdminCreditCoinSellerStock(command)
    Wallet->>DB: BEGIN
    Wallet->>DB: 按 command_id / payment_ref 做幂等和重复收款校验
    Wallet->>DB: SELECT wallet_accounts FOR UPDATE
    Wallet->>DB: 增加 COIN_SELLER_COIN
    Wallet->>DB: 写 wallet_transactions / wallet_entries
    Wallet->>DB: 写 coin_seller_stock_records
    Wallet->>DB: 写 wallet_outbox
    Wallet->>DB: COMMIT
    AdminSrv->>Audit: 写后台操作审计
    AdminSrv-->>Admin: 返回 transaction_id 和账后余额

失败边界：

user-service 判断不是 active 币商时，不调用 wallet-service。
wallet-service 入账失败时，不写成功审计；可以写失败审计或错误日志。
钱包事务提交成功但后台审计写失败时，必须记录告警；后续需要审计补偿任务，不能静默吞掉。

Admin API

新增后台接口：

POST /admin/coin-sellers/{user_id}/stock-credits

权限：

coin-seller:stock-credit

请求：

{
  "commandId": "admin-coin-seller-stock-20260509-001",
  "type": "usdt_purchase",
  "coinAmount": 8000000,
  "rechargeAmount": "100.000000",
  "paymentRef": "usdt-tx-hash-or-offline-receipt",
  "evidenceRef": "oss://admin-evidence/receipt.png",
  "reason": "币商 USDT 进货"
}

金币补偿请求：

{
  "commandId": "admin-coin-seller-comp-20260509-001",
  "type": "coin_compensation",
  "coinAmount": 50000,
  "evidenceRef": "ticket-12345",
  "reason": "上次转账异常补偿"
}

响应：

{
  "transactionId": "lalu_admin_coin_seller_stock_...",
  "sellerUserId": "163001",
  "stockType": "usdt_purchase",
  "coinAmount": 8000000,
  "paidCurrencyCode": "USDT",
  "paidAmountMicro": 100000000,
  "countsAsSellerRecharge": true,
  "balanceAfter": 12800000,
  "createdAtMs": 1760000000000
}

校验：

user_id 必须是 active coin_seller。
coinAmount > 0。
type=usdt_purchase 时，rechargeAmount > 0、paymentRef 必填、paid_currency_code=USDT。
type=coin_compensation 时，不能提交 rechargeAmount，paid_amount_micro 固定为 0。
reason 必填。
evidenceRef 首版建议必填，方便财务和客服追踪。

gRPC 契约建议

在 wallet.v1.WalletService 增加后台命令：

message AdminCreditCoinSellerStockRequest {
  string command_id = 1;
  int64 seller_user_id = 2;
  string stock_type = 3;
  int64 coin_amount = 4;
  string paid_currency_code = 5;
  int64 paid_amount_micro = 6;
  string payment_ref = 7;
  string evidence_ref = 8;
  int64 operator_user_id = 9;
  string reason = 10;
  string app_code = 11;
}

message AdminCreditCoinSellerStockResponse {
  string transaction_id = 1;
  int64 seller_user_id = 2;
  string stock_type = 3;
  int64 coin_amount = 4;
  string paid_currency_code = 5;
  int64 paid_amount_micro = 6;
  bool counts_as_seller_recharge = 7;
  int64 balance_after = 8;
  int64 created_at_ms = 9;
}

server/admin 负责在调用前通过 user-service 校验币商身份；wallet-service 负责校验金额、类型、幂等、重复 payment_ref 和钱包事务。

统计口径

币商库存相关统计从 coin_seller_stock_records 读取：

指标	查询条件
币商累计 USDT 进货金币	`stock_type='usdt_purchase'`
币商累计 USDT 进货金额	`counts_as_seller_recharge=true`，汇总 `paid_amount_micro`
币商累计金币补偿	`stock_type='coin_compensation'`
当前库存余额	`wallet_accounts.asset_type='COIN_SELLER_COIN'`
币商给玩家充值金币	现有 `wallet_recharge_records` 或 `biz_type='coin_seller_transfer'`

金币补偿不计入币商充值统计的落地方式：

表单不展示 充值金额。
API 不接受 rechargeAmount。
数据库存 paid_amount_micro=0。
counts_as_seller_recharge=false。
统计 SQL 必须带 counts_as_seller_recharge=true 或 stock_type='usdt_purchase'。

列表性能

币商列表不要每行实时做大范围流水汇总。

首版建议：

列表只展示当前库存余额 merchantBalance，继续按当前实现从 wallet_accounts 按当页 user_id 批量查询。
如果产品要展示累计进货金额、累计补偿金币、最近进货时间，只对当前页 user_id 从 coin_seller_stock_records 做 group by。
如果后续需要按累计进货金额排序或筛选，再增加 coin_seller_stock_stats 投影表。

可选投影表：

coin_seller_stock_stats(
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  seller_user_id BIGINT NOT NULL,
  purchase_coin_total BIGINT NOT NULL DEFAULT 0,
  purchase_paid_usdt_micro_total BIGINT NOT NULL DEFAULT 0,
  compensation_coin_total BIGINT NOT NULL DEFAULT 0,
  last_stock_at_ms BIGINT NOT NULL DEFAULT 0,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, seller_user_id)
);

投影更新可以和钱包事务同事务完成，也可以由 wallet outbox 异步更新。首版如果列表不展示累计值，不需要这张表。

Outbox 事件

钱包事务成功后写出：

WalletCoinSellerStockPurchased
WalletCoinSellerCoinCompensated
WalletBalanceChanged

事件 payload：

seller_user_id
stock_type
coin_amount
paid_currency_code
paid_amount_micro
counts_as_seller_recharge
transaction_id
operator_user_id
created_at_ms

这些事件可用于后台通知、财务报表、风控告警和统计投影。

权限和审计

新增权限：

Permission	Kind	Usage
`coin-seller:stock-credit`	`button`	币商进货、金币补偿

审计 action：

Action	Resource	说明
`coin-seller-stock-credit`	`coin_seller_stock_records`	USDT 进货或金币补偿成功

审计 detail 必须包含：

command_id
seller_user_id
stock_type
coin_amount
paid_currency_code
paid_amount_micro
payment_ref
transaction_id
reason

USDT 进货金额属于财务口径，不能只放前端日志。

错误码建议

纳入 pkg/xerr catalog：

业务错误	gRPC code	说明
`COIN_SELLER_NOT_ACTIVE`	`FailedPrecondition`	目标用户不是 active 币商
`COIN_SELLER_STOCK_TYPE_INVALID`	`InvalidArgument`	类型不是 USDT 进货或金币补偿
`COIN_SELLER_STOCK_AMOUNT_INVALID`	`InvalidArgument`	金币数或 USDT 金额不合法
`COIN_SELLER_PAYMENT_REF_DUPLICATED`	`AlreadyExists`	同一 USDT 凭证已入账
`IDEMPOTENCY_CONFLICT`	`AlreadyExists`	command_id 重复但 payload 不同

客户端展示文案由 admin 前端根据业务 code 转换，不从内部错误字符串拼 UI。

实现顺序

增加权限种子：coin-seller:stock-credit，币商列表行操作按权限展示。
扩展 api/proto/wallet/v1/wallet.proto：新增 AdminCreditCoinSellerStock 请求和响应。
增加 wallet MySQL 表 coin_seller_stock_records。
在 wallet-service 实现专用命令：校验类型、金额、payment_ref、幂等，锁定 COIN_SELLER_COIN 账户并入账。
在 server/admin 增加接口：校验 active 币商身份，调用 wallet-service，成功后写 admin_operation_logs。
后台页面币商列表增加“加金币”按钮和弹窗表单。
增加列表成功后的刷新策略：成功后刷新当前行余额或重新拉取当前页。
如需累计统计，再增加当前页聚合查询或 coin_seller_stock_stats 投影。

测试重点

必须覆盖：

active 币商 USDT 进货成功，COIN_SELLER_COIN 增加，counts_as_seller_recharge=true。
USDT 进货缺少 rechargeAmount 或 paymentRef 被拒绝。
同一个 paymentRef 不能重复进货。
金币补偿成功，COIN_SELLER_COIN 增加，paid_amount_micro=0，counts_as_seller_recharge=false。
金币补偿传入 rechargeAmount 被拒绝。
disabled 或不存在的币商不能加金币。
相同 command_id 和相同 payload 重试返回原交易结果。
相同 command_id 但 payload 不同返回幂等冲突。
wallet 事务失败时不写进货记录、不改余额。
admin 审计记录包含 transaction_id、类型、金币数、USDT 金额和操作人。

15 KiB Raw Permalink Blame History Unescape Escape