# 红包功能技术设计

本文定义普通红包和延迟红包的产品规则、服务边界、账务模型、后台配置、App 接口、区域飘屏、过期退款和验收边界。红包是房间内用户主动发起的金币互动玩法，资金事实必须由 `wallet-service` 持久化，区域飘屏只是已提交红包事实的实时展示入口。所有业务时间统一使用 UTC，跨服务字段统一使用 Unix epoch milliseconds，字段名保持 `*_ms`。

相关现有文档：

```text
docs/钱包服务架构.md
docs/IM全局与区域广播架构.md
docs/资源组与礼物架构.md
docs/语音房客户端接口流程.md
```

## 当前实现依据

| 能力 | 当前事实 | 红包设计决策 |
| --- | --- | --- |
| 账务 owner | `wallet-service` 已拥有 `wallet_accounts`、`wallet_transactions`、`wallet_entries`、`wallet_outbox` | 红包扣款、领取入账和过期退款全部放在 `wallet-service` |
| 账务幂等 | `wallet_transactions.command_id` 和 `request_hash` 已作为命令幂等模型 | 发红包、抢红包和退款都必须有稳定 `command_id` |
| 事件投递 | 钱包文档约束 `wallet_outbox` 必须和账务交易同事务写入 | 红包创建成功后写 wallet outbox，不让 MQ 成为资金事实来源 |
| 区域播报 | `activity-service` 已有 `BroadcastService.PublishRegionBroadcast` 和 `im_broadcast_outbox` | 红包飘屏由 activity 消费红包创建事件后写区域播报 outbox |
| App HTTP | `gateway-service` `/api/v1` 响应使用 `{code,message,request_id,data}` envelope | 红包 App 接口只在 gateway 暴露，内部走 gRPC |
| 后台入口 | `server/admin` 只能通过 protobuf client 或明确集成接口访问 app 后端 | 后台红包配置通过 admin server 调 wallet-service 管理 RPC |
| 时间规则 | 全局业务时间统一 UTC，时间范围使用 `[start_ms,end_ms)` | 每日发送次数按 UTC 日期统计，过期和延迟打开都用 UTC epoch ms |

## Goals

- 支持普通红包和延迟红包。
- 后台可配置红包数量档位、红包金额档位、延迟红包秒数、每用户每日发送次数上限和红包过期秒数。
- 发红包时立即扣除发送者金币，并把红包金额拆成服务端随机份额。
- 每个用户每个红包最多领取一次，领取金额随机且总和严格等于红包总金额。
- 红包过期后自动退回未领取金额，退款必须幂等。
- 发红包成功后触发区域飘屏，飘屏失败不能回滚已提交账务事实。
- Flutter 只对接接口和 IM 飘屏消息，不在客户端计算红包金额、过期、限次或随机结果。

## Non-Goals

| 不做 | 原因 |
| --- | --- |
| 客户端提交随机拆分结果 | 金额分配必须由服务端生成并持久化 |
| 只用 Redis 保存红包剩余金额 | 红包资金事实需要 MySQL 事务和账务分录恢复 |
| 把红包状态放进 `room-service` | 红包不是 Room Cell 核心状态，房间只提供入口上下文 |
| 用 MQ 直接表示扣款或退款成功 | MQ 可以投递事实，不能成为账务事实来源 |
| 为每个红包创建 IM 群 | 红包是业务消息，不是会话边界 |
| 后台直接写 wallet 业务表 | 后台必须调用 owner service 管理接口并写审计 |

## 产品规则

| 规则 | 决策 |
| --- | --- |
| 红包类型 | `normal` 普通红包，`delayed` 延迟红包 |
| 普通红包 | 创建成功后立即可领取，`open_at_ms = created_at_ms` |
| 延迟红包 | 创建成功时立即扣款，`open_at_ms = created_at_ms + delay_seconds * 1000` |
| 扣款资产 | 只允许 `COIN` 金币 |
| 金额单位 | 整数金币，不使用小数或浮点数 |
| 档位校验 | `total_amount` 必须命中金额档位，`packet_count` 必须命中数量档位 |
| 最小金额 | `total_amount >= packet_count`，保证每份至少 1 金币 |
| 每日次数 | 按 UTC 日期统计 `sender_user_id` 发红包次数 |
| 过期退款 | 过期后未领取金额退回发送者金币账户 |
| 可见范围 | 红包绑定 `room_id`，飘屏发送到房间所在 `region_id` |
| 发送者自领 | 默认允许发送者领取自己的红包；如果产品要求禁止，只需要在领取校验加 `sender_user_id != claimer_user_id` |

