集成Claude代码的时间报告系统
一个时间报告系统，将Claude Code与基于GraphQL的自定义时间跟踪器集成在一起，使开发人员能够通过自然语言命令自动或手动跟踪编码任务所花费的时间。
______________________________________________________________________
🚀 快速开始
使用3个命令启动并运行：
# 1. Clone the repository
git clone https://github.com/YOUR_USERNAME/time-reporting-system.git
cd time-reporting-system
# 2. Login to Azure and setup environment
az login
./setup.sh
source env.sh
# 3. Deploy the full stack (database + API)
/deploy就是这样！ 身份验证使用Azure Entra ID:
- ✅
az login使用您的Azure帐户进行身份验证 - ✅
./setup.sh验证Azure身份验证→ 创造env.sh - ✅
source env.sh将环境变量导出到shell - ✅ MCP服务器使用
AzureCliCredential自动获取代币 - ✅ GraphQL API通过Microsoft验证JWT令牌。身份。网络
- ✅ 无承载令牌或秘密-使用Azure AD身份验证
- ✅ 用户跟踪：时间条目包括您的Azure AD身份
100%Azure AD身份验证-安全且可审计！
______________________________________________________________________
🎯 概述
此项目允许您：
- 记录时间条目 直接从Claude Code使用自然语言
- 管理时间条目 （创建、更新、删除、在项目之间移动）
- 提交参赛作品 用于审批工作流
- 查询时间数据 带柔性过滤器
- 单一技术栈 -一切都用C#！
______________________________________________________________________
🏗️ 建筑
Claude Code (Natural Language)
↓ stdio (JSON-RPC)
C# MCP Server (Console App ~200 lines!)
↓ HTTP/GraphQL
C# GraphQL API (ASP.NET Core + HotChocolate)
↓ Entity Framework
PostgreSQL Database组件：
- PostgreSQL 16 -数据持久性
- ASP。NET Core 10+热巧克力 -GraphQL API
- C#控制台应用程序 -MCP服务器（简单！）
- Docker/Podman -容器编排
______________________________________________________________________
📚 文档
入门指南
- 实施总结 - ⭐ 从这里开始！ 简化方法的快速概述
- 安装指南 -使用MCP服务器配置Claude代码
- 部署指南 -使用Docker/Podman进行部署
- 用户指南 -自然语言时间跟踪命令
- Podman设置 -使用Podman代替Docker桌面
技术文档
产品规格
- 产品要求文件（PRD） -完整的产品规格
- 建筑规范（PRD） -详细的实现规范和代码示例
- API 规范 -GraphQL模式和示例
- ADR指数 -架构决策记录
实施指南
实施任务
- 第一阶段： 数据库和基础设施（3项任务）
- 第二阶段： GraphQL API-核心设置（5项任务）
- 第三阶段： GraphQL API-查询（5个任务）
- 第四阶段： GraphQL API-变体第1部分（5项任务）
- 第五阶段： GraphQL API-变体第2部分（5项任务）
- 第6阶段： GraphQL API-Docker（4项任务）
- 第7阶段： MCP服务器-设置（4个任务）
- 第8阶段： MCP服务器-工具第1部分（4个任务）
- 第9阶段： MCP服务器-工具第2部分（4个任务）
- 第10阶段： MCP服务器-自动跟踪（4个任务）
- 第11阶段： 集成与测试（5项任务）
- 第12阶段： 文档和部署（5项任务）
- 第13阶段： 草莓奶昔迁移（4个任务）
总计： 65项任务，约58-72小时
______________________________________________________________________
📋 先决条件
- Docker或Podman (Podman设置指南)
- .NET 10 SDK （适用于API和MCP服务器）
- 克劳德代码 安装
- PostgreSQL客户端 （可选，用于测试）
有关详细的部署说明，请参阅 部署指南.
开发流程
贡献或扩展系统：
# 1. Follow the Task Index
open docs/TASK-INDEX.md
# 2. Read task guides
cd docs/tasks/
# 3. Run tests
/test
# 4. Build and deploy
/build
/deploy______________________________________________________________________
💡 使用示例
一旦实施，您将能够：
User: "Log 8 hours of development work on INTERNAL project for today"
Claude Code: "Time entry created successfully! Entry ID: abc-123, Status: NOT_REPORTED"
User: "Show me all time entries for this week"
Claude Code: "Found 5 entries:
1. INTERNAL - Development - 8.0 hours (Oct 21)
2. CLIENT-A - Bug Fixing - 6.5 hours (Oct 22)
..."
User: "Move yesterday's entry from INTERNAL to CLIENT-A Feature Development"
Claude Code: "Entry moved to CLIENT-A - Feature Development"
User: "Submit all my time entries for approval"
Claude Code: "Submitted 5 time entries for approval"______________________________________________________________________
🗂️ 项目结构
claude-code-time-reporting/
├── .claude/ # Claude Code configuration
│ ├── commands/ # Custom slash commands
│ └── hooks/ # Pre-bash and guardrail hooks
├── docs/ # Documentation
│ ├── adr/ # Architecture Decision Records
│ ├── integration/ # Integration guides
│ ├── prd/ # Product Requirements Document
│ ├── tasks/ # Phase-by-phase implementation guides
│ ├── workflows/ # Workflow test documentation
│ ├── ARCHITECTURE.md # Main architecture documentation
│ ├── API.md # GraphQL API reference
│ ├── DEPLOYMENT.md # Deployment guide
│ └── USER_GUIDE.md # User guide for natural language commands
├── db/
│ └── schema/ # SQL schema and seed data
├── scripts/ # Utility scripts
│ └── generate-token.sh # Token generation script
├── tests/ # Test files
│ ├── e2e/ # End-to-end test scenarios
│ └── integration/ # Integration test scripts
├── TimeReportingApi/ # C# GraphQL API ✅
├── TimeReportingApi.Tests/ # API unit tests ✅
├── TimeReportingMcp/ # C# MCP Server ✅
├── TimeReportingMcp.Tests/ # MCP Server unit tests ✅
├── TimeReportingSeeder/ # Database seeder ✅
├── TimeReportingAnalyzers/ # Roslyn analyzers ✅
├── docker-compose.yml # Container orchestration
├── Directory.Build.props # Shared MSBuild properties
├── Directory.Packages.props # Central Package Management
├── setup.sh # Setup script (generates env.sh)
├── run-mcp.sh # MCP server wrapper script
├── .env.example # Environment variable template
├── .mcp.json # MCP server configuration
└── README.md # This file
Note: env.sh (generated by setup.sh) contains secrets and is in .gitignore______________________________________________________________________
🎓 学习路径
- 从这里开始 -阅读 实施总结 ⭐
- 了解产品 -阅读 产品需求文档
- 审查架构 -学习 建筑 （请参阅C#MCP服务器代码！）
- 检查数据模型 -了解 数据模型
- 开始实施 -跟随 任务索引 依次
- 使用Podman？ -阅读 Podman设置指南
______________________________________________________________________
🔧 技术栈
单一语言：C#🎯
- C净值10 -一切（API+MCP服务器）
- 热巧克力13+ -GraphQL服务器
- 实体框架核心10 -ORM
- 草莓奶昔15 -具有代码生成功能的强类型GraphQL客户端
- PostgreSQL 16 -数据库
基础设施
- Docker或Podman -集装箱化
- Docker作曲/Podman作曲 -多容器编排
代码生成
- 草莓奶昔 自动生成C#客户端代码
.graphql操作文件 - 为所有GraphQL操作提供编译时类型安全和IntelliSense
- 消除了约250行手动类型定义和查询字符串
没有Node.js，没有TypeScript，只有C#！ 🎉
______________________________________________________________________
📊 数据模型摘要
核心实体
- 时间输入 -个人时间日志记录
- 项目、任务、工时（标准/加班） - 开始/完成日期 - 状态工作流、标签、描述
- 项目 -可用项目
- 代码、名称、活动状态 - 可用任务、标签配置
- 项目任务 -每个项目允许的任务
- 项目标签 -每个项目的元数据标记（允许的值使用TagValue）
- 标签名称，允许值
______________________________________________________________________
🔒 安全
- Azure Entra ID身份验证 用于API访问和JWT令牌验证
- 用户身份跟踪 -所有时间条目都包含Azure AD用户信息
- 输入验证 多层（MCP、GraphQL、业务逻辑、数据库）
- 环境变量 用于配置（不存储机密）
- AzureCliCredential 为了地方发展， Managed身份 用于生产
______________________________________________________________________
📈 路线图
v1.0（完成！✅)
- ✅ 完成PRD和任务分解
- ✅ PostgreSQL数据库设置
- ✅ C#GraphQL API实现（4个查询，8个突变）
- ✅ 带有11个工具的C#MCP服务器
- ✅ 带有智能建议的自动跟踪
- ✅ StrawberryShake类型的GraphQL客户端迁移
- ✅ Docker/Podman部署
- ✅ 全面的文件
- ✅ E2E测试和集成指南
状态： 生产准备就绪！全部65项任务已完成（100%）
文档：
- 自然语言命令用户指南
- API文档及示例
- Claude代码集成设置指南
- Docker/Podman部署指南
- 带图表的架构文档
v2.0（未来增强功能）
- 具有身份验证/授权的多用户支持
- 用于管理员配置的Web UI
- 实时定时器功能
- JIRA/GitHub问题集成
- 高级报告和分析
- 移动应用程序
- 批准通知（电子邮件/Slack）
- 团队仪表板
______________________________________________________________________
🤝 贡献
遵循基于任务的工作流程：
- 从中选择任务 任务索引md
- 阅读任务的详细实施指南
- 根据验收标准实施
- 彻底测试
- 在索引中勾选任务
- 转到下一个任务
______________________________________________________________________
📝 许可证
\[您的许可证在这里\]
______________________________________________________________________
🆘 支持
如有疑问或问题：
______________________________________________________________________
🎉 准备好使用了吗？
用户（部署和使用）
👉 从这里开始： 部署指南
开发者（贡献或扩展）
👉 从这里开始： 任务索引
- 审查已完成的实施情况
- 了解架构(建筑)
- 遵循TDD工作流程以获取新功能
______________________________________________________________________
🌟 v1.0的新增功能
第12阶段完成-完整文档套件！