docs: add CLAUDE.md and project documentation

Add CLAUDE.md for AI assistant context. Create four new docs: deployment-guide.md (full deploy flow + secret rotation + rollback), code-standards.md (formatting, naming, module conventions, testing), codebase-summary.md (tech stack, modules, data flows, external APIs), development-roadmap.md (completed phases + planned work).
2026-04-17 13:21:31 +00:00 · 2026-04-14 15:28:53 +07:00
parent 0f0dc1c108
commit 4277f11c48
5 changed files with 405 additions and 0 deletions
--- a/docs/deployment-guide.md
+++ b/docs/deployment-guide.md
@@ -0,0 +1,123 @@
+# Deployment Guide
+
+## Prerequisites
+
+- Node.js ≥ 20.6
+- Cloudflare account with Workers + KV enabled
+- Telegram bot token from [@BotFather](https://t.me/BotFather)
+- `wrangler` CLI authenticated: `npx wrangler login`
+
+## Environment Setup
+
+### 1. Cloudflare KV Namespaces
+
+```bash
+npx wrangler kv namespace create miti99bot-kv
+npx wrangler kv namespace create miti99bot-kv --preview
+```
+
+Paste returned IDs into `wrangler.toml`:
+
+```toml
+[[kv_namespaces]]
+binding = "KV"
+id = "<production-id>"
+preview_id = "<preview-id>"
+```
+
+### 2. Worker Secrets
+
+```bash
+npx wrangler secret put TELEGRAM_BOT_TOKEN
+npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
+```
+
+`TELEGRAM_WEBHOOK_SECRET` — any high-entropy string (e.g. `openssl rand -hex 32`). grammY validates it on every webhook update via `X-Telegram-Bot-Api-Secret-Token`.
+
+### 3. Local Dev Config
+
+```bash
+cp .dev.vars.example .dev.vars    # for wrangler dev
+cp .env.deploy.example .env.deploy # for register script
+```
+
+Both are gitignored. Fill in matching token + secret values.
+
+`.env.deploy` also needs:
+- `WORKER_URL` — the `*.workers.dev` URL (known after first deploy)
+- `MODULES` — comma-separated, must match `wrangler.toml` `[vars].MODULES`
+
+## Deploy
+
+### First Time
+
+```bash
+npx wrangler deploy                # learn the *.workers.dev URL
+# paste URL into .env.deploy as WORKER_URL
+npm run register:dry               # preview payloads
+npm run deploy                     # deploy + register webhook + commands
+```
+
+### Subsequent Deploys
+
+```bash
+npm run deploy
+```
+
+This runs `wrangler deploy` then `scripts/register.js` (setWebhook + setMyCommands).
+
+### What the Register Script Does
+
+`scripts/register.js` imports the same registry the Worker uses, builds it with a stub KV to derive public commands, then calls two Telegram APIs:
+
+1. `setWebhook` — points Telegram at `WORKER_URL/webhook` with the secret token
+2. `setMyCommands` — pushes public command list to Telegram's `/` menu
+
+### Dry Run
+
+```bash
+npm run register:dry
+```
+
+Prints both payloads (webhook secret redacted) without calling Telegram.
+
+## Secret Rotation
+
+1. Generate new secret: `openssl rand -hex 32`
+2. Update Cloudflare: `npx wrangler secret put TELEGRAM_WEBHOOK_SECRET`
+3. Update `.env.deploy` with same value
+4. Redeploy: `npm run deploy` (register step re-calls setWebhook with new secret)
+
+Both values MUST match — mismatch causes 401 on every webhook.
+
+## Adding/Removing Modules
+
+When changing the active module list:
+
+1. Update `MODULES` in `wrangler.toml` `[vars]`
+2. Update `MODULES` in `.env.deploy`
+3. If adding: ensure module exists in `src/modules/index.js` import map
+4. `npm run deploy`
+
+Removing a module from `MODULES` makes it inert — its KV data remains but nothing loads it.
+
+## Rollback
+
+Cloudflare Workers supports instant rollback via the dashboard or:
+
+```bash
+npx wrangler rollback
+```
+
+To disable a specific module without rollback, remove its name from `MODULES` and redeploy.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 401 on all webhooks | Secret mismatch between CF secret and `.env.deploy` | Re-set both to same value, redeploy |
+| Bot doesn't respond to commands | `MODULES` missing the module name | Add to both `wrangler.toml` and `.env.deploy` |
+| `command conflict` at deploy | Two modules register same command name | Rename one command |
+| `missing env: X` from register | `.env.deploy` incomplete | Add missing variable |
+| `--env-file` not recognized | Node < 20.6 | Upgrade Node |
+| `/help` missing a module | Module has no public or protected commands | Add at least one non-private command |