# 第一阶段实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 搭建 Go 微服务游戏平台第一阶段可运行工程骨架，明确服务边界、公共库、文档规范、K3s 部署目录和核心服务启动方式。

**Architecture:** 第一阶段采用单仓多服务方式管理，所有服务独立文件夹、独立中文文档、独立 Dockerfile、独立 K8s 部署目录。对外 HTTP 统一按 CloudWeGo Hertz 方向预留，内部 RPC 按 CloudWeGo Kitex/IDL 方向预留，主链路遵守 Redpanda 顺序日志、wallet-shard 分片处理、ledger 不可变账本的约束。

**Tech Stack:** Go、CloudWeGo Hertz、CloudWeGo Kitex、PostgreSQL、Redis、Redpanda、ClickHouse、MinIO、K3s/Kubernetes、Prometheus、OpenTelemetry。

---

## 文件结构

第一阶段在 `golang新架构` 下创建以下目录：

```text
golang新架构/
├── 平台服务/
│   ├── merchant-gateway/
│   ├── order-ingest-service/
│   ├── wallet-service/
│   ├── wallet-shard-service/
│   ├── ledger-service/
│   ├── ledger-writer-service/
│   ├── bet-order-service/
│   ├── settlement-service/
│   └── callback-service/
├── 游戏服务/
│   ├── game-gateway/
│   ├── game-router/
│   ├── game-session-service/
│   ├── game-config-service/
│   ├── risk-rtp-service/
│   └── game-pg-mahjong/
├── 实时服务/
│   ├── ranking-service/
│   └── presence-service/
├── 数据服务/
│   ├── warehouse-writer/
│   └── report-service/
├── 公共库/
│   ├── go.mod
│   ├── pkg/
│   │   ├── app/
│   │   ├── errors/
│   │   ├── ids/
│   │   ├── observability/
│   │   └── contracts/
│   └── README.md
├── 接口协议/
│   ├── proto/
│   ├── thrift/
│   └── README.md
├── 项目文档/
│   ├── 架构文档/
│   ├── 实施计划/
│   ├── 服务文档/
│   ├── 数据库文档/
│   └── 运维文档/
├── 部署/
│   ├── k8s/
│   └── docker-compose/
└── Makefile
```

## Task 1: 创建项目目录骨架

**Files:**
- Create directories under `golang新架构/`
- Create: `golang新架构/README.md`
- Create: `golang新架构/Makefile`

- [ ] **Step 1: 创建中文分层目录**

Run:

```bash
mkdir -p \
  平台服务/{merchant-gateway,order-ingest-service,wallet-service,wallet-shard-service,ledger-service,ledger-writer-service,bet-order-service,settlement-service,callback-service} \
  游戏服务/{game-gateway,game-router,game-session-service,game-config-service,risk-rtp-service,game-pg-mahjong} \
  实时服务/{ranking-service,presence-service} \
  数据服务/{warehouse-writer,report-service} \
  公共库/pkg/{app,errors,ids,observability,contracts} \
  接口协议/{proto,thrift} \
  项目文档/{架构文档,实施计划,服务文档,数据库文档,运维文档} \
  部署/{k8s,docker-compose}
```

- [ ] **Step 2: 写根 README**

Create `README.md` explaining the directory layout and requiring all development to follow `AI开发约束与架构定稿.md`.

- [ ] **Step 3: 写根 Makefile**

Create `Makefile` with commands:

```makefile
.PHONY: test fmt list

list:
	find . -maxdepth 3 -type d | sort

fmt:
	find . -name go.mod -maxdepth 4 -execdir gofmt -w ./pkg ./cmd 2>/dev/null \; || true

test:
	find . -name go.mod -maxdepth 4 -execdir go test ./... \;
```

## Task 2: 搭建公共库 Go 模块

**Files:**
- Create: `公共库/go.mod`
- Create: `公共库/pkg/app/service.go`
- Create: `公共库/pkg/errors/code.go`
- Create: `公共库/pkg/ids/ids.go`
- Create: `公共库/pkg/observability/log.go`
- Create: `公共库/pkg/contracts/events.go`
- Create: `公共库/pkg/contracts/orders.go`
- Create: `公共库/README.md`

- [ ] **Step 1: 创建公共库 go.mod**

Module name:

```text
game-platform/common
```

