# AI 开发约束与架构定稿 ## 1. 文档目的 本文档用于约束 Codex、AI 编程助手、后端开发人员在开发本 Go 微服务游戏平台时必须遵守的架构边界、技术选型、服务拆分、数据一致性、并发处理和文档规范。 本项目属于高并发交易型游戏平台，不允许 AI 根据个人习惯随意改架构、换框架、合并服务、绕过账本、绕过事件流或直接操作核心数据库。 如果后续开发过程中出现需求不清楚、接口不明确、数据库字段不明确、服务边界不明确，AI 必须先提出问题，不允许盲目实现。 ## 2. 架构定稿结论 本项目后端架构正式确定为： ```text Go 微服务 单机第一阶段使用 K3s/Kubernetes 主链路 HTTP 框架使用 CloudWeGo Hertz 内部 RPC 框架使用 CloudWeGo Kitex 内部服务结构使用 Clean Architecture / Hexagonal Architecture 交易数据库使用 PostgreSQL 缓存和实时状态使用 Redis 消息队列使用 Redpanda 数仓使用 ClickHouse 对象存储使用 MinIO 日志监控使用 Prometheus + Grafana + Loki 链路追踪使用 OpenTelemetry + Tempo/Jaeger ``` 高并发商户 API、钱包扣款、下注、派奖、回调、游戏结果处理必须围绕该架构设计。 重要说明： ```text 框架选型正确不等于服务实现完成。 只有一个 cmd//main.go 并且只调用 RunHealthService 的服务，只能算占位骨架，不能宣称可用，更不能宣称能抗并发。 ``` Go 服务实现成熟度必须遵守 [Go服务实现成熟度约束.md](./Go服务实现成熟度约束.md)。 ## 3. 核心开源选型 ### 3.1 HTTP 网关框架 必须使用： ```text CloudWeGo Hertz GitHub: https://github.com/cloudwego/hertz 官方文档: https://www.cloudwego.io/docs/hertz/overview/ ``` 用途： - merchant-gateway - game-gateway - admin-gateway - 对外 HTTP API - 高并发商户接入 禁止事项： - 禁止在主链路网关中使用 Gin、Echo、Fiber 替代 Hertz。 - 禁止用 net/http 手写主链路网关。 - 禁止使用低维护、冷门、文档不完整的 HTTP 框架。 ### 3.2 内部 RPC 框架 必须使用： ```text CloudWeGo Kitex GitHub: https://github.com/cloudwego/kitex 官方文档: https://www.cloudwego.io/docs/kitex/ ``` 用途： - 服务间高性能 RPC。 - 钱包服务调用。 - 注单服务调用。 - 结算服务调用。 - 游戏服务调用。 - 配置服务调用。 必须启用或预留： - 超时控制。 - 重试策略。 - 熔断。 - 限流。 - 服务发现。 - 负载均衡。 - 链路追踪。 - 指标监控。 禁止事项： - 禁止服务之间随意 HTTP 调用核心交易接口。 - 禁止核心交易服务之间绕过 RPC 契约直接访问对方数据库。 - 禁止在没有 IDL 的情况下随意传 map/json 作为长期内部协议。 ### 3.3 其他框架定位 Kratos、go-zero、Go Micro 只允许作为参考或非主链路后台服务候选，不作为本项目高并发交易主链路首选。 禁止 AI 在没有明确评审的情况下把主链路改成： ```text go-zero 主架构 Kratos 主架构 Go Micro 主架构 Gin 单体架构 NestJS/Java/PHP 主链路 ``` ### 3.4 Go 服务实现成熟度 当前项目里存在两类 Go 服务： ```text 第一阶段可运行服务：已经有标准 internal 分层、接口、测试、文档。 占位骨架服务：只有 main.go 和 /health /ready。 ``` 占位骨架服务必须显式登记在： ```text scripts/go-service-placeholder.allowlist ``` 每次实现服务前后必须运行： ```bash ./scripts/check-go-service-maturity.sh ``` 禁止事项： - 禁止把只有 `main.go` 的服务说成已完成。 - 禁止把只启动 `/health`、`/ready` 的服务说成能抗并发。 - 禁止没有 `internal/bootstrap`、`internal/service`、`internal/repository`、`api/openapi` 或 `api/thrift` 的服务进入正式部署。 - 禁止没有幂等、限流、超时、连接池、批量处理、异步事件、监控指标的主链路服务宣称能承接高并发。 - 禁止没有压测报告就宣称能承接“每毫秒 1 万单”。 - 禁止服务实现后仍留在 `go-service-placeholder.allowlist`。 ### 3.5 前端工程框架 总后台、商户后台、C 端正式前端必须使用成熟开源工程框架，不允许把单个 `index.html`、散落 CSS/JS、无构建工具的静态原型当作正式工程。 默认前端技术栈定稿： ```text 总后台：admin-web Vue 3 + Vite + TypeScript + Vue Router + Pinia + Naive UI Admin 或 Element Plus Admin 商户后台：merchant-web Vue 3 + Vite + TypeScript + Vue Router + Pinia + Naive UI Admin 或 Element Plus Admin C 端：player-web Vue 3 + Vite + TypeScript + Vue Router + Pinia ``` 如果后续选择 React 技术栈，只允许使用成熟企业级方案： ```text React 19 + Umi Max + Ant Design Pro + Pro Components ``` React 方案必须先单独评审并写入文档，不能由 AI 临时自行切换。 当前 `前端页面/C端/index.html`、`前端页面/总后台/index.html`、`前端页面/商户后台/index.html` 只允许作为第一阶段原型和接口联调页面，不允许继续在单文件上堆正式功能。 正式前端工程必须具备： ```text package.json vite.config.ts tsconfig.json src/main.ts src/router src/stores src/api src/layouts src/views src/components src/permissions src/styles src/types ``` 总后台和商户后台必须具备： - 登录页。 - 主布局。 - 侧边菜单。 - 动态路由。 - token 鉴权。 - RBAC 权限点。 - 请求封装。 - 错误码处理。 - 表格、表单、弹窗、分页、筛选、导出基础组件。 - 开发、测试、生产环境配置。 禁止事项： - 禁止正式后台继续只有一个 `index.html`。 - 禁止无 TypeScript。 - 禁止无路由系统。 - 禁止无状态管理。 - 禁止页面直接散写 `fetch` 调接口。 - 禁止把接口地址硬编码在页面里。 - 禁止没有构建命令、测试命令、lint 命令。 - 禁止引入低维护、小众、文档不完整的后台模板。 - 禁止未评审就从 Vue 切 React，或从 React 切 Vue。 ## 4. 高并发订单链路硬约束 本项目目标订单量非常大，商户 API 不允许按传统同步数据库写入方式设计。 必须遵守： ```text 高并发下单主链路禁止同步逐单写 PostgreSQL 后再返回。 订单接入必须先进入顺序事件日志 Redpanda。 钱包处理必须按玩家或商户玩家维度分片。 账本落库必须支持批量写入。 后台统计必须进入 ClickHouse，不允许扫 PostgreSQL 主交易库。 ``` 推荐主链路： ```text 商户请求 -> merchant-gateway 验签/限流/幂等预检 -> order-ingest-service 写 Redpanda -> wallet-shard-service 按 player_id 分片顺序处理 -> ledger-service 生成不可变账本事件 -> ledger-writer-service 批量写 PostgreSQL -> warehouse-writer 写 ClickHouse -> callback-service 异步推送商户 ``` 如果某个接口必须强同步返回最终扣款结果，必须在接口文档中明确写清楚，并单独评估吞吐损耗。 ## 5. 服务拆分硬约束 服务必须按职责拆分，不允许随意合并。 第一阶段至少包含： ```text 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 ranking-service chat-service（后置按需开发，不作为当前阶段已实现服务） presence-service warehouse-writer report-service 至少一个 game-* 子游戏服务 ``` 禁止事项： - 禁止把钱包、注单、游戏开奖写成一个服务。 - 禁止子游戏服务直接修改玩家余额表。 - 禁止后台服务直接改核心账本。 - 禁止 callback-service 参与玩家下注主链路。 - 禁止 report-service 查询 PostgreSQL 大表做统计。 - 禁止 game 服务直接绕过 bet-order-service 创建注单。 ## 6. 钱包和账本约束 钱包系统是核心，不允许简化成普通余额字段加减。 必须遵守： - 所有资金变化必须写 ledger entry。 - 账本只追加，不允许更新历史账本金额。 - 当前余额可以使用快照表，但最终以账本为准。 - 扣款、派奖、退款、冲正必须有独立 transaction_id。 - 钱包操作必须幂等。 - 同一个玩家的钱包事件必须按分片顺序处理。 禁止事项： - 禁止直接 `UPDATE users SET balance = balance - amount` 作为最终方案。 - 禁止没有账本流水的余额变化。 - 禁止游戏服务直接写余额。 - 禁止后台人工调整绕过 ledger-service。 - 禁止重复 request_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 ``` ## 7. 注单状态机约束 注单必须使用状态机，不允许散乱更新状态。 标准状态： ```text CREATED INGESTED DEBIT_PENDING DEBIT_SUCCESS RESULT_GENERATED SETTLE_PENDING SETTLED CALLBACK_PENDING CALLBACK_SUCCESS FAILED REVERSED MANUAL_REVIEW ``` 展示状态单独维护： ```text NOT_DISPLAYED DISPLAYED ``` 禁止事项： - 禁止重新生成已生成的游戏结果。 - 禁止同一个 round_id 出现多个有效结果。 - 禁止同一个 client_request_id 创建多笔有效注单。 - 禁止玩家超时后直接退款，除非服务端确认未扣款或进入冲正规则。 ## 8. 玩家超时处理约束 玩家请求超时但服务端下注成功时，必须以服务端状态为准。 规则： ```text 不重新扣款 不重新开局 不重新生成结果 不直接退款 必须支持重试返回同一局结果 必须支持 latest-unconfirmed 查询 ``` 必须提供： ```text GET /game/round/latest-unconfirmed POST /game/round/confirm-displayed ``` 如果注单卡在中间状态： - `DEBIT_SUCCESS`：补偿 worker 继续生成结果或按规则冲正。 - `RESULT_GENERATED`：补偿 worker 继续派奖，不能重开结果。 - `CALLBACK_PENDING`：callback-service 继续异步重试。 ## 9. slots 返奖和采集数据约束 slots 返奖主路径必须使用本地内存配置计算，不能每局查询数据库。 采集数据处理流程： ```text 外部采集包/旧系统备份 -> game-data-importer -> game-data-validator -> game-data-normalizer -> MinIO 保存原始文件和标准化配置包 -> PostgreSQL 保存配置元数据 -> game-config-service 发布配置版本 -> 子游戏服务热加载到本地内存 ``` 当前阶段优先落地真实 `game-pg-mahjong`（PG Mahjong Ways），结果池参考旧系统 `slotsdata`，旧 `dat` 文件必须通过导入工具转换为新格式后再发布给子游戏服务。 必须支持的数据状态： ```text MISSING_DATA IMPORTED PARSED VALIDATED PUBLISHED DISABLED ``` 每个游戏上线前必须校验： ```text 是否有 init 配置 是否有 betconfig 是否有 slotsdata 是否有 reel_set 是否有 paytable 是否有 RTP 是否有币种配置 是否有最大赢配置 是否有 free spin 配置 是否有 bonus 配置 是否支持 buy free ``` 禁止事项： - 禁止把采集文件直接散落复制到生产容器里作为唯一发布方式。 - 禁止没有版本号的游戏配置上线。 - 禁止游戏服务每局 spin 时访问 MinIO 或 PostgreSQL 拉配置。 - 禁止修改已发布版本的配置内容，只能发布新版本。 ## 10. 数据库约束 所有数据库必须自建。 正式选型： ```text PostgreSQL：交易库、账本库、配置元数据 Redis：实时状态、幂等短缓存、排行榜热榜 Redpanda：顺序事件日志和异步事件总线 ClickHouse：数仓统计和大规模明细查询 MinIO：采集文件、配置文件、回放文件、归档文件 ``` PostgreSQL 禁止事项： - 禁止作为高并发订单的唯一第一写入点。 - 禁止后台大统计直接扫交易库。 - 禁止核心账本无分区、无索引、无备份策略。 - 禁止 ORM 随意生成不可控 SQL 查询核心大表。 ClickHouse 禁止事项： - 禁止作为交易强一致账本。 - 禁止用 ClickHouse 承担扣款、派奖事务。 Redis 禁止事项： - 禁止把 Redis 作为最终账本。 - 禁止 Redis 丢失后无法从 PostgreSQL/Redpanda 恢复。 ## 11. 消息队列和事件约束 Redpanda 是高并发订单入口后的核心顺序日志。 必须定义 topic： ```text order.ingested wallet.debit.requested wallet.debit.succeeded wallet.credit.requested wallet.credit.succeeded game.result.generated bet.settled merchant.callback.requested merchant.callback.succeeded merchant.callback.failed warehouse.bet.events warehouse.wallet.events ``` 事件必须包含： ```text event_id event_type trace_id merchant_id player_id round_id bet_order_id occurred_at payload schema_version ``` 禁止事项： - 禁止无 event_id。 - 禁止无 schema_version。 - 禁止消费者处理失败后静默丢弃消息。 - 禁止没有死信队列。 - 禁止没有重放能力。 ## 12. API 设计约束 商户 API 必须具备： - 签名。 - 时间戳。 - nonce。 - request_id。 - 幂等。 - IP 白名单。 - 限流。 - 错误码标准化。 禁止事项： - 禁止没有 request_id 的扣款/派奖接口。 - 禁止错误码直接返回内部异常。 - 禁止接口无超时时间。 - 禁止接口无压测指标。 - 禁止接口文档缺少示例请求和响应。 ## 13. 代码结构约束 每个服务必须使用 Clean Architecture / Hexagonal Architecture。 CloudWeGo Hertz 和 Kitex 的官方 GitHub 仓库是框架源码仓库，不是本项目业务目录模板。禁止把官方仓库中的 `cmd/hz`、`examples`、`internal`、`pkg` 等根目录照抄到本项目根目录后当成业务架构。 正确方式是：每个业务服务独立拥有自己的 `cmd/`、`api`、`internal`、`configs`、`migrations`、`deploy`、`README.md`，并在该服务 `go.mod` 中依赖 Hertz/Kitex。需要生成代码时，可以在该服务目录内使用 `hz` 或 `kitex` 工具生成，生成结果必须纳入该服务边界。 标准目录： ```text service-name/ ├── cmd/ │ └── service-name/ │ └── main.go ├── api/ │ ├── openapi/ │ └── thrift/ ├── configs/ │ ├── config.example.yaml │ └── config.local.yaml ├── internal/ │ ├── config/ │ ├── handler/ │ │ └── http/ │ ├── middleware/ │ ├── service/ │ ├── repository/ │ │ ├── postgres/ │ │ ├── redis/ │ │ └── kafka/ │ ├── domain/ │ ├── model/ │ └── bootstrap/ ├── migrations/ ├── deploy/ ├── test/ ├── Dockerfile ├── Makefile └── README.md ``` 依赖方向： ```text domain 不依赖 usecase domain 不依赖 adapter domain 不依赖 infrastructure usecase 可以依赖 domain adapter 可以依赖 usecase infrastructure 可以实现 usecase 定义的接口 ``` 禁止事项： - 禁止把 Hertz 官方源码仓库结构当作本项目业务根目录。 - 禁止多个服务共用一个根级 `internal` 写业务逻辑。 - 禁止没有 `api/openapi` 或 `api/thrift` 的长期对外/内部协议。 - 禁止数据库建表逻辑长期写在业务启动代码里，必须提供 `migrations`。 - 禁止业务逻辑写在 HTTP handler 里。 - 禁止 domain 层直接引用 Redis/PostgreSQL/Kafka。 - 禁止核心业务逻辑没有单元测试。 - 禁止一个文件超过合理职责范围后继续堆代码。 ## 14. 性能和压测约束 商户 API 主链路必须做压测。 必须关注： - QPS。 - P50/P95/P99 延迟。 - 错误率。 - 超时率。 - Redpanda 写入延迟。 - wallet-shard 处理积压。 - PostgreSQL 批量写入延迟。 - ClickHouse 写入延迟。 - callback 积压。 禁止事项： - 禁止只用功能测试判断接口可上线。 - 禁止没有压测报告上线商户主链路。 - 禁止没有限流策略上线。 - 禁止没有降级策略上线。 ## 15. K8s 部署约束 第一阶段单机 K3s，后续平滑扩展到多节点。 每个服务必须提供： ```text Deployment Service ConfigMap Secret HorizontalPodAutoscaler 预留 readinessProbe livenessProbe resources requests/limits ``` 禁止事项： - 禁止容器内写死 IP。 - 禁止配置写死在代码里。 - 禁止没有健康检查。 - 禁止没有优雅停机。 - 禁止没有资源限制。 ## 16. 观测性约束 每个服务必须接入： - Prometheus metrics。 - OpenTelemetry trace。 - 结构化日志。 - 统一错误码。 日志必须包含： ```text trace_id request_id merchant_id player_id round_id bet_order_id service_name method latency_ms error_code ``` 禁止事项： - 禁止打印明文密码、密钥、商户 secret。 - 禁止没有 trace_id 的核心日志。 - 禁止 panic 后无恢复和告警。 ## 17. AI 开发行为约束 AI 开发时必须遵守： - 先读本文档。 - 再读总架构文档。 - 再读 `旧项目与新架构目录对齐审计.md`。 - 再读 `Go服务实现成熟度约束.md`。 - 再读 `前端工程架构约束.md`。 - 再读对应服务中文文档。 - 不明确先问。 - 不允许自行更换框架。 - 不允许自行合并服务。 - 不允许照抄官方框架源码目录当业务项目目录。 - 不允许把只有 `main.go` 的 Go 服务当作正式实现。 - 不允许把健康检查占位服务说成能抗并发。 - 不允许把单个 `index.html` 原型当正式前端工程。 - 不允许绕过前端工程框架约束继续堆静态页面。 - 不允许绕过状态机。 - 不允许绕过账本。 - 不允许绕过事件队列。 - 不允许直接改核心库表结构，除非文档和迁移脚本同步更新。 - 不允许只写代码不写文档。 AI 每次实现服务时必须输出： ```text 1. 本次实现了哪个服务 2. 遵守了哪些架构约束 3. 新增了哪些 API 4. 新增了哪些数据库表 5. 新增了哪些 Redis key 6. 新增了哪些 Redpanda topic 7. 如何本地启动 8. 如何测试 9. 有哪些未完成项 ``` ## 18. 必须拒绝的错误实现 以下实现必须拒绝： ```text 用 Gin 快速写一个 merchant-api 用一个 Go 服务同时做钱包、注单、游戏、回调 下注接口同步逐单写 PostgreSQL 后返回 游戏服务直接 UPDATE 玩家余额 没有 ledger 的余额变化 没有 request_id 的扣款接口 没有 round_id 的游戏结果 玩家超时后直接重新开奖 结果生成后允许修改 result_json 后台统计直接查 PostgreSQL 大表 游戏配置没有版本管理 slots 每局从数据库读取 paytable/reel_set Redis 作为唯一账本 没有 Redpanda 事件日志 没有中文服务文档 ``` ## 19. 最终定稿 本项目架构正式定稿为： ```text CloudWeGo Hertz 对外承接高并发 HTTP CloudWeGo Kitex 承接内部高性能 RPC Redpanda 作为订单洪峰的顺序事件日志 wallet-shard-service 按玩家分片顺序处理钱包事件 ledger-service 保证不可变账本 PostgreSQL 承担强一致交易存储和批量落账 ClickHouse 承担后台统计和大规模查询 MinIO 承担采集文件和配置版本存储 Redis 承担实时状态和短期幂等 每个子游戏独立 Deployment slots 返奖主路径内存计算 所有服务必须有中文文档和可执行命令 ``` 任何开发、重构、AI 自动生成代码，都必须以本文档为最高约束之一。