## 服务边界

| 模块 | 拥有 | 不拥有 |
| --- | --- | --- |
| `wallet-service` | 红包配置、发红包扣款、随机份额、领取入账、过期退款、每日发送次数、红包账务 outbox | 房间核心状态、IM 群生命周期、用户资料展示 |
| `gateway-service` | App HTTP envelope、鉴权、协议转换、从 room/user 上下文补齐 `room_id/region_id` 后调用 wallet | 红包金额随机、账务分录、过期扫描 |
| `activity-service` | 消费红包创建事实并写 `im_broadcast_outbox`，调用 `PublishRegionBroadcast` | 红包扣款、领取、退款和剩余金额 |
| `server/admin` | 后台菜单、配置表单、审计、调用 wallet 管理 RPC | 直接修改红包业务表或钱包账本 |
| `hyapp-admin-platform` | `活动管理 / 红包配置` 页面和红包记录查询 | 业务校验最终裁决 |
| `hyapp-flutter` | 展示配置档位、发红包、抢红包、展示领取结果和飘屏入口 | 本地计算可抢状态之外的账务结果 |

## 状态机

```mermaid
stateDiagram-v2
  [*] --> created
  created --> active: normal created
  created --> waiting_open: delayed created
  waiting_open --> active: now_ms >= open_at_ms
  active --> finished: remaining_count = 0
  active --> expired: now_ms >= expires_at_ms
  waiting_open --> expired: now_ms >= expires_at_ms
  expired --> refunded: refund remaining_amount
  finished --> [*]
  refunded --> [*]
```

| 状态 | 语义 |
| --- | --- |
| `created` | 红包创建命令开始，通常不作为长期状态暴露 |
| `waiting_open` | 延迟红包已扣款，但未到领取时间 |
| `active` | 可领取 |
| `finished` | 所有份额已领取 |
| `expired` | 已过期，等待或正在执行退款 |
| `refunded` | 未领取金额已退回发送者 |

## 数据库设计

红包表放在 `wallet-service` 所属 MySQL schema，和账务交易同库，便于在同一事务中维护金额、分录和 outbox。

### 配置表

```sql
CREATE TABLE red_packet_configs (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  enabled TINYINT(1) NOT NULL DEFAULT 0,
  delayed_open_seconds INT NOT NULL DEFAULT 0,
  expire_seconds INT NOT NULL DEFAULT 300,
  daily_send_limit INT NOT NULL DEFAULT 0,
  updated_by_admin_id BIGINT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code)
);

CREATE TABLE red_packet_count_tiers (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  tier_id BIGINT NOT NULL AUTO_INCREMENT,
  packet_count INT NOT NULL,
  status VARCHAR(32) NOT NULL,
  sort_order INT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (tier_id),
  UNIQUE KEY uk_red_packet_count_tier (app_code, packet_count)
);

CREATE TABLE red_packet_amount_tiers (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  tier_id BIGINT NOT NULL AUTO_INCREMENT,
  total_amount BIGINT NOT NULL,
  status VARCHAR(32) NOT NULL,
  sort_order INT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (tier_id),
  UNIQUE KEY uk_red_packet_amount_tier (app_code, total_amount)
);
```

`daily_send_limit = 0` 表示禁止发送，不表示无限制。需要无限制时必须用显式大值，避免运营误配置。

### 红包事实表

