Add complimentary OOBE polish and configurable admin mTLS

Allow one server-audited onboarding polish request without credits and make the certificate gate temporarily reversible while preserving application authentication.

docs/DEPLOYMENT.md

@@ -132,10 +132,16 @@ docker compose logs --since=10m account-server
 2. 将三个 `server` 块作为站点配置；按 1Panel 实际证书路径调整 `ssl_certificate`。
 3. 示例 upstream 指向宿主机 `127.0.0.1:18080`。若 OpenResty 自身在容器中，则将其加入
    `account-backend`，并改为 `account-server:8080`。
-4. 配置明确对 `/admin`、`/internal`、`/v1/admin` 返回 404；不要新增绕过该规则的泛域名代理。
+4. `/internal` 始终返回 404；`/admin` 和 `/v1/admin` 是否要求客户端证书由
+   `ADMIN_MTLS_REQUIRED` 控制，默认值为 `true`。
 5. API 示例按 IP 限制 20 请求/秒，邀请页限制 5 请求/秒，可基于真实流量谨慎调整。
 6. 代理统一支持 HTTP/1.1 Upgrade/Connection，因此当前 HTTP API 与后续 WebSocket 入口都可用。
 
+临时关闭管理端 mTLS 时，在 1Panel/Compose 环境中显式设置
+`ADMIN_MTLS_REQUIRED=false` 并重启 `account-server`。此时管理端仍要求用户名、密码和 TOTP，
+且保留登录限流、失败锁定、同源校验、CSRF、会话 Cookie 与审计。恢复时将该值改回 `true`；
+不要删除客户端 CA、证书或轮换记录。
+
 两个 AASA 地址由 Ktor 根据 `appleAppId` 模板输出，不需要复制静态文件。配置检查成功后再通过
 1Panel 重载 OpenResty：
 

docs/mysql-minimum-privileges.sql

@@ -29,6 +29,7 @@ GRANT SELECT ON osg_account.usage_records TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_grants TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_grant_scopes TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.gateway_complimentary_requests TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.devicecheck_trial_claims TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.app_attest_challenges TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.app_attest_keys TO 'osg_account_runtime'@'10.20.%';
@@ -60,6 +61,8 @@ GRANT INSERT ON osg_account.usage_records TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.gateway_grants TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT ON osg_account.gateway_grant_scopes TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT, UPDATE, DELETE ON osg_account.gateway_complimentary_requests
+    TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.devicecheck_trial_claims TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.app_attest_challenges TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.app_attest_keys TO 'osg_account_runtime'@'10.20.%';

docs/openapi.yaml

@@ -410,6 +410,9 @@ paths:
         and output-budget policy from `capability` plus optional `taskKind`. It
         never infers task type from `input` or `context`, and clients cannot
         supply provider parameters. Search and tools are currently disabled.
+        An authenticated `oobe` purpose is accepted only for dictation polish.
+        The first successful request per account is complimentary; later attempts
+        fail without falling through to paid billing.
       parameters:
         - $ref: "#/components/parameters/RequestId"
         - name: capability
@@ -529,7 +532,7 @@ paths:
           content:
             application/json:
               schema: { $ref: "#/components/schemas/AdminSessionState" }
-        "404": { description: Verified administrator client certificate is absent }
+        "404": { description: Verified administrator client certificate is absent while mTLS is required }
   /v1/admin/auth/login:
     post:
       security:
@@ -887,7 +890,7 @@ components:
       bearerFormat: JWT
     adminMtls:
       type: mutualTLS
-      description: Client certificate issued by the dedicated administrator CA.
+      description: Client certificate issued by the dedicated administrator CA; required when ADMIN_MTLS_REQUIRED is true.
     adminSession:
       type: apiKey
       in: cookie
@@ -1714,6 +1717,12 @@ components:
           type: ["string", "null"]
           enum: [hotword, null]
           description: Optional product entry point; hotword is accepted only for AI requests
+        requestPurpose:
+          type: ["string", "null"]
+          enum: [oobe, null]
+          description: |
+            Optional server-audited billing purpose. `oobe` is valid only with
+            `polish` and `dictation_polish`, and is complimentary once per account.
     CreateGatewayGrantRequest:
       type: object
       additionalProperties: false