# order-ingest-service 订单接入服务

## 服务职责

order-ingest-service 是高并发订单进入平台后的第一落点，负责把通过网关校验的订单快速写入 Redpanda 顺序事件日志。

## 核心原则

- 不同步逐单写 PostgreSQL 后返回。
- 必须把订单写入 Redpanda。
- 必须生成 event_id、trace_id、bet_order_id。
- 必须保留幂等 key。

## 不负责的边界

- 不直接扣款。
- 不直接派奖。
- 不直接生成游戏结果。
- 不直接回调商户。

## 下游依赖

- Redpanda topic: `order.ingested`
- bet-order-service
- wallet-shard-service

## 命令

```bash
cd /Users/amumu/Desktop/beifen/golang新架构/平台服务/order-ingest-service
go test ./...
PORT=8091 go run ./cmd/order-ingest-service
docker build -t registry.local/order-ingest-service:v1 .
kubectl apply -f deploy/k8s/deployment.yaml
```

## 当前代码目录

```text
平台服务/order-ingest-service
├── cmd/order-ingest-service      进程入口
├── api/openapi                   HTTP API 契约
├── configs                       配置模板
├── internal/bootstrap            服务启动组装
├── internal/config               环境变量读取
├── internal/domain               领域错误
├── internal/handler/http         Hertz 路由和请求响应适配
├── internal/middleware           中间件预留
├── internal/model                请求和响应模型
├── internal/repository/redpanda  Redpanda/Kafka API producer
└── internal/service              订单接入、幂等、队列背压和 producer 接口
```

## 第一阶段已实现

第一阶段已经从健康检查占位升级为可运行订单接入服务：

```text
POST /orders/ingest
```

当前具备：

- 参数校验。
- `merchant_id + client_request_id` 幂等。
- `bet_order_id` 生成。
- `event_id` 生成。
- `trace_id` 生成。
- `merchant_id + player_id` 分区键。
- 本地有界队列。
- 队列满时返回背压错误。
- producer 接口抽象。
- Redpanda/Kafka API producer。
- 未配置 `REDPANDA_BROKERS` 时回退内存 producer，便于本地开发。
- producer 事件 JSON 编码、topic、key、headers 单元测试。
- 单元测试覆盖正常写入、幂等、队列满、参数校验。

注意：当前已经支持 Redpanda producer，但本地如果没有配置 `REDPANDA_BROKERS` 会自动使用内存 producer。正式生产必须配置 `REDPANDA_BROKERS`，否则订单事件不会写入 Redpanda。

## 本地请求示例

```bash
curl -sS http://127.0.0.1:8091/orders/ingest \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: req-local-001' \
  -d '{
    "merchant_id": "DEMO",
    "player_id": "player_001",
    "game_code": "demo-slots",
    "round_id": "round_001",
    "client_request_id": "req_001",
    "bet_amount": 100,
    "currency": "CNY"
  }'
```

返回：

```json
{
  "code": "OK",
  "message": "success",
  "data": {
    "code": "OK",
    "status": "INGESTED",
    "event_id": "evt_xxx",
    "bet_order_id": "bet_xxx",
    "partition_key": "DEMO:player_001",
    "client_request_id": "req_001"
  }
}
```

## 环境变量

```text
ORDER_INGEST_QUEUE_CAPACITY=65536
REDPANDA_BROKERS=127.0.0.1:9092
REDPANDA_TOPIC_ORDER_INGESTED=order.ingested
```

`REDPANDA_BROKERS` 支持逗号分隔：

```text
REDPANDA_BROKERS=10.0.0.1:9092,10.0.0.2:9092,10.0.0.3:9092
```

## 下一阶段必须补齐

- topic 自动检查或启动前检查。
- 批量 publish。
- producer 失败重试。
- 死信队列。
- Prometheus 指标。
- OpenTelemetry trace。
- 压测脚本和报告。