项目文档目录 (docs/)
模块简介
docs/ 目录包含项目的所有技术文档、API设计文档、功能说明文档等。这些文档为开发者提供详细的功能说明、使用指南和设计思路。
目录结构
docs/
├── README.md # 文档目录说明
├── chat.md # 聊天API设计文档
└── 忘记密码和重置密码.md # 密码重置功能文档
主要文件说明
chat.md - 聊天API设计文档
功能描述: 详细描述智能问答接口的设计规范和使用方法
主要内容:
- 🤖 问答模式: 普通聊天(chat)和深度研究(research)两种模式
- 📥 请求格式: POST /api/qa/ask 接口的请求参数说明
- 📤 响应格式: 返回数据的结构和字段说明
- 💡 使用示例: 包含完整的请求和响应示例
- 🔧 字段说明: 每个参数的类型、必填性和用途
核心接口:
POST /api/qa/ask
{
"mode": "chat|research",
"conversation_id": "可选会话ID",
"message": "用户问题"
}
适用场景:
- API接口开发参考
- 前端对接指南
- 测试用例编写
- 产品功能说明
忘记密码和重置密码.md - 密码重置功能文档
功能描述: 详细说明用户密码重置功能的实现流程和技术细节
主要内容:
- 🔐 安全机制: 验证码生成和验证流程
- 📧 邮件服务: 邮件发送配置和模板设计
- ⏰ 时效控制: 验证码过期时间和重试机制
- 🛡️ 安全防护: 防止暴力破解和恶意攻击
- 🔄 完整流程: 从申请重置到密码更新的全流程
核心流程:
- 用户申请密码重置
- 系统发送验证码邮件
- 用户输入验证码
- 验证通过后设置新密码
适用场景:
- 密码重置功能开发
- 安全机制设计参考
- 邮件服务配置指南
- 用户体验优化
如何使用文档
开发者使用指南
1. API开发参考
# 查看聊天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等平台上直接预览。