🛠️ Level-up the project setup: .env.example, backups, /health, docs (inspired by SnapMonster)

[longmaolab]

Suggested labels: enhancement, documentation

TL;DR (English)

The game itself is the hard part, and you nailed it. 🎮 This issue is a menu of "grown-up project" habits that make a codebase easier to run, deploy, and not lose data — inspired by a sibling project (SnapMonster / 拍拍怪兽) that does all of these.

Pick ONE and do it whenever — there's no rush and no order. Each is small on its own. Don't let the length scare you; it's a checklist for future you, not a to-do for this weekend.

• (1) .env.example — a committed, commented template of your env vars (the real .env stays gitignored).
• (2) Back up users.json — one tiny scheduled copy + rotate, so a bad redeploy or oops-delete doesn't wipe everyone's account.
• (3) A /health endpoint + a deploy smoke-check — so "is the new version actually live?" is one command, not a guess.
• (4) A docs/ folder + a production runbook in CLAUDE.md — write down the URL, port, service, and deploy steps once.
• (5) An .agent/ task log — todo.md / test.md to track work and root-cause bugs.

---

中文详细说明

先夸一句:最难的部分(把整个游戏做出来)你已经搞定了。🎮 这个 issue 是一份**"正经项目"的工程习惯菜单** —— 让代码更好运行、好部署、不丢数据。灵感来自你的一个兄弟项目 SnapMonster(拍拍怪兽),它这几样都做了。

挑一个,什么时候有空什么时候做,没有顺序、不急。 每一条单独看都很小。别被长度吓到 —— 这是给"未来的你"准备的清单,不是这周末的任务。

(1) .env.example —— 环境变量的"说明书"

你的 server.js 现在用到 8 个环境变量(我数过了):
DATA_DIR、PORT、ADMIN_MASTER_PASS、GROQ_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、CHAT_AI_MODEL、CHAT_AI_BASE_URL。

做法: 建一个 .env.example(提交进仓库),每个变量写一句注释说明用途 + 不填会怎样;真正的 .env 加进 .gitignore(里面是真 key,永远别提交)。

# .env.example —— 复制成 .env 再填真实值
DATA_DIR=/data            # users.json 存哪;Railway 上要指到持久卷,否则每次重新部署账号清空
PORT=3001                 # 不填默认 3001
ADMIN_MASTER_PASS=        # 管理员主密码;不填则后门关闭
GROQ_API_KEY=             # 角色 AI 聊天(免费,推荐);不填聊天会显示离线
# OPENAI_API_KEY= / ANTHROPIC_API_KEY= / CHAT_AI_MODEL= / CHAT_AI_BASE_URL=  # 可选备选

好处:换台机器 / 别人帮你跑,照着 .env.example 填就行,不用翻代码猜要哪些 key。

(2) 给 users.json 做备份

现在所有账号都在一个文件 users.json 里。CLAUDE.md 已经记了那个坑:Railway 不挂持久卷的话,一重新部署账号就没了。哪怕挂了卷,一次误删/写坏也会全没。

做法(最小版): 一个每天跑一次的小脚本,把 users.json 复制一份带日期的副本,只保留最近 14 份。SnapMonster 的 ops/backup-db.sh 就是这个思路(它还做了完整性校验 + 异地上传,你可以先从"复制+轮转"起步)。

(3) /health 端点 + 部署后冒烟检查

server.js 现在没有 /health 路由。CLAUDE.md 的 gotcha #6 记着血泪史:"好几个 bug 其实是 Railway 在跑旧版本"。

做法:

app.get('/health', (req, res) => res.json({ ok: true, players: Object.keys(players).length }));

然后部署完敲一句 curl https://<你的域名>/health —— 能返回就说明新版本真上线了。比肉眼猜强多了。SnapMonster 的 deploy.sh 最后一步就是 curl /health。

(4) docs/ 文件夹 + CLAUDE.md 里的生产环境表

做法: 建个 docs/,先放两份最"承重"的:

• docs/architecture.md —— 一句话讲清:一个 server 进程、matchId 隔离、客户端权威命中、bot 在 host 端模拟。
• docs/balance.md —— 武器数值表的说明(你很在意平衡!),并在 CLAUDE.md 写一条"改数值前先读 balance.md"。

再在 CLAUDE.md 加一张生产环境表:公网 URL、Railway 服务名、端口、需要哪些 env 变量、部署命令。这样运维知识就不只存在你脑子里了。

(5) .agent/ 任务日志(三件套)

SnapMonster 用 .agent/todo.md(P0–P3 优先级)、.agent/test.md(贴手测报告 → 找根因 → 写"已修复 + 文件 + commit")。这套很轻,但能逼自己"先溯源再说修好了"—— 正好治"一拍脑袋就说修好了结果没修对"的毛病。

---

🔗 相关 / Related: 这份菜单和 #7(单一数据源 shared/tables.js)、#6(加测试)是同一个"工程升级"主题的不同侧面。全做完,这个项目就从"能跑的游戏"变成"专业级项目"了。但记住 —— 一次一小步,挑顺手的先来。你已经做到了最难的 95%,这些只是锦上添花。加油!🛠️