克劳德代码时间报告
项目介绍
集成Claude Code的时间报告系统
一个集成了Claude Code的自定义GraphQL时间跟踪器的时间报告系统，使开发者能够通过自然语言命令自动或手动记录编码任务所花费的时间。
🚀 快速开始
三步启动：
# 1. 克隆仓库
git clone https://github.com/YOUR_USERNAME/time-reporting-system.git
cd time-reporting-system
# 2. 登录Azure并设置环境
az login
./setup.sh
source env.sh
# 3. 部署全栈（数据库 + API）
/deploy
就这样！ 认证使用Azure Entra ID：
- ✅
az login使用您的Azure账户进行认证 - ✅
./setup.sh验证Azure认证 → 创建env.sh - ✅
source env.sh导出环境变量到shell - ✅ MCP服务器使用
AzureCliCredential自动获取令牌 - ✅ GraphQL API 使用Microsoft.Identity.Web验证JWT令牌
- ✅ 不使用Bearer令牌或密钥 - 使用Azure AD认证
- ✅ 用户追踪：时间条目包括您的Azure AD身份
100% Azure AD认证 - 安全且可审计！
🎯 概览
本项目允许您：
- 从Claude Code直接记录时间条目 使用自然语言
- 管理时间条目 （创建、更新、删除、在项目之间移动）
- 提交条目 进入审批流程
- 查询时间数据 使用灵活的过滤器
- 单一技术栈 - C#用于一切！
🏗️ 架构
Claude Code (自然语言)
↓ stdio (JSON-RPC)
C# MCP服务器 (控制台应用 ~200行！)
↓ HTTP/GraphQL
C# GraphQL API (ASP.NET Core + HotChocolate)
↓ Entity Framework
PostgreSQL数据库
组件：
- PostgreSQL 16 - 数据持久化
- ASP.NET Core 10 + HotChocolate - GraphQL API
- C# 控制台应用 - MCP服务器（简单！）
- Docker/Podman - 容器编排
📚 文档
入门指南
- 实现概要 - ⭐ 从这里开始！ 简化的快速概述
- 配置指南 - 配置Claude Code与MCP服务器
- 部署指南 - 使用Docker/Podman部署
- 用户指南 - 自然语言时间跟踪命令
- Podman配置 - 使用Podman而不是Docker Desktop
技术文档
产品规格
- 产品需求文档 (PRD) - 完整的产品规范
- 架构规范 (PRD) - 带有代码示例的详细实施规范
- API规范 - GraphQL模式和示例
- 架构决策记录索引 - 架构决策记录
实现指南
实现任务
- 阶段1: 数据库及基础设施 (3个任务)
- 阶段2: GraphQL API - 核心设置 (5个任务)
- 阶段3: GraphQL API - 查询 (5个任务)
- 阶段4: GraphQL API - 变异部分1 (5个任务)
- 阶段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: StrawberryShake迁移 (4个任务)
总计: 65个任务，约58-72小时
📋 先决条件
- Docker或Podman (Podman配置指南)
- .NET 10 SDK (用于API和MCP服务器)
- 已安装Claude Code
- PostgreSQL客户端 (可选，用于测试)
详细的部署说明，请参阅部署指南。
开发工作流
要贡献或扩展系统：
# 1. 跟随任务索引
open docs/TASK-INDEX.md
# 2. 阅读任务指南
cd docs/tasks/
# 3. 运行测试
/test
# 4. 构建和部署
/build
/deploy
💡 使用示例
一旦实现，您可以：
用户: "记录今天在INTERNAL项目上花费了8个小时的开发工作"
Claude Code: "时间条目创建成功！条目ID: abc-123, 状态: NOT_REPORTED"
用户: "显示本周的所有时间条目"
Claude Code: "找到5个条目:
1. INTERNAL - 开发 - 8.0小时 (10月21日)
2. CLIENT-A - 修复错误 - 6.5小时 (10月22日)
..."
用户: "将昨天的条目从INTERNAL移到CLIENT-A特性开发"
Claude Code: "条目已移至CLIENT-A - 特性开发"
用户: "提交我的所有时间条目以供审批"
Claude Code: "提交了5个时间条目以供审批"
🗂️ 项目结构
claude-code-time-reporting/
├── .claude/ # Claude Code配置
│ ├── commands/ # 自定义斜杠命令
│ └── hooks/ # 预bash和护栏钩子
├── docs/ # 文档
│ ├── adr/ # 架构决策记录
│ ├── integration/ # 集成指南
│ ├── prd/ # 产品需求文档
│ ├── tasks/ # 分阶段实现指南
│ ├── workflows/ # 流程测试文档
│ ├── ARCHITECTURE.md # 主架构文档
│ ├── API.md # GraphQL API参考
│ ├── DEPLOYMENT.md # 部署指南
│ └── USER_GUIDE.md # 自然语言命令用户指南
├── db/
│ └── schema/ # SQL模式和种子数据
├── scripts/ # 实用脚本
│ └── generate-token.sh # 令牌生成脚本
├── tests/ # 测试文件
│ ├── e2e/ # 端到端测试场景
│ └── integration/ # 集成测试脚本
├── TimeReportingApi/ # C# GraphQL API ✅
├── TimeReportingApi.Tests/ # API单元测试 ✅
├── TimeReportingMcp/ # C# MCP服务器 ✅
├── TimeReportingMcp.Tests/ # MCP服务器单元测试 ✅
├── TimeReportingSeeder/ # 数据库播种器 ✅
├── TimeReportingAnalyzers/ # Roslyn分析器 ✅
├── docker-compose.yml # 容器编排
├── Directory.Build.props # 共享MSBuild属性
├── Directory.Packages.props # 中央包管理
├── setup.sh # 设置脚本（生成env.sh）
├── run-mcp.sh # MCP服务器包装脚本
├── .env.example # 环境变量模板
├── .mcp.json # MCP服务器配置
└── README.md # 此文件
注意：env.sh（由setup.sh生成）包含秘密信息，并被.gitignore忽略
🎓 学习路径
- 从这里开始 - 阅读实现概要 ⭐
- 理解产品 - 阅读PRD
- 回顾架构 - 学习架构（查看C# MCP服务器代码！）
- 检查数据模型 - 理解数据模型
- 开始实现 - 按顺序跟随任务索引
- 使用Podman？ - 阅读Podman配置指南
🔧 技术栈
单一语言：C# 🎯
- C# / .NET 10 - 一切（API + MCP服务器）
- HotChocolate 13+ - GraphQL服务器
- Entity Framework Core 1.0 - ORM
- StrawberryShake 15 - 强类型GraphQL客户端，带代码生成
- PostgreSQL 16 - 数据库
基础设施
- Docker或Podman - 容器化
- Docker Compose / Podman Compose - 多容器编排
代码生成
- StrawberryShake 自动从
.graphql操作文件生成C#客户端代码 - 提供所有GraphQL操作的编译时类型安全和IntelliSense
- 消除约250行的手动类型定义和查询字符串
没有Node.js，没有TypeScript - 只有C#! 🎉
📊 数据模型概要
核心实体
-
TimeEntry - 个别时间日志记录
- 项目，任务，小时数（标准/加班）
- 开始/完成日期
- 状态工作流，标签，描述
-
Project - 可用项目
- 编码，名称，活动状态
- 可用任务，标签配置
-
ProjectTask - 每个项目允许的任务
-
ProjectTag - 每个项目元数据标签（带有TagValue允许值）
- 标签名，允许值
🔒 安全
- Azure Entra ID认证 对API访问进行JWT令牌验证
- 用户身份追踪 - 所有时条目都包含Azure AD用户信息
- 多层输入验证 （MCP，GraphQL，业务逻辑，数据库）
- 环境变量 配置（不存储秘密）
- AzureCliCredential 本地开发，ManagedIdentity 生产
📈 发展路线图
v1.0（已完成！✅）
- ✅ 完整的PRD和任务分解
- ✅ PostgreSQL数据库设置
- ✅ C# GraphQL API实现（4个查询，8个变异）
- ✅ 带有7个工具的C# MCP服务器
- ✅ 带智能建议的自动追踪
- ✅ StrawberryShake强类型GraphQL客户端迁移
- ✅ Docker/Podman部署
- ✅ 综合文档
- ✅ 端到端测试和集成指南
状态： 生产就绪！所有65个任务已完成（100%）
文档：
- 自然语言命令用户指南
- 带示例的API文档
- Claude Code集成设置指南
- Docker/Podman部署指南
- 带图表的架构文档
v2.0（未来增强）
- 多用户支持，带认证/授权
- 管理员配置的Web UI
- 实时计时器功能
- JIRA/GitHub问题集成
- 高级报告和分析
- 移动应用
- 审批通知（电子邮件/Slack）
- 团队仪表板
🤝 贡献
遵循基于任务的工作流程：
- 从TASK-INDEX.md中选择一个任务
- 阅读任务的详细实施指南
- 根据验收标准实施
- 彻底测试
- 在索引中勾选任务
- 转到下一个任务
📝 许可
[您的许可在这里]
🆘 支持
对于问题或问题：
🎉 准备使用？
对于用户（部署和使用）
👉 从这里开始： 部署指南
对于开发者（贡献或扩展）
👉 从这里开始： 任务索引
- 审查已完成的实现
- 理解架构 (架构)
- 遵循TDD工作流程以添加新功能
🌟 v1.0的新内容
阶段12完成 - 完整的文档套件！