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