# ledger-service 账本服务

## 服务职责

ledger-service 负责不可变资金账本。所有扣款、派奖、退款、冲正都必须形成 ledger entry，后续对账、报表、风控和商户回调都以账本事件为资金事实来源。

当前第一阶段先完成扣款链路：

```text
wallet.debit.requested 语义请求
        ↓
POST /ledger/debit
        ↓
append-only ledger entry
        ↓
wallet.debit.succeeded 事件
```

## 核心约束

- 账本只追加。
- 历史账本金额不可修改。
- 每笔账变必须有关联 transaction_id。
- 账本必须支持对账和审计。
- `idempotency_key` 优先作为幂等键；没有传时使用 `bet_order_id`。
- 重复扣款请求必须返回同一个 `ledger_transaction_id`，不能重复追加账本，也不能重复发布成功事件。
- 任何余额视图都只能从账本派生，不能把余额表当作最终事实。

## 必须字段

```text
ledger_transaction_id
merchant_id
player_id
round_id
bet_order_id
entry_type
amount
balance_before
balance_after
idempotency_key
created_at
```

## 当前代码目录

```text
平台服务/ledger-service
├── cmd/ledger-service             进程入口
├── api/openapi                    HTTP API 契约
├── configs                        配置模板
├── internal/architecture          目录结构约束测试
├── internal/bootstrap             服务启动组装
├── internal/config                环境变量读取
├── internal/domain                领域错误
├── internal/handler/http          Hertz 路由和请求响应适配
├── internal/middleware            中间件预留
├── internal/model                 请求、响应、账本 entry 模型
├── internal/repository/postgres   第一阶段内存账本仓储；后续替换 PostgreSQL
└── internal/service               扣款账本、幂等、成功事件生成
```

## 第一阶段已实现

当前已经从健康检查占位升级为可运行服务：

```text
POST /ledger/debit
```

当前具备：

- 生成不可变 debit ledger entry。
- 内存 append-only repository，`Entries()` 返回副本，外部不能修改历史 entry。
- `idempotency_key` / `bet_order_id` 幂等。
- 重复请求返回同一个 `ledger_transaction_id`。
- 生成 `wallet.debit.succeeded` 事件。
- 单元测试覆盖创建账本、幂等、参数校验、成功事件、append-only 行为。

注意：当前 repository 和 producer 是第一阶段内存实现。下一阶段需要接 PostgreSQL append-only 表和 Redpanda producer。

## 本地请求示例

```bash
curl -sS http://127.0.0.1:8093/ledger/debit \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: ledger-local-001' \
  -d '{
    "event_id": "wallet_evt_001",
    "trace_id": "trace_001",
    "merchant_id": "DEMO",
    "player_id": "player_001",
    "round_id": "round_001",
    "bet_order_id": "bet_001",
    "idempotency_key": "bet_001",
    "amount": 100,
    "currency": "CNY",
    "shard_id": 7
  }'
```

## 命令

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

## 下一阶段必须补齐

- PostgreSQL append-only ledger_entries 表。
- Redpanda consumer：消费 `wallet.debit.requested`。
- Redpanda producer：写入 `wallet.debit.succeeded`。
- 余额快照/余额视图派生服务。
- Prometheus 指标。
- OpenTelemetry trace。
- 压测脚本和报告。