tax-calculator-api4

v1.0.0

Published

7 months ago

互联网平台劳务报酬个税计算器 API

Downloads

0High
0Medium
0Low

pengbo518

tax calculator api mcp nodejs express

个税计算器 API

基于 Node.js + Express 构建的互联网平台劳务报酬个税计算器 API，支持 MCP (Model Context Protocol) 插件功能，提供高精度的个税计算服务。

✨ 功能特性

🧮 精确个税计算：基于最新个税政策的劳务报酬计算
🔌 MCP 插件支持：提供标准化的 MCP 接口，支持 AI 模型集成
📊 批量计算：支持多组数据的批量计算和方案对比
🔒 数据验证：完整的输入验证和错误处理
📈 高精度计算：使用 Decimal.js 确保计算精度，避免浮点数误差
🛡️ 安全防护：CORS、请求限制、安全头等全方位安全保护
📝 详细日志：完整的请求日志和错误追踪
🧪 测试覆盖：完整的单元测试和集成测试

🚀 快速开始

环境要求

Node.js >= 16.0.0
npm >= 8.0.0

安装和运行

# 克隆项目
git clone https://github.com/pengbo518/tax-calculator-mcp.git
cd tax-calculator-mcp

# 安装依赖
npm install

# 配置环境变量
cp env.example .env

# 开发环境运行
npm run dev

# 生产环境运行
npm start

验证安装

访问健康检查接口确认服务正常运行：

curl http://localhost:3000/health

📋 API 接口文档

个税计算接口

POST `/api/tax/calculate`

计算个税

请求体：

{
  "monthlyIncomes": [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
}

参数说明：

monthlyIncomes: 月收入数组，支持1-12个元素
数组长度对应月份：[10000] = 1月收入10000，其他月份为0
自动补全：不足12个月的数组会自动补全到12个月，未传月份默认为0
支持不连续月份：[200, 0, 300, 0] = 1月200，2月0，3月300，4月0，5-12月为0

响应示例：

{
  "success": true,
  "message": "个税计算成功",
  "data": {
    "monthlyResults": [
      {
        "month": 1,
        "income": 10000,
        "totalIncome": 10000,
        "totalFee": 2000,
        "totalDeduction": 5000,
        "taxableAmount": 3000,
        "rate": 0.03,
        "deduct": 0,
        "tax": 90,
        "afterTaxIncome": 9910,
        "prevTaxPaid": 0,
        "taxBurden": 0.9
      }
    ],
    "summary": {
      "totalIncome": 75000,
      "totalTax": 4500,
      "totalAfterTax": 70500,
      "totalTaxBurden": 6.0
    }
  }
}

GET `/api/tax/rates`

获取税率表

GET `/api/tax/policy`

获取个税政策信息

POST `/api/tax/flexible-income`

批量设置灵活就业收入

MCP 插件接口

GET `/api/mcp`

获取 MCP 插件信息

POST `/api/mcp/calculate`

MCP 个税计算接口

GET `/api/mcp/rates`

MCP 税率表接口

GET `/api/mcp/policy`

MCP 政策信息接口

POST `/api/mcp/batch-calculate`

MCP 批量计算接口

💡 使用示例

基本个税计算

const response = await fetch('http://localhost:3000/api/tax/calculate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    monthlyIncomes: [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
  })
});

const result = await response.json();
console.log(result.data.summary);

不同入参示例

// 示例1: 只有1月份收入
const response1 = await fetch('http://localhost:3000/api/mcp/calculate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    monthlyIncomes: [10000]  // 1月收入10000，2-12月默认为0
  })
});

// 示例2: 前两个月收入
const response2 = await fetch('http://localhost:3000/api/mcp/calculate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    monthlyIncomes: [20000, 30000]  // 1月20000，2月30000，3-12月默认为0
  })
});

// 示例3: 不连续月份收入
const response3 = await fetch('http://localhost:3000/api/mcp/calculate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    monthlyIncomes: [200, 0, 300, 0]  // 1月200，2月0，3月300，4月0，5-12月默认为0
  })
});

批量计算

const response = await fetch('http://localhost:3000/api/mcp/batch-calculate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    calculations: [
      {
        name: '方案A',
        monthlyIncomes: [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
      },
      {
        name: '方案B',
        monthlyIncomes: [15000, 15000, 15000, 15000, 0, 0, 0, 0, 0, 0, 0, 0]
      },
      {
        name: '方案C',
        monthlyIncomes: [20000, 30000]
      },
      {
        name: '方案D',
        monthlyIncomes: [50000]
      }
    ]
  })
});

const result = await response.json();
console.log(result.results);

⚙️ 配置说明

环境变量

复制 env.example 为 .env 并配置以下变量：

# 服务器配置
PORT=3000
NODE_ENV=development

# 跨域配置
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# 日志配置
LOG_LEVEL=info

# 安全配置
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

请求限制

每个 IP 15 分钟内最多 100 个请求
请求体大小限制 1MB
支持自定义限制配置

🧪 测试

运行测试

# 运行所有测试
npm test

# 运行 API 测试
npm run test:api

# 运行优化测试
npm run test:optimized

# 运行快速测试
npm run quick-test

调试 MCP

# 调试 MCP 功能
npm run debug:mcp

📁 项目结构

tax-calculator-mcp/
├── src/
│   ├── index.js              # 服务器入口文件
│   ├── routes/               # 路由文件
│   │   ├── taxCalculator.js  # 个税计算路由
│   │   └── mcp.js           # MCP 插件路由
│   ├── services/             # 业务逻辑层
│   │   └── taxCalculator.js  # 个税计算服务
│   ├── middleware/           # 中间件
│   │   └── errorHandler.js   # 错误处理中间件
│   └── utils/               # 工具函数
│       └── logger.js        # 日志工具
├── tests/                   # 测试文件
│   └── taxCalculator.test.js
├── debug-mcp.js            # MCP 调试脚本
├── env.example             # 环境变量示例
├── package.json
└── README.md

🔒 安全特性

CORS 保护：配置允许的跨域来源
请求限制：防止 API 滥用和 DDoS 攻击
输入验证：完整的参数验证和类型检查
安全头：使用 Helmet 设置安全头
错误处理：统一的错误响应格式，避免信息泄露
日志记录：完整的请求日志和错误追踪

📈 性能优化

高精度计算：使用 Decimal.js 避免浮点数精度问题
内存优化：合理的数据结构和算法设计
响应缓存：税率表等静态数据缓存
错误恢复：优雅的错误处理和恢复机制
并发处理：支持高并发请求处理

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发流程

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

代码规范

使用 ESLint 进行代码检查
遵循项目现有的代码风格
添加必要的测试用例
更新相关文档

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

项目主页：GitHub Repository
邮箱：[email protected]
问题反馈：Issues

🙏 致谢

感谢所有为这个项目做出贡献的开发者！

⭐ 如果这个项目对您有帮助，请给我们一个星标！