```sql
CREATE TABLE red_packets (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  packet_id VARCHAR(96) NOT NULL,
  command_id VARCHAR(128) NOT NULL,
  sender_user_id BIGINT NOT NULL,
  room_id VARCHAR(96) NOT NULL,
  region_id BIGINT NOT NULL,
  packet_type VARCHAR(32) NOT NULL,
  total_amount BIGINT NOT NULL,
  packet_count INT NOT NULL,
  remaining_amount BIGINT NOT NULL,
  remaining_count INT NOT NULL,
  status VARCHAR(32) NOT NULL,
  open_at_ms BIGINT NOT NULL,
  expires_at_ms BIGINT NOT NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, packet_id),
  UNIQUE KEY uk_red_packets_command (app_code, command_id),
  KEY idx_red_packets_room_time (app_code, room_id, created_at_ms),
  KEY idx_red_packets_expire (app_code, status, expires_at_ms)
);

CREATE TABLE red_packet_allocations (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  packet_id VARCHAR(96) NOT NULL,
  allocation_no INT NOT NULL,
  amount BIGINT NOT NULL,
  status VARCHAR(32) NOT NULL,
  claimed_by_user_id BIGINT NOT NULL DEFAULT 0,
  claim_id VARCHAR(96) NOT NULL DEFAULT '',
  claimed_at_ms BIGINT NOT NULL DEFAULT 0,
  PRIMARY KEY (app_code, packet_id, allocation_no),
  KEY idx_red_packet_alloc_claimable (app_code, packet_id, status, allocation_no),
  KEY idx_red_packet_alloc_user (app_code, claimed_by_user_id, claimed_at_ms)
);

CREATE TABLE red_packet_claims (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  claim_id VARCHAR(96) NOT NULL,
  command_id VARCHAR(128) NOT NULL,
  packet_id VARCHAR(96) NOT NULL,
  user_id BIGINT NOT NULL,
  amount BIGINT NOT NULL,
  wallet_transaction_id VARCHAR(96) NOT NULL,
  status VARCHAR(32) NOT NULL,
  failure_reason VARCHAR(64) NOT NULL DEFAULT '',
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, claim_id),
  UNIQUE KEY uk_red_packet_claim_command (app_code, command_id),
  UNIQUE KEY uk_red_packet_claim_user (app_code, packet_id, user_id),
  KEY idx_red_packet_claim_packet (app_code, packet_id, created_at_ms)
);
```

### 退款和次数表

```sql
CREATE TABLE red_packet_refunds (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  refund_id VARCHAR(96) NOT NULL,
  command_id VARCHAR(128) NOT NULL,
  packet_id VARCHAR(96) NOT NULL,
  sender_user_id BIGINT NOT NULL,
  refund_amount BIGINT NOT NULL,
  wallet_transaction_id VARCHAR(96) NOT NULL,
  status VARCHAR(32) NOT NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, refund_id),
  UNIQUE KEY uk_red_packet_refund_command (app_code, command_id),
  UNIQUE KEY uk_red_packet_refund_packet (app_code, packet_id)
);

CREATE TABLE red_packet_user_daily_counters (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  user_id BIGINT NOT NULL,
  send_day CHAR(10) NOT NULL,
  sent_count INT NOT NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, user_id, send_day)
);
```

`send_day` 使用 UTC 日期字符串，例如 `2026-05-22`。不要使用服务器本地时区或客户端时区。

## 账务分录

红包使用 `COIN` 资产，建议新增账务类型：

| `biz_type` | 场景 | 分录 |
| --- | --- | --- |
| `red_packet_create` | 发送红包 | sender `COIN` `available_delta = -total_amount` |
| `red_packet_claim` | 抢红包成功 | claimer `COIN` `available_delta = +amount` |
| `red_packet_refund` | 过期退款 | sender `COIN` `available_delta = +remaining_amount` |

发红包扣款不是冻结余额，而是实际扣除并形成红包负债。未领取金额由 `red_packets.remaining_amount` 表达，过期后通过退款交易回到发送者账户。这样账本只保留用户余额事实，红包池余额由红包领域表负责审计，避免给用户账户引入复杂冻结语义。

## 随机金额拆分

红包创建时一次性生成所有份额，写入 `red_packet_allocations`。领取时只分配已经生成的未领取份额，不再动态计算金额。

约束：

- 每份最小 `1` 金币。
- 份额数量等于 `packet_count`。
- 份额总和严格等于 `total_amount`。
- 使用服务端安全随机数。
- 生成后打乱 `allocation_no`，避免领取顺序和金额排序相关。

推荐算法：

