埋点管理系统 (Tracking Management System)

一个现代化的埋点需求管理平台，支持灵活的需求组合、全局参数管理和完整的变更追踪。

🚀 项目特性

核心功能

• 灵活需求组合: 支持新建事件和编辑现有事件的混合需求
• 全局参数管理: 避免参数重复，支持跨事件共享
• 完整变更追踪: 记录所有修改历史，支持版本管理
• 安全控制: 防止破坏性修改，确保数据安全
• 测试数据隔离: 支持测试数据与生产数据的分离管理

技术栈

• 后端: Node.js + Express + TypeScript + PostgreSQL
• 前端: React 19 + TypeScript + Ant Design 5.x + Vite
• 数据库: PostgreSQL 14+ (支持UUID、JSONB等高级特性)

📊 数据库设计

核心表结构

• page: 页面管理
• element: 页面元素
• event: 埋点事件
• param: 参数定义
• event_param_mapping: 事件参数关联
• tracking_request: 埋点需求
• tracking_request_item: 需求项
• tracking_request_version: 需求版本历史
• review: 评审记录
• test: 测试记录

关键特性

• 使用UUID作为主键
• is_test_data字段区分测试/生产数据
• 完整的审计字段 (created_at, updated_at)
• 外键约束保证数据一致性

🛠️ 安装和启动

前置要求

• Node.js 18+
• PostgreSQL 14+
• npm 或 yarn

快速启动

# 1. 克隆项目
git clone <repository-url>
cd tracking_platform

# 2. 安装依赖
cd backend && npm install
cd ../frontend && npm install

# 3. 配置数据库
# 确保PostgreSQL运行并创建用户
brew services start postgresql@14
createuser -s postgres

# 4. 启动系统
./start.sh

手动启动

# 后端
cd backend
npm run dev

# 前端
cd frontend
npm run dev

📱 使用指南

访问地址

• 前端: http://localhost:5173
• 后端API: http://localhost:3001
• 健康检查: http://localhost:3001/health

主要功能模块

1. 事件管理

• 创建、编辑、删除埋点事件
• 关联页面和元素
• 配置事件参数
• 支持多种事件类型 (点击、浏览、曝光等)

2. 页面管理

• 管理应用页面信息
• 支持多平台 (iOS、Android、Web、H5)
• 页面版本控制

3. 参数管理

• 全局参数定义
• 参数类型验证
• 使用统计和重复检测

4. 埋点需求

• 创建埋点需求单
• 需求项管理 (新建/编辑事件)
• 需求流转和状态管理
• 版本历史追踪

5. 数据分析

• 事件使用统计
• 参数使用分析
• 需求完成情况

测试数据管理

• 使用页面右上角的开关控制测试数据显示
• 测试数据与生产数据完全隔离
• 支持快速切换查看不同环境的数据

🔧 API 文档

核心端点

GET    /api/events              # 获取事件列表
POST   /api/events              # 创建事件
PUT    /api/events/:id          # 更新事件
DELETE /api/events/:id          # 删除事件

GET    /api/pages               # 获取页面列表
GET    /api/elements            # 获取元素列表
GET    /api/parameters          # 获取参数列表

GET    /api/tracking-requests   # 获取埋点需求
POST   /api/tracking-requests   # 创建埋点需求
PUT    /api/tracking-requests/:id # 更新埋点需求

查询参数

• showTestData=true/false: 控制是否显示测试数据

🗄️ 数据库管理

初始化数据库

# 自动初始化 (推荐)
./start.sh

# 手动初始化
psql -d tracking_system -f backend/database/init.sql

迁移测试数据

cd backend
npm run migrate-data

清空数据

psql -d tracking_system -c "TRUNCATE TABLE test, review, tracking_request_version, tracking_flow_log, tracking_request_item, tracking_request, event_param_mapping, event_version_log, event, param_usage_stats, param, element, page, \"user\" RESTART IDENTITY CASCADE;"

🧪 测试数据

系统预置了完整的测试数据，包括：

• 5个埋点事件
• 3个埋点需求
• 多个页面、元素和参数
• 完整的关联关系

所有测试数据都标记为 is_test_data = true，可以通过前端开关控制显示。

🔒 安全特性

• 所有用户操作都限制在测试数据范围内
• 数据库约束防止数据不一致
• 事务保证数据完整性
• 参数化查询防止SQL注入

📈 性能优化

• 数据库索引优化查询性能
• 前端组件懒加载
• API响应缓存
• 分页查询支持

🐛 故障排除

常见问题

1. PostgreSQL连接失败

   brew services start postgresql@14

2. 端口被占用

   # 检查端口占用
   lsof -i :3001
   lsof -i :5173

3. 数据库表已存在错误

   • 这是正常现象，可以忽略
   • 或使用 2>/dev/null 隐藏错误信息

4. 前端API调用失败

   • 检查后端服务是否启动
   • 确认API地址正确
   • 检查CORS配置

🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📄 许可证

MIT License

📞 支持

如有问题，请提交 Issue 或联系开发团队。