327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
# 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分钟
|
||
- 用户信息：本地存储，带失效时间
|
||
|
||
### 监控告警
|
||
- 指标
|
||
- 请求量、错误率、响应时间、缓存命中率
|
||
- 告警
|
||
- 错误率超过阈值触发告警
|
||
- 响应时间异常波动告警 |