Nexus/docs/changelog/2026-06-09-service-valueerror-zh.md

2026-06-09 — 服务层 ValueError 中文化（str(exc) 透传源头）

摘要

将经 API detail=str(exc) 透传、且原先为英文的 ValueError 文案改为中文，避免 sync/scripts/批量/调度等接口在未走全局 http_errors_zh 映射时仍显示英文。

动机

待办 #1（API detail 英改中）方案 1：优先改下层异常源头，比统一包装 raise_api_error 改动小、语义稳定。

涉及文件

文件	变更
server/application/services/script_service.py	Execution not found → 执行记录不存在
server/application/services/server_batch_service.py	Unknown batch op → 未知的批量操作
server/infrastructure/database/crypto.py	Failed to decrypt credential → 凭据解密失败
server/infrastructure/ssh/asyncssh_pool.py	SSH 凭据缺失提示中文化
server/utils/schedule_cycle.py	自定义 cron / 字段数 / 周期类型校验中文化
server/api/schemas.py	batch_id 校验中文化
server/infrastructure/redis/script_execution_store.py	执行记录不存在提示中文化

迁移 / 重启

• 无需 DB 迁移
• 需重启 API 进程后生效

验证

pytest tests/test_schedule_cycle.py tests/test_http_errors_zh.py -q
bash scripts/local_verify.sh

手动：脚本重试不存在 execution、批量未知 op、调度非法 cycle、推送 batch_id 非法 → 422/400 detail 为中文。

未覆盖（后续）

• f"SSH 连接失败: {e}" 等库异常后缀（方案 2：translate_sync_error_message 包装）
• API 层字面量 detail="Server not found"（已由 http_errors_zh 全局处理，待部署）