Skip Tracing POC - Professional Demo Platform

Skip Tracing POC - 专业演示平台

采用 6 个 MCP 服务构建的专业寻人演示平台，兼顾最高开发效率与企业级品质。

🎯 项目概览

Skip Tracing POC 是一个概念验证演示平台，展示了面向回收公司、债务催收人员和法律从业者的自动化寻人能力。系统汇总来自 20 多个经过验证的数据源的信息，以专业的置信度评分定位个人并收集联系方式。

主要功能

• ⚡ 实时多源搜索 - 同时查询 20 多个数据库
• 🎯 置信度评分 - 由 AI 驱动的结果验证与排序
• 📊 专业报告 - 支持带品牌标识的 PDF/CSV 导出
• 📱 适配移动设备 - 兼容所有设备和浏览器
• 🔒 符合隐私规范 - 按 GDPR/CCPA 要求处理数据
• 🚀 满足企业需求 - 可扩展架构，配备全面测试

目标成功指标

• 50 位以上的测试用户 参与演示测试
• 60% 以上的正面反馈 认可该概念
• 搜索响应时间低于 30 秒
• 测试期间正常运行时间达到 95% 以上

🏗️ MCP 技术栈架构

本项目采用顶尖的 6 服务 MCP 技术栈，支持专业开发：

MCP 服务	用途	状态
🗂️ Filesystem	直接进行文件操作和管理	✅ 已配置
🔧 Git	专业的版本控制工作流	✅ 已配置
🐙 GitHub	项目管理与协作	✅ 已配置
🎭 Playwright	全面的测试与质量保证	✅ 已配置
🔍 Apify	寻人功能与验证	✅ 已配置
🗄️ Supabase	数据库操作与分析	✅ 已配置

🚀 快速开始

前置条件

• Node.js 18+ 和 npm
• 用于版本控制的 Git
• 用于数据库的 Supabase 账户
• 用于寻人 API 的 Apify 账户
• 配置了 MCP 的 Claude Desktop

安装

1. 克隆仓库

   git clone https://github.com/GautaVaid/Skip_Tracing.git
   cd Skip_Tracing
   

2. 安装依赖项

   # Install backend dependencies
   cd server && npm install
   
   # Install frontend dependencies  
   cd ../client && npm install
   

3. 配置环境

   # Copy environment template
   cp .env.example .env
   
   # Configure your API keys:
   # - APIFY_TOKEN=your_apify_token
   # - SUPABASE_URL=your_supabase_url
   # - SUPABASE_ANON_KEY=your_supabase_key
   

4. 设置数据库

   cd database
   npm run migrate
   npm run seed
   

5. 启动开发服务器

   # Terminal 1: Backend
   cd server && npm run dev
   
   # Terminal 2: Frontend
   cd client && npm run dev
   

6. 打开应用

   • 前端：http://localhost:3000
   • 后端 API：http://localhost:8000
   • API 文档：http://localhost:8000/docs

📁 项目结构

Skip_Tracing/
├── client/                 # React frontend application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Page-level components
│   │   └── utils/         # Frontend utilities
│   └── package.json
├── server/                # Node.js backend API
│   ├── routes/           # API endpoint definitions
│   ├── engines/          # Skip tracing engine core
│   ├── actors/           # Apify actor integrations
│   └── package.json
├── database/             # Database schema and migrations
│   ├── schema/          # Supabase table definitions
│   └── migrations/      # Database migration files
├── tests/               # Comprehensive test suite
│   ├── e2e/            # End-to-end tests (Playwright)
│   ├── api/            # API integration tests
│   └── unit/           # Unit tests
├── docs/               # Project documentation
├── deployment/         # Deployment configuration
└── config/            # MCP and application configuration

🧪 测试

运行测试套件

# Run all tests
npm run test

# Run specific test types
npm run test:unit        # Unit tests
npm run test:api         # API integration tests  
npm run test:e2e         # End-to-end tests (Playwright)
npm run test:performance # Performance benchmarks