- [ ] **Step 2: 定义服务元信息**

Create `pkg/app/service.go` with `ServiceInfo` and `HealthResponse`.

- [ ] **Step 3: 定义统一错误码**

Create `pkg/errors/code.go` with typed error code constants for merchant API, wallet, order, game, callback, config.

- [ ] **Step 4: 定义 ID 生成接口**

Create `pkg/ids/ids.go` with functions for trace id, round id, order id, ledger transaction id.

- [ ] **Step 5: 定义事件契约**

Create `pkg/contracts/events.go` with `EventEnvelope`.

- [ ] **Step 6: 定义注单状态契约**

Create `pkg/contracts/orders.go` with order statuses and display statuses.

- [ ] **Step 7: 运行公共库测试**

Run:

```bash
cd 公共库
go test ./...
```

Expected: `ok` or `[no test files]`.

## Task 3: 创建服务脚手架模板

**Files:**
- For each service folder create:
  - `README.md`
  - `cmd/<service>/main.go`
  - `internal/domain/doc.go`
  - `internal/usecase/doc.go`
  - `internal/adapter/http/doc.go`
  - `internal/infrastructure/doc.go`
  - `deploy/k8s/deployment.yaml`
  - `Dockerfile`
  - `Makefile`

- [ ] **Step 1: 为 merchant-gateway 创建完整服务模板**

`merchant-gateway` 必须包含中文 README，列出职责、不负责边界、上游、下游、API、命令。

- [ ] **Step 2: 复制模板到其他服务**

每个服务保留独立文件夹和独立中文 README，不允许多个服务混在一个目录。

- [ ] **Step 3: 每个服务 main.go 必须提供 health 输出**

第一阶段 main.go 可以先启动最小 HTTP 健康检查，后续替换为 Hertz server。

## Task 4: 创建数据库中文文档

**Files:**
- Create: `项目文档/数据库文档/platform_db-平台库.md`
- Create: `项目文档/数据库文档/wallet_db-钱包账本库.md`
- Create: `项目文档/数据库文档/order_db-注单库.md`
- Create: `项目文档/数据库文档/config_db-配置库.md`
- Create: `项目文档/数据库文档/risk_db-风控库.md`
- Create: `项目文档/数据库文档/clickhouse-数仓表说明.md`

- [ ] **Step 1: 写 platform_db 文档**

必须包含商户表、密钥表、IP 白名单表、管理员表、角色权限表。

- [ ] **Step 2: 写 wallet_db 文档**

必须包含钱包余额快照、不可变账本、冻结资金、账变事务。

- [ ] **Step 3: 写 order_db 文档**

必须包含注单主表、状态流转、round 表、结算表、退款表、回调任务表。

- [ ] **Step 4: 写 config_db/risk_db/ClickHouse 文档**

必须包含 slots 配置版本、采集文件元数据、RTP、单控、事件表。

## Task 5: 创建部署与运维文档

**Files:**
- Create: `项目文档/运维文档/单机K3s部署说明.md`
- Create: `项目文档/运维文档/服务发布与回滚说明.md`
- Create: `项目文档/运维文档/数据库备份恢复说明.md`
- Create: `项目文档/运维文档/故障排查命令.md`
- Create: `部署/docker-compose/README.md`
- Create: `部署/k8s/README.md`

- [ ] **Step 1: 写单机 K3s 部署说明**

必须说明第一阶段状态组件跑宿主机或 Docker Compose，业务服务进 K3s。

- [ ] **Step 2: 写发布回滚命令**

必须包含 `kubectl apply`、`kubectl rollout status`、`kubectl rollout undo`。

- [ ] **Step 3: 写故障排查命令**

必须覆盖 Pod、日志、服务、配置、数据库连接、Redpanda、Redis、ClickHouse。

## Task 6: 验证

**Files:**
- Modify as needed.

- [ ] **Step 1: 列出目录**

Run:

```bash
make list
```

Expected: 所有中文目录和服务目录清晰展示。

- [ ] **Step 2: 运行 Go 测试**

Run:

```bash
make test
```

Expected: 所有已创建 Go 模块测试通过。

- [ ] **Step 3: 检查 Markdown**

Run:

```bash
find . -name '*.md' | sort
```

Expected: 总架构、AI 约束、项目文档/服务文档、项目文档/数据库文档、项目文档/运维文档都存在。