opencatd-open/BACKEND_REFACTOR_PLAN.md

opencatd-open 后端重构计划

参考项目：/home/ubuntu/Code/git/openteam 创建时间：2026-08-30 当前分支：team 状态：执行中

---

一、决策记录

#	决策项	结论	确认时间
1	旧系统处理	完全移除（opencat.go、store/、team/、pkg/team/、pkg/store/）	2026-08-30
2	数据迁移	从旧表迁移（保留用户数据，apikeys → channels）	2026-08-30
3	认证统一	统一到新系统（API Key SHA-256 hash 查表）	2026-08-30
4	Redis 依赖	内存起步（后续可升级）	2026-08-30
5	llm/ 目录	全部删除（纯代理模式，不需要 LLM 客户端库）	2026-08-30
6	cobra CLI	保留（支持 reset_admin 等子命令）	2026-08-30

---

二、目标目录结构

opencatd-open/
├── cmd/openteam/main.go           # 唯一入口（cobra CLI + embed）
├── internal/
│   ├── config/config.go           # Viper + env（OT_ 前缀）
│   ├── auth/auth.go               # JWT access/refresh + argon2id
│   ├── cli/                       # Cobra CLI（root/serve/reset_admin）
│   ├── store/
│   │   ├── models.go              # 全部 GORM 模型
│   │   ├── db.go                  # DB init + AutoMigrate
│   │   └── db_postgres.go         # Postgres dialector
│   ├── dao/                       # 数据访问层
│   ├── channel/
│   │   ├── channel.go             # 候选选择、LB、并发信号量
│   │   └── health.go              # 健康检查
│   ├── proxy/
│   │   ├── gateway.go             # 网关核心
│   │   ├── handlers.go            # 协议分派
│   │   ├── passthrough.go         # HTTP 代理 + 记账
│   │   └── convert/               # 三协议互转
│   ├── api/                       # 管理 API
│   ├── usage/recorder.go          # 异步记账
│   ├── dto/                       # 数据传输对象
│   └── pkg/                       # 工具包
├── frontend/                      # Vue 3 SPA
├── deploy/docker/                 # Docker 部署
├── wire/                          # 依赖注入
└── go.mod

---

三、删除清单

文件/目录

删除项	原因
opencat.go	旧入口
store/	旧数据层
team/	旧 handler
pkg/team/	旧 service
pkg/store/	DB 初始化（合并到 internal/store）
pkg/error/	合并到 pkg/resp
pkg/search/	不需要
internal/model/	合并到 internal/store/models.go
internal/service/team/	合并到 internal/service
internal/dto/team/	合并到 internal/dto
internal/controller/team/	合并到 internal/api
internal/consts/	合并到 internal/store/models.go
llm/	整个删除
dist/	旧构建产物
assets/	旧静态资源
router/router.go	旧路由
router/chat.go	旧 chat 路由
middleware/auth_team.go	旧认证

Go 依赖（移除）

移除依赖	原因
sashabaranov/go-openai	LLM 客户端
liushuangls/go-anthropic/v2	LLM 客户端
google/generative-ai-go	LLM 客户端
google.golang.org/genai	LLM 客户端
cloud.google.com/go/vertexai	LLM 客户端
gorilla/websocket	WebSocket
coder/websocket	WebSocket
faiface/beep	音频
gopkg.in/vansante/go-ffprobe.v2	音频
patrickmn/go-cache	用 gcache 替代
Sakurasan/to	指针工具
duke-git/lancet/v2	大杂烩
go-ozzo/ozzo-validation/v4	验证
mileusna/useragent	UA 解析
golang.org/x/exp	实验性包
google.golang.org/api	Google API
golang.org/x/oauth2	OAuth2

---

四、执行阶段

Phase 0：清理旧代码 + 目录重组

• 状态：✅ 完成
• 内容：删除旧文件、重构 models.go、更新 go.mod、更新 wire
• 验收：go build ./cmd/openteam 通过

Phase 1：渠道服务 + 加密

• 状态：✅ 完成
• 内容：crypto（AES-GCM）、channel（候选/LB/健康检查）
• 验收：单元测试通过

Phase 2：协议转换系统

• 状态：✅ 完成
• 内容：convert 包（6 种转换 + 流式 SSE）
• 验收：全部转换路径测试通过

Phase 3：代理网关

• 状态：✅ 完成
• 内容：gateway、handlers、passthrough
• 验收：curl 冒烟测试通过

Phase 4：异步记账

• 状态：✅ 完成
• 内容：usage recorder
• 验收：用量记录正确

Phase 5：管理 API

• 状态：✅ 完成
• 内容：渠道/模型 CRUD、模型导入
• 验收：管理后台可用

Phase 6：集成测试 + 收尾

• 状态：✅ 完成
• 内容：端到端测试、makefile、README
• 验收：8 种组合通过

---

五、执行记录

Phase 0 — 执行记录

• 开始时间：2026-08-30
• 完成时间：2026-08-30
• 变更摘要：
  • 删除旧文件：opencat.go, store/, team/, pkg/team/, pkg/store/, pkg/error/, pkg/search/, llm/, dist/, assets/, internal/model/, internal/service/team/, internal/dto/team/, internal/controller/team/, internal/consts/, router/router.go, router/chat.go, middleware/auth_team.go
  • 新增 internal/store/models.go（9 个 GORM 模型）+ db.go（多数据库支持）
  • 新增 internal/pkg/：crypto, apikey, jwt, ratelimit, resp, tokenizer
  • 重写 internal/auth, internal/cli, internal/dao/, internal/service/, internal/controller/*
  • 新增 middleware/auth_llm.go（API Key 验证）
  • 重写 router/setRouter.go（无 wire 依赖）
  • 重写 wire/wire.go（简化为 proxy handler）
  • go mod tidy 清理未使用依赖
• 验收结果：✅ go build ./cmd/openteam 通过