“wuzhen”andCursor
a0bb39d069
班级树改为 xg_class_msg 主数据源（无住宿生也可见），统一入学年口径与学院向上解析，避免代理院一年级列表不全或挂错。 Co-authored-by: Cursor <cursoragent@cursor.com>
业务模块管理
📋 业务模块总览
本文档管理所有业务模块的文档，为 Cursor AI 辅助开发 提供完整的业务上下文和技术实现参考。每个业务模块都包含从需求分析到部署运维的全生命周期文档。
🎯 文档管理目标
为 Cursor AI 提供的价值
- 🧠 业务理解：完整的业务逻辑和流程说明，帮助 AI 理解业务需求
- 🔧 技术实现：标准的代码结构和实现模式，指导 AI 生成高质量代码
- 🔗 上下文关联：模块间的依赖关系和接口定义，确保集成一致性
- 📚 最佳实践：经过验证的开发模式和代码规范，提升开发效率
文档维护原则
- 实时同步：代码变更时立即更新对应文档
- 结构化：使用统一的文档模板和格式
- 可追溯：记录所有变更历史和决策过程
- AI 友好：使用清晰的结构和标准化的描述方式
📊 当前业务模块清单
🔥 核心业务模块
1. 后勤满意度调查系统 (hq-satisfaction-survey)
- 状态：🟢 已完成开发
- 负责人：李四
- 技术栈：Spring Boot + Vue3 + MyBatis-Plus
- 核心功能：问卷设计、数据收集、统计分析、报告生成
- API 数量：18 个接口
- 文档完整度：✅ 100%
2. 报告厅预约管理系统 (hall-reservation)
- 状态：🟡 开发中
- 负责人：王五
- 技术栈：Spring Boot + Vue3 + Warm-Flow
- 核心功能：场地管理、预约申请、审批流程、冲突检测
- API 数量：15 个接口（规划中）
- 文档完整度：🟡 80%
3. 系统管理模块 (system-management)
- 状态：🟢 基础框架完成
- 负责人：张三
- 技术栈：Spring Boot + Vue3 + Sa-Token
- 核心功能：用户管理、权限控制、组织架构、系统配置
- API 数量：25 个接口
- 文档完整度：✅ 95%
4. 用户管理模块 (user-management)
- 状态：🟢 已完成
- 负责人：张三
- 技术栈：Spring Boot + Vue3 + Sa-Token
- 核心功能：用户注册、登录认证、个人信息、角色分配
- API 数量：12 个接口
- 文档完整度：✅ 100%
🚀 计划中模块
5. 物业报修管理系统 (property-maintenance)
- 状态：🔄 前端开发完成
- 负责人：待分配
- 技术栈：Spring Boot 3.4.6 + Vue3 + TypeScript + Warm-Flow + Element Plus
- 核心功能：报修申请管理、工单分派系统、维修进度跟踪、服务质量评价、数据统计分析
- API 数量：15 个接口（规划中）
- 文档完整度：🟡 95%（前端代码完成）
- 数据库表：6 个核心表（已部署到研发环境）
- 部署环境：47.99.164.66:3306/hzdyjs_xg
- 开发进度：
- ✅ 需求分析完成
- ✅ 数据库设计完成
- ✅ 数据库部署完成
- ✅ 前端代码完成（API 层 + 页面组件）
- 🔄 后端接口开发中
- ⏳ 功能联调测试
- 前端代码：
- API 接口定义：17 个 TypeScript 类型，22 个接口方法
- 页面组件：报修工单管理、维修类型管理
- 技术特性：模拟数据、完整表单验证、状态流转、树形结构
- 特殊说明：
- 系统管理功能：使用系统自带的用户、角色、权限管理，无需重新开发
- 通知功能：本模块暂不包含通知功能，状态更新通过系统界面显示
- 数据库环境：已在研发环境部署完成，支持后端开发和前端联调
- 前端环境：使用模拟数据，支持独立开发调试
- 下一步：开始后端 API 接口开发，对接前端代码
6. 餐饮服务管理系统 (catering-management)
- 状态：⭕ 待开发
- 计划开始：2024 年 8 月
- 技术栈：Spring Boot + Vue3 + uniapp
- 核心功能：菜品管理、订餐服务、营养配餐、食堂管理
📁 业务模块文档结构标准
每个业务模块都按照以下标准结构组织文档：
业务模块/
├── [模块名称]/
│ ├── README.md # 模块总览
│ ├── 需求分析/
│ │ ├── 业务需求说明.md # 业务需求详细说明
│ │ ├── 功能需求清单.md # 功能点清单
│ │ ├── 非功能需求.md # 性能、安全等要求
│ │ └── 用户故事.md # 用户使用场景
│ ├── 技术设计/
│ │ ├── 数据库设计.md # 表结构设计
│ │ ├── API接口设计.md # 接口定义
│ │ ├── 架构设计.md # 模块架构
│ │ └── 技术选型.md # 技术决策
│ ├── 实现文档/
│ │ ├── 后端实现说明.md # 后端代码结构
│ │ ├── 前端实现说明.md # 前端代码结构
│ │ ├── 关键业务逻辑.md # 核心算法
│ │ └── 代码规范.md # 编码规范
│ ├── 测试文档/
│ │ ├── 测试计划.md # 测试策略
│ │ ├── 测试用例.md # 具体测试用例
│ │ └── 测试报告.md # 测试结果
│ └── 运维文档/
│ ├── 部署指南.md # 部署步骤
│ ├── 监控配置.md # 监控指标
│ └── 故障处理.md # 常见问题
🔧 Cursor AI 辅助开发指南
如何使用业务模块文档
1. 新功能开发
📋 开发前准备清单：
1. 阅读模块的 README.md 了解整体架构
2. 查看 需求分析/ 目录了解业务逻辑
3. 参考 技术设计/ 目录了解设计模式
4. 查看 实现文档/ 目录了解代码结构
5. 使用 API 接口设计.md 了解接口规范
2. 代码生成提示词模板
基于 [模块名称] 的业务需求文档和技术设计文档，生成以下功能的代码：
业务背景：[从需求分析文档中提取]
技术要求：[从技术设计文档中提取]
代码结构：[从实现文档中提取]
接口规范：[从API设计文档中提取]
请按照项目规范生成：
1. Controller 层代码
2. Service 层代码
3. Mapper 层代码
4. DTO/VO 类
5. 单元测试代码
3. 文档更新提示词模板
根据刚才的代码变更，请更新以下业务模块文档：
变更内容：[具体变更说明]
影响模块：[模块名称]
需要更新的文档：
1. API接口设计.md - 新增/修改的接口
2. 数据库设计.md - 表结构变更
3. 实现文档/ - 代码结构变更
4. README.md - 模块概览更新
请保持文档格式一致，确保信息准确。
📈 模块开发生命周期管理
阶段 1：需求分析 📋
- 输入：业务需求、用户反馈
- 输出：需求分析文档
- AI 角色：需求梳理、用户故事生成
- 文档：业务需求说明.md、功能需求清单.md
阶段 2：技术设计 🎨
- 输入：需求分析结果
- 输出：技术设计文档
- AI 角色：架构设计、接口设计
- 文档：数据库设计.md、API 接口设计.md、架构设计.md
阶段 3：代码实现 💻
- 输入：技术设计文档
- 输出：功能代码、单元测试
- AI 角色：代码生成、测试用例生成
- 文档：后端实现说明.md、前端实现说明.md
阶段 4：测试验证 🧪
- 输入：实现代码
- 输出：测试报告
- AI 角色：测试用例补充、问题分析
- 文档：测试计划.md、测试用例.md、测试报告.md
阶段 5：部署运维 🚀
- 输入：测试通过的代码
- 输出：生产环境部署
- AI 角色：部署脚本生成、监控配置
- 文档：部署指南.md、监控配置.md
🔄 文档维护工作流
日常维护流程
- 代码变更 → 2. 识别影响的文档 → 3. 更新相关文档 → 4. 验证文档准确性 → 5. 提交变更
文档质量检查清单
- 文档结构符合标准模板
- 内容与实际代码一致
- API 文档包含完整示例
- 业务逻辑描述清晰
- 技术实现有详细说明
- 变更历史有记录
文档版本管理
- 版本号规则：主版本.次版本.修订版本 (如：1.2.3)
- 变更记录：每次更新记录变更内容和原因
- 向后兼容：重大变更需要保留历史版本说明
📚 模块间集成指南
模块依赖关系
graph TD
A[用户管理模块] --> B[系统管理模块]
A --> C[满意度调查模块]
A --> D[报告厅预约模块]
B --> C
B --> D
C --> E[数据分析模块]
D --> F[工作流引擎]
公共服务模块
- 用户认证服务：所有模块的用户身份验证
- 权限控制服务：统一的权限管理
- 通知服务：跨模块的消息通知
- 文件服务：文件上传和存储
- 数据字典服务：系统配置和枚举值
接口调用规范
- 统一响应格式：所有模块使用相同的响应结构
- 错误码标准：统一的错误码定义和处理
- 接口版本管理：API 版本兼容性处理
- 性能要求：响应时间和并发量标准
🚀 下一步行动计划
近期任务（2 周内）
- 完善报告厅预约模块的技术设计文档
- 补充满意度调查模块的运维文档
- 建立模块间接口测试用例
- 优化文档模板，提升 AI 理解度
中期规划（1 个月内）
- 启动维修服务模块的需求分析
- 建立自动化文档生成流程
- 完善模块间集成测试
- 建立文档质量评估体系
长期愿景（3 个月内）
- 实现文档与代码的自动同步
- 建立智能化的模块推荐系统
- 完成所有计划模块的开发
- 建立模块复用和扩展机制
📖 相关文档
- 项目总览：项目总览
- 开发指南：开发文档
- API 文档：开发文档/API.md
- 变更管理：变更管理