# 极码 GeekCode

集开发者社区、AI 工具库和经验知识库为一体的综合平台，为程序员提供 AI 驱动的需求分析、架构选型、智能排版、联网搜索等工具，同时支持经验分享、API 管理、导航站等社区功能。

## 功能特性

### 1. 经验知识库（帖子系统）
- **功能说明**：用户发布技术经验帖，支持 Markdown 编辑、分类标签、点赞收藏评论、草稿保存
- **实现方式**：`backend/routers/posts.py` 提供完整 CRUD API，支持信息流（关注/热门/最新）三种排序，自动提取首张图片作为封面（`_extract_cover_image`），热门排序算法为 `like_count * 3 + comment_count * 2 + view_count`
- **优点**：程序员可沉淀技术经验，形成团队知识资产

### 2. AI 智能排版
- **功能说明**：一键将文章重新排版为结构清晰的 Markdown 格式，可选自动生成配图
- **实现方式**：`backend/routers/ai_format.py` 调用 reasoning 类型 AI 模型排版，支持 Seedream 5.0 生成配图并上传 COS 永久存储，自动过滤 `<think>` 思考过程
- **优点**：保持原文不变只改格式，大幅提升文章可读性

### 3. 需求理解助手
- **功能说明**：将甲方原始需求（口语、截图、文档）转化为结构化需求文档
- **实现方式**：`backend/routers/requirement.py` 使用多模态 AI 模型，支持图片上传分析，流式输出 SSE，输出包含 MECE 功能拆解、用户故事、验收标准、复杂度预警
- **优点**：兼具产品经理和程序员双重视角，直接产出可开发的需求文档

### 4. 架构选型助手
- **功能说明**：根据功能需求输出完整技术方案，包含技术选型对比、架构图、数据模型、开发路线图
- **实现方式**：`backend/routers/architecture.py` 流式输出，包含 Mermaid 架构图、ER 图、API 清单、工期评估
- **优点**：基于实战经验推荐最合适的技术栈，避免过度设计

### 5. 联网搜索
- **功能说明**：基于火山方舟豆包大模型的联网搜索工具，获取最新信息
- **实现方式**：`backend/routers/web_search.py` 调用火山方舟 API 的 `web_search` 工具，搜索结果条数可配置（1-50 条），流式输出，保存对话历史
- **优点**：获取实时信息，搜索结果经 AI 整合总结

### 6. 团队知识库
- **功能说明**：从经验帖中精选内容构建团队知识库，支持分类和密码保护
- **实现方式**：`backend/routers/knowledge_base.py` 管理员从帖子中选择添加，支持分类管理、排序、摘要生成，独立密码认证（`X-Kb-Token`）
- **优点**：沉淀高质量内容，控制知识库访问权限

### 7. API Hub（共享 API 管理）
- **功能说明**：团队 API 端点管理平台，支持分类、加密存储 API Key、健康检查、调用日志
- **实现方式**：`backend/routers/shared_api.py` 提供完整管理功能，API Key 加密存储，支持 4 种认证方式（none/api_key/bearer/basic），独立密码认证（`X-Hub-Token`）
- **优点**：团队共享 API 资源，自动监控 API 可用性

### 8. 导航站
- **功能说明**：开发者常用网站导航，支持用户提交和管理员审核
- **实现方式**：`backend/routers/nav.py` 提供分类管理、链接管理、用户提交审核流程（pending → approved/rejected）
- **优点**：UGC 模式丰富导航内容，审核机制保证质量

### 9. 开源项目收藏
- **功能说明**：GitHub 开源项目浏览和收藏，支持实时搜索 GitHub
- **实现方式**：`backend/routers/projects.py` 集成 GitHub API 实时搜索，管理员可批量导入，用户可收藏项目
- **优点**：一站式发现和管理开源项目

