From 327f2f0aa67696e4ec1175334164b71ff304041d Mon Sep 17 00:00:00 2001 From: wuzhen <52326163@qq.com> Date: Tue, 22 Jul 2025 18:02:49 +0800 Subject: [PATCH] =?UTF-8?q?wuzhen=E6=8B=9B=E7=94=9F=E5=8A=9F=E8=83=BD?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/开发文档/API/API文档总览.md | 193 +++---------------------------- 1 file changed, 17 insertions(+), 176 deletions(-) diff --git a/docs/开发文档/API/API文档总览.md b/docs/开发文档/API/API文档总览.md index cff3f2ab..ba9f54e4 100644 --- a/docs/开发文档/API/API文档总览.md +++ b/docs/开发文档/API/API文档总览.md @@ -1,189 +1,30 @@ -# API 文档总览 +# API文档总览 -## 📋 文档说明 +本文档作为所有API文档的总入口，提供快速导航功能。 -本文档是校园管理系统 API 接口的总览和导航页面。为了提高文档的可维护性和可读性，API 文档已按业务模块进行拆分。 +## 基础规范 -**拆分完成时间**: 2025-07-01 -**拆分目的**: 按业务模块管理，便于维护和查找，减少单个文件过大的问题 +- [API文档基础规范](./API文档基础规范.md) ---- +## 认证登录 -## 📊 API 文档架构 +- [用户认证登录API](./用户认证登录API.md) -### 🔗 分模块 API 文档 +## 后勤管理 -| 文档名称 | 文件路径 | 主要内容 | 适用场景 | -| ------------------------- | ----------------------------------------------- | ---------------------------------------------- | -------------------- | -| **📋 API 文档基础规范** | [API 文档基础规范.md](./API文档基础规范.md) | 请求头规范、响应格式、状态码、错误码、数据字典 | **所有开发人员必读** | -| **🔐 用户认证登录 API** | [用户认证登录 API.md](./用户认证登录API.md) | 用户登录、退出、验证码、用户信息、租户管理 | 认证相关开发 | -| **🛠️ 物业报修管理 API** | [物业报修管理 API.md](./物业报修管理API.md) | 维修分类、报修工单、进度跟踪、服务评价 | 物业报修功能开发 | -| **📊 后勤满意度调查 API** | [后勤满意度调查 API.md](./后勤满意度调查API.md) | 问卷管理、答题、题目管理、答题记录 | 满意度调查功能开发 | -| **🏢 场地预约管理 API** | [场地预约管理 API.md](./场地预约管理API.md) | 场地信息管理、预约申请、审批流程、冲突检查 | 场地预约功能开发 | -| **🎭 报告厅预约审核 API** | [报告厅预约审核 API.md](./报告厅预约审核API.md) | 审核建议生成、时间冲突检查、批量审核处理 | 报告厅审核功能开发 | +- [物业报修管理API](./物业报修管理API.md) +- [后勤满意度调查API](./后勤满意度调查API.md) +- [场地预约管理API](./场地预约管理API.md) +- [报告厅预约审核API](./报告厅预约审核API.md) -### 📝 阅读建议 +## 招生迎新 -1. **首次阅读**: 先阅读 [API 文档基础规范.md](./API文档基础规范.md) 了解通用规范 -2. **业务开发**: 根据开发的功能模块选择对应的 API 文档 -3. **交叉引用**: 各模块文档间有交叉引用，便于快速查找相关接口 +- [招生统计API](./招生统计API.md) ---- +## 学工管理 -## 🎯 快速导航 +- [班干部管理API](./班干部管理API.md) -### 🔍 按功能查找接口 +## 开发工具 -#### 🔐 用户认证相关 - -- [用户登录](./用户认证登录API.md#用户登录) - AES+RSA 加密登录 -- [退出登录](./用户认证登录API.md#退出登录) - 清除会话 -- [获取验证码](./用户认证登录API.md#获取验证码) - 图形验证码 -- [获取用户信息](./用户认证登录API.md#获取当前用户信息) - 用户详情和权限 -- [租户管理](./用户认证登录API.md#租户管理) - 多租户支持 - -#### 🛠️ 物业报修相关 - -- [维修分类管理](./物业报修管理API.md#维修分类管理) - 分类 CRUD 操作 -- [报修工单管理](./物业报修管理API.md#报修工单管理) - 工单生命周期 -- [工单进度跟踪](./物业报修管理API.md#获取工单进度列表) - 进度记录 -- [服务评价](./物业报修管理API.md#服务评价管理) - 评价系统 - -#### 📊 满意度调查相关 - -- [问卷管理](./后勤满意度调查API.md#问卷基础管理) - 问卷 CRUD 操作 -- [答题功能](./后勤满意度调查API.md#答题API) - 答题提交和查询 -- [题目管理](./后勤满意度调查API.md#题目管理API) - 题目和选项 -- [答题记录](./后勤满意度调查API.md#答题记录管理API) - 记录查询 - -#### 🏢 场地预约相关 - -- [场地信息管理](./场地预约管理API.md#场地信息管理api) - 场地 CRUD 操作 -- [场地预约申请](./场地预约管理API.md#场地预约管理api) - 预约提交和修改 -- [预约审批](./场地预约管理API.md#审批场地预约) - 审批流程管理 -- [时间冲突检查](./场地预约管理API.md#检查时间冲突) - 预约冲突检测 - -#### 🎭 报告厅审核相关 - -- [报告厅预约查询](./报告厅预约审核API.md#报告厅预约查询-api) - 预约列表和详情查询 -- [时间冲突检查](./报告厅预约审核API.md#时间冲突检查-api) - 智能冲突检测 -- [批量审核处理](./报告厅预约审核API.md#报告厅预约审核-api) - 批准/拒绝预约申请 -- [审核建议生成](./报告厅预约审核API.md#时间冲突检查-api) - 基于冲突检查的智能建议 - -### 🔍 按开发阶段查找 - -#### 🚀 项目初期 - -1. [API 文档基础规范.md](./API文档基础规范.md) - 了解通用规范 -2. [用户认证登录 API.md](./用户认证登录API.md) - 实现用户认证 -3. 选择业务模块文档进行开发 - -#### 🛠️ 功能开发 - -- 根据具体功能模块查找对应 API 文档 -- 参考接口示例和错误码说明 -- 使用数据字典了解枚举值含义 - -#### 🧪 接口测试 - -- 参考各文档中的请求示例 -- 使用提供的测试脚本 -- 查看错误码说明进行问题排查 - ---- - -## 📋 通用信息 - -### 🔧 基础配置 - -- **基础路径**: `/api` -- **响应格式**: JSON -- **字符编码**: UTF-8 -- **权限认证**: Sa-Token + JWT -- **版本**: v1.0 -- **🌐 在线 API 文档**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) ⭐ - -### 📊 API 文档查看方式 - -1. **🌟 Swagger UI 在线文档** (推荐) - - - **访问地址**: http://localhost:8080/swagger-ui/index.html - - **特点**: 可视化界面，支持在线测试，按模块分组 - - **使用场景**: 接口调试、快速查看、在线测试 - -2. **📁 项目内置文档** (详细) - - **位置**: `docs/开发文档/API/` - - **特点**: 中文详细说明，业务逻辑解释，完整示例 - - **使用场景**: 深入了解业务逻辑、开发参考 - -### 🔐 认证要求 - -所有需要认证的接口都必须在请求头中携带： - -```json -{ - "Authorization": "Bearer {access_token}", - "clientid": "e5cd7e4891bf95d1d19206ce24a7b32e", - "Content-Type": "application/json;charset=utf-8" -} -``` - -详细说明请参考：[API 文档基础规范.md](./API文档基础规范.md#请求头规范强制性) - -### 📊 响应格式 - -- **分页列表**: TableDataInfo 格式 (total, rows, code, msg) -- **非分页接口**: R 类型格式 (code, msg, data) -- **错误响应**: 统一错误格式 - -详细说明请参考：[API 文档基础规范.md](./API文档基础规范.md#统一响应格式强制性) - ---- - -## 🔄 文档维护 - -### 📝 更新规则 - -1. **基础规范变更**: 更新 [API 文档基础规范.md](./API文档基础规范.md) -2. **认证相关变更**: 更新 [用户认证登录 API.md](./用户认证登录API.md) -3. **物业报修变更**: 更新 [物业报修管理 API.md](./物业报修管理API.md) -4. **满意度调查变更**: 更新 [后勤满意度调查 API.md](./后勤满意度调查API.md) -5. **总览更新**: 根据需要更新本文档 - -### 🚨 强制要求 - -- **同步更新**: 代码变更时必须同步更新对应的 API 文档 -- **向下兼容**: 新版本 API 必须考虑向下兼容性 -- **版本记录**: 重大变更需要在相应文档中记录版本信息 - ---- - -## 📞 联系方式 - -如有 API 文档相关问题，请联系开发团队或查看项目仓库的 Issues。 - ---- - -## 📈 版本历史 - -### v2.0.0 (2025-07-01) - API 文档拆分重构 - -- 🔄 **重大架构调整**: API 文档按业务模块拆分 -- 📋 **新增基础规范文档**: 统一管理通用规范 -- 🔐 **独立认证 API 文档**: 用户认证登录专门文档 -- 🛠️ **物业报修 API 文档**: 报修管理专门文档 -- 📊 **满意度调查 API 文档**: 问卷答题专门文档 -- 📝 **中文文件命名**: 便于快速识别和查找 -- 🔗 **交叉引用系统**: 各文档间建立引用关系 -- 📚 **总览导航**: 提供统一的文档入口 - -### v1.x.x (2025-01-26 及之前) - -参考各个拆分文档中的版本历史记录。 - ---- - -**📝 维护**: API 文档总览和导航 -**🔄 更新**: 2025-07-01 -**📁 架构**: 4 个专门 API 文档 + 1 个总览文档 -**🎯 目标**: 提供清晰的 API 文档导航和管理体系 +- [API文档模板](./API文档模板.md)