feat: add configurable verification and redemption codes

docs/api.md

@@ -576,8 +576,9 @@ Authorization: Bearer <token>
     "used_units": 120,
     "included_units": 10000,
     "bonus_units": 500,
-    "total_units": 10500,
-    "remaining_units": 10380
+    "redeemed_units": 200,
+    "total_units": 10700,
+    "remaining_units": 10580
   }
 }
 ```
@@ -612,6 +613,23 @@ GET /billing/invoices?page=1&limit=20
 Authorization: Bearer <token>
 ```
 
+### 9.7 兑换套餐卡或次数卡
+```http
+POST /redemptions/redeem
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "code": "IMG-XXXX-XXXX-XXXX-XXXX" }
+```
+
+### 9.8 获取自己的兑换记录
+```http
+GET /redemptions
+Authorization: Bearer <token>
+```
+
+次数卡额度拥有独立有效期，扣减时优先使用更早到期的可用额度。套餐卡不会覆盖仍然有效的 Stripe 订阅。
+
 ---
 
 ## 10. Webhooks（支付回调）
@@ -713,6 +731,42 @@ Authorization: Bearer <admin_token>
 
 凭据加密保存且不通过 API 回传。测试接口执行 Bucket 检查、内部临时对象读写删和公网预签名下载；激活接口会再次测试并原子切换活动端点。活动端点不能直接编辑或删除。
 
+### 11.7 兑换码管理
+
+```http
+GET /admin/redemption-codes?page=1&limit=50
+Authorization: Bearer <admin_token>
+```
+
+```http
+POST /admin/redemption-codes
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+
+{
+  "benefit_kind": "units",
+  "units": 100,
+  "duration_days": 30,
+  "quantity": 10,
+  "redeem_before": "2026-12-31T15:59:59Z",
+  "note": "活动批次"
+}
+```
+
+套餐卡使用 `benefit_kind: "plan"` 并传入 `plan_id`。完整兑换码只在创建响应中返回一次，数据库只保存 HMAC 哈希和脱敏标识。
+
+```http
+PUT /admin/redemption-codes/{code_id}
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+
+{ "is_active": false }
+```
+
+### 11.8 邮箱验证开关
+
+`GET /admin/auth` 和 `PUT /admin/auth` 的配置体包含 `email_verification_required`。该配置独立于 SMTP，修改后立即生效，不需要重启服务。
+
 ---
 
 ## 12. WebSocket（网站任务进度）

docs/database.md

@@ -594,7 +594,8 @@ VALUES
 ### 7.2 默认系统配置
 ```sql
 INSERT INTO system_config (key, value, description) VALUES
-('features', '{"registration_enabled": true, "api_key_enabled": true, "anonymous_upload_enabled": true, "email_verification_required": true}', '功能开关'),
+('features', '{"registration_enabled": true, "api_key_enabled": true, "anonymous_upload_enabled": true}', '功能开关'),
+('auth', '{"email_verification_required": true}', '认证功能开关'),
 ('rate_limits', '{"anonymous_per_minute": 10, "anonymous_units_per_day": 10, "user_per_minute": 60, "api_key_per_minute": 100}', '速率限制默认值'),
 ('file_limits', '{"max_image_pixels": 40000000}', '图片安全限制（像素上限等）'),
 ('mail', '{"enabled": true, "provider": "custom", "from": "noreply@example.com", "from_name": "ImageForge"}', '邮件服务配置（密码加密存储）');

docs/deployment.md

@@ -37,6 +37,8 @@ docker compose \
 
 API 健康后 Worker 才会启动，避免两个进程在首次部署时同时执行迁移。
 
+管理员可用邮箱或用户名登录。首次启动时设置 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 即可创建管理员；若未设置 `ADMIN_EMAIL`，系统会生成仅用于满足内部数据约束的 `用户名@local.invalid` 占位邮箱。确认账号创建后应从生产环境文件中移除 `ADMIN_PASSWORD`，避免每次重启都重置密码。
+
 ```bash
 docker compose --env-file .env.production -f docker/docker-compose.prod.yml ps
 curl --fail http://127.0.0.1:8080/health