## [ERR-20260429-006] /qr-token 等接口报 SHARED_CHECKIN_SECRET_MISSING

**日期**: 2026-04-29
**类别**: 配置缺失 / setup-worktree.sh 第 5 条手工尾巴

### 现象
新建 worktree、跑完 setup → 启动服务 → 登录 → 打开签到点详情页（accessMode=SIGNED 或共享签到）：
```
GET /api/v1/site-attendance/checkpoints/code/<code>/qr-token → 500
Error Code: INTERNAL_SERVER_ERROR  Message: SHARED_CHECKIN_SECRET_MISSING
```

### 根因
`backend/src/modules/site-attendance/utils/shared-checkin.util.ts:25` 的 `getSecretOrThrow()` 检查 `process.env.SHARED_CHECKIN_SECRET`，缺失则抛错。

而项目里：
1. `.env.example` **本来就没列** `SHARED_CHECKIN_SECRET` —— 这是 v1.5 共享签到才加的 env，加 feature 时漏更新了 example
2. `scripts/dev/setup-worktree.sh` 仅复制 `.env`、改端口、改 db 名，不生成 / 不补齐 v1.5 必需的 env
3. 主 `.env` 也是从 `.env.example` 起家、然后人手维护，多数开发者根本不知道有这个 key

→ 任何全新 worktree（除非源 `.env` 早就被人手动加过）都会踩。

### 修复
本次 PR 同时改三处：
1. `setup-worktree.sh` 在 `configure_isolated_env` 末尾自动 ensure：缺则生成 `openssl rand -hex 32`，存在则保留
2. `setup_caddy_domain` 把 `SHARED_CHECKIN_ALLOWED_HOSTS` 改为 `<domain>,localhost`
3. `.env.example` 补两个 key 占位 + 注释说明

### 普适规律
**新 feature 引入 env → 必须同步加到 `.env.example` 并加注释说明缺失症状。** 这是个跨模块的纪律，不只 site-attendance。建议把"feature 加 env → .env.example 同步"加到 PR checklist。

### Metadata
- Reproducible: yes（v1.5 之后任何全新 worktree）
- Related Files: backend/src/modules/site-attendance/utils/shared-checkin.util.ts:25, .env.example, scripts/dev/setup-worktree.sh:configure_isolated_env

---