### 10. 用户头像上传
- **功能说明**：用户可上传自定义头像，存储到腾讯云 COS
- **实现方式**：前端 `Profile.vue` 点击头像触发上传，调用 `uploadApi.uploadImage` 上传到 COS，再通过 `authApi.updateProfile` 保存头像 URL
- **优点**：个性化用户形象，对象存储保证访问速度

### 11. 多 AI 模型管理
- **功能说明**：后台可视化配置多个 AI 服务商和模型，按任务类型分配
- **实现方式**：`backend/routers/ai_models.py` 支持 5 大服务商预置模型（DeepSeek、OpenAI、Anthropic、Google Gemini、火山方舟），6 种任务类型，支持测试连接
- **优点**：灵活切换模型，按场景选择最合适的 AI 能力

### 12. 用户系统
- **功能说明**：注册登录、个人资料、关注粉丝、消息通知
- **实现方式**：JWT 认证（7 天有效期），新用户注册需管理员审核，支持封禁/解禁，实时通知（点赞、评论、关注）
- **优点**：审核机制保证社区质量

### 13. 后台管理
- **功能说明**：用户管理、帖子管理、分类管理、对象存储配置、AI 模型配置、知识库管理、导航站管理、项目管理
- **实现方式**：`backend/routers/admin.py` + 前端 `views/admin/` 10 个管理页面，仅管理员可访问
- **优点**：完整的运营管理能力

## 业务流程

### 整体流程图

```mermaid
graph TB
    A[用户注册] --> B{管理员审核}
    B -->|通过| C[登录系统]
    B -->|拒绝| A
    C --> D[首页信息流]
    D --> E[写文章]
    D --> F[AI工具库]
    D --> G[导航/项目/知识库]
    E --> H[Markdown编辑]
    H --> I[AI智能排版]
    H --> J[上传图片/附件]
    H --> K[发布/保存草稿]
    F --> L[需求理解助手]
    F --> M[架构选型助手]
    F --> N[联网搜索]
    F --> O[API Hub]
    G --> P[导航站]
    G --> Q[开源项目]
    G --> R[团队知识库]
```

### 内容发布流程

1. 用户进入文章编辑器，选择分类和标签
2. 使用 Markdown 编写内容，可上传图片到 COS
3. 可选使用 AI 智能排版一键优化格式
4. 保存为草稿或直接发布
5. 发布后自动提取首图作为封面
6. 其他用户可点赞、收藏、评论，触发通知

### API 调用链路

