# Janus - 完整开发计划

> AI API 网关（中转站），Go 语言学习项目。

---

## 总览（8 阶段）

| Phase | 主题 | 核心 Go 知识点 |
|-------|------|---------------|
| 1 | 项目骨架 & 基础设施 | go mod、package、Gin、Viper、指针 vs 值 |
| **2** | **数据模型 & Repository** | **struct、GORM tags、interface 隐式满足** |
| 3 | 管理 API CRUD | gin.Context、JSON、binding 验证、统一错误响应 |
| 4 | 代理引擎 | http.Client、io.Reader/Writer、SSE streaming |
| 5 | 负载均衡 | sync.Mutex、RWMutex、加权轮询算法 |
| 6 | 健康检查 & 故障转移 | goroutine、channel、context、熔断器 |
| 7 | 速率限制 & 可观测性 | Gin 中间件链、slog、Token bucket |
| 8 | Dashboard & 容器化 | Vue 3、Docker 多阶段构建、graceful shutdown |

---

# Phase 2：数据模型 & Repository 层

## 学习目标

与 Java 对照理解：

| Go 概念 | Java 对照 | 关键差异 |
|---------|-----------|---------|
| struct + GORM tag | `@Entity` + JPA annotation | 无继承，字段是直接嵌入而非注解驱动 |
| interface 隐式满足 | `implements` 关键字 | 不需要显式声明，只要方法签名匹配就自动满足 |
| repository interface + impl | DAO 接口 + 实现类 | 模式相似，但 Go 用隐式满足，无 `@Autowired` |
| `*gorm.DB` | `EntityManager` / `JpaRepository` | GORM 更接近 MyBatis 风格的链式 API |

## 表结构设计

### providers（供应商）

AI 服务供应商（OpenAI、Anthropic、Azure 等）。

```sql
CREATE TABLE providers (
    id          BIGSERIAL       PRIMARY KEY,
    name        VARCHAR(100)    NOT NULL UNIQUE,       -- openai / anthropic / azure
    base_url    VARCHAR(255)    NOT NULL,               -- API 基础地址
    status      SMALLINT        NOT NULL DEFAULT 1,     -- 1=启用 0=停用
    created_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW()
);

COMMENT ON COLUMN providers.status IS '1: enabled, 0: disabled';
```

### models（模型）

每个供应商下可用的 AI 模型。

```sql
CREATE TABLE models (
    id          BIGSERIAL       PRIMARY KEY,
    provider_id BIGINT          NOT NULL REFERENCES providers(id),
    name        VARCHAR(100)    NOT NULL,               -- gpt-4 / claude-3-opus / text-embedding-3
    model_type  VARCHAR(50)     NOT NULL,               -- chat / completion / embedding / image
    status      SMALLINT        NOT NULL DEFAULT 1,
    created_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    UNIQUE(provider_id, name)
);

COMMENT ON COLUMN models.model_type IS 'chat|completion|embedding|image';
```

### channels（通道）

路由转发通道，连接 provider + model，支持权重和优先级（Phase 5 负载均衡使用）。

```sql
CREATE TABLE channels (
    id          BIGSERIAL       PRIMARY KEY,
    name        VARCHAR(100)    NOT NULL,               -- 通道名称（如 "主通道-OpenAI"）
    provider_id BIGINT          NOT NULL REFERENCES providers(id),
    model_id    BIGINT          REFERENCES models(id),  -- NULL 表示供应商级别通道（透传）
    weight      INT             NOT NULL DEFAULT 1,     -- 负载均衡权重
    priority    INT             NOT NULL DEFAULT 1,     -- 优先级（数字越小越高）
    rate_limit  INT             NOT NULL DEFAULT 60,    -- 每分钟请求数上限
    status      SMALLINT        NOT NULL DEFAULT 1,
    created_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW()
);
```

### api_keys（API 密钥）

调用方认证密钥。

```sql
CREATE TABLE api_keys (
    id          BIGSERIAL       PRIMARY KEY,
    key         VARCHAR(64)     NOT NULL UNIQUE,        -- 实际密钥字符串
    name        VARCHAR(100)    NOT NULL,               -- 密钥名称/用途描述
    rate_limit  INT             NOT NULL DEFAULT 60,    -- 每分钟请求数上限
    status      SMALLINT        NOT NULL DEFAULT 1,
    expired_at  TIMESTAMPTZ,                            -- NULL = 永不过期
    created_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ     NOT NULL DEFAULT NOW()
);
```

---

## Go 代码组织

### 新增目录结构

```
internal/
├── model/               # ← 新增：数据模型
│   ├── provider.go
│   ├── model.go         (模型表 struct)
│   ├── channel.go
│   └── api_key.go
├── repository/           # ← 新增：数据访问层
│   ├── interfaces.go    (所有 repository interface 定义)
│   ├── provider_repo.go (GORM 实现)
│   ├── model_repo.go
│   ├── channel_repo.go
│   └── api_key_repo.go
└── database/
    └── database.go      # 已有，需增加自动迁移
```

### model 包设计要点

每个文件一个 struct，包含：
- GORM tags（`gorm:"column:xxx;type:xxx"`）
- JSON tags（`json:"xxx"`）
- GORM 约定：`ID` 为主键，`CreatedAt`/`UpdatedAt` 自动管理
- 嵌入 `gorm.Model` 还是手写 → 建议**手写**（学习目的，显式看到字段）

示例思路（非完整代码）：

```go
type Provider struct {
    ID        int64          `gorm:"primaryKey;autoIncrement" json:"id"`
    Name      string         `gorm:"uniqueIndex;size:100;not null" json:"name"`
    BaseURL   string         `gorm:"size:255;not null" json:"base_url"`
    Status    int16          `gorm:"default:1;not null" json:"status"`
    CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at"`
    UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at"`
}
```

### repository 包设计要点

**interface 定义**（`interfaces.go`）— 类比 Java 的 DAO 接口：

```go
type ProviderRepository interface {
    Create(ctx context.Context, provider *model.Provider) error
    GetByID(ctx context.Context, id int64) (*model.Provider, error)
    GetAll(ctx context.Context) ([]*model.Provider, error)
    Update(ctx context.Context, provider *model.Provider) error
    Delete(ctx context.Context, id int64) error
}
```

**GORM 实现**（`provider_repo.go`）— 类比 Java 的 DAO Impl：

```go
type providerRepository struct {
    db *gorm.DB
}

func NewProviderRepository(db *gorm.DB) ProviderRepository {
    return &providerRepository{db: db}
}
```

**关键 Go 知识点（与 Java 对比）：**
- `providerRepository` 没有 `implements ProviderRepository` 关键字 — 只要方法签名匹配就自动满足 interface，这叫**隐式满足**
- 构造函数 `NewProviderRepository` 返回 `ProviderRepository`（interface 类型），而不是具体类型 — 调用方只依赖 interface，不依赖具体实现
- 接口定义在哪里？**在 repository 包（使用方附近）**，而不是像 Java 那样单独抽一个 api 模块

---

## GORM 关联关系

- **Model → Provider**：多对一（`BelongsTo`）
- **Channel → Provider**：多对一
- **Channel → Model**：多对一（可空）

Phase 2 先用手写外键 + 手动关联查询来理解，后续可以引入 GORM 的 `Preload` / `Association`。

---

## 数据库迁移

在 `internal/database/database.go` 的 `Connect` 函数后增加自动迁移：

```go
func AutoMigrate(db *gorm.DB) error {
    return db.AutoMigrate(
        &model.Provider{},
        &model.Model{},        // 注意命名冲突，Go 里可以用 ModelName
        &model.Channel{},
        &model.APIKey{},
    )
}
```

同时创建 `migrations/` 目录下的 SQL 文件作为正式迁移脚本（与自动迁移并存，生产环境用 SQL）。

---

## 实施步骤

按顺序完成，每一步都可以编译验证：

### Step 1：创建 SQL 迁移脚本
- 在 `migrations/` 下创建 `001_init.sql`，包含 4 张建表语句

### Step 2：创建 model struct
- `internal/model/provider.go`
- `internal/model/model.go`（注意 Go 标准库 `builtin` 没有 model，但包名 model + 类型名 Model 会造成 `model.Model` 有点别扭，可以考虑命名为 `AiModel` 或在调用时用别名，由你决定）
- `internal/model/channel.go`
- `internal/model/api_key.go`

### Step 3：创建 repository interface
- `internal/repository/interfaces.go` — 4 个 interface 定义

### Step 4：创建 repository 实现
- 每个 repository 一个文件，GORM CRUD 实现

### Step 5：集成自动迁移
- 修改 `database/database.go` 增加 `AutoMigrate`
- 修改 `cmd/server/main.go` 在连接后调用迁移

---

## 设计决策说明

| 决策 | 选择 | 理由 |
|------|------|------|
| 主键类型 | `int64` (BIGSERIAL) | 适合中小规模，比 UUID 性能好，比自增 int 容量大 |
| 时间字段 | `time.Time` + `TIMESTAMPTZ` | GORM 自动管理，带时区避免歧义 |
| 状态字段 | `int16` (SMALLINT) | 扩展性强，可后续加更多状态值 |
| 软删除 | 暂不使用 | GORM 默认支持 `gorm.DeletedAt`，但 Phase 2 先学基础，不引入 |
| model_type | varchar | 比 enum 灵活，Go 端用 const 常量约束 |
| 外键约束 | 数据库级 REFERENCES | GORM 不强制外键，但数据库层保证完整性 |