First Commit

有维项目/.qoder/repowiki/zh/content/扩展与集成/API集成方案.md

@@ -0,0 +1,327 @@
+# API集成方案
+
+<cite>
+**本文档引用的文件**
+- [index.html](file://index.html)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“有维项目”的API集成与前端交互，基于仓库中提供的单页应用入口文件，梳理用户认证、数据存储、第三方服务集成（微信登录、短信、支付）相关的RESTful API规范、认证与安全策略、调用示例、错误处理、性能优化、版本管理与迁移、限流与缓存、监控告警等。由于当前仓库仅包含前端页面与脚本，本文档在未直接分析具体后端实现的前提下，提供可落地的API集成蓝图与最佳实践，便于前后端协作与后续扩展。
+
+## 项目结构
+- 仓库根目录包含一个HTML入口文件，内含完整的前端页面结构、样式与脚本，涵盖登录、仪表盘、AI智能体等页面与交互逻辑。
+- 该HTML文件承担了用户认证、页面切换、用户菜单、AI对话等前端功能，但未包含任何后端API调用逻辑。
+
+```mermaid
+graph TB
+A["index.html<br/>前端入口"] --> B["登录页面<br/>表单与社交登录"]
+A --> C["仪表盘页面<br/>导航与Tab"]
+A --> D["AI智能体页面<br/>对话与筛选"]
+A --> E["聊天弹窗<br/>消息收发"]
+A --> F["用户菜单<br/>账户设置与退出"]
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+## 核心组件
+- 登录与认证：包含用户名/密码登录、记住我、忘记密码、社交登录（微信、手机验证码）等入口。
+- 仪表盘：包含平台概览、有维教育、AI工具、有维校友、会员体系等Tab页面。
+- AI智能体：提供多种AI助手卡片，支持快速问答与对话。
+- 用户菜单：用户头像、通知、账户设置、退出登录。
+- 聊天对话：模态框内的消息发送、快捷问答、自动滚动。
+
+章节来源
+- [index.html](file://index.html)
+
+## 架构总览
+前端采用单页应用（SPA）模式，页面通过JavaScript控制切换与状态更新；用户认证与业务数据通过后端API提供。下图展示了从前端到后端的关键交互路径。
+
+```mermaid
+graph TB
+subgraph "前端"
+U["用户界面<br/>index.html"] --> L["登录流程"]
+U --> D["仪表盘与Tab"]
+U --> A["AI智能体与对话"]
+U --> M["用户菜单"]
+end
+subgraph "后端API"
+AUTH["认证服务<br/>登录/注册/会话"]
+DATA["数据服务<br/>用户信息/课程/对话历史"]
+THIRD["第三方服务<br/>微信/短信/支付"]
+end
+L --> AUTH
+D --> DATA
+A --> DATA
+M --> AUTH
+AUTH --> THIRD
+DATA --> THIRD
+```
+
+图表来源
+- [index.html](file://index.html)
+
+## 详细组件分析
+
+### 用户认证API
+- 登录接口
+  - 方法与URL：POST /api/v1/auth/login
+  - 请求参数：
+    - username: 字符串，支持手机号或邮箱
+    - password: 字符串
+    - rememberMe: 布尔值（可选）
+  - 成功响应：返回令牌与用户信息
+  - 失败响应：返回错误码与错误信息
+- 注册接口
+  - 方法与URL：POST /api/v1/auth/register
+  - 请求参数：
+    - username: 字符串
+    - email: 字符串
+    - password: 字符串
+  - 成功响应：返回用户ID与状态
+  - 失败响应：返回错误码与错误信息
+- 忘记密码接口
+  - 方法与URL：POST /api/v1/auth/forgot-password
+  - 请求参数：
+    - email: 字符串
+  - 成功响应：返回操作结果
+  - 失败响应：返回错误码与错误信息
+- 社交登录接口
+  - 微信登录
+    - 方法与URL：POST /api/v1/auth/wechat
+    - 请求参数：
+      - code: 字符串，授权码
+    - 成功响应：返回令牌与用户信息
+    - 失败响应：返回错误码与错误信息
+  - 手机验证码登录
+    - 方法与URL：POST /api/v1/auth/sms-login
+    - 请求参数：
+      - phone: 字符串
+      - smsCode: 字符串
+    - 成功响应：返回令牌与用户信息
+    - 失败响应：返回错误码与错误信息
+- 会话管理
+  - 刷新令牌
+    - 方法与URL：POST /api/v1/auth/refresh
+    - 请求参数：
+      - refreshToken: 字符串
+    - 成功响应：返回新令牌
+    - 失败响应：返回错误码与错误信息
+  - 退出登录
+    - 方法与URL：POST /api/v1/auth/logout
+    - 请求参数：无
+    - 成功响应：返回操作结果
+    - 失败响应：返回错误码与错误信息
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据存储API
+- 用户信息获取
+  - 方法与URL：GET /api/v1/users/profile
+  - 认证：Bearer Token
+  - 成功响应：返回用户基本信息
+  - 失败响应：返回错误码与错误信息
+- 课程数据同步
+  - 获取课程列表
+    - 方法与URL：GET /api/v1/courses
+    - 查询参数：
+      - page: 整数（可选）
+      - limit: 整数（可选）
+    - 成功响应：返回分页课程列表
+    - 失败响应：返回错误码与错误信息
+  - 获取课程详情
+    - 方法与URL：GET /api/v1/courses/{id}
+    - 成功响应：返回课程详情
+    - 失败响应：返回错误码与错误信息
+- AI对话历史存储
+  - 保存对话
+    - 方法与URL：POST /api/v1/ai/conversations
+    - 请求参数：
+      - agentId: 字符串
+      - messages: 数组（用户与AI消息）
+    - 成功响应：返回对话ID
+    - 失败响应：返回错误码与错误信息
+  - 获取对话历史
+    - 方法与URL：GET /api/v1/ai/conversations
+    - 查询参数：
+      - agentId: 字符串（可选）
+      - limit: 整数（可选）
+    - 成功响应：返回历史记录列表
+    - 失败响应：返回错误码与错误信息
+
+章节来源
+- [index.html](file://index.html)
+
+### 第三方服务集成API
+- 微信登录API
+  - 授权回调
+    - 方法与URL：GET /api/v1/oauth/wechat/callback
+    - 查询参数：
+      - code: 字符串
+    - 成功响应：返回令牌与用户信息
+    - 失败响应：返回错误码与错误信息
+- 短信服务接口
+  - 发送验证码
+    - 方法与URL：POST /api/v1/sms/send
+    - 请求参数：
+      - phone: 字符串
+      - templateId: 字符串（模板ID）
+    - 成功响应：返回发送结果
+    - 失败响应：返回错误码与错误信息
+- 支付网关集成
+  - 创建支付订单
+    - 方法与URL：POST /api/v1/payments/orders
+    - 请求参数：
+      - amount: 整数（分）
+      - productId: 字符串
+      - paymentMethod: 字符串（如 wechat 或 alipay）
+    - 成功响应：返回支付链接或二维码
+    - 失败响应：返回错误码与错误信息
+  - 支付状态查询
+    - 方法与URL：GET /api/v1/payments/orders/{orderId}
+    - 成功响应：返回订单状态
+    - 失败响应：返回错误码与错误信息
+
+章节来源
+- [index.html](file://index.html)
+
+### API认证与安全
+- 认证方法
+  - JWT令牌：所有受保护接口需携带 Authorization: Bearer <token>
+  - OAuth2.0：社交登录采用授权码模式，回调后换取令牌
+- 安全措施
+  - HTTPS：所有API必须通过HTTPS传输
+  - 数据加密：敏感字段（如密码）需服务端加密存储
+  - 防重放攻击：引入随机nonce与时间戳校验
+  - 防暴力破解：登录失败次数限制与临时封禁
+  - CORS：严格配置允许域与方法
+  - CSRF：对状态变更请求启用CSRF令牌校验
+
+章节来源
+- [index.html](file://index.html)
+
+### 错误处理策略
+- 错误码规范
+  - 通用错误：400（参数错误）、401（未授权）、403（权限不足）、404（资源不存在）、429（请求过频）、500（服务器内部错误）
+  - 自定义错误：业务错误返回业务码与中文描述
+- 前端处理
+  - 统一拦截器：捕获HTTP错误并提示用户
+  - 重试机制：对瞬时错误（如502/503）进行指数退避重试
+  - 降级策略：网络异常时使用本地缓存数据
+
+章节来源
+- [index.html](file://index.html)
+
+### API调用示例（示意）
+- 登录
+  - POST /api/v1/auth/login
+  - 请求体：{"username":"user","password":"pass","rememberMe":true}
+  - 成功响应：{"token":"...","user":{"id":"...","name":"..."}}
+- 获取用户信息
+  - GET /api/v1/users/profile
+  - 请求头：Authorization: Bearer <token>
+  - 成功响应：{"id":"...","name":"...","email":"..."}
+- 发送短信验证码
+  - POST /api/v1/sms/send
+  - 请求体：{"phone":"13800000000","templateId":"SMS_XXXXXX"}
+  - 成功响应：{"success":true,"message":"发送成功"}
+
+章节来源
+- [index.html](file://index.html)
+
+## 依赖关系分析
+- 前端依赖
+  - HTML/CSS/JS：单页应用结构，无外部框架依赖
+  - 交互逻辑：通过原生JavaScript实现页面切换、用户菜单、聊天对话
+- 后端依赖
+  - 认证服务：JWT/OAuth2.0
+  - 数据服务：用户、课程、对话历史
+  - 第三方服务：微信、短信、支付
+
+```mermaid
+graph LR
+FE["前端(index.html)"] --> AUTH["认证服务"]
+FE --> DATA["数据服务"]
+FE --> THIRD["第三方服务"]
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+## 性能考量
+- 前端优化
+  - 懒加载：按需加载AI卡片与对话内容
+  - 缓存策略：本地存储用户信息与最近对话，减少重复请求
+  - 防抖节流：输入框与筛选操作使用防抖
+- 后端优化
+  - 分页与索引：课程列表与对话历史分页查询
+  - CDN：静态资源走CDN加速
+  - 异步处理：短信与支付异步回调，避免阻塞主流程
+
+章节来源
+- [index.html](file://index.html)
+
+## 故障排查指南
+- 登录失败
+  - 检查用户名/密码是否正确
+  - 确认网络与HTTPS可用
+  - 查看浏览器控制台是否有跨域错误
+- 社交登录异常
+  - 确认微信授权回调地址配置正确
+  - 检查授权码是否过期
+- 短信发送失败
+  - 检查手机号格式与模板ID
+  - 查看短信服务商返回状态
+- 支付异常
+  - 检查订单状态与回调通知
+  - 确认支付金额与支付方式匹配
+
+章节来源
+- [index.html](file://index.html)
+
+## 结论
+本方案基于现有前端页面，给出了完整的API集成蓝图，涵盖认证、数据存储与第三方服务。建议尽快完善后端服务与数据库设计，确保API的高可用、高性能与安全性。后续可根据业务发展逐步引入版本管理、灰度发布与监控告警体系。
+
+## 附录
+
+### API版本管理与迁移
+- 版本策略
+  - 使用语义化版本号：/api/v1/...
+  - 保持向后兼容：新增字段以默认值存在
+- 迁移指南
+  - 提供迁移脚本与兼容层
+  - 旧版本在到期前提供过渡期
+
+### 限流与缓存
+- 限流
+  - 登录接口：每IP每分钟限制10次
+  - 短信接口：每IP每小时限制50条
+- 缓存
+  - 课程列表：Redis缓存，TTL 5分钟
+  - 用户信息：本地存储，带失效时间
+
+### 监控告警
+- 指标
+  - 请求量、错误率、响应时间、缓存命中率
+- 告警
+  - 错误率超过阈值触发告警
+  - 响应时间异常波动告警