| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 1 | 5 | 14% |
| Commands | 0 | 0 | 4 | 0% |
| Section tags | 1 | 0 | 2 | 33% |
What each file covers
Sections
1 shared · 1 only in A · 5 only in B- − Go项目开发规则
- + GreatestWorks 项目 AI 协作说明（必读）
- + 代码组织与分层约定（DDD）
- + 协议与兼容性（Proto/TCP）
- + 变更落地清单（AI 执行时务必遵循）
- + 不要做（DON’Ts）
- 禁止使用的命令
Commands
0 shared · 0 only in A · 4 only in B- + go.mod
- + docker-compose.yml
- + go mod tidy
- + go test ./...
Section tags
1 shared · 0 only in A · 2 only in B- + test
- + git-pr
- lint-format
Line diff
phuhao00/greatestworks · .cursor/rules/p.mdc
@@ −1 @@
1---
2description: Go项目开发规则 - 遵循Go最佳实践，不使用checkout和reset命令
3globs: ["**/*.go", "**/go.mod", "**/go.sum", "**/*.yaml", "**/*.yml"]
4alwaysApply: true
5---
6
7# Go项目开发规则
8
9## 代码规范
10- 遵循Go官方代码规范
11- 使用gofmt格式化代码
12- 变量命名使用驼峰命名法
13- 常量使用大写字母和下划线
14- 包名使用小写字母，简短有意义
15
16## 错误处理
17- 始终检查错误返回值
18- 使用errors.New()或fmt.Errorf()创建错误
19- 避免使用panic，除非是程序启动时的致命错误
20- 使用defer进行资源清理
21
22## 并发编程
23- 使用goroutine处理并发任务
24- 使用channel进行goroutine间通信
25- 避免共享内存，使用通信来共享内存
26- 使用sync包进行同步控制
27
28## 性能优化
29- 避免不必要的内存分配
30- 使用对象池复用对象
31- 合理使用缓存
32- 避免在循环中进行重复计算
33
34
35## 项目结构
36- 遵循标准Go项目布局
37- 按功能模块组织代码
38- 使用internal包限制内部代码访问
39- 合理使用接口和依赖注入
40
41## 禁止使用的命令
42- 不使用git checkout命令
43- 不使用git reset命令
44- 使用git switch切换分支
45- 使用git restore恢复文件
46
phuhao00/greatestworks · .github/instructions/gw.instructions.md
@@ +1 @@
1---
2applyTo: '**'
3---
4# GreatestWorks 项目 AI 协作说明（必读）
5
6本文件为 AI 与协作者在本仓库中进行代码生成、变更评审与文档撰写时的统一约束与上下文指引。请严格遵循以下规范，确保改动与项目架构、风格和运行形态保持一致。
7
8## 工作流程补充要求
9
10每次开始编写新功能或进行较大改动时，需先列出本次开发的 todo list（任务清单），明确拆分为具体、可执行的小步骤，并在开发过程中逐项完成和勾选。todo list 应包含：
11
12- 主要功能点拆解（如领域模型、应用服务、接口适配、配置变更等）
13- 相关协议/配置/文档同步
14- 单元测试与集成验证
15- 变更影响面评估与回滚方案
16
17todo list 可在 PR 描述、评论或协作工具中展示，便于团队成员跟进进度与评审。
18
19## 项目上下文速览
20
21- 语言与版本：Go 1.24（见 `go.mod`）
22- 架构风格：DDD（领域驱动）+ 分层架构 + 微服务
23- 服务与入口：
24 - 认证服务：`cmd/auth-service/main.go`（HTTP: 8080）
25 - 网关服务：`cmd/gateway-service/main.go`（TCP: 9090）
26 - 游戏服务：`cmd/game-service/main.go`（Go 原生 RPC: 8081）
27 - 其他服务：`cmd/scene/main.go`、`cmd/replication/main.go`（保留/扩展）
28- 配置位置：`configs/*.yaml`（支持 dev/prod/docker 等环境示例）
29- 数据存储：MongoDB（主存储）+ Redis（缓存）
30- 协议与通信：
31 - 客户端 → 认证：HTTP
32 - 客户端 → 网关：TCP（自定义二进制协议，参考 `internal/network` 与 `proto/`）
33 - 网关 ↔ 游戏：Go 原生 RPC
34- 协议定义：根目录 `proto/*.proto`（以及 `internal/proto/*` 目录结构），存在独立 proto 模块替换：`replace github.com/phuhao00/greatestworks-proto => ../greatestworks-proto`
35- 压测/集成测试工具：`tools/simclient`（支持 E2E/压测/功能验证场景）
36- 容器与脚本：`Dockerfile`、`docker-compose.yml`、`scripts/*`、`Makefile`
37
38## 代码组织与分层约定（DDD）
39
40- 领域层：`internal/domain/*`
41 - 聚合根/实体/值对象仅暴露必要行为，字段使用小写私有化，保持不变式。
42 - 领域服务仅聚焦业务规则，不做基础设施细节。
43 - 领域事件放在 `internal/domain/events`。
44- 应用层：`internal/application/*`
45 - 命令/查询处理器与应用服务；通过 `services.ServiceRegistry` 进行装配。
46 - 面向用例编排，不直接依赖具体基础设施实现，依赖接口。
47- 基础设施层：`internal/infrastructure/*`
48 - 持久化、缓存、消息、日志、配置、网络等适配与实现。
49 - 仓储实现放于 `infrastructure/persistence/*`，接口在领域层定义。
50- 接口层：`internal/interfaces/{http,tcp,rpc}/*`
51 - 将传输协议与应用层解耦；在此完成 DTO/协议消息 ↔ 领域模型映射。
52
53新增功能时遵循“自内向外”原则：先领域模型与用例，再接口适配与基础设施实现，最后编排到入口服务。
54
55## 依赖与模块策略
56
57- 优先使用标准库与现有依赖，不轻易新增第三方库；如需新增必须：
58 1) 说明动机与替代方案；2) 版本固定并最小化；3) 兼容 Go 1.24。
59- 修改依赖后执行 `go mod tidy` 保持清洁；不要引入需要 CGO 的库（跨平台/容器化负担）。
60- 保留并尊重 `go.mod` 中的 `replace github.com/phuhao00/greatestworks-proto`，该仓库用于统一管理协议代码；不要在本仓库内随意复制粘贴生成代码覆盖。
61
62## 协议与兼容性（Proto/TCP）
63
64- 修改 `.proto` 前务必确认兼容性策略：
65 - 仅追加字段，避免复用/更改现有 tag；删除请改为 `reserved`。
66 - 变更需同步网关与游戏服务的处理逻辑，保持向后兼容。
67- 生成代码：优先使用 `scripts/generate_proto.bat`（Windows）或 `scripts/generate_proto.sh`（Unix）；不要手工在 `internal/proto` 下散落生成物。
68- TCP 二进制协议格式固定（见 README）；非兼容性变更需评审并更新 `internal/network` 与模拟客户端映射。
69
70## 配置管理
71
72- 所有服务读取 `configs/*.yaml`，经 `internal/config` 管理加载；禁止硬编码端口/密钥/连接串。
73- 支持环境变量覆盖（在文档/示例配置中体现）；新增配置项需：
74 - 更新对应 `configs/*.yaml` 示例；
75 - 更新读取/校验逻辑与默认值；
76 - 在 README 或服务说明中记录。
77
78## 日志与监控
79
80- 使用 `internal/infrastructure/logging` 提供的 `Logger`，禁止使用 `fmt.Println`。
81- 日志规范：结构化（json），带关键字段：`service`, `module`, `player_id`, `trace_id`（如可用）。
82- 级别：`debug`（开发调试）、`info`（业务里程碑）、`warn`（可恢复异常）、`error`（失败/降级）、`fatal`（进程退出）。
83- 性能剖析：通过配置开启 pprof（参考 README 的 monitoring.profiling）；仅在可信网络或受控环境开放。
84
85## 错误处理
86
87- 领域错误集中于 `internal/errors`（如 `domain_errors.go`）；服务/接口层使用 `errors.Is/As` 判断语义。
88- Wrap 原始错误保留栈上下文：`fmt.Errorf("…: %w", err)`。
89- HTTP 映射：领域校验错误 → 400，权限问题 → 401/403，找不到 → 404，服务内部错误 → 500。
90- TCP/RPC：映射到协议内的错误码或错误消息，保持一致性并记录日志。
91
92## 并发与资源管理
93
94- 所有跨边界函数均传递 `context.Context`，尊重取消与超时；网络/数据库调用设置合理超时。
95- 禁止无限制 goroutine 派生；使用工作池（见 `infrastructure/messaging/worker_pool.go`）或事件驱动（`internal/events`）。
96- 连接/句柄必须在 `defer` 中关闭；大对象复用需证明收益且不影响可读性。
97
98## 测试与验证
99
100- 单元测试：同包 `_test.go`，采用表驱动，覆盖核心分支；提交前保证 `go test ./...` 通过。
101- 集成/E2E：使用 `tools/simclient`；支持 smoke/feature/load 模式：
102 - smoke：在服务运行下进行冒烟；可通过环境变量控制跳过。
103 - feature：按功能库驱动场景（参考 `tools/simclient/feature_library.go`）。
104 - load：并发用户压测，输出 P50/P95/Max 时延统计。
105- 新增协议或接口时，应提供最小可运行的集成验证脚本/说明。
106
107## 代码风格与提交
108
109- 风格：`gofmt`/`goimports` 必须；命名符合 Go 惯例（接口以 `er` 结尾、包名简短小写）。
110- 变更最小化：倾向小步提交，避免无关重构；保留公开 API 稳定性。
111- 提交信息（建议使用 Conventional Commits）：
112 - feat: 新功能；fix: 修复；refactor: 重构；docs: 文档；test: 测试；chore: 其它；build/ci: 构建与流水线。
113- PR 要求：
114 - 说明动机、设计要点、影响面（协议/配置/数据/性能）；
115 - 附上验证方式（单测/模拟客户端步骤）；
116 - 涉及配置或脚本的，更新对应示例与 README 片段。
117
118## 变更落地清单（AI 执行时务必遵循）
119
1201) 读取相关代码与文档，明确所处层与依赖关系；
1212) 若涉及协议/配置/公共接口，先出兼容性策略与影响面；
1223) 优先修改领域/应用层契约，再补充基础设施与接口适配；
1234) 如需新依赖，给出选择理由与安全性评估，版本固定；
1245) 同步更新：示例配置、脚本、文档与模拟客户端用例；
1256) 保持改动最小并可回滚；
1267) 本地自检：静态检查 + 单测通过（若仓库上下文缺依赖导致无法编译，请在说明中标注并提供可替代验证方式）。
127
128## 不要做（DON’Ts）
129
130- 不要绕过 `internal/infrastructure/logging` 打印日志。
131- 不要在接口层直接操作数据库或 Redis；通过应用/领域契约间接访问。
132- 不要破坏 `.proto` 的兼容性（更改已有 tag、复用 tag、删除非 reserved）。
133- 不要硬编码端口、密钥、连接字符串。
134- 不要引入重量级依赖或需要本地原生编译的库（除非有充分理由与替代方案评审）。
135
136## 附：常用位置速查
137
138- 入口：`cmd/*/main.go`
139- 配置：`configs/*.yaml`
140- 领域：`internal/domain/*`
141- 应用：`internal/application/*`（`services/service_registry.go` 装配）
142- 基础设施：`internal/infrastructure/*`
143- 接口适配：`internal/interfaces/{http,tcp,rpc}`
144- 协议：`proto/*.proto`（生成脚本见 `scripts/generate_proto.*`）
145- 网络协议实现：`internal/network/*`
146- 模拟客户端：`tools/simclient/*`
147
148如对以上规范与上下文有疑问，请在 PR 描述中明确提出并给出权衡与建议方案，以便评审达成一致。
@@ −1 +1 @@
11 ---
2−description: Go项目开发规则 - 遵循Go最佳实践，不使用checkout和reset命令
3−globs: ["**/*.go", "**/go.mod", "**/go.sum", "**/*.yaml", "**/*.yml"]
4−alwaysApply: true
2+applyTo: '**'
53 ---
4+# GreatestWorks 项目 AI 协作说明（必读）
65
7−# Go项目开发规则
6+本文件为 AI 与协作者在本仓库中进行代码生成、变更评审与文档撰写时的统一约束与上下文指引。请严格遵循以下规范，确保改动与项目架构、风格和运行形态保持一致。
87
9−## 代码规范
10−- 遵循Go官方代码规范
11−- 使用gofmt格式化代码
12−- 变量命名使用驼峰命名法
13−- 常量使用大写字母和下划线
14−- 包名使用小写字母，简短有意义
8+## 工作流程补充要求
159
10+每次开始编写新功能或进行较大改动时，需先列出本次开发的 todo list（任务清单），明确拆分为具体、可执行的小步骤，并在开发过程中逐项完成和勾选。todo list 应包含：
11+
12+- 主要功能点拆解（如领域模型、应用服务、接口适配、配置变更等）
13+- 相关协议/配置/文档同步
14+- 单元测试与集成验证
15+- 变更影响面评估与回滚方案
16+
17+todo list 可在 PR 描述、评论或协作工具中展示，便于团队成员跟进进度与评审。
18+
19+## 项目上下文速览
20+
21+- 语言与版本：Go 1.24（见 `go.mod`）
22+- 架构风格：DDD（领域驱动）+ 分层架构 + 微服务
23+- 服务与入口：
24+ - 认证服务：`cmd/auth-service/main.go`（HTTP: 8080）
25+ - 网关服务：`cmd/gateway-service/main.go`（TCP: 9090）
26+ - 游戏服务：`cmd/game-service/main.go`（Go 原生 RPC: 8081）
27+ - 其他服务：`cmd/scene/main.go`、`cmd/replication/main.go`（保留/扩展）
28+- 配置位置：`configs/*.yaml`（支持 dev/prod/docker 等环境示例）
29+- 数据存储：MongoDB（主存储）+ Redis（缓存）
30+- 协议与通信：
31+ - 客户端 → 认证：HTTP
32+ - 客户端 → 网关：TCP（自定义二进制协议，参考 `internal/network` 与 `proto/`）
33+ - 网关 ↔ 游戏：Go 原生 RPC
34+- 协议定义：根目录 `proto/*.proto`（以及 `internal/proto/*` 目录结构），存在独立 proto 模块替换：`replace github.com/phuhao00/greatestworks-proto => ../greatestworks-proto`
35+- 压测/集成测试工具：`tools/simclient`（支持 E2E/压测/功能验证场景）
36+- 容器与脚本：`Dockerfile`、`docker-compose.yml`、`scripts/*`、`Makefile`
37+
38+## 代码组织与分层约定（DDD）
39+
40+- 领域层：`internal/domain/*`
41+ - 聚合根/实体/值对象仅暴露必要行为，字段使用小写私有化，保持不变式。
42+ - 领域服务仅聚焦业务规则，不做基础设施细节。
43+ - 领域事件放在 `internal/domain/events`。
44+- 应用层：`internal/application/*`
45+ - 命令/查询处理器与应用服务；通过 `services.ServiceRegistry` 进行装配。
46+ - 面向用例编排，不直接依赖具体基础设施实现，依赖接口。
47+- 基础设施层：`internal/infrastructure/*`
48+ - 持久化、缓存、消息、日志、配置、网络等适配与实现。
49+ - 仓储实现放于 `infrastructure/persistence/*`，接口在领域层定义。
50+- 接口层：`internal/interfaces/{http,tcp,rpc}/*`
51+ - 将传输协议与应用层解耦；在此完成 DTO/协议消息 ↔ 领域模型映射。
52+
53+新增功能时遵循“自内向外”原则：先领域模型与用例，再接口适配与基础设施实现，最后编排到入口服务。
54+
55+## 依赖与模块策略
56+
57+- 优先使用标准库与现有依赖，不轻易新增第三方库；如需新增必须：
58+ 1) 说明动机与替代方案；2) 版本固定并最小化；3) 兼容 Go 1.24。
59+- 修改依赖后执行 `go mod tidy` 保持清洁；不要引入需要 CGO 的库（跨平台/容器化负担）。
60+- 保留并尊重 `go.mod` 中的 `replace github.com/phuhao00/greatestworks-proto`，该仓库用于统一管理协议代码；不要在本仓库内随意复制粘贴生成代码覆盖。
61+
62+## 协议与兼容性（Proto/TCP）
63+
64+- 修改 `.proto` 前务必确认兼容性策略：
65+ - 仅追加字段，避免复用/更改现有 tag；删除请改为 `reserved`。
66+ - 变更需同步网关与游戏服务的处理逻辑，保持向后兼容。
67+- 生成代码：优先使用 `scripts/generate_proto.bat`（Windows）或 `scripts/generate_proto.sh`（Unix）；不要手工在 `internal/proto` 下散落生成物。
68+- TCP 二进制协议格式固定（见 README）；非兼容性变更需评审并更新 `internal/network` 与模拟客户端映射。
69+
70+## 配置管理
71+
72+- 所有服务读取 `configs/*.yaml`，经 `internal/config` 管理加载；禁止硬编码端口/密钥/连接串。
73+- 支持环境变量覆盖（在文档/示例配置中体现）；新增配置项需：
74+ - 更新对应 `configs/*.yaml` 示例；
75+ - 更新读取/校验逻辑与默认值；
76+ - 在 README 或服务说明中记录。
77+
78+## 日志与监控
79+
80+- 使用 `internal/infrastructure/logging` 提供的 `Logger`，禁止使用 `fmt.Println`。
81+- 日志规范：结构化（json），带关键字段：`service`, `module`, `player_id`, `trace_id`（如可用）。
82+- 级别：`debug`（开发调试）、`info`（业务里程碑）、`warn`（可恢复异常）、`error`（失败/降级）、`fatal`（进程退出）。
83+- 性能剖析：通过配置开启 pprof（参考 README 的 monitoring.profiling）；仅在可信网络或受控环境开放。
84+
1685 ## 错误处理
17−- 始终检查错误返回值
18−- 使用errors.New()或fmt.Errorf()创建错误
19−- 避免使用panic，除非是程序启动时的致命错误
20−- 使用defer进行资源清理
2186
22−## 并发编程
23−- 使用goroutine处理并发任务
24−- 使用channel进行goroutine间通信
25−- 避免共享内存，使用通信来共享内存
26−- 使用sync包进行同步控制
87+- 领域错误集中于 `internal/errors`（如 `domain_errors.go`）；服务/接口层使用 `errors.Is/As` 判断语义。
88+- Wrap 原始错误保留栈上下文：`fmt.Errorf("…: %w", err)`。
89+- HTTP 映射：领域校验错误 → 400，权限问题 → 401/403，找不到 → 404，服务内部错误 → 500。
90+- TCP/RPC：映射到协议内的错误码或错误消息，保持一致性并记录日志。
2791
28−## 性能优化
29−- 避免不必要的内存分配
30−- 使用对象池复用对象
31−- 合理使用缓存
32−- 避免在循环中进行重复计算
92+## 并发与资源管理
3393
94+- 所有跨边界函数均传递 `context.Context`，尊重取消与超时；网络/数据库调用设置合理超时。
95+- 禁止无限制 goroutine 派生；使用工作池（见 `infrastructure/messaging/worker_pool.go`）或事件驱动（`internal/events`）。
96+- 连接/句柄必须在 `defer` 中关闭；大对象复用需证明收益且不影响可读性。
3497
35−## 项目结构
36−- 遵循标准Go项目布局
37−- 按功能模块组织代码
38−- 使用internal包限制内部代码访问
39−- 合理使用接口和依赖注入
98+## 测试与验证
4099
41−## 禁止使用的命令
42−- 不使用git checkout命令
43−- 不使用git reset命令
44−- 使用git switch切换分支
45−- 使用git restore恢复文件
100+- 单元测试：同包 `_test.go`，采用表驱动，覆盖核心分支；提交前保证 `go test ./...` 通过。
101+- 集成/E2E：使用 `tools/simclient`；支持 smoke/feature/load 模式：
102+ - smoke：在服务运行下进行冒烟；可通过环境变量控制跳过。
103+ - feature：按功能库驱动场景（参考 `tools/simclient/feature_library.go`）。
104+ - load：并发用户压测，输出 P50/P95/Max 时延统计。
105+- 新增协议或接口时，应提供最小可运行的集成验证脚本/说明。
46106
107+## 代码风格与提交
108+
109+- 风格：`gofmt`/`goimports` 必须；命名符合 Go 惯例（接口以 `er` 结尾、包名简短小写）。
110+- 变更最小化：倾向小步提交，避免无关重构；保留公开 API 稳定性。
111+- 提交信息（建议使用 Conventional Commits）：
112+ - feat: 新功能；fix: 修复；refactor: 重构；docs: 文档；test: 测试；chore: 其它；build/ci: 构建与流水线。
113+- PR 要求：
114+ - 说明动机、设计要点、影响面（协议/配置/数据/性能）；
115+ - 附上验证方式（单测/模拟客户端步骤）；
116+ - 涉及配置或脚本的，更新对应示例与 README 片段。
117+
118+## 变更落地清单（AI 执行时务必遵循）
119+
120+1) 读取相关代码与文档，明确所处层与依赖关系；
121+2) 若涉及协议/配置/公共接口，先出兼容性策略与影响面；
122+3) 优先修改领域/应用层契约，再补充基础设施与接口适配；
123+4) 如需新依赖，给出选择理由与安全性评估，版本固定；
124+5) 同步更新：示例配置、脚本、文档与模拟客户端用例；
125+6) 保持改动最小并可回滚；
126+7) 本地自检：静态检查 + 单测通过（若仓库上下文缺依赖导致无法编译，请在说明中标注并提供可替代验证方式）。
127+
128+## 不要做（DON’Ts）
129+
130+- 不要绕过 `internal/infrastructure/logging` 打印日志。
131+- 不要在接口层直接操作数据库或 Redis；通过应用/领域契约间接访问。
132+- 不要破坏 `.proto` 的兼容性（更改已有 tag、复用 tag、删除非 reserved）。
133+- 不要硬编码端口、密钥、连接字符串。
134+- 不要引入重量级依赖或需要本地原生编译的库（除非有充分理由与替代方案评审）。
135+
136+## 附：常用位置速查
137+
138+- 入口：`cmd/*/main.go`
139+- 配置：`configs/*.yaml`
140+- 领域：`internal/domain/*`
141+- 应用：`internal/application/*`（`services/service_registry.go` 装配）
142+- 基础设施：`internal/infrastructure/*`
143+- 接口适配：`internal/interfaces/{http,tcp,rpc}`
144+- 协议：`proto/*.proto`（生成脚本见 `scripts/generate_proto.*`）
145+- 网络协议实现：`internal/network/*`
146+- 模拟客户端：`tools/simclient/*`
147+
148+如对以上规范与上下文有疑问，请在 PR 描述中明确提出并给出权衡与建议方案，以便评审达成一致。