```text
remaining_amount = total_amount
remaining_count = packet_count

for i in 1..packet_count:
  if remaining_count == 1:
    amount = remaining_amount
  else:
    min_amount = 1
    max_amount = remaining_amount - (remaining_count - 1)
    avg = remaining_amount / remaining_count
    draw_max = min(max_amount, max(1, avg * 2))
    amount = secure_random_int(min_amount, draw_max)

  append amount
  remaining_amount -= amount
  remaining_count -= 1

shuffle amounts
```

这个算法保留随机波动，同时保证最后不会出现剩余金额不足以分配最小份额的情况。后续如果产品需要更平滑分布，可以把 `avg * 2` 改成配置项，但不能让客户端控制。

## 发红包流程

```mermaid
sequenceDiagram
  participant C as Flutter
  participant G as gateway-service
  participant R as room-service
  participant W as wallet-service
  participant DB as wallet MySQL
  participant A as activity-service
  participant IM as Tencent IM

  C->>G: POST /api/v1/rooms/{room_id}/red-packets
  G->>R: GetRoomContext(room_id)
  R-->>G: room_id, visible_region_id
  G->>W: CreateRedPacket(command_id, sender, room, region, type, amount, count)
  W->>DB: validate config + daily counter + debit + allocations + wallet_outbox
  W-->>G: packet_id, open_at_ms, expires_at_ms
  G-->>C: red packet created
  A->>DB: scan wallet_outbox red_packet.created
  A->>A: PublishRegionBroadcast
  A->>IM: region floating broadcast
```

关键规则：

- `gateway-service` 不能信任客户端提交的 `region_id`，必须从房间上下文取房间可见区域。
- `wallet-service` 在同一个 MySQL 事务内完成配置校验、每日次数递增、sender 扣款、红包记录、份额记录、钱包交易、钱包分录和 `wallet_outbox`。
- 同一个 `app_code + command_id` 重复调用，payload 相同返回原红包，payload 不同返回 `REQUEST_CONFLICT`。
- 延迟红包创建成功后立即扣款和飘屏，客户端根据 `open_at_ms` 展示倒计时。

## 抢红包流程

```mermaid
sequenceDiagram
  participant C as Flutter
  participant G as gateway-service
  participant W as wallet-service
  participant DB as wallet MySQL

  C->>G: POST /api/v1/red-packets/{packet_id}/claim
  G->>W: ClaimRedPacket(command_id, packet_id, user_id)
  W->>DB: lock packet
  W->>DB: check open/expire/already claimed
  W->>DB: lock one unclaimed allocation
  W->>DB: credit claimer + claim + update remaining
  W-->>G: amount, claim_id
  G-->>C: claim result
```

并发控制：

- `red_packets` 行先加锁，保证剩余金额和数量更新一致。
- `red_packet_claims` 上 `uk_red_packet_claim_user(app_code, packet_id, user_id)` 保证每人每红包最多领取一次。
- 未领取份额使用 `SELECT ... FOR UPDATE SKIP LOCKED` 或等价行锁策略获取一条 `unclaimed` allocation。
- 领取成功必须和 claimer 钱包入账、红包剩余数量更新在同一个事务中提交。
- 如果没有未领取份额，返回 `RED_PACKET_SOLD_OUT`。

## 过期退款流程

过期退款由 `wallet-service` worker 执行。`cron-service` 可以通过内部 gRPC 触发批处理，但不能直接修改红包或钱包表。

```mermaid
sequenceDiagram
  participant Cron as cron-service or wallet worker
  participant W as wallet-service
  participant DB as wallet MySQL

  Cron->>W: ExpireRedPackets(batch_size)
  W->>DB: select active/waiting packets expires_at_ms <= now for update
  W->>DB: sum unclaimed allocations
  W->>DB: credit sender refund
  W->>DB: mark allocations expired
  W->>DB: mark packet refunded
  W->>DB: insert wallet_outbox red_packet.refunded
```

退款命令号固定：

```text
red_packet_refund:<packet_id>
```

规则：

- 退款金额等于未领取 allocation 金额总和，不由客户端或外部任务传入。
- `remaining_amount = 0` 时只把红包改成 `finished` 或 `expired`，不产生 0 金额退款交易。
- 重复扫描同一个过期红包必须返回同一退款结果，不能重复加钱。
- 过期判断使用 `expires_at_ms <= now_ms`。

