📋 项目现状评估 — Claude Code Review (2026-03-03)

[wwbluechip]

nbAPI 项目分析 — 未完成事项总览

一、未实现的功能（Stub/Placeholder）

文件	问题	说明
backend/internal/service/account_service.go:378-392	API 凭证测试未实现	Anthropic/OpenAI/Gemini 三个平台的凭证测试全部 return nil，未做实际验证
backend/internal/service/admin_service.go:1667	RefreshAccountCredentials 未实现	直接返回账号，无刷新逻辑
backend/internal/service/proxy_service.go:172-184	TestConnection 代理连接测试未实现	函数体为空，只 return nil
backend/internal/service/redeem_service.go:455-468	GetStats 兑换码统计未实现	返回全零硬编码值，未查询数据库
backend/internal/handler/admin/group_handler.go:301	分组统计未实现	_ = groupID // TODO: implement actual stats，返回硬编码零值

二、被跳过的测试（18 个）

• Sora 相关：17 个测试被 t.Skip 跳过，原因是"待流程稳定后恢复"
  • 6 个 processGeneration 集成测试
  • 11 个上游模型同步/缓存测试
• 并发缓存：1 个测试 TestGetAccountsLoadBatch 因 CI 中返回值不符预期被跳过

三、被回滚的功能

• Provision API（58745625）：/api/v1/provision 端点已被 revert，包括 go.mod 路径修复、路由升级和测试。原因未明，待恢复。

四、未纳入版本控制的内容

• website/ 目录：包含一个单独的 index.html（36KB 静态落地页），未被 git 追踪。可能是未完成的官网项目或构建产物。

五、文档不足

• 缺少 OpenAPI/Swagger 规范文件，网关和管理端点无系统性 API 文档
• 仅有 ADMIN_PAYMENT_INTEGRATION_API.md 和 dependency-security.md 两份文档
• 近期重要修复（Migration 061、OAuth 401 处理、分组隔离）缺乏文档记录

六、总结优先级建议

优先级	事项	影响
高	实现 API 凭证测试（3 个平台）	用户添加账号时无法验证凭证有效性
高	实现代理连接测试	配置代理后无法确认是否可用
高	恢复或重做 Provision API	设备配置功能不可用
中	实现兑换码/分组统计	管理后台显示错误数据
中	修复并恢复 18 个跳过的测试	测试覆盖率缺口
中	处理 website/ 目录	决定保留/完善或 .gitignore
低	实现 RefreshAccountCredentials	凭证过期时需要手动处理
低	补充 API 文档 / OpenAPI spec	影响第三方集成

[wwbluechip]

🔧 API 凭证测试实现方案

背景

AccountService.TestCredentials() 方法（account_service.go:378-392）是一个轻量级的凭证验证方法，返回 error。与 AccountTestService（account_test_service.go 的 SSE 流式测试）不同，这个方法用于快速验证凭证有效性，不需要流式响应。

实现方案

三个平台的验证策略：

平台	方法	端点	说明
Anthropic	POST	/v1/messages	最小 payload（haiku, max_tokens=1），支持 API Key (x-api-key) 和 OAuth (Bearer)
OpenAI	GET	/v1/models	轻量只读端点，支持 API Key 和 OAuth
Gemini API Key	GET	/v1beta/models?key=<key>&pageSize=1	列出模型验证 key
Gemini OAuth	POST	/v1beta/models/gemini-2.0-flash:generateContent	最小 payload (maxOutputTokens=1)

设计要点：

• 5s 超时控制（context.WithTimeout + http.Client.Timeout 双保险）
• 只判断 401/403 为凭证无效，429/500 等视为凭证有效（服务端问题不算凭证问题）
• 支持 base_url 自定义端点（上游透传场景）
• 使用独立 http.Client（不依赖 HTTPUpstream，不改变 AccountService 构造函数签名）
• 错误信息友好，包含 HTTP 状态码和截断的响应体

测试覆盖（18 个测试用例）：

• 每个平台：有效凭证、无效凭证（401）、禁止访问（403）、缺少凭证
• Anthropic：429 限流仍视为有效、OAuth 模式
• OpenAI：OAuth 模式
• Gemini：OAuth 过期（401）
• 不支持的平台
• truncateString 工具函数

实现中...

[wwbluechip]

✅ 实现完成

PR

• PR refactor(backend): 添加 service 缓存端口 #8: feat: implement API credential tests for Anthropic/OpenAI/Gemini
  • https://github.com/ai-yl/nbapi/pull/8

变更文件

• backend/internal/service/account_service.go — 实现 TestCredentials() 方法（+235 行）
• backend/internal/service/account_service_credential_test.go — 18 个单元测试（新文件）

Codex Review

• Codex (gpt-5.3-codex) 做了静态分析
• 审查了请求构造、错误处理、类型匹配、安全性
• 注意到 base_url 未经 validateUpstreamBaseURL 验证，但 AccountService 设计上不持有 config 对象，且 base_url 由管理员配置，SSRF 风险可接受
• 无 blocking issues

⚠️ 已知限制

• 单元测试因 go.mod 模块路径不匹配（sub2api vs nbapi rebrand 📋 nbAPI 未完成事项（品牌重塑 + 部署 + 官网）— Claude Code Review (2026-03-03) #740）无法本地运行
• Go 语法通过 gofmt -e 验证
• rebrand 问题修复后测试即可运行