# CLAUDE.md

本文件为 Claude Code（claude.ai/code）在本仓库中工作时提供指导。**它只是入口与红线缓存，不复述规范细节**——权威、完整的规范在 `docs/` 三套文档里（见下「文档」一节），改动前先读对应文档。

## 这是一个什么仓库

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

`client/js/01_SubGame/codes/` 和 `server/games` 目前都是**空的**——尚未接入任何具体子游戏。本仓库是平台层 + 可复用框架的脚手架，未来第一个子游戏会在此基础上搭建。

## 常用命令

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

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

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

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

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

## 架构速览

> 完整的分层、模块清单与数据流以各 README 及编号文档为权威（client 01 / server 01）；此处只留改动前必须在上下文里的骨架。

- **两套代码库、一份协议**：`client/`（浏览器，严格 ES5，gameabc 引擎）与 `server/`（Node.js，严格 ES5，youle 平台）通过 `{ app: "youle", route, rpc, data }` JSON 包通信——`route`→模块、`rpc`→方法（`mod[pack.rpc](pack)`，一操作一 RPC，无二次 `switch(action)`）。**服务端只靠主动推送**（`o_room.method.sendpack_toseat/toother`）告知结果，`DoPack` 返回值不是下发通道。
- **客户端依赖严格单向**：`01_SubGame/codes` → `gameabc-framework` → `gameabc.min.js`；`index.html` 的加载顺序就是依赖图，新增文件须插在依赖之后、使用者之前（无模块系统，否则拿到 `undefined`）。框架必须**游戏中立**，禁止渗入任何具体玩法逻辑/常量。
- **服务端三层路由** app→mod→method；每房间状态挂 `o_room.o_desk.data.*`（`export.makewar` 内创建，双向引用 `o_room.o_desk ⇄ o_desk.o_room`），按房间隔离。子游戏只在 `server/<游戏容器目录>/<游戏>/` 内开发。
- **子游戏接入二选一、不混用**：内联模式（逻辑写进三个契约文件）或 Hooks 外置模式（三契约文件退化为转发壳，逻辑放 `codes/SubGameHooks.js` + `codes/`，模板见 `gameabc-framework/templates/subgame-entry/`）。详见 client 06。

**可编辑范围**（完整规则见各 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/` 的只读同步副本；改服务端一侧后再同步 |

## 红线摘要

> always-on 缓存，**权威与完整清单见各 README 红线速查（client 05 / server 04）与 games/engineering 一页纸总则**；每条都对应过真实事故，冲突时一律以文档为准。

- **严格 ES5**：`var`/`function`、继承用 `Object.create`；禁 `let/const`/箭头函数/模板字符串/`class`/解构/`Promise`。服务端 `require` 只能写在文件开头 `if (typeof require !== 'undefined') { ... }` 守卫块内，禁止函数体内中途 `require`。
- **成败只认推送包 `data.success`**（布尔值，主动推送的 `data` 必须自带）——绝不用 `status`/`code`，不写两者都判的兼容兜底。
- **权威数据缺失要显式报错**：影响发牌/庄家/手牌/计分/重连的权威数据禁止 `|| 0`/`|| []`/`|| ''` 兜底掩盖；默认值仅允许用于纯展示/日志字段。
- **房间隔离**：对局状态挂 `o_room.o_desk.data.*`，缓存/定时器/决策表以 `房间 + seat` 为 key（非仅 `seat`）；禁止模块级单例/全局变量存对局态，小局结束/解散/开新局时清理干净。
- **一个职能只在一个模块实现**：需要某能力时调用其所属模块，而不是在别处重造一份。
- **自动操作复用真人链路**：服务端代玩家执行的操作（AI 托管、超时等）必须走与真人完全相同的 handler → 广播链路，客户端不为其单开解析分支。

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

本仓库开发**必须遵守**以下三套文档；改哪块就先读对应 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 为准。

各编号对应主题（改哪块查哪篇）：

| 文档 | 编号与主题 |
|---|---|
| `client/development-guide/` | 01 前端架构与运行环境 · 02 渲染与UI组件体系 · 03 事件·动画·音频·Spine · 04 网络对接与启动编排 · 05 开发规范与红线 · 06 子游戏接入模式与Hooks外置 |
| `server/development-guide/` | 01 服务端环境与框架基础 · 02 子游戏接入与开发流程 · 03 数据收发与通信协议 · 04 开发规范与红线 |
| `games/engineering/` | 01 架构总则与分层 · 02 可扩展性与配置化 · 03 数据权威·错误处理·演进 |

## 测试与 Git

- **测试纪律**：细则见 client 05 §10 / server 04 §10。要点——测试代码可用现代语法（只跑 Node，不上线）；**正式代码禁止为测试而加逻辑/放宽校验**，禁止为过测而改正式代码或降低测试标准（skip、软化断言、吞异常等）；失败先用证据裁定「业务缺陷 vs 脚本缺陷」；正面/反面/边界用例都要覆盖。
- **Git 提交**（细则见 server 04 §11）：完成一个可独立成立的逻辑改动即可**自动提交、无需逐次确认**（`push` 按需）；提交信息用中文、聚焦一件事、结尾保留 `Co-Authored-By` 署名；不用 `git add -A`/`git add .`、不跳过 hooks、不做 `reset --hard`/`push --force`。