docs: bring en and zh to parity

- Translate add-new-group, local-development, requirements, telegram-integration-guide from zh into en
- Translate architecture and user-experience walkthrough from en into zh
- Mirror user-experience screenshots (page-1/2/3) into zh/user-experience
- All command snippets, JSON, and CDK examples preserved verbatim across locales

Author: AoyuQC

docs/en/add-new-group.md

@@ -0,0 +1,182 @@
+# How to Create a New Group Photo Wall
+
+This guide explains how to add an independent photo wall for a new Telegram group. Each group requires its own Bot.
+
+---
+
+## Prerequisites
+
+- The project has been deployed at least once (`./deploy.sh` or `npx cdk deploy`)
+- AWS CLI is installed and credentials are configured
+- You have a Telegram account
+
+---
+
+## Step 1: Create a New Telegram Bot
+
+1. Open Telegram and search for **@BotFather**
+2. Send `/newbot`
+3. Provide a Bot name (e.g. `Marketing Wall Bot`) and a username (e.g. `marketing_wall_bot`, must end in `bot`)
+4. Save the returned **Bot Token**
+5. Turn off Privacy Mode: BotFather → `/mybots` → select the Bot → Bot Settings → Group Privacy → **Turn off**
+
+---
+
+## Step 2: Store the Bot Token in Secrets Manager
+
+```bash
+aws secretsmanager create-secret \
+  --name "telegram/bot-token/marketing" \
+  --secret-string "YOUR_NEW_BOT_TOKEN" \
+  --region us-west-2
+```
+
+> The `marketing` suffix in `telegram/bot-token/marketing` is arbitrary; it just has to match the `secretName` you set in the next step.
+
+---
+
+## Step 3: Add the New Group to `cdk.json`
+
+Edit the project root `cdk.json` and append a new entry to the `telegramGroups` array:
+
+```json
+{
+  "context": {
+    "telegramGroups": [
+      {
+        "groupId": "demo-group",
+        "chatId": "-1001234567890",
+        "name": "Demo Photo Wall",
+        "secretName": "telegram/bot-token/demo-group",
+        "botUsername": "your_photo_wall_bot"
+      },
+      {
+        "groupId": "marketing",
+        "chatId": "-1009876543210",
+        "name": "Marketing Photo Wall",
+        "secretName": "telegram/bot-token/marketing",
+        "botUsername": "marketing_wall_bot"
+      }
+    ]
+  }
+}
+```
+
+### Field Reference
+
+| Field | Required | Description | Example |
+|-------|----------|-------------|---------|
+| `groupId` | Yes | URL identifier for the wall; letters, digits, underscore, hyphen only | `marketing` |
+| `chatId` | Yes | Telegram group Chat ID (negative integer); see the appendix for how to obtain it | `-1009876543210` |
+| `name` | Yes | Title shown on the photo wall page | `Marketing Photo Wall` |
+| `secretName` | Yes | Name in Secrets Manager that holds the Bot Token; must match Step 2 | `telegram/bot-token/marketing` |
+| `botUsername` | Yes | The Bot's `@username` (without `@`); only messages that `@mention` it are surfaced on the wall | `marketing_wall_bot` |
+
+---
+
+## Step 4: Deploy
+
+```bash
+cd photo-wall && npm run build && cd ..
+npx cdk deploy --require-approval never
+```
+
+After the deployment, the CDK output prints the new group's webhook URL:
+
+```
+TelegramPhotoWallStack.WebhookUrlmarketing = https://<YOUR_DOMAIN>/api/webhook/marketing
+```
+
+---
+
+## Step 5: Register the Telegram Webhook
+
+```bash
+# Fetch the webhook verification secret
+WEBHOOK_SECRET=$(aws secretsmanager get-secret-value \
+  --secret-id "telegram/webhook-secret" \
+  --query SecretString --output text \
+  --region us-west-2)
+
+# Fetch the new Bot Token
+NEW_BOT_TOKEN=$(aws secretsmanager get-secret-value \
+  --secret-id "telegram/bot-token/marketing" \
+  --query SecretString --output text \
+  --region us-west-2)
+
+# Register the webhook
+curl -X POST "https://api.telegram.org/bot${NEW_BOT_TOKEN}/setWebhook" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"url\": \"https://<YOUR_DOMAIN>/api/webhook/marketing\",
+    \"secret_token\": \"${WEBHOOK_SECRET}\",
+    \"allowed_updates\": [\"message\"]
+  }"
+```
+
+> Replace `https://<YOUR_DOMAIN>` with the actual CloudFront URL emitted by CDK.
+
+### Verify the Webhook
+
+```bash
+curl -s "https://api.telegram.org/bot${NEW_BOT_TOKEN}/getWebhookInfo" | python3 -m json.tool
+```
+
+---
+
+## Step 6: Add the Bot to the Group
+
+1. Open the target Telegram group
+2. Add member → search for `@marketing_wall_bot` → add
+3. Send a test message in the group: `@marketing_wall_bot hello`
+
+---
+
+## Step 7: Open the Photo Wall
+
+```
+https://<YOUR_DOMAIN>/wall/marketing
+```
+
+If multiple groups are configured, a group switcher appears at the top of the page.
+
+---
+
+## Appendix
+
+### Get the Telegram Group Chat ID
+
+**Method 1: Via the Bot API**
+
+1. Add the Bot to the group
+2. Send any message in the group
+3. Run:
+```bash
+curl -s "https://api.telegram.org/bot${NEW_BOT_TOKEN}/getUpdates" | python3 -m json.tool
+```
+4. Locate `message.chat.id` in the returned JSON (group Chat IDs are negative, e.g. `-1009876543210`)
+
+**Method 2: Via @userinfobot**
+
+1. Add `@userinfobot` to the group
+2. It will reply with the group's Chat ID
+3. Remove it once you have the value
+
+### Remove a Group
+
+1. Remove the entry from `telegramGroups` in `cdk.json`
+2. Redeploy: `npx cdk deploy`
+3. (Optional) Delete the Bot Token: `aws secretsmanager delete-secret --secret-id "telegram/bot-token/marketing" --region us-west-2`
+4. (Optional) Remove the webhook: `curl -X POST "https://api.telegram.org/bot${NEW_BOT_TOKEN}/deleteWebhook"`
+
+### Quick Reference
+
+| Step | Command / Action |
+|------|------------------|
+| 1. Create the Bot | BotFather `/newbot` + turn off Privacy Mode |
+| 2. Store the Token | `aws secretsmanager create-secret ...` |
+| 3. Update config | Edit `cdk.json`, append the new group |
+| 4. Deploy | `npx cdk deploy` |
+| 5. Register webhook | `curl ... setWebhook` |
+| 6. Add Bot to group | Add as a Telegram group member |
+| 7. Test | Send `@bot hello` in the group, open `/wall/groupId` |

