# CLAUDE.md

本文件为 Claude Code（claude.ai/code）在本仓库中工作时提供指导。**它是入口与强制指引**：三套文档的「红线速查 / 一页纸总则」单页已通过 `@import` 常驻上下文（见下「文档」一节），**红线以它们为权威、始终在上下文里，本文件不再另抄一份**；规范的完整细节在 `docs/` 编号文档里，改动前先读对应文档。

## 这是一个什么仓库

一个友乐/gameabc 房卡类小游戏平台：浏览器端由私有的 `gameabc.min.js` 2D Canvas 引擎驱动，服务端是一个 Node.js 游戏服务器平台（`youle` 应用），双方通过 WebSocket/HTTP 收发 JSON 包通信。项目根目录**没有 `package.json`、没有 npm 构建/lint/测试流水线**——这是纯静态 JS：客户端靠 `<script>` 标签加载，服务端靠平台自带的 `min_loadJsFile`/`require` 加载。

本仓库是平台层 + 可复用框架的脚手架，尚未接入任何具体子游戏，未来第一个子游戏会在此基础上搭建。

本仓库是**模板项目**——后续会被克隆出去开新项目。因此所有需要长期保留的约定与知识**一律进仓库**（`docs/` 权威文档、本 CLAUDE.md、`.claude/` 钩子与 `settings.json`、`.githooks/`），**不依赖 Claude memory**（memory 按机器/会话存放、不随 `git clone` 迁移，对模板克隆无效）。

## 常用命令

没有配置任何构建/lint/测试工具。仓库里的脚本：

```bash
# 根据 client/assets/spine/*.json 重新生成 client/generated/spine_assets.js 与 spine_data.js
client/scripts/build_spine_data.cmd        # 内部调用 build_spine_data.ps1
```

```bash
# 把服务端共享算法同步到前端只读副本（改动一律落在服务端 shared/，改完跑一次）
sync_shared.cmd
```

`server/games/erqiwang/shared/` 是前后端共享算法的**唯一可修改处**；`client/js/01_SubGame/codes/shared/` 是它的只读副本，手改会被下次同步覆盖，且 `client/tests/test_shared_sync.js` 会因字节不一致而失败。

在 `client/assets/spine/` 增删 Spine 导出文件后运行；不要手改这两个生成文件。

查看客户端效果需用 HTTP 方式（而非 `file://`）打开 `client/index.html`，例如 `npx http-server client -p 8080`。

**启用提交前机械红线校验**（严格 ES5、可编辑范围等硬红线的 git 提交闸）——`.githooks/pre-commit` 已随仓库提交，但 `core.hooksPath` 是本地配置、不随克隆迁移，故**每个新克隆需一次性**执行：

```bash
git config core.hooksPath .githooks
```

（Claude Code 内 `.claude/` 的 PreToolUse 钩子会自动生效、无需此步；这一步只为让**提交闸**对所有工具/人手改也生效。测试脚本 `tests/`、`*.test.js`、`*.spec.js` 允许现代语法，不受严格 ES5 拦截；只有正式代码严格 ES5。）

`shared/`（共享算法，待子游戏接入后才有）的改动应按两套文档「§10 测试纪律」的要求跑 Node 单测验证——目前尚未接入测试框架，意味着需要直接用 `node` 运行相应脚本。

## 可编辑范围

> 架构骨架（前端分层 / 服务端运作模型 / 工程七大总则）、成败协议、子游戏接入两模式等，均在下方 `@import` 常驻的三份 README「一页纸」与对应编号文档里，本文件不复述。此处只留改动前最需在手边的一张表（完整规则见各 README「红线速查」）：

| 路径 | 规则 |
|---|---|
| `js/vendor/`、`js/00_Surface/`、`server/` 平台代码 | 禁止修改 |
| `01_SubGame/00_SubGame_Config.js` | 仅可改**已有** `Game_Config.*` 配置项的值——禁止新增/删除/改名/改结构 |
| `01_SubGame/01_SubGame_modify.js` | 仅可填顶部「配置区」（`Type_1/Type_2/CreateRoomData/combat/game_config/roomDes`）；转发壳部分不碰 |
| `01_SubGame/02_SubGame_Input.js` | 完全不碰 |
| `js/gameabc-framework/` | 可改，但须保持游戏中立（不含具体玩法常量/逻辑） |
| `01_SubGame/codes/`（除 `shared/`）、`server/<游戏容器目录>/<游戏>/` | 子游戏自由开发区 |
| `01_SubGame/codes/shared/` | 服务端 `shared/` 的只读同步副本；改服务端一侧后再同步 |

## 文档（改动前先读——这三套是权威源）

本仓库开发**必须严格遵守**以下三套文档；改哪块就先读对应 README 与编号文档，而不是从代码反推约定：

- `docs/client/development-guide/`（01→06）、`docs/server/development-guide/`（01→04）——项目专属的平台接入规范与红线。
- `docs/games/engineering/`（01→03）——位于两者之上、与平台无关的工程方法论（SSOT、单向依赖、职责单一、OCP、配置优先于硬编码、显式失败优于隐式兜底）。

三者互补不冲突：engineering 讲「该怎么设计、怎么长久演进」，dev-guide 讲「平台怎么接、红线是什么」；硬红线冲突时以 dev-guide 为准。

以下三份「红线速查 / 一页纸总则」通过 `@import` **自动加载进每次会话的上下文**——红线以它们为权威，无需在本文件另抄一份；改动具体区域时再深入读对应编号文档：

@docs/client/development-guide/红线速查.md
@docs/server/development-guide/红线速查.md
@docs/games/engineering/一页纸总则.md

各套文档的「编号 ↔ 主题」导航表、面向人的阅读顺序与定位说明留在各自 README（`docs/client/development-guide/README.md`、`docs/server/development-guide/README.md`、`docs/games/engineering/README.md`）——那些是查阅时才需要的内容，不常驻上下文，需要时直接读。

## 测试与 Git

- **测试纪律**：细则见 client 05 §10 / server 04 §10。要点——测试代码可用现代语法（只跑 Node，不上线）；**正式代码禁止为测试而加逻辑/放宽校验**，禁止为过测而改正式代码或降低测试标准（skip、软化断言、吞异常等）；失败先用证据裁定「业务缺陷 vs 脚本缺陷」；正面/反面/边界用例都要覆盖。
- **新增断言要反向验证**：写完一条守卫断言，**故意破坏它守的那处逻辑，确认它真会变红**——否则你加的可能是一条空转断言（「全绿但什么都没验」比红更有害）。
- ⚠️ **本仓库文件是 CRLF 行尾**：任何基于行尾的脚本化改写（`sed`/正则批量删改）必须按 `\r?\n` 处理。写 `\n` 会**一行都匹配不上却静默成功**——曾据此得出「测试抓不住缺陷」的错误结论。脚本改完先 `git diff --stat` 确认文件真的变了，再据其结果下判断。
- **Git 提交**（细则见 server 04 §11）：完成一个可独立成立的逻辑改动即可**自动提交、无需逐次确认**（`push` 按需）；提交信息用中文、聚焦一件事、结尾保留 `Co-Authored-By` 署名；不用 `git add -A`/`git add .`、不跳过 hooks、不做 `reset --hard`/`push --force`。