测试覆盖率

• 目标：代码覆盖率达到 80% 以上
• 当前：首次运行测试后显示
• 报告：生成在 coverage/ 目录中

🔧 开发工作流

分支策略（GitFlow）

• main - 可用于生产环境的代码
• develop - 功能集成分支
• feature/ - 单项功能开发
• hotfix/ - 生产环境关键问题修复
• release/ - 发布准备

提交规范

我们使用 Conventional Commits：

feat: add skip trace result confidence scoring
fix: resolve mobile responsive layout issues  
docs: update API documentation for search endpoints
test: add end-to-end tests for export functionality

代码质量

• ESLint - 代码检查与风格规范
• Prettier - 代码格式化
• Husky - 用于质量门禁的 Git 钩子
• 文件行数限制 - 每个文件最多 500 行

📊 API 文档

核心端点

搜索操作

• POST /api/search - 执行寻人搜索
• GET /api/search/:id - 获取搜索结果
• DELETE /api/search/:id - 取消进行中的搜索

导出操作

• POST /api/export/pdf - 生成 PDF 报告
• POST /api/export/csv - 生成 CSV 导出文件
• POST /api/export/email - 通过电子邮件向用户发送报告

分析

• GET /api/analytics/dashboard - 获取分析仪表板数据
• POST /api/analytics/event - 跟踪用户交互事件

速率限制

• 搜索 API：每个 IP 每分钟 10 个请求
• 导出 API：每个 IP 每分钟 5 个请求
• 分析 API：每个 IP 每分钟 100 个请求

🔒 安全与隐私

数据保护

• 所有个人身份信息均经过静态加密和传输加密
• 搜索结果会在 24 小时后自动清除
• 演示无需用户身份验证（匿名使用）
• 数据处理流程符合 GDPR/CCPA 要求

API 安全

• 所有端点均实施速率限制
• 输入验证与清理
• 防范 XSS 和 SQL 注入
• 为前端域名配置 CORS

🚀 部署

开发环境

• 前端：部署到开发服务器
• 后端：使用 Docker 容器化
• 数据库：Supabase 云实例

生产环境（未来）

• 前端：通过 CDN 部署并启用缓存
• 后端：自动扩缩容的容器编排
• 数据库：用于生产环境的 Supabase，并提供备份
• 监控：完善的日志记录与告警

📈 性能基准

目标性能

• 搜索响应时间：平均 < 30 秒
• 页面加载时间：首次加载 < 3 秒
• API 响应时间：非搜索端点 < 500 毫秒
• 正常运行时间：目标可用性为 99.9%

优化功能

• 缓存重复搜索的结果
• 优化数据库查询
• 前端代码拆分与延迟加载
• 使用 CDN 提供静态资源

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解以下内容：

• 行为准则
• 开发环境设置
• Pull Request 流程
• 编码规范
• 测试要求

获取帮助

• 问题：创建 GitHub 问题，报告错误或提交功能请求
• 讨论：使用 GitHub Discussions 提问
• 文档：查看 /docs 目录中的详细指南

📋 开发路线图

阶段 1：基础 ✅

• MCP 技术栈配置与验证
• 仓库设置与 Git 工作流
• 项目结构与文档

阶段 2：核心开发 🚧

• 数据库架构与后端 API
• 跳过追踪引擎与 Apify 集成
• 前端组件与用户界面

阶段 3：测试与质量 📋

• 实施全面的测试套件
• 性能优化与基准测试
• 安全审计与合规性验证

阶段 4：生产就绪 🎯

• 导出功能与专业功能
• 部署自动化与监控
• Beta 用户引导与反馈收集

📄 许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• Apify Platform - 跳过追踪数据源集成
• Supabase - 数据库与后端服务
• MCP Protocol - AI 驱动的开发加速
• Beta 用户 - 宝贵的反馈与测试支持

---

采用 6-Server MCP Stack 构建，❤️ 加持，实现最高开发效率

借助 AI 驱动的专业工作流，将数周的开发工作缩短至数天