Accounting MCP Server

# TDD 开发计划 - 记账 MCP 工具 ## TDD 开发方法论 ### 核心原则 1. **红**: 先写测试用例（失败） 2. **绿**: 编写最小实现（通过） 3. **重构**: 优化代码质量 ### 测试层次 - **单元测试**: 测试单个函数/方法 - **集成测试**: 测试 MCP 协议通信 - **端到端测试**: 测试完整用户场景 ## 开发迭代计划 ### 迭代 1: 数据模型和存储 📚 **🔴 红阶段 - 编写失败测试** ```python # tests/test_models.py def test_transaction_creation(): """测试交易记录创建""" # 应该失败：Transaction 类还不存在 pass def test_transaction_validation(): """测试交易数据验证""" # 应该失败：验证逻辑还没实现 pass # tests/test_storage.py def test_json_storage_save_load(): """测试 JSON 文件存储和读取""" # 应该失败：Storage 类还不存在 pass ``` **🟢 绿阶段 - 最小实现** - 创建 `models.py` 中的 `Transaction` 类 - 实现基础的数据验证 - 创建 `storage.py` 中的 `JSONStorage` 类 **🔄 重构阶段** - 优化数据模型设计 - 添加更多验证逻辑 - 改进错误处理 ### 迭代 2: MCP 服务器框架 🔧 **🔴 红阶段 - 编写失败测试** ```python # tests/test_mcp_server.py def test_server_initialization(): """测试 MCP 服务器初始化""" pass def test_tools_registration(): """测试工具注册功能""" pass def test_resources_registration(): """测试资源注册功能""" pass ``` **🟢 绿阶段 - 最小实现** - 使用 MCP Python SDK 创建基础服务器 - 实现工具和资源的注册机制 - 建立 stdio 通信框架 **🔄 重构阶段** - 抽象通用的 MCP 服务器逻辑 - 优化错误处理和日志记录 - 改进代码结构 ### 迭代 3: 核心工具实现 ⚡ **🔴 红阶段 - 编写失败测试** ```python # tests/test_tools.py def test_add_transaction_tool(): """测试添加交易工具""" # 测试正常添加 # 测试参数验证 # 测试错误处理 pass def test_get_balance_tool(): """测试余额查询工具""" pass def test_list_transactions_tool(): """测试交易记录查询工具""" pass ``` **🟢 绿阶段 - 最小实现** - 实现 `add_transaction` 工具 - 实现 `get_balance` 工具 - 实现 `list_transactions` 工具 **🔄 重构阶段** - 抽象通用的工具逻辑 - 优化参数验证 - 改进性能 ### 迭代 4: MCP 资源实现 📊 **🔴 红阶段 - 编写失败测试** ```python # tests/test_resources.py def test_transactions_resource(): """测试交易记录资源""" pass def test_categories_resource(): """测试分类列表资源""" pass def test_summary_resource(): """测试汇总信息资源""" pass ``` **🟢 绿阶段 - 最小实现** - 实现 `transactions://all` 资源 - 实现 `categories://list` 资源 - 实现 `summary://current` 资源 **🔄 重构阶段** - 优化资源访问性能 - 改进数据格式 - 添加缓存机制 ### 迭代 5: 高级功能 🚀 **🔴 红阶段 - 编写失败测试** ```python # tests/test_advanced.py def test_monthly_summary_tool(): """测试月度汇总工具""" pass def test_category_filtering(): """测试分类筛选功能""" pass def test_date_range_queries(): """测试日期范围查询""" pass ``` **🟢 绿阶段 - 最小实现** - 实现 `get_monthly_summary` 工具 - 添加高级筛选功能 - 实现日期范围查询 **🔄 重构阶段** - 优化查询性能 - 改进用户体验 - 添加更多统计功能 ## 测试策略详细规划 ### 单元测试覆盖范围 **models.py 模块测试** ```python class TestTransaction: def test_valid_transaction_creation(self): """测试有效交易创建""" def test_invalid_amount_validation(self): """测试无效金额验证""" def test_invalid_category_validation(self): """测试无效分类验证""" def test_date_parsing(self): """测试日期解析""" ``` **storage.py 模块测试** ```python class TestJSONStorage: def test_empty_file_initialization(self): """测试空文件初始化""" def test_data_persistence(self): """测试数据持久化""" def test_file_corruption_recovery(self): """测试文件损坏恢复""" def test_concurrent_access(self): """测试并发访问""" ``` **server.py 模块测试** ```python class TestMCPServer: def test_tool_registration(self): """测试工具注册""" def test_resource_registration(self): """测试资源注册""" def test_json_rpc_handling(self): """测试 JSON-RPC 消息处理""" def test_error_responses(self): """测试错误响应""" ``` ### 集成测试场景 **MCP 协议通信测试** ```python class TestMCPIntegration: def test_stdio_communication(self): """测试 stdio 通信""" # 模拟完整的 JSON-RPC 请求响应 def test_tool_invocation_flow(self): """测试工具调用流程""" # 端到端测试工具调用 def test_resource_access_flow(self): """测试资源访问流程""" # 端到端测试资源访问 ``` ### 端到端测试场景 **用户场景测试** ```python class TestUserScenarios: def test_basic_accounting_flow(self): """测试基础记账流程""" # 1. 添加收入 # 2. 添加支出 # 3. 查询余额 # 4. 查看交易记录 def test_monthly_analysis_flow(self): """测试月度分析流程""" # 1. 添加多笔交易 # 2. 查询月度汇总 # 3. 按分类统计 def test_error_handling_flow(self): """测试错误处理流程""" # 1. 无效输入处理 # 2. 文件权限错误 # 3. 数据损坏恢复 ``` ## 开发工具和配置 ### 测试框架选择 - **pytest**: 主要测试框架 - **pytest-cov**: 代码覆盖率 - **pytest-mock**: Mock 对象支持 - **pytest-asyncio**: 异步测试支持 ### 代码质量工具 - **black**: 代码格式化 - **flake8**: 代码风格检查 - **mypy**: 类型检查 - **pre-commit**: 提交前检查 ### 测试配置文件 **pytest.ini** ```ini [tool:pytest] testpaths = tests python_files = test_*.py python_functions = test_* addopts = --cov=accounting_mcp --cov-report=html --cov-report=term-missing --cov-fail-under=90 ``` **requirements-dev.txt** ``` pytest>=7.0.0 pytest-cov>=4.0.0 pytest-mock>=3.0.0 pytest-asyncio>=0.21.0 black>=23.0.0 flake8>=5.0.0 mypy>=1.0.0 pre-commit>=3.0.0 ``` ## 持续集成策略 ### 本地开发流程 1. **红阶段**: 编写失败测试 2. **绿阶段**: 编写最小实现 3. **重构阶段**: 优化代码质量 4. **验证**: 运行全部测试套件 5. **提交**: 通过 pre-commit 检查 ### 测试自动化 ```bash # 运行所有测试 pytest # 运行特定模块测试 pytest tests/test_models.py # 生成覆盖率报告 pytest --cov-report=html # 类型检查 mypy accounting_mcp/ # 代码格式化 black accounting_mcp/ tests/ ``` ## 成功指标 ### 代码质量指标 - **测试覆盖率**: ≥ 90% - **类型覆盖率**: ≥ 85% - **代码复杂度**: 每函数 ≤ 10 - **文档覆盖率**: ≥ 80% ### 功能完成度指标 - **核心工具**: 100% 实现并通过测试 - **资源访问**: 100% 实现并通过测试 - **错误处理**: 100% 覆盖边界情况 - **性能要求**: 满足 PRD 中的响应时间要求 --- *本 TDD 计划确保每个功能都从测试开始开发，保证代码质量和需求匹配度。通过迭代式开发，我们将逐步构建完整的 MCP 记账工具。*