mehediakash01/Knowledge-Trader-Backend

# 知识交易者     **一个由多模型 AI 网关驱动的高性能、高弹性技能交换市场。** 知识交易者通过代币化的知识经济、安全的交易流程和 AI 驱动的匹配，在学习者和专家之间架起桥梁。该平台专为生产环境的可靠性、数据完整性和运维可观察性而设计。 ## 目录 - [项目身份与使命](#project-identity-and-mission) - [高级工程亮点](#senior-engineering-highlights) - [技术规格](#technical-specifications) - [按模块划分的 API 文档](#api-documentation-by-module) - [安装与设置](#installation-and-setup) - [环境变量](#environment-variables) - [架构图 (MSC 模式)](#architecture-diagram-msc-pattern) - [系统可靠性与数据完整性](#system-reliability-and-data-integrity) - [项目状态](#project-status) - [未来路线图](#future-roadmap) ## 项目身份与使命 知识交易者是一个用于技能交换的高弹性后端平台，其中： - 专家发布高质量的、结构化的技能帖子。 - 学习者使用平台代币发现、评估和购买知识。 - AI 服务个性化发现、内容构建和评论智能。 - 交易引擎对代币转移和内容访问强制执行严格的事务一致性。 其核心使命是提供一个安全、高信号的市场，让高质量的学习和货币化的专业知识能够规模化，同时不损害可靠性。 ## 高级工程亮点 ### 1. 高弹性 AI 网关 AI 网关围绕**供应商故障转移和结构化输出保证**构建： - 供应商顺序：**Gemini -> Groq -> OpenRouter**。 - 基于超时的执行，并支持取消（`AbortController`）以防止模型调用挂起。 - 使用 Zod 验证强制结构化模式。 - JSON 修复策略： - 去除 markdown/代码围栏， - 尝试提取对象边界， - 当解析/验证失败时重试供应商回退。 - 当所有供应商失败时，安全回退模式返回确定性的、类似 mock 的结构化数据。 - **每用户 AI 速率限制**，使用 Redis 主存储和内存回退。 - 当前策略：`20 请求数 / 小时 / 用户`。 ### 2. 知识经济 代币化交互受**原子事务引擎**保护： - 交易执行在单个 Prisma 事务内运行。 - 学习者代币扣款和教师代币入账是原子性提交的。 - 交易 + 事务 + 通知记录作为一致性单元持久化。 - 重复购买和自我购买尝试会被拒绝。 - 内容门控逻辑确保 `lockedContent` 仅对以下对象可见： - 帖子所有者，或 - 已完成该帖子交易的用户。 ### 3. 高级安全性 安全控制应用于多个层面： - 用于受保护模块（`USER`、`MANAGER`、`ADMIN`）的 **RBAC（基于角色的访问控制）**。 - **XSS 净化中间件**递归净化 POST/PATCH 请求体。 - **Helmet** 加固 HTTP 安全头。 - 基于 JWT 的认证，具有访问令牌和刷新令牌语义。 - 使用 Zod 模式进行验证优先的请求处理。 ### 4. 性能工程 以性能为中心的架构包括： - **基于 Redis 的缓存**，带内存回退。 - 缓存的类别发现， - 缓存的首页信息流， - 内容变更时的缓存失效。 - 用于 AI 端点的**基于 Redis 的速率限制**。 - 对高基数和搜索/筛选字段进行**数据库索引**。 - `category`、`tokenPrice`、`title`、`slug`、复合 `category + tokenPrice`。 - 用于生产环境诊断的 **Winston 日志**，支持控制台 + 文件传输。 ## 技术规格 ### 核心栈 - **语言：** TypeScript - **运行时：** Node.js + Express.js - **数据库：** PostgreSQL (Prisma ORM + Prisma PG 适配器) - **缓存 / 速率限制：** Redis (带内存优雅回退) - **AI 模型：** - Google Gemini (`gemini-1.5-flash`) - Groq (`llama-3.1-8b-instant`) - OpenRouter (`meta-llama/llama-3.1-8b-instruct:free`) - **文档：** Swagger UI / OpenAPI 3 (`/api-docs`) ### 使用的其他生产环境库 - `helmet` 用于 HTTP 加固 - `xss` 用于请求体净化 - `jsonwebtoken` 用于认证令牌 - `zod` 用于运行时契约验证 - `winston` 用于结构化日志 - `socket.io` 用于实时通知流 - `http-status`, `cors`, `cookie-parser`, `bcrypt` ## 按模块划分的 API 文档 基础 URL：`http://localhost:5000/api/v1` ### 认证模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | POST | `/users/register` | 注册新用户账户 | 公开 | | POST | `/auth/login` | 登录并接收访问/刷新令牌 | 公开 | | POST | `/auth/refresh` | 使用刷新令牌刷新访问令牌 | 计划中（登录时已发出刷新令牌） | ### 技能帖子模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | GET | `/skill-posts` | 搜索/筛选/列出技能帖子 | 公开 | | GET | `/skill-posts/categories` | 缓存的不同类别 | 公开 | | GET | `/skill-posts/home-feed` | 缓存的精选/最新信息流 | 公开 | | GET | `/skill-posts/:id` | 获取单个帖子及其门控的锁定内容 | 可选认证 | | POST | `/skill-posts` | 创建技能帖子 | USER / MANAGER / ADMIN | | PATCH | `/skill-posts/:id` | 更新自己的技能帖子 | USER / MANAGER / ADMIN | ### 交易模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | POST | `/trades/token-trade` | 执行基于代币的购买交易 | USER | | GET | `/trades/my-trades` | 学习 + 教学交易历史 | USER | ### AI 模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | POST | `/ai/match` | AI 技能匹配 | USER / MANAGER / ADMIN | | POST | `/ai/generate-content` | 用于课程详情的 AI 内容构建器 | USER / MANAGER / ADMIN | | POST | `/ai/summarize-reviews/:postId` | AI 评论摘要器 | USER / MANAGER / ADMIN | | POST | `/ai/consultant` | AI 路线图/交易顾问 | USER / MANAGER / ADMIN | ### 分析模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | GET | `/analytics/admin-stats` | 管理后台仪表板 KPIs | ADMIN / MANAGER | | GET | `/analytics/trades?groupBy=date|category` | 交易趋势和代币交易量分析 | ADMIN / MANAGER | ### 通知模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | POST | `/notifications` | 创建通知 | ADMIN / MANAGER | | GET | `/notifications/my-notifications` | 获取已认证用户的通知 | USER / MANAGER / ADMIN | | PATCH | `/notifications/:id/read` | 将自己的通知标记为已读 | USER / MANAGER / ADMIN | ### 评论模块 | 方法 | 端点 | 描述 | 访问权限 | |---|---|---|---| | POST | `/reviews` | 在完成交易后提交评论 | USER | 交互式文档可访问：`GET /api-docs` ## 安装与设置 ### 1. 克隆仓库 ``` git clone cd Knowledge-Trader-Backend ``` ### 2. 安装依赖 ``` npm install ``` ### 3. 配置环境 使用 [环境变量](#environment-variables) 中的变量，在项目根目录创建一个 `.env` 文件。 ### 4. 生成 Prisma 客户端并运行迁移 ``` npx prisma generate npx prisma migrate dev ``` ### 5. 填充数据库 ``` npm run seed ``` ### 6. 运行开发服务器 ``` npm run dev ``` 服务器将在配置的端口（默认 `5000`）上启动。 ### 7. 为生产环境构建 ``` npm run build ``` ## 环境变量 在你的 `.env` 文件中使用以下键： ``` # 应用 NODE_ENV=development PORT=5000 CORS_ORIGIN=http://localhost:3000,http://localhost:5173 # 数据库 DATABASE_URL=postgresql://username:password@localhost:5432/knowledge_trader # JWT JWT_SECRET=change-me JWT_ACCESS_SECRET=change-me-access JWT_REFRESH_SECRET=change-me-refresh JWT_ACCESS_EXPIRES_IN=1d JWT_REFRESH_EXPIRES_IN=30d # Google OAuth GOOGLE_CLIENT_ID=your-google-oauth-client-id GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret # Redis REDIS_URL=redis://localhost:6379 # AI 提供商 GEMINI_API_KEY=your-gemini-key GROQ_API_KEY=your-groq-key OPENROUTER_API_KEY=your-openrouter-key AI_TIMEOUT_MS=10000 ``` 注意事项： - `JWT_SECRET` 如果省略了特定的访问/刷新密钥，可作为回退。 - 当密钥存在时，AI 网关会自动在供应商间回退。 - Redis 是可选的，但推荐用于生产级缓存和速率限制。 ## 架构图 (MSC 模式) 该项目遵循受企业后端系统启发的**模块化服务-控制器 (MSC)** 架构。 ``` Client / Postman / Frontend | v Express Router (Module-based) | v Middleware Layer (Helmet, CORS, Auth, RBAC, Validation, XSS Sanitization, Rate Limiting) | v Controller Layer (HTTP orchestration) | v Service Layer (Business logic, Transactions, Caching, AI orchestration) | +-------------------+ | | v v Prisma ORM AI Gateway (Failover) | Gemini -> Groq -> OpenRouter v PostgreSQL | v Redis (cache/rate-limit state) + Socket.IO (live notifications) ``` ### 为何在此处使用 MSC - 强制实现清晰的关注点分离。 - 提高模块级别的可测试性和可维护性。 - 简化添加新领域（AI、分析、交易、通知）。 - 保持业务规则集中化和可重用。 ## 系统可靠性与数据完整性 可靠性和完整性是此系统的首要关注点： - 原子交易事务防止部分财务状态更新。 - 防御性 AI 编排保护用户工作流免受供应商不稳定的影响。 - 写入时的缓存失效使高读取端点保持高性能和新鲜。 - 模式验证和严格的认证网关减少格式错误/未授权的状态转换。 - 结构化日志和 API 文档提高了运维可观察性和可支持性。 ## 项目状态 - 构建：通过 - API 文档：活跃 (`/api-docs`) - 核心模块：认证、技能帖子、交易、评论、通知、分析、AI - 生产环境加固：安全头、XSS 过滤、RBAC、速率限制、缓存、日志 ## 未来路线图 - 学习者和专家之间的 WebSocket 优先实时聊天 - 移动应用程序 (iOS/Android)，提供统一的代币钱包体验 - 专用的刷新令牌轮换端点和会话管理仪表板 - 用于 AI 预计算和摘要通知的事件驱动后台任务 - 增强的审计跟踪，满足合规级交易取证要求 - 利用行为和群组信号的高级推荐排名 如果你正在评估此后端的生产就绪性，请从以下开始： 1. `GET /api-docs` 进行端点发现 2. 交易流程 (`/trades/token-trade`) 以验证事务完整性 3. AI 流程 (`/ai/*`) 以观察负载下的故障转移和结构化响应 4. 通知流程 (`/notifications/*` + Socket.IO) 以了解实时用户体验行为

标签：AI网关, AI驱动匹配, GNU通用公共许可证, MITM代理, Node.js, TypeScript, Zenmap, 专家平台, 个性化推荐, 事务处理, 代币化平台, 内容管理, 匹配算法, 在线学习, 多模型AI, 安全交易, 安全插件, 弹性系统, 技能交换市场, 搜索引擎查询, 操作可观察性, 教育科技, 数据完整性, 测试用例, 生产可靠性, 知识经济, 自动化攻击