a0c907beed
- 新增热门帖子、热门作者、榜单接口及实现 - 新增api-documentation，更好的ai协作 - 修复types没有导出的问题 BREAKING CHANGES: 1.0.0->1.1.0(latest)
136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# KnowAI Core
|
||
|
||
## 概述
|
||
|
||
KnowAI Core 是前端核心库，提供业务逻辑、数据处理和认证功能，严格遵循分层架构原则，专注于核心功能实现，不包含UI交互逻辑。
|
||
|
||
## 架构设计
|
||
|
||
### 分层架构
|
||
|
||
- **Core层**：提供核心业务逻辑、数据处理和状态管理
|
||
|
||
### 事件驱动设计
|
||
|
||
为了实现层间解耦，认证模块采用事件驱动架构：
|
||
- Core层定义事件类型和事件触发机制
|
||
- 上层应用注册事件监听器，处理UI交互逻辑
|
||
- 避免Core层直接依赖UI层或路由系统
|
||
|
||
## 核心模块
|
||
|
||
### API 模块
|
||
|
||
API模块负责处理所有与后端通信相关的逻辑，提供统一的HTTP请求接口和模块化的API服务：
|
||
|
||
#### 核心功能
|
||
- **请求工厂**：使用工厂模式创建API实例，统一配置请求参数
|
||
- **拦截器系统**：支持请求/响应拦截器，实现统一的错误处理、日志记录和认证
|
||
- **模块化API服务**：按功能域划分API服务，如用户API、帖子API等
|
||
- **响应标准化**：统一处理API响应格式，提供一致的错误处理机制
|
||
- **内容发现**：提供热门帖子、帖子榜单和热门作者功能，支持多种排序和统计周期
|
||
|
||
#### 新增功能
|
||
##### 帖子相关
|
||
- **热门帖子**：通过`getHotPosts()`获取指定时间内的热门帖子
|
||
- **帖子榜单**：通过`getPostRanking()`获取不同周期（日/周/月）的帖子排行榜，支持按浏览量、点赞数、评论数排序
|
||
|
||
##### 用户相关
|
||
- **热门作者**：通过`getHotAuthors()`获取指定时间内的热门作者
|
||
- **作者榜单**：通过`getAuthorRanking()`获取不同周期（日/周/月）的作者排行榜，支持按发帖量、浏览量、点赞数排序
|
||
|
||
#### 架构特点
|
||
- 基于axios构建，支持请求/响应转换
|
||
- 自动处理认证令牌附加
|
||
- 统一的错误处理和重试机制
|
||
- 支持请求取消和超时控制
|
||
|
||
### Auth 模块
|
||
|
||
Auth模块提供完整的认证功能，管理用户身份验证和授权状态：
|
||
|
||
#### 核心功能
|
||
- **令牌管理**：管理访问令牌和刷新令牌，实现自动令牌刷新
|
||
- **认证状态管理**：维护用户登录状态，提供状态查询接口
|
||
- **事件驱动通知**：通过事件系统通知认证状态变化，如登录、登出、令牌过期等
|
||
- **权限控制**：提供基于角色的权限检查功能
|
||
|
||
#### 架构特点
|
||
- 事件驱动的状态通知机制，实现与UI层的解耦
|
||
- 自动处理令牌过期和刷新流程
|
||
- 支持多种认证方式（令牌、OAuth等）
|
||
- 安全的令牌存储机制
|
||
|
||
### Utils 模块
|
||
|
||
Utils模块提供常用的工具函数，支持数据处理和业务逻辑实现：
|
||
|
||
#### 核心功能
|
||
- **数据处理工具**：提供数据转换、过滤、排序等常用数据处理函数
|
||
- **字符串处理工具**：提供字符串格式化、验证、转换等工具函数
|
||
- **日期处理工具**：提供日期格式化、计算、比较等日期相关函数
|
||
- **验证工具**：提供表单验证、数据格式验证等验证函数
|
||
|
||
#### 架构特点
|
||
- 纯函数设计，无副作用，易于测试
|
||
- 函数式编程风格，支持链式调用
|
||
- 完整的TypeScript类型支持
|
||
- 模块化设计，按需导入
|
||
|
||
### Types 模块
|
||
|
||
Types模块提供TypeScript类型定义，确保整个应用的类型安全：
|
||
|
||
#### 核心功能
|
||
- **API相关类型**：定义请求参数、响应数据等API相关类型
|
||
- **业务实体类型**：定义业务领域中的实体类型，如用户、内容等
|
||
- **通用类型定义**：提供通用的工具类型和类型别名
|
||
- **事件类型定义**：定义事件系统中使用的事件类型
|
||
|
||
#### 架构特点
|
||
- 严格的类型定义，提供编译时类型检查
|
||
- 支持泛型和高级类型特性
|
||
- 类型文档完善，提高开发体验
|
||
- 与业务逻辑紧密关联，确保类型一致性
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
knowai-core/
|
||
├── api/ # API模块
|
||
├── auth/ # 认证模块
|
||
├── utils/ # 工具函数模块
|
||
├── types/ # 类型定义模块
|
||
├── test/ # 测试文件
|
||
├── index.ts # 主入口文件
|
||
├── package.json # 项目配置
|
||
├── tsconfig.json # TypeScript配置
|
||
└── vitest.config.ts # 测试配置
|
||
```
|
||
|
||
## 设计原则
|
||
|
||
1. **关注点分离**：业务逻辑与UI逻辑分离，Core层专注于核心功能实现
|
||
2. **事件驱动**：通过事件系统实现层间解耦，降低模块间耦合度
|
||
3. **类型安全**：充分利用TypeScript类型系统，提供编译时类型检查
|
||
4. **模块化**：按功能域组织，按需导入，提高代码复用性
|
||
5. **可测试性**：纯函数和依赖注入提高可测试性，确保代码质量
|
||
|
||
## 更新记录
|
||
|
||
### 2025-11-10
|
||
- 完成tsc eslint vitest测试，构建1.0.0镜像并推送
|
||
|
||
### 2025-11-11
|
||
- 因服务器性能原因去除CI pipeline
|
||
- 重新整理所有逻辑模块架构，完成对应README撰写
|
||
|
||
### 2025-11-12
|
||
- 实现帖子相关新功能：热门帖子、帖子榜单
|
||
- 实现用户相关新功能：热门作者、作者榜单
|
||
- 更新README文档，添加新功能说明
|
||
|
||
### 2025-11-18
|
||
- 添加热门帖子、榜单、热门作者接口
|
||
- 完成api-documentation.md文档，详细描述所有接口的功能、参数、响应格式等
|
||
- 修复类型未导出问题 |