初始提交：极码 GeekCode 全栈项目（FastAPI + Vue3）

2026-04-12 10:12:18 +08:00
commit 6aecef16f6
104 changed files with 21009 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,438 @@
+# 极码 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               # 查看后端日志
+```