# 项目文档目录 (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等平台上直接预览。