| 接口路径 | 方法 | 功能 | 认证 |
|---------|------|------|------|
| /api/auth/register | POST | 用户注册 | 无 |
| /api/auth/login | POST | 用户登录 | 无 |
| /api/auth/me | GET | 获取当前用户 | JWT |
| /api/auth/profile | PUT | 更新资料/头像 | JWT |
| /api/posts | GET/POST | 帖子列表/发布 | JWT |
| /api/posts/feed | GET | 关注信息流 | JWT |
| /api/posts/hot | GET | 热门帖子 | JWT |
| /api/posts/{id} | GET/PUT/DELETE | 帖子详情/编辑/删除 | JWT |
| /api/posts/{id}/like | POST | 点赞/取消 | JWT |
| /api/posts/{id}/collect | POST | 收藏/取消 | JWT |
| /api/posts/{id}/comments | GET/POST | 评论列表/发表 | JWT |
| /api/upload/image | POST | 上传图片 | JWT |
| /api/upload/attachment | POST | 上传附件 | JWT |
| /api/ai/format | POST | AI 智能排版 | JWT |
| /api/requirement/analyze | POST | 需求分析（SSE） | JWT |
| /api/architecture/analyze | POST | 架构分析（SSE） | JWT |
| /api/web-search/search | POST | 联网搜索（SSE） | JWT |
| /api/api-hub/* | GET/POST/PUT/DELETE | API Hub 管理 | Hub Token |
| /api/kb/* | GET/POST/PUT/DELETE | 知识库管理 | Kb Token |
| /api/nav/* | GET/POST/PUT/DELETE | 导航站管理 | JWT |
| /api/projects/* | GET/POST | 项目管理 | JWT |
| /api/users/{id} | GET | 用户主页 | JWT |
| /api/users/{id}/follow | POST | 关注/取消 | JWT |
| /api/notifications | GET | 通知列表 | JWT |
| /api/search | GET | 全文搜索 | JWT |
| /api/admin/* | GET/POST/PUT/DELETE | 后台管理 | JWT + Admin |
| /api/admin/models/* | GET/POST/PUT/DELETE | AI 模型管理 | JWT + Admin |

## 技术栈

| 分类 | 技术 | 版本 |
|------|------|------|
| **后端框架** | FastAPI | 0.115.0 |
| **ASGI 服务器** | Uvicorn | 0.30.0 |
| **ORM** | SQLAlchemy | 2.0.35 |
| **数据库** | MySQL | 8.0 |
| **数据库驱动** | PyMySQL | 1.1.2 |
| **JWT 认证** | python-jose | 3.3.0 |
| **密码哈希** | passlib + bcrypt | 1.7.4 / 4.0.1 |
| **HTTP 客户端** | httpx | 0.27.0 |
| **AI - OpenAI** | openai | 1.51.0 |
| **AI - Anthropic** | anthropic | 0.34.0 |
| **AI - Google** | google-generativeai | 0.8.0 |
| **对象存储** | 腾讯云 COS (cos-python-sdk-v5) | 运行时安装 |
| **图像处理** | Pillow | 10.4.0 |
| **前端框架** | Vue | 3.5.30 |
| **前端路由** | Vue Router | 4.6.4 |
| **状态管理** | Pinia | 3.0.4 |
| **HTTP 客户端** | Axios | 1.14.0 |
| **Markdown 渲染** | markdown-it | 14.1.1 |
| **代码高亮** | highlight.js | 11.11.1 |
| **图表绘制** | Mermaid | 11.13.0 |
| **CSS 框架** | Tailwind CSS | 4.2.2 |
| **构建工具** | Vite | 8.0.1 |

## 目录结构

```
BianCheng/
├── backend/
│   ├── main.py                    # FastAPI 应用入口，路由注册
│   ├── config.py                  # 全局配置（数据库、JWT、AI模型）
│   ├── database.py                # SQLAlchemy 连接和会话管理
│   ├── requirements.txt           # Python 依赖
│   ├── .env                       # 环境变量
│   ├── models/                    # 数据库 ORM 模型（18张表）
│   │   ├── user.py               # 用户
│   │   ├── post.py               # 经验帖
│   │   ├── comment.py            # 评论
│   │   ├── like.py               # 赞和收藏
│   │   ├── follow.py             # 关注关系
│   │   ├── notification.py       # 通知
│   │   ├── ai_model.py           # AI 模型配置
│   │   ├── attachment.py         # 附件
│   │   ├── conversation.py       # AI 对话
│   │   ├── shared_api.py         # 共享 API
│   │   ├── knowledge_base.py     # 知识库
│   │   ├── category.py           # 文章分类
│   │   ├── nav_category.py       # 导航分类
│   │   ├── nav_link.py           # 导航链接
│   │   ├── project.py            # 开源项目
│   │   ├── bookmark.py           # 网站收藏
│   │   └── system_config.py      # 系统配置
│   ├── routers/                   # API 路由（18个模块）
│   │   ├── auth.py               # 认证（注册/登录/资料）
│   │   ├── posts.py              # 帖子 CRUD + 互动
│   │   ├── users.py              # 用户主页 + 关注
│   │   ├── upload.py             # 图片/附件上传（COS）
│   │   ├── ai_format.py          # AI 智能排版
│   │   ├── ai_models.py          # AI 模型管理
│   │   ├── requirement.py        # 需求理解助手
│   │   ├── architecture.py       # 架构选型助手
│   │   ├── web_search.py         # 联网搜索
│   │   ├── knowledge_base.py     # 知识库
│   │   ├── shared_api.py         # API Hub
│   │   ├── nav.py                # 导航站
│   │   ├── projects.py           # 开源项目
│   │   ├── bookmarks.py          # 网站收藏
│   │   ├── notifications.py      # 消息通知
│   │   ├── search.py             # 搜索
│   │   └── admin.py              # 后台管理
│   ├── schemas/                   # Pydantic 数据校验
│   ├── services/                  # 业务逻辑（AI 调用）
│   └── uploads/                   # 本地上传目录（COS 降级）
├── frontend/
│   ├── src/
│   │   ├── main.js               # Vue 应用入口
│   │   ├── App.vue               # 根组件
│   │   ├── style.css             # 全局样式
│   │   ├── router/index.js       # 路由定义（前台+后台）
│   │   ├── stores/               # Pinia 状态管理
│   │   │   ├── user.js           # 用户状态
│   │   │   └── tabs.js           # 标签页
│   │   ├── api/
│   │   │   ├── index.js          # Axios 配置 + 拦截器
│   │   │   └── modules.js        # API 模块（20+）
│   │   └── views/                # 页面组件
│   │       ├── Home.vue          # 首页信息流
│   │       ├── PostEditor.vue    # 文章编辑器
│   │       ├── PostDetail.vue    # 文章详情
│   │       ├── Profile.vue       # 个人资料（头像上传）
│   │       ├── ToolHub.vue       # 工具库
│   │       ├── RequirementAssistant.vue  # 需求助手
│   │       ├── ArchitectureAssistant.vue # 架构助手
│   │       ├── WebSearch.vue     # 联网搜索
│   │       ├── ApiHub.vue        # API Hub
│   │       ├── KnowledgeBase.vue # 知识库
│   │       ├── Navigation.vue    # 导航站
│   │       ├── Projects.vue      # 开源项目
│   │       └── admin/            # 后台管理（10个组件）
│   ├── package.json
│   └── vite.config.js
└── biancheng_full.sql             # 数据库 SQL 转储
```

## 本地开发

### 环境要求
- Python 3.9+
- Node.js 18+
- MySQL 8.0

### 启动步骤

```bash
# 1. 克隆项目
git clone <repo-url> BianCheng
cd BianCheng

# 2. 后端
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install cos-python-sdk-v5    # COS 对象存储（必装）

# 3. 配置环境变量
cp .env .env.local
# 编辑 .env 配置 DATABASE_URL 和 AI API Key

# 4. 创建数据库
mysql -u root -p -e "CREATE DATABASE biancheng CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 5. 启动后端（自动建表）
python main.py
# 后端运行在 http://localhost:8000

# 6. 前端（新终端）
cd ../frontend
npm install
npm run dev
# 前端运行在 http://localhost:5173
```

## 服务器部署

### 部署步骤

```bash
# 1. 本地编译前端
cd frontend && npm run build

# 2. 上传文件到服务器
# - backend/ 整个目录 → /www/wwwroot/BianCheng/backend/
# - frontend/dist/ → /www/wwwroot/BianCheng/frontend/dist/
# ⚠️ 不要上传 venv 虚拟环境，在服务器重建

# 3. 服务器配置 .env（生产环境）
cat > /www/wwwroot/BianCheng/backend/.env << 'EOF'
DATABASE_URL=mysql+pymysql://biancheng:biancheng@127.0.0.1:3306/biancheng?charset=utf8mb4
SECRET_KEY=your-production-secret-key
ARK_API_KEY=your-ark-api-key
ARK_ENDPOINT=ep-xxxxx
EOF

# 4. 安装 Python 依赖
cd /www/wwwroot/BianCheng/backend
pip3 install -r requirements.txt
pip3 install cos-python-sdk-v5

# 5. Nginx 配置要点
# - 前端静态文件指向 frontend/dist/
# - /api 反向代理到后端 127.0.0.1:8000
# - client_max_body_size 20m（支持附件上传）
# - SPA 路由 try_files $uri /index.html

# 6. 启动后端（宝塔/supervisor/systemd）
cd /www/wwwroot/BianCheng/backend
python main.py
```

### Nginx 配置示例

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    root /www/wwwroot/BianCheng/frontend/dist;
    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }

    location /uploads {
        proxy_pass http://127.0.0.1:8000/uploads;
    }
}
```

## 数据库

### 表结构说明

| 分类 | 表名 | 说明 |
|------|------|------|
| **用户系统** | users | 用户信息（含审核、封禁状态） |
| **用户系统** | follows | 关注关系 |
| **用户系统** | notifications | 消息通知 |
| **内容管理** | posts | 经验帖（含草稿） |
| **内容管理** | comments | 评论 |
| **内容管理** | likes | 点赞记录 |
| **内容管理** | collects | 收藏记录 |
| **内容管理** | categories | 文章分类 |
| **内容管理** | attachments | 文件附件 |
| **AI 功能** | ai_model_configs | AI 模型配置 |
| **AI 功能** | conversations | AI 对话记录 |
| **AI 功能** | messages | 对话消息 |
| **知识库** | kb_categories | 知识库分类 |
| **知识库** | kb_items | 知识库条目 |
| **API Hub** | shared_api_categories | API 分类 |
| **API Hub** | shared_apis | 共享 API |
| **API Hub** | shared_api_logs | API 调用日志 |
| **导航站** | nav_categories | 导航分类 |
| **导航站** | nav_links | 导航链接（含审核） |
| **开源项目** | projects | 项目信息 |
| **开源项目** | project_collects | 项目收藏 |
| **其他** | bookmarks | 网站收藏 |
| **其他** | system_config | 系统配置（COS等） |

## 环境变量

### backend/.env

```bash
# 数据库（MySQL 8.0）
DATABASE_URL=mysql+pymysql://root:root@127.0.0.1:3306/biancheng?charset=utf8mb4

# JWT 密钥（生产环境必须更换）
SECRET_KEY=your-secret-key-change-in-production

# AI 模型 API Key（至少配置一个，也可在后台模型管理中配置）
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
DEEPSEEK_API_KEY=

# 火山方舟（豆包大模型 + 联网搜索）
ARK_API_KEY=
ARK_ENDPOINT=ep-20260411180700-z6nll
```

| 配置项 | 说明 | 必填 |
|-------|------|------|
| DATABASE_URL | MySQL 连接字符串，必须包含 `charset=utf8mb4` | 是 |
| SECRET_KEY | JWT 签名密钥，生产环境必须更换 | 是 |
| AI API Keys | 各服务商密钥，可在后台模型管理中配置 | 至少一个 |
| ARK_API_KEY | 火山方舟密钥（联网搜索必需） | 联网搜索需要 |
| ARK_ENDPOINT | 火山方舟模型端点 ID | 联网搜索需要 |

### 系统运行配置（system_config 表）

| 配置项 | 说明 | 必填 |
|-------|------|------|
| cos_secret_id | 腾讯云 COS SecretId | 图片上传需要 |
| cos_secret_key | 腾讯云 COS SecretKey | 图片上传需要 |
| cos_bucket | COS 存储桶名称 | 图片上传需要 |
| cos_region | COS 区域（如 ap-guangzhou） | 图片上传需要 |
| cos_custom_domain | CDN 自定义域名（可选） | 否 |

## 常用命令

```bash
# === 开发 ===
cd backend && python main.py              # 启动后端
cd frontend && npm run dev                 # 启动前端开发服务器
cd frontend && npm run build               # 编译前端

# === 数据库 ===
mysql -u root -p biancheng < biancheng_full.sql     # 导入数据库
mysqldump -u root -p biancheng > backup.sql          # 备份数据库

# === 部署 ===
pip3 install -r requirements.txt          # 安装后端依赖
pip3 install cos-python-sdk-v5            # 安装 COS SDK（必装）

# === 调试 ===
curl http://localhost:8000/api/health      # 健康检查
tail -f backend/GeekCode.log               # 查看后端日志
```