docs(zulip): 完善Zulip业务模块功能文档

范围: src/business/zulip/README.md
- 补充对外提供的接口章节(14个公共方法)
- 添加使用的项目内部依赖说明(7个依赖)
- 完善核心特性描述(5个特性)
- 添加潜在风险评估(4个风险及缓解措施)
- 优化文档结构和内容完整性
This commit is contained in:
moyin
2026-01-15 10:53:04 +08:00
parent 30a4a2813d
commit ed04b8c92d
32 changed files with 622 additions and 8886 deletions

106
src/gateway/zulip/README.md Normal file
View File

@@ -0,0 +1,106 @@
# Zulip Gateway Module
## 📋 模块概述
Zulip网关模块负责提供Zulip相关功能的HTTP API接口。
## 🏗️ 架构定位
- **层级**: Gateway层网关层
- **职责**: HTTP协议处理、API接口暴露、请求验证
- **依赖**: Business层的ZulipModule
## 📁 文件结构
```
src/gateway/zulip/
├── dynamic_config.controller.ts # 动态配置管理API
├── websocket_docs.controller.ts # WebSocket文档API
├── websocket_openapi.controller.ts # WebSocket OpenAPI规范
├── websocket_test.controller.ts # WebSocket测试工具
├── zulip_accounts.controller.ts # Zulip账号管理API
├── zulip.gateway.module.ts # 网关模块定义
└── README.md # 本文档
```
## 🎯 主要功能
### 1. 动态配置管理 (DynamicConfigController)
- 获取当前配置
- 同步远程配置
- 配置状态查询
- 备份管理
### 2. WebSocket文档 (WebSocketDocsController)
- 提供WebSocket API使用文档
- 消息格式示例
- 连接示例代码
### 3. WebSocket OpenAPI (WebSocketOpenApiController)
- 在Swagger中展示WebSocket接口
- 提供测试工具推荐
- 架构信息展示
### 4. WebSocket测试工具 (WebSocketTestController)
- 交互式WebSocket测试页面
- 支持连接、认证、消息发送测试
- API调用监控功能
### 5. Zulip账号管理 (ZulipAccountsController)
- Zulip账号关联CRUD操作
- 账号验证和统计
- 批量管理功能
## 🔗 依赖关系
```
ZulipGatewayModule
├─ imports: ZulipModule (Business层)
├─ imports: AuthModule (Business层)
└─ controllers: [所有Controller]
```
## 📝 使用示例
### 在AppModule中导入
```typescript
import { ZulipGatewayModule } from './gateway/zulip/zulip.gateway.module';
@Module({
imports: [
// ... 其他模块
ZulipGatewayModule,
],
})
export class AppModule {}
```
## 🚨 架构规范
### Gateway层职责
- ✅ HTTP协议处理
- ✅ 请求参数验证DTO
- ✅ 调用Business层服务
- ✅ 响应格式转换
- ✅ 错误处理和转换
### Gateway层禁止
- ❌ 包含业务逻辑
- ❌ 直接访问数据库
- ❌ 直接调用Core层应通过Business层
- ❌ 包含复杂的业务规则
## 📚 相关文档
- [架构文档](../../docs/ARCHITECTURE.md)
- [Zulip Business模块](../../business/zulip/README.md)
- [开发指南](../../docs/development/backend_development_guide.md)
## 🔄 最近更新
- 2026-01-14: 架构优化 - 从Business层分离Controller到Gateway层 (moyin)
## 👥 维护者
- moyin