docs/en/local-development.md

@@ -0,0 +1,163 @@
+# Local Development Guide
+
+## How It Works
+
+For local development, Next.js runs on your machine but **connects directly to the deployed AWS resources** (DynamoDB, S3, Secrets Manager). No local database is required.
+
+```
+Local Next.js (localhost:3000)
+   ├── read/write → AWS DynamoDB (the same table used in production)
+   ├── read/write → AWS S3 (the same bucket used in production)
+   └── read       → AWS Secrets Manager (Bot Token)
+
+Telegram → ngrok → localhost:3000   (only when debugging the webhook)
+```
+
+## Prerequisites
+
+- Node.js 20+
+- AWS CLI with configured credentials (`aws configure`) that can access the deployed resources
+- (Optional) [ngrok](https://ngrok.com/) — only needed when debugging the Telegram webhook
+
+## Quick Start
+
+### 1. Generate the Local Environment File
+
+```bash
+# Pull every resource ID from the deployed CDK stack
+./scripts/setup-local-env.sh
+```
+
+The script writes `photo-wall/.env.local`, which looks like:
+
+```env
+AWS_REGION_NAME=us-west-2
+TABLE_NAME=TelegramPhotoWallStack-MessagesTable05B58A27-xxxxx
+BUCKET_NAME=telegramphotowallstack-photobucket465738b3-xxxxx
+WEBHOOK_SECRET_ARN=arn:aws:secretsmanager:us-west-2:xxxxx:secret:telegram/webhook-secret-xxxxx
+GROUP_CONFIG=[{"groupId":"demo-group","chatId":"-1001234567890","name":"Demo Photo Wall","secretName":"telegram/bot-token/demo-group"}]
+```
+
+> If you have not deployed the stack yet, run `./deploy.sh` first.
+
+### 2. Start the Dev Server
+
+```bash
+cd photo-wall
+npm install   # only on first run or when dependencies change
+npm run dev
+```
+
+Open http://localhost:3000/wall/demo-group to view the photo wall.
+
+**Hot reload**: edits to frontend components (TSX/CSS) refresh the browser automatically; edits to API routes apply on the next request.
+
+### 3. Debug the Telegram Webhook (optional)
+
+If you need to debug incoming Telegram messages locally, expose your local port to the internet with ngrok:
+
+```bash
+# Terminal 1: start ngrok
+ngrok http 3000
+
+# Note the public URL it prints, e.g. https://abcd1234.ngrok-free.app
+```
+
+```bash
+# Terminal 2: point the Telegram webhook at your ngrok URL
+./scripts/set-webhook-local.sh https://abcd1234.ngrok-free.app
+```
+
+Telegram messages in the group will now flow to your local Next.js server.
+
+**When you're done, restore the production webhook:**
+
+```bash
+./scripts/set-webhook-prod.sh
+```
+
+## Common Workflows
+
+### Frontend-only Changes (Styles / Interactions)
+
+Edit files under `photo-wall/src/components/` or `photo-wall/src/app/`. The browser hot-reloads. ngrok is not required, and existing messages load via the API as usual.
+
+### API Changes (Message Queries)
+
+Edit files under `photo-wall/src/app/api/messages/` and refresh the page to test. Data is read from the deployed DynamoDB table.
+
+### Webhook Changes (Inbound Messages)
+
+This requires ngrok plus switching the webhook to your local URL. You can also simulate Telegram requests with curl:
+
+```bash
+# Fetch the webhook secret
+WEBHOOK_SECRET=$(aws secretsmanager get-secret-value \
+  --secret-id "telegram/webhook-secret" \
+  --query SecretString --output text --region us-west-2)
+
+# Simulate a text message
+curl -X POST http://localhost:3000/api/webhook/demo-group \
+  -H "Content-Type: application/json" \
+  -H "X-Telegram-Bot-Api-Secret-Token: $WEBHOOK_SECRET" \
+  -d '{
+    "update_id": 12345,
+    "message": {
+      "message_id": 999,
+      "from": {"id": 123, "first_name": "Test"},
+      "chat": {"id": -1001234567890},
+      "date": 1700000000,
+      "text": "Hello from local dev"
+    }
+  }'
+
+# Simulate a photo message (file_id is fake; download will fail but the row is persisted)
+curl -X POST http://localhost:3000/api/webhook/demo-group \
+  -H "Content-Type: application/json" \
+  -H "X-Telegram-Bot-Api-Secret-Token: $WEBHOOK_SECRET" \
+  -d '{
+    "update_id": 12346,
+    "message": {
+      "message_id": 1000,
+      "from": {"id": 123, "first_name": "Test"},
+      "chat": {"id": -1001234567890},
+      "date": 1700000001,
+      "photo": [
+        {"file_id": "fake_small", "file_unique_id": "u1", "width": 90, "height": 90},
+        {"file_id": "fake_large", "file_unique_id": "u2", "width": 800, "height": 600}
+      ],
+      "caption": "Test photo"
+    }
+  }'
+```
+
+### CDK Infrastructure Changes
+
+```bash
+# Preview the diff
+npx cdk diff
+
+# Apply the change
+npx cdk deploy
+
+# Refresh the local env file if any resource names changed
+./scripts/setup-local-env.sh
+```
+
+## Project Layout
+
+```
+telegram-photo-wall/
+├── photo-wall/                     ← Next.js application (where local dev happens)
+│   ├── src/app/api/                ← API routes (webhook, messages, health)
+│   ├── src/components/             ← React components (photo wall UI)
+│   ├── src/lib/                    ← Utilities (AWS clients, config, sanitization)
+│   ├── .env.local                  ← Local env file (gitignored)
+│   └── package.json
+├── lib/                            ← CDK infrastructure definitions
+├── scripts/
+│   ├── setup-local-env.sh          ← Generate .env.local
+│   ├── set-webhook-local.sh        ← Webhook → ngrok (local debugging)
+│   └── set-webhook-prod.sh         ← Webhook → CloudFront (restore production)
+└── cdk.json                        ← Group configuration
+```