## 区域飘屏与 MQ

红包创建成功后，`wallet-service` 写 `wallet_outbox`：

```json
{
  "event_type": "red_packet.created",
  "packet_id": "rp_xxx",
  "packet_type": "normal",
  "sender_user_id": 123,
  "room_id": "100001",
  "region_id": 86,
  "total_amount": 1000,
  "packet_count": 10,
  "open_at_ms": 1780000000000,
  "expires_at_ms": 1780000300000,
  "created_at_ms": 1780000000000
}
```

`activity-service` 消费该事实后调用现有播报能力：

```text
BroadcastService.PublishRegionBroadcast(
  region_id = event.region_id,
  broadcast_type = "red_packet_created",
  payload_json = event payload
)
```

MQ 设计结论：

- 可以把 `wallet_outbox` relay 到 MQ，提高实时性。
- 不能让 MQ 成为扣款、领取或退款事实来源。
- activity 消费失败只影响飘屏实时性，不回滚红包创建。
- activity 必须按 `event_id` 幂等，避免 outbox 重投导致重复飘屏。
- 如果 MQ 不可用，activity 可以像首冲奖励 worker 一样轮询 `wallet_outbox` 作为补偿路径。

## 内部 gRPC 契约

建议在 `api/proto/wallet/v1/wallet.proto` 增加红包 RPC。

```proto
message RedPacketConfig {
  bool enabled = 1;
  repeated int32 count_tiers = 2;
  repeated int64 amount_tiers = 3;
  int32 delayed_open_seconds = 4;
  int32 expire_seconds = 5;
  int32 daily_send_limit = 6;
  int64 updated_at_ms = 7;
}

message CreateRedPacketRequest {
  common.v1.RequestMeta meta = 1;
  string command_id = 2;
  string app_code = 3;
  int64 sender_user_id = 4;
  string room_id = 5;
  int64 region_id = 6;
  string packet_type = 7;
  int64 total_amount = 8;
  int32 packet_count = 9;
}

message CreateRedPacketResponse {
  string packet_id = 1;
  string status = 2;
  int64 total_amount = 3;
  int32 packet_count = 4;
  int64 open_at_ms = 5;
  int64 expires_at_ms = 6;
  int64 balance_after = 7;
}

message ClaimRedPacketRequest {
  common.v1.RequestMeta meta = 1;
  string command_id = 2;
  string app_code = 3;
  string packet_id = 4;
  int64 user_id = 5;
}

message ClaimRedPacketResponse {
  string claim_id = 1;
  string packet_id = 2;
  int64 amount = 3;
  int64 claimed_at_ms = 4;
  int64 balance_after = 5;
}
```

管理侧 RPC：

```proto
rpc GetRedPacketConfig(GetRedPacketConfigRequest) returns (GetRedPacketConfigResponse);
rpc UpdateRedPacketConfig(UpdateRedPacketConfigRequest) returns (UpdateRedPacketConfigResponse);
rpc ListRedPackets(ListRedPacketsRequest) returns (ListRedPacketsResponse);
rpc GetRedPacket(GetRedPacketRequest) returns (GetRedPacketResponse);
rpc ExpireRedPackets(ExpireRedPacketsRequest) returns (ExpireRedPacketsResponse);
```

## App HTTP 接口

### 获取红包配置

```http
GET /api/v1/red-packets/config
Authorization: Bearer <access_token>
```

Response `data`：

```json
{
  "config": {
    "enabled": true,
    "count_tiers": [5, 10, 20],
    "amount_tiers": [100, 500, 1000],
    "delayed_open_seconds": 30,
    "expire_seconds": 300,
    "daily_send_limit": 5
  },
  "server_time_ms": 1780000000000
}
```

### 发送红包

