feat: 更新项目代码

infogenie-backend-go/后端文档.md

@@ -0,0 +1,117 @@
+# 万象口袋 — 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`**。