164 lines
4.5 KiB
Markdown
164 lines
4.5 KiB
Markdown
|
# 项目文档目录 (docs/)
|
|||
|
|
|
|||
|
|
## 模块简介
|
|||
|
|
|
|||
|
|
`docs/` 目录包含项目的所有技术文档、API设计文档、功能说明文档等。这些文档为开发者提供详细的功能说明、使用指南和设计思路。
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
docs/
|
|||
|
|
├── README.md # 文档目录说明
|
|||
|
|
├── chat.md # 聊天API设计文档
|
|||
|
|
└── 忘记密码和重置密码.md # 密码重置功能文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 主要文件说明
|
|||
|
|
|
|||
|
|
### chat.md - 聊天API设计文档
|
|||
|
|
**功能描述**: 详细描述智能问答接口的设计规范和使用方法
|
|||
|
|
|
|||
|
|
**主要内容**:
|
|||
|
|
- 🤖 **问答模式**: 普通聊天(chat)和深度研究(research)两种模式
|
|||
|
|
- 📥 **请求格式**: POST /api/qa/ask 接口的请求参数说明
|
|||
|
|
- 📤 **响应格式**: 返回数据的结构和字段说明
|
|||
|
|
- 💡 **使用示例**: 包含完整的请求和响应示例
|
|||
|
|
- 🔧 **字段说明**: 每个参数的类型、必填性和用途
|
|||
|
|
|
|||
|
|
**核心接口**:
|
|||
|
|
```http
|
|||
|
|
POST /api/qa/ask
|
|||
|
|
{
|
|||
|
|
"mode": "chat|research",
|
|||
|
|
"conversation_id": "可选会话ID",
|
|||
|
|
"message": "用户问题"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**适用场景**:
|
|||
|
|
- API接口开发参考
|
|||
|
|
- 前端对接指南
|
|||
|
|
- 测试用例编写
|
|||
|
|
- 产品功能说明
|
|||
|
|
|
|||
|
|
### 忘记密码和重置密码.md - 密码重置功能文档
|
|||
|
|
**功能描述**: 详细说明用户密码重置功能的实现流程和技术细节
|
|||
|
|
|
|||
|
|
**主要内容**:
|
|||
|
|
- 🔐 **安全机制**: 验证码生成和验证流程
|
|||
|
|
- 📧 **邮件服务**: 邮件发送配置和模板设计
|
|||
|
|
- ⏰ **时效控制**: 验证码过期时间和重试机制
|
|||
|
|
- 🛡️ **安全防护**: 防止暴力破解和恶意攻击
|
|||
|
|
- 🔄 **完整流程**: 从申请重置到密码更新的全流程
|
|||
|
|
|
|||
|
|
**核心流程**:
|
|||
|
|
1. 用户申请密码重置
|
|||
|
|
2. 系统发送验证码邮件
|
|||
|
|
3. 用户输入验证码
|
|||
|
|
4. 验证通过后设置新密码
|
|||
|
|
|
|||
|
|
**适用场景**:
|
|||
|
|
- 密码重置功能开发
|
|||
|
|
- 安全机制设计参考
|
|||
|
|
- 邮件服务配置指南
|
|||
|
|
- 用户体验优化
|
|||
|
|
|
|||
|
|
## 如何使用文档
|
|||
|
|
|
|||
|
|
### 开发者使用指南
|
|||
|
|
|
|||
|
|
#### 1. API开发参考
|
|||
|
|
```bash
|
|||
|
|
# 查看聊天API设计
|
|||
|
|
cat docs/chat.md
|
|||
|
|
|
|||
|
|
# 了解密码重置流程
|
|||
|
|
cat docs/忘记密码和重置密码.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2. 接口测试
|
|||
|
|
- 参考`chat.md`中的示例进行API测试
|
|||
|
|
- 使用Swagger UI: http://localhost:8080/swagger-ui.html
|
|||
|
|
- 使用Postman导入API文档进行测试
|
|||
|
|
|
|||
|
|
#### 3. 功能实现
|
|||
|
|
- 按照文档中的设计规范实现功能
|
|||
|
|
- 遵循文档中的数据格式和错误处理机制
|
|||
|
|
- 参考安全机制设计相关功能
|
|||
|
|
|
|||
|
|
### 文档维护规范
|
|||
|
|
|
|||
|
|
#### 1. 文档更新
|
|||
|
|
- 功能变更时及时更新相关文档
|
|||
|
|
- 保持文档与代码实现的一致性
|
|||
|
|
- 添加版本号和更新日期
|
|||
|
|
|
|||
|
|
#### 2. 文档格式
|
|||
|
|
- 使用Markdown格式编写
|
|||
|
|
- 包含清晰的标题和目录结构
|
|||
|
|
- 提供完整的示例代码
|
|||
|
|
|
|||
|
|
#### 3. 文档审查
|
|||
|
|
- 新增文档需要代码审查
|
|||
|
|
- 定期检查文档的准确性
|
|||
|
|
- 收集用户反馈并改进文档
|
|||
|
|
|
|||
|
|
## 文档扩展计划
|
|||
|
|
|
|||
|
|
### 待添加文档
|
|||
|
|
|
|||
|
|
#### 技术文档
|
|||
|
|
- **数据库设计文档**: 详细的表结构和关系说明
|
|||
|
|
- **架构设计文档**: 系统整体架构和模块关系
|
|||
|
|
- **部署指南**: 详细的生产环境部署步骤
|
|||
|
|
- **性能优化指南**: 系统性能调优建议
|
|||
|
|
|
|||
|
|
#### API文档
|
|||
|
|
- **用户管理API**: 用户注册、登录、资料管理接口
|
|||
|
|
- **会话管理API**: 会话创建、查询、删除接口
|
|||
|
|
- **系统管理API**: 系统配置、监控、日志接口
|
|||
|
|
|
|||
|
|
#### 开发文档
|
|||
|
|
- **开发环境搭建**: 详细的本地开发环境配置
|
|||
|
|
- **代码规范**: Java代码编写规范和最佳实践
|
|||
|
|
- **测试指南**: 单元测试、集成测试编写指南
|
|||
|
|
- **故障排除**: 常见问题和解决方案
|
|||
|
|
|
|||
|
|
#### 用户文档
|
|||
|
|
- **用户使用手册**: 面向最终用户的功能说明
|
|||
|
|
- **管理员指南**: 系统管理和配置说明
|
|||
|
|
- **FAQ**: 常见问题解答
|
|||
|
|
|
|||
|
|
### 文档工具
|
|||
|
|
|
|||
|
|
#### 文档生成
|
|||
|
|
- **Swagger/OpenAPI**: 自动生成API文档
|
|||
|
|
- **JavaDoc**: 生成代码文档
|
|||
|
|
- **GitBook**: 在线文档平台
|
|||
|
|
|
|||
|
|
#### 文档管理
|
|||
|
|
- **版本控制**: 使用Git管理文档版本
|
|||
|
|
- **协作编辑**: 支持多人协作编辑
|
|||
|
|
- **自动发布**: 文档自动部署和更新
|
|||
|
|
|
|||
|
|
## 重要注意事项
|
|||
|
|
|
|||
|
|
### 文档质量
|
|||
|
|
- 确保文档内容准确无误
|
|||
|
|
- 提供完整的示例和说明
|
|||
|
|
- 保持文档结构清晰易读
|
|||
|
|
|
|||
|
|
### 安全考虑
|
|||
|
|
- 不在文档中暴露敏感信息
|
|||
|
|
- 密钥和密码使用占位符
|
|||
|
|
- 生产环境配置单独管理
|
|||
|
|
|
|||
|
|
### 维护更新
|
|||
|
|
- 定期检查文档的时效性
|
|||
|
|
- 及时更新过时的信息
|
|||
|
|
- 收集用户反馈并改进
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**提示**: 如需查看具体文档内容，请直接打开对应的.md文件。所有文档都使用Markdown格式编写，支持在GitHub、GitLab等平台上直接预览。
|