```http
POST /api/v1/rooms/{room_id}/red-packets/create
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request：

```json
{
  "command_id": "uuid",
  "packet_type": "normal",
  "total_amount": 1000,
  "packet_count": 10
}
```

`packet_type`：

| 值 | 语义 |
| --- | --- |
| `normal` | 普通红包 |
| `delayed` | 延迟红包，打开时间由后台 `delayed_open_seconds` 决定 |

Response `data`：

```json
{
  "packet": {
    "packet_id": "rp_xxx",
    "packet_type": "normal",
    "status": "active",
    "total_amount": 1000,
    "packet_count": 10,
    "remaining_count": 10,
    "open_at_ms": 1780000000000,
    "expires_at_ms": 1780000300000
  },
  "server_time_ms": 1780000000000,
  "balance_after": 99000
}
```

### 房间红包列表

```http
GET /api/v1/rooms/{room_id}/red-packets?status=active&page=1&page_size=20
Authorization: Bearer <access_token>
```

Response `data`：

```json
{
  "packets": [
    {
      "packet_id": "rp_xxx",
      "packet_type": "delayed",
      "sender_user_id": 123,
      "total_amount": 1000,
      "packet_count": 10,
      "remaining_count": 10,
      "status": "waiting_open",
      "open_at_ms": 1780000030000,
      "expires_at_ms": 1780000300000,
      "created_at_ms": 1780000000000,
      "claimed_by_viewer": false
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "server_time_ms": 1780000001000
}
```

### 红包详情

```http
GET /api/v1/red-packets/{packet_id}
Authorization: Bearer <access_token>
```

Response `data`：

```json
{
  "packet": {
    "packet_id": "rp_xxx",
    "packet_type": "normal",
    "sender_user_id": 123,
    "room_id": "100001",
    "region_id": 86,
    "total_amount": 1000,
    "packet_count": 10,
    "remaining_amount": 420,
    "remaining_count": 4,
    "status": "active",
    "open_at_ms": 1780000000000,
    "expires_at_ms": 1780000300000,
    "claimed_by_viewer": true,
    "viewer_claim_amount": 88,
    "claims": [
      {
        "user_id": 456,
        "amount": 120,
        "created_at_ms": 1780000005000
      }
    ]
  },
  "server_time_ms": 1780000010000
}
```

领取列表是否展示完整金额由产品决定；如果需要弱化刺激，可以只展示自己的领取金额和已领取人数。

### 抢红包

```http
POST /api/v1/red-packets/{packet_id}/claim
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request：

```json
{
  "command_id": "uuid"
}
```

Response `data`：

```json
{
  "claim": {
    "claim_id": "rpc_xxx",
    "packet_id": "rp_xxx",
    "amount": 88,
    "created_at_ms": 1780000010000
  },
  "server_time_ms": 1780000010000,
  "balance_after": 100088
}
```

## 错误码

| code | HTTP | 场景 | Flutter 处理 |
| --- | --- | --- | --- |
| `RED_PACKET_DISABLED` | 409 | 红包功能未启用 | 隐藏入口或提示暂不可用 |
| `INVALID_ARGUMENT` | 400 | 类型不是 `normal/delayed` 或请求字段缺失 | 不重试，刷新配置 |
| `INVALID_AMOUNT_TIER` | 400 | 金额未命中后台档位 | 不重试，刷新配置 |
| `INVALID_COUNT_TIER` | 400 | 数量未命中后台档位 | 不重试，刷新配置 |
| `RED_PACKET_AMOUNT_TOO_SMALL` | 400 | 总金额小于红包数量 | 不重试，前端校验兜底 |
| `DAILY_SEND_LIMIT_REACHED` | 429 | 达到 UTC 当日发送上限 | 禁用发送入口到下一 UTC 日 |
| `INSUFFICIENT_BALANCE` | 409 | 金币不足 | 引导充值或选择低档 |
| `NOT_FOUND` | 404 | 红包不存在 | 关闭详情页并刷新列表 |
| `RED_PACKET_NOT_OPEN` | 409 | 延迟红包未到打开时间 | 展示倒计时，不重试抢 |
| `RED_PACKET_EXPIRED` | 409 | 红包已过期 | 刷新详情和列表 |
| `RED_PACKET_ALREADY_CLAIMED` | 409 | 当前用户已领取 | 展示已领取金额 |
| `RED_PACKET_SOLD_OUT` | 409 | 已被抢完 | 展示已抢完 |
| `REQUEST_CONFLICT` | 409 | 同一 `command_id` payload 不一致 | 重新生成命令号后由用户重新发起 |

## 后台设计

菜单：

```text
活动管理
  红包配置
  红包记录
```

### 红包配置页

字段：

| 字段 | 控件 | 校验 |
| --- | --- | --- |
| 是否启用 | Switch | 关闭后 App 获取配置仍返回档位，但发送接口拒绝 |
| 红包数量档位 | 可增删数字列表 | 每项 `> 0`，去重，建议排序 |
| 红包金额档位 | 可增删数字列表 | 每项 `> 0`，去重，金额单位金币 |
| 延迟红包秒数 | 数字输入 | `>= 0`，`0` 表示延迟红包立即可抢，但仍标记为 delayed |
| 每人每日最多发送次数 | 数字输入 | `>= 0`，`0` 表示禁止发送 |
| 红包过期秒数 | 数字输入 | `> 0`，必须大于延迟秒数，否则延迟红包可能还没打开就过期 |

后台提交时 admin server 生成审计字段：

```text
admin_id
request_id
operation
before_config
after_config
created_at_ms
```

### 红包记录页

筛选：

```text
packet_id
sender_user_id
room_id
region_id
packet_type
status
created_start_ms / created_end_ms
```

列表字段：

```text
packet_id
sender_user_id
room_id
region_id
packet_type
total_amount
packet_count
remaining_amount
remaining_count
status
open_at_ms
expires_at_ms
created_at_ms
```

详情页展示领取明细、退款记录和钱包交易 ID，只读，不允许后台手动改红包状态。需要人工补偿时走现有后台调账或补偿命令，不直接改红包表。

Admin HTTP：

```http
GET /api/v1/admin/activity/red-packets/config
PUT /api/v1/admin/activity/red-packets/config
GET /api/v1/admin/activity/red-packets
GET /api/v1/admin/activity/red-packets/{packet_id}
```

## Flutter 对接方案

Flutter 不实现红包金额随机、发送次数、过期退款或账务判断，只消费服务端结果。

### 初始化

进入房间时并行拉取：

```text
GET /api/v1/red-packets/config
GET /api/v1/rooms/{room_id}/red-packets?status=active&page=1&page_size=20
```

UI 使用 `server_time_ms` 计算倒计时偏移：

```text
client_offset_ms = server_time_ms - local_now_ms
effective_now_ms = local_now_ms + client_offset_ms
```

倒计时只用于展示，最终可抢状态以服务端 `ClaimRedPacket` 结果为准。

### 发红包

用户只能从 `count_tiers` 和 `amount_tiers` 选择。提交前生成一次性 `command_id`，网络超时可用同一个 `command_id` 重试同一请求。

普通红包：

```json
{
  "command_id": "uuid",
  "packet_type": "normal",
  "total_amount": 1000,
  "packet_count": 10
}
```

延迟红包：

```json
{
  "command_id": "uuid",
  "packet_type": "delayed",
  "total_amount": 1000,
  "packet_count": 10
}
```

延迟秒数不由 Flutter 传入，只使用后台配置。

### 抢红包

每次点击抢红包生成新的 `command_id`。如果返回超时，可以用同一个 `command_id` 查询或重试。收到 `RED_PACKET_ALREADY_CLAIMED` 时需要拉详情展示已领取金额。

### IM 飘屏

区域播报消息：

```json
{
  "broadcast_type": "red_packet_created",
  "packet_id": "rp_xxx",
  "packet_type": "delayed",
  "sender_user_id": 123,
  "room_id": "100001",
  "region_id": 86,
  "total_amount": 1000,
  "packet_count": 10,
  "open_at_ms": 1780000030000,
  "expires_at_ms": 1780000300000,
  "created_at_ms": 1780000000000
}
```

Flutter 收到飘屏后：

- 当前在同区域时展示飘屏。
- 点击飘屏进入对应房间或打开红包详情。
- 如果 `effective_now_ms < open_at_ms`，展示倒计时。
- 如果 `effective_now_ms >= expires_at_ms`，点击后直接拉详情，以服务端状态为准。

## 实现顺序

1. `wallet-service` 增加红包表、配置表、领域模型和 MySQL repository。
2. `api/proto/wallet/v1` 增加红包 App RPC、Admin RPC 和 `ExpireRedPackets` 批处理 RPC，运行 `make proto`。
3. `wallet-service` 实现 `CreateRedPacket`，覆盖档位、余额、每日次数、随机拆分、幂等和 outbox。
4. `wallet-service` 实现 `ClaimRedPacket`，覆盖延迟未开、过期、重复领取、并发抢完和入账。
5. `wallet-service` 实现过期退款 worker 或批处理 RPC。
6. `activity-service` 增加红包 outbox consumer，调用 `PublishRegionBroadcast` 写区域播报。
7. `gateway-service` 增加 App HTTP 接口，保持 `{code,message,request_id,data}` envelope。
8. `server/admin` 增加配置和记录查询接口，写后台审计。
9. `hyapp-admin-platform` 增加 `活动管理 / 红包配置` 和红包记录页。
10. 更新 Flutter 对接文档，不改 Flutter 代码，等 App 侧按接口接入。

## 验证计划

### wallet-service 单元和 MySQL 集成

| 场景 | 预期 |
| --- | --- |
| 创建普通红包 | sender 扣款，红包 active，allocation 总和等于总金额 |
| 创建延迟红包 | sender 扣款，红包 waiting_open，`open_at_ms` 正确 |
| 非档位金额 | 返回 `INVALID_AMOUNT_TIER`，余额不变 |
| 非档位数量 | 返回 `INVALID_COUNT_TIER`，余额不变 |
| 总金额小于数量 | 返回 `RED_PACKET_AMOUNT_TOO_SMALL` |
| 金币不足 | 返回 `INSUFFICIENT_BALANCE`，不写红包 |
| 每日次数超过 | 返回 `DAILY_SEND_LIMIT_REACHED`，按 UTC 日期切换 |
| 同 command 重试 | 返回同一 `packet_id`，余额只扣一次 |
| 同 command 不同 payload | 返回 `REQUEST_CONFLICT` |
| 未到打开时间领取 | 返回 `RED_PACKET_NOT_OPEN` |
| 重复领取 | 第二次返回 `RED_PACKET_ALREADY_CLAIMED` |
| 并发领取 | 不超发，领取总额等于红包总额 |
| 抢完后领取 | 返回 `RED_PACKET_SOLD_OUT` |
| 过期退款 | 未领取金额退回 sender，重复扫描不重复退款 |

### activity-service 验证

| 场景 | 预期 |
| --- | --- |
| 消费 `red_packet.created` | 写入一条 `im_broadcast_outbox` |
| outbox 重投 | 不重复写同一飘屏 |
| 区域 ID 无效 | 记录失败原因，不影响红包账务 |

### gateway/admin 验证

| 场景 | 预期 |
| --- | --- |
| App 接口 envelope | 所有业务响应符合 `{code,message,request_id,data}` |
| gateway 不信任 region_id | 客户端无法伪造区域飘屏 |
| admin 更新配置 | wallet 配置生效，写后台审计 |
| admin 记录查询 | 可按用户、房间、状态和时间范围查询 |

### 本地真实数据流程

```text
1. admin 配置数量档位、金额档位、延迟秒数、过期秒数和每日次数。
2. 用户 A 充值金币或后台入账金币。
3. 用户 A 在房间发普通红包，确认钱包扣款、红包 active、区域飘屏 outbox 产生。
4. 用户 B/C/D 抢红包，确认每人金额随机、总和不超过总额、钱包入账。
5. 用户 A 发延迟红包，open_at_ms 前抢返回 RED_PACKET_NOT_OPEN。
6. 到 open_at_ms 后领取成功。
7. 创建一个短过期红包，等待过期 worker 执行，确认未领取金额退回用户 A。
8. 同一 UTC 日连续发送到上限，再发送返回 DAILY_SEND_LIMIT_REACHED。
```

## 待确认产品点

| 问题 | 默认建议 |
| --- | --- |
| 发送者是否可以抢自己的红包 | 默认允许，减少用户困惑；如需禁止，加领取校验即可 |
| 红包详情是否展示所有领取金额 | 默认展示自己的金额和领取人数，完整明细可配置 |
| 飘屏点击是否跨房间跳转 | 默认点击进入对应房间并打开红包详情 |
| 延迟红包倒计时期间是否展示总额 | 默认展示总额、数量、打开时间，不展示任何随机份额 |