# 万象口袋 — Go 后端文档

**技术栈**：Go 1.25+ · Gin · GORM · MySQL  

**模块路径**：`infogenie-backend`（见 `go.mod`）

**入口**：`cmd/server/main.go` — 加载配置、连接数据库、`AutoMigrate`、启动 HTTP 服务。

---

## 运行与配置

- 环境由 **`APP_ENV`** 决定：`development` 或 `production`（见 `config.Load()`）。
- 若存在 **`.env.development`** / **`.env.production`**，会通过 `godotenv` 加载对应文件。
- **`APP_PORT`** 默认 **5002**（与前端 `REACT_APP_API_URL` 开发默认一致）。
- 数据库、邮件、认证中心、`INFOGENIE_SITE_ADMIN_TOKEN` 等从环境变量读取，详见 `config/config.go`。

**健康检查**：`GET /api/health` — 返回服务状态与数据库 `Ping` 结果。

**根路径**：`GET /` — 返回服务说明与主要 endpoint 分组（`version` 当前为 **3.3.0-go**）。

---

## 数据库（GORM AutoMigrate）

启动时会迁移以下模型（见 `internal/database/mysql.go`）：

| 模型 | 用途 |
|------|------|
| `AIConfig` | 多厂商 AI Key / Base / 模型列表（如 deepseek、kimi） |
| `Site60sDisabled` | 60s 功能在前端隐藏的 `feature_id` |
| `SiteAIRuntime` | DeepSeek 兼容网关（Base + Key + 默认模型），优先级高于部分 AIConfig |
| `Site60sUpstream` | 60s 上游节点（单例 id=1） |
| `SiteAIModelDisabled` | AI 应用在前端隐藏的 `app_id` |
| `SiteFeatureCardClick` | 四大板块功能卡片点击统计（`section` + `item_id` 联合主键） |

---

## 路由概览（`internal/router/router.go`）

### CORS

全局 `middleware.CORS()`，放行常用 Method/Header（含 `Authorization`、`X-Site-Admin-Token`）。

### 认证与用户

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/auth/check` | 可选 JWT：校验登录态 |
| GET | `/api/user/profile` | **需 JWT**：用户资料 |

实际登录、发 token 由 **萌芽账户认证中心** 完成；后端校验 JWT。

### 站点公开配置（无需登录）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/site/60s-disabled` | 被隐藏的 60s `feature_id` 列表 |
| GET | `/api/site/60s-source` | 60s 上游 `source_id` / `base_url` |
| GET | `/api/site/ai-model-disabled` | 被隐藏的 AI 应用 id 列表 |
| GET | `/api/site/feature-card-clicks?section=` | 功能卡片点击次数（见下） |
| POST | `/api/site/feature-card-clicks/increment` | 上报一次点击，返回最新 count |

**`section` 合法值**：`60sapi` · `smallgame` · `toolbox` · `aimodel`  

**increment 请求体**：`{ "section": "...", "item_id": "..." }`

### 站点管理（需 `X-Site-Admin-Token`，与环境变量 `INFOGENIE_SITE_ADMIN_TOKEN` 一致）

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | `/api/admin/site/60s-disabled` | 更新 60s 隐藏列表 |
| PUT | `/api/admin/site/60s-source` | 切换 60s 上游 |
| PUT | `/api/admin/site/ai-model-disabled` | 更新 AI 应用隐藏列表 |
| GET/PUT | `/api/admin/site/ai-runtime` | 读取/更新 DeepSeek 兼容运行时配置 |

### AI 应用（`/api/aimodelapp`，默认 **需 JWT**）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/chat` | 非流式对话，JSON 返回全文 |
| POST | `/chat/stream` | **SSE 流式**：透传上游 OpenAI 兼容流（`text/event-stream`） |
| POST | `/name-analysis` 等 | 各垂直能力（姓名、变量命名、写诗、翻译等） |
| GET | `/models` | 模型列表 |

**流式说明**（`internal/handler/aimodel.go` + `internal/service/ai.go`）：

- 上游请求带 `stream: true`，成功后将上游 body **分块写入并 Flush** 到客户端。
- 支持 **deepseek**（运行时或 `AIConfig`）与 **kimi**（`AIConfig`）。
- 与 `/chat` 共用同一套 `bindAIModelChat` 校验（消息条数、长度、模型白名单等）。

**模型白名单**：见 `internal/handler/aimodel.go` 中 `allowedModels`（如 deepseek-chat、deepseek-reasoner、部分 kimi 模型）。

---

## 核心源码目录

```
cmd/server/          # main
config/              # 配置加载
internal/
  database/          # MySQL 初始化、AutoMigrate
  handler/           # HTTP 处理器（auth、user、aimodel、siteconfig、ai_runtime、feature_card_clicks）
  middleware/        # CORS、JWT
  model/             # GORM 模型
  router/            # 路由注册
  service/           # AI 调用（含 OpenAI 兼容非流式与流式）
```

---

## 与其他工程的关系

- **前端 SPA** 通过 `REACT_APP_API_URL` 指向本服务（开发默认 `http://127.0.0.1:5002`）。
- **`public/aimodelapp/*/shared/ai-chat.js`** 优先调用 `/api/aimodelapp/chat/stream`，失败时回退 `/chat`。

更完整的前端集成说明见 **`infogenie-frontend/前端文档.md`**。