# 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 通过