# Cow_horse工时报告系统 **Repository Path**: lainyu/cowhorse_workhour_sys_report ## Basic Information - **Project Name**: Cow_horse工时报告系统 - **Description**: 这是一个基于人工智能驱动的工时日志自动总结汇报系统，通过集成先进的AI技术，实现工时数据的智能分析与汇报。系统采用现代化的技术架构，提供友好的Web界面和完整的RESTful API服务。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-04 - **Last Updated**: 2025-07-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🐂 牛马工时日志汇报系统 ## 📝 项目介绍 这是一个基于人工智能驱动的工时日志自动总结汇报系统，通过集成先进的AI技术，实现工时数据的智能分析与汇报。系统采用现代化的技术架构，提供友好的Web界面和完整的RESTful API服务。 ![](assets/webui_stable.png) ### ✨ 核心特性 - **🤖 智能汇报**: 基于Deepseek-V3大模型的工时日志智能总结 - **🎨 友好界面**: Streamlit提供的现代化Web交互界面 - **🔍 灵活查询**: 支持多维度条件查询（人员、部门、项目） - **🌐 RESTful API**: 完整的API接口支持，便于系统集成 - **📊 数据可视化**: 丰富的图表展示和数据分析 - **💬 自然语言查询**: 支持Chatbot形式的自然语言查询 - **⚡ 高性能**: 优化的数据库查询和缓存机制 ## 🛠 技术架构 ### 核心技术栈 - **前端界面**: Streamlit - 快速构建数据应用的Python框架 - **AI引擎**: 硅基流动 Deepseek-V3 - 提供智能文本总结能力 - **数据存储**: MySQL - 稳定可靠的关系型数据库 - **API框架**: FastAPI - 构建高性能RESTful服务 - **ORM框架**: SQLAlchemy - 数据库对象关系映射 - **AI集成**: LangChain - AI应用开发框架 ### 系统架构设计 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Streamlit │ │ FastAPI │ │ MySQL │ │ Web界面 │◄──►│ API服务 │◄──►│ 数据存储 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Deepseek-V3 │ │ AI总结服务 │ └─────────────────┘ ``` ### 推荐架构模式 1. **分层架构**: - 表现层 (Streamlit Web UI) - 服务层 (FastAPI REST Services) - 数据访问层 (SQLAlchemy ORM) - 数据层 (MySQL Database) 2. **服务拆分**: - 用户界面服务 (Streamlit) - 业务逻辑服务 (FastAPI) - AI处理服务 (Deepseek-V3 集成) - 数据服务 (MySQL) ## 🔌 API接口设计 ### 主要接口 #### 1. 综合查询接口 ```http POST /api/v1/reports Content-Type: application/json ``` **请求体示例:** ```json { "peopleName": "张三", // 员工姓名（可选） "framework": "技术部", // 部门名称（可选） "projectId": "PROJ001", // 项目ID（可选） "dateRange": { // 时间范围 "startDate": "2024-01-01", "endDate": "2024-01-31" } } ``` **响应示例:** ```json { "code": 200, "message": "查询成功", "data": { "summary": "AI生成的工时总结", "totalHours": 160, "details": [...] } } ``` #### 2. 按人员查询 ```http GET /api/v1/people/{peopleName}/worklogs ``` #### 3. 按部门查询 ```http GET /api/v1/frameworks/{frameworkName}/worklogs ``` #### 4. 按项目查询 ```http GET /api/v1/projects/{projectId}/worklogs ``` #### 5. 健康检查 ```http GET /api/v1/health ``` ### API文档 - **Swagger UI**: `http://localhost:8500/docs` - **ReDoc**: `http://localhost:8500/redoc` ## 💾 数据库设计 ### 数据库配置 - **数据库类型**: MySQL 8.0+ - **访问地址**: 192.168.1.25 - **端口**: 3306 - **账号**: agi - **密码**: The password ### 数据表结构 #### 1. framework (部门表) | 字段名 | 类型 | 说明 | |--------|------|------| | id | INT | 主键，部门ID | | FrameworkName | VARCHAR(100) | 部门名称 | | Description | TEXT | 部门描述 | | CreateTime | DATETIME | 创建时间 | #### 2. Peopleinf (员工表) | 字段名 | 类型 | 说明 | |--------|------|------| | id | INT | 主键，员工ID | | PeopleName | VARCHAR(50) | 员工姓名 | | FrameworkId | INT | 部门ID，外键关联framework.id | | CreateTime | DATETIME | 创建时间 | #### 3. ProjectInf (项目表) | 字段名 | 类型 | 说明 | |--------|------|------| | Id | INT | 主键，项目数据ID | | ProjectId | VARCHAR(50) | 项目编号 | | ProjectName | VARCHAR(200) | 项目名称 | | ProjectType | VARCHAR(50) | 项目类型 | | ProjectState | VARCHAR(45) | 项目状态（已结项，暂停中，进行中） | | CreateTime | DATETIME | 创建时间 | #### 4. log (工时日志表) | 字段名 | 类型 | 说明 | |--------|------|------| | LogId | INT | 主键，日志ID | | PeopleName | VARCHAR(50) | 员工姓名 | | ProjectDataId | INT | 项目数据ID，外键关联ProjectInf.Id | | LogText | TEXT | 工时日志内容 | | WorkHour | DECIMAL(5,2) | 工时数量 | | WorkHourType | VARCHAR(20) | 工时类型（正常/加班/请假等） | | CreateTime | DATETIME | 创建时间 | ### 表关系 ```sql -- 外键约束 ALTER TABLE Peopleinf ADD CONSTRAINT FK_People_Framework FOREIGN KEY (FrameworkId) REFERENCES framework(id); ALTER TABLE log ADD CONSTRAINT FK_Log_Project FOREIGN KEY (ProjectDataId) REFERENCES ProjectInf(Id); ``` ## 📁 项目结构 ``` cowhourse_workinghours/ ├── app.py # Streamlit主应用 ├── api/ # FastAPI应用 │ ├── __init__.py │ ├── main.py # FastAPI主入口 │ ├── routers/ # API路由 │ │ ├── health.py # 健康检查 │ │ ├── reports.py # 报告相关 │ │ ├── people.py # 人员相关 │ │ ├── frameworks.py # 部门相关 │ │ └── projects.py # 项目相关 │ └── models/ # 数据模型 │ ├── models.py # SQLAlchemy模型 │ └── schemas.py # Pydantic模式 ├── database/ # 数据库相关 │ ├── __init__.py │ └── connection.py # 数据库连接 ├── services/ # 业务服务 │ ├── report_service.py # 报告生成服务 │ ├── system_prompt.py # AI系统提示词 │ └── example_usage.py # 使用示例 ├── utils/ # 工具模块 │ ├── config.py # 配置管理 │ ├── logger.py # 日志管理 │ └── tools.py # 工具函数 ├── tests/ # 测试文件 │ ├── test_ai_service.py │ ├── test_logger.py │ ├── test_models.py │ └── examples.py ├── assets/ # 静态资源 ├── logs/ # 日志文件 ├── output/ # 输出文件 ├── pyproject.toml # 项目配置和依赖管理 ├── uv.lock # 依赖锁定文件 ├── strings.py # 字符串常量 ├── streamlit_requests.py # Streamlit请求工具 └── README.md # 项目文档 ``` ## 🔧 开发指南 ### 环境要求 - Python 3.9+ - MySQL 8.0+ - uv (Python包管理器) ### 依赖管理 项目使用 `pyproject.toml` 文件管理依赖和配置： - **基础依赖**: Streamlit、FastAPI、SQLAlchemy、Deepseek API等 - **开发依赖**: 测试框架、代码格式化工具、类型检查等 - **生产依赖**: Gunicorn、Redis、错误监控等 ```bash # 安装基础依赖 uv sync # 安装开发依赖 uv sync --extra dev # 安装生产依赖 uv sync --extra prod # 安装所有依赖 uv sync --all-extras ``` ### 环境变量配置 ```env # 数据库配置 DB_HOST=192.168.1.25 DB_PORT=3306 DB_USER=agi DB_PASSWORD=The password DB_NAME=workhourmanagementdb_v2 # AI服务配置 DEEPSEEK_API_KEY=your_api_key_here DEEPSEEK_BASE_URL=https://api.siliconflow.cn/v1 DEEPSEEK_MODEL=deepseek-ai/DeepSeek-V3 DEEPSEEK_MAX_TOKENS=30000 DEEPSEEK_TEMPERATURE=0 # 应用配置 APP_ENV=development DEBUG=True LOG_LEVEL=INFO STREAMLIT_PORT=8501 API_PORT=8500 API_HOST=0.0.0.0 ``` ## 🚀 快速开始 ### 1. 克隆项目 ```bash git clone cd cowhourse_workinghours ``` ### 2. 安装依赖 ```bash uv sync ``` ### 3. 配置环境变量 ```bash cp .env.example .env # 编辑 .env 文件，配置数据库连接和API密钥 ``` ### 4. 启动服务 ```bash # 启动 Streamlit 应用 uv run streamlit run app.py # 启动 API 服务 (另开终端) uv run python -m api.main ``` ### 5. 访问应用 - **Streamlit界面**: http://localhost:8501 - **API文档**: http://localhost:8500/docs ## 📊 功能特性详解 ### 1. 固定查询功能 - **多维度筛选**: 支持按员工、部门、项目、时间范围进行组合查询 - **智能时间限制**: 根据查询类型自动调整时间范围限制 - **快捷选项**: 提供常用的时间范围快捷选择 - **实时验证**: 查询条件实时验证和提示 ### 2. Chatbot查询功能 - **自然语言处理**: 支持中文自然语言查询 - **智能SQL生成**: 自动将自然语言转换为SQL查询 - **安全查询**: 只允许SELECT查询，确保数据安全 - **结果可视化**: 查询结果自动生成图表展示 ### 3. AI报告生成 - **智能总结**: 基于工时数据自动生成工作总结 - **多格式输出**: 支持HTML和Markdown格式 - **数据统计**: 自动计算工时统计和趋势分析 - **个性化配置**: 支持自定义报告模板和样式 ### 4. 数据可视化 - **图表展示**: 工时分布、趋势分析、对比图表 - **交互式图表**: 支持图表交互和数据钻取 - **实时更新**: 数据变化时图表自动更新 - **导出功能**: 支持图表和数据导出 ## 🔒 安全特性 ### 1. 数据安全 - **查询限制**: 只允许SELECT查询，防止数据修改 - **参数验证**: 严格的输入参数验证和过滤 - **SQL注入防护**: 使用参数化查询防止SQL注入 ### 2. API安全 - **CORS配置**: 可配置的跨域资源共享策略 - **请求限制**: 支持API请求频率限制 - **错误处理**: 统一的错误处理和日志记录 ### 3. 环境安全 - **环境变量**: 敏感信息通过环境变量管理 - **配置分离**: 开发和生产环境配置分离 - **日志脱敏**: 敏感信息在日志中自动脱敏 ## 📈 性能优化 ### 1. 数据库优化 - **连接池**: 使用数据库连接池提高性能 - **查询优化**: 优化的SQL查询和索引设计 - **缓存机制**: 对频繁查询的数据进行缓存 ### 2. API优化 - **异步处理**: AI总结服务采用异步处理模式 - **分页查询**: 大数据量查询实现分页功能 - **响应压缩**: 支持响应数据压缩 ### 3. 前端优化 - **数据缓存**: 前端数据缓存减少重复请求 - **懒加载**: 图表和数据懒加载 - **状态管理**: 高效的页面状态管理 ## 🧪 测试 ### 测试覆盖 - **单元测试**: 核心业务逻辑单元测试 - **集成测试**: API接口集成测试 - **端到端测试**: 完整业务流程测试 ### 运行测试 ```bash # 运行所有测试 uv run pytest # 运行特定测试 uv run pytest tests/test_ai_service.py # 生成测试覆盖率报告 uv run pytest --cov=. --cov-report=html ``` ## 🤝 贡献指南 ### 开发流程 1. Fork项目到个人仓库 2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建Pull Request ### 代码规范 - 遵循PEP 8代码风格 - 使用类型注解 - 编写详细的文档字符串 - 添加适当的单元测试 ### 提交规范 使用约定式提交格式： ``` feat: 添加新功能 fix: 修复bug docs: 更新文档 style: 代码格式调整 refactor: 代码重构 test: 添加测试 chore: 构建过程或辅助工具的变动 ``` ## 📄 许可证 本项目采用 [MIT License](LICENSE) 许可证。 ## 📞 联系方式 如有问题或建议，请通过以下方式联系： - 提交Issue: [GitHub Issues](https://github.com/yourusername/cowhourse-workinghours/issues) - 邮箱: your.email@example.com --- **注意**: 部署相关文档请参考 [DEPLOY.md](DEPLOY.md)