docs: audit and deploy verification for API detail zh rollout

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-09 08:54:27 +08:00
parent 1c0d7e9eb6
commit 64c8bd74b8
2 changed files with 67 additions and 0 deletions
@@ -0,0 +1,46 @@
+# 审计 — 服务层 ValueError 中文化 + HTTP detail 翻译层部署
+
+**Changelog**: `docs/changelog/2026-06-09-service-valueerror-zh.md` · `docs/changelog/2026-06-09-http-api-detail-zh.md`
+
+## 变更文件清单（本次 commit）
+
+| 文件 | 说明 |
+|------|------|
+| `server/api/schemas.py` | batch_id 校验文案中文化 |
+| `server/application/services/script_service.py` | 执行记录不存在 |
+| `server/application/services/server_batch_service.py` | 未知批量 op |
+| `server/infrastructure/database/crypto.py` | 凭据解密失败 |
+| `server/infrastructure/redis/script_execution_store.py` | Redis 执行记录不存在 |
+| `server/infrastructure/ssh/asyncssh_pool.py` | SSH 凭据缺失 |
+| `server/utils/schedule_cycle.py` | cron / 周期类型校验 |
+
+## 一并部署（已在 main，非本 commit diff）
+
+| 文件 | 说明 |
+|------|------|
+| `server/utils/http_errors_zh.py` | 管理端 HTTP detail 翻译层（A） |
+| `server/main.py` | 全局 exception handler |
+| `server/api/auth.py` | auth_failure_detail |
+
+## Step 3 规则扫描
+
+| 规则 | 结论 |
+|------|------|
+| 安全 | PASS — 仅改用户可见文案，无鉴权变更 |
+| 行为 | PASS — 异常类型与 HTTP 状态码不变 |
+| Agent API | PASS — `/api/agent/*` 仍跳过翻译 |
+
+## Closure
+
+| 项 | 结果 |
+|----|------|
+| `test_schedule_cycle.py` | passed |
+| `test_http_errors_zh.py` | passed |
+| `test_validation_errors_zh.py` | passed |
+
+## DoD
+
+- [x] changelog
+- [x] 定向审计
+- [ ] 生产 deploy + 健康检查
+- [ ] 浏览器 spot-check 404 detail 中文
@@ -0,0 +1,21 @@
+# HTTP API detail 中文化 — 生产部署验证（2026-06-09）
+
+## 部署范围
+
+- `3ba78cd` — `http_errors_zh` 全局层（方案 A：字面量 detail 翻译）
+- `a842af2` — auth reason / fallback 中文
+- `1c0d7e9` — 服务层 ValueError 源头中文（方案 1）
+
+## 验证项
+
+| # | 检查 | 命令/操作 | 期望 | 结果 |
+|---|------|-----------|------|------|
+| 1 | 健康检查 | `curl https://api.synaglobal.vip/health` | `ok` | |
+| 2 | 404 字面量翻译 | 无 token 访问不存在 server id | `服务器不存在` | |
+| 3 | 422 Pydantic | 非法 batch_id | 中文字段错误 | |
+| 4 | str(exc) | 脚本重试不存在 execution | `执行记录不存在` | |
+
+## 备注
+
+- `/api/agent/*` 仍返回英文（设计如此）
+- `f"SSH 连接失败: {e}"` 后缀未做方案 B