# field-sync-tracker

> 前后端字段统一管理与追踪系统。用于记录和追踪前后端字段的增删改操作，确保字段定义的一致性。触发场景：涉及字段操作、API开发、数据模型设计、前后端对接、类型定义、数据库schema变更时使用。

- Author: xielin
- Repository: HJ-uncle/skills
- Version: 20260127110444
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/HJ-uncle/skills
- Web: https://mule.run/skillshub/@@HJ-uncle/skills~field-sync-tracker:20260127110444

---

---
name: field-sync-tracker
description: 前后端字段统一管理与追踪系统。用于记录和追踪前后端字段的增删改操作，确保字段定义的一致性。触发场景：涉及字段操作、API开发、数据模型设计、前后端对接、类型定义、数据库schema变更时使用。
---

# Field Sync Tracker

前后端字段统一管理与追踪系统，通过持久化记录字段的增删改操作，帮助团队保持前后端字段定义的一致性。

## 核心功能

1. **字段变更追踪**: 记录所有字段的添加、更新、删除操作
2. **历史记录管理**: 持久化保存完整的变更历史
3. **一致性检查**: 自动检查前后端字段的一致性
4. **智能查询**: 快速查询字段的当前状态和历史演变

## 使用场景

在以下情况下使用此技能：

- 添加新的API字段或数据模型字段
- 修改现有字段的类型或定义
- 删除不再使用的字段
- 检查前后端字段是否一致
- 查询字段的历史变更记录
- 进行数据库schema变更
- 前后端团队协作开发时

## 工作流程

### 1. 初始化项目

在首次使用前，为项目初始化字段记录系统：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/init_project.py <项目名称>
```

这将在 `/home/ubuntu/field-sync-records/<项目名称>/` 创建记录文件。

### 2. 添加字段

当需要添加新字段时：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/add_field.py <项目名称> '<字段数据JSON>'
```

字段数据JSON格式：
```json
{
  "field_name": "userId",
  "field_type": "string",
  "scope": "both",
  "description": "用户唯一标识符",
  "frontend_path": "src/types/user.ts",
  "backend_path": "models/user.model.js",
  "related_fields": ["userName", "userEmail"],
  "notes": "初始创建"
}
```

必需字段：
- `field_name`: 字段名称
- `field_type`: 数据类型
- `scope`: 作用域（frontend/backend/both）

可选字段：
- `description`: 字段描述
- `frontend_path`: 前端文件路径
- `backend_path`: 后端文件路径
- `related_fields`: 关联字段列表
- `notes`: 备注信息

### 3. 更新字段

当需要修改字段定义时：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/update_field.py <项目名称> <字段名称> '<更新数据JSON>'
```

更新数据JSON只需包含要修改的字段，未指定的字段将保持原值。

示例：
```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/update_field.py myproject userId '{"field_type":"number","notes":"改为数字类型"}'
```

### 4. 删除字段

当需要删除字段时：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/delete_field.py <项目名称> <字段名称> [删除原因]
```

注意：删除操作会添加一条删除记录，但不会物理删除历史记录，保证可追溯性。

### 5. 查询字段

查询项目的所有活跃字段：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py <项目名称>
```

查询特定字段：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py <项目名称> <字段名称>
```

高级查询选项：
- `--scope=frontend|backend|both`: 按作用域过滤
- `--include-deleted`: 包含已删除的字段

### 6. 一致性检查

检查前后端字段一致性：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/check_consistency.py <项目名称>
```

检查报告包括：
- 前后端共用字段统计
- 仅前端/后端字段列表
- 一致性问题和警告

## AI工作流程

作为AI助手，在处理字段相关任务时遵循以下流程：

### 步骤1: 识别触发条件

当用户提到以下关键词时，主动使用此技能：
- "字段"、"field"
- "前后端同步"、"API对接"
- "数据模型"、"类型定义"
- "schema"、"数据库字段"

### 步骤2: 查询现有状态

在进行任何字段操作前，先查询相关字段的当前状态：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py <项目名称> [字段名称]
```

这样可以：
- 了解字段是否已存在
- 查看字段的历史演变
- 保持命名和类型的一致性
- 识别相关联的字段

### 步骤3: 执行字段操作

根据任务类型，执行相应的脚本：
- 新增字段 → `add_field.py`
- 修改字段 → `update_field.py`
- 删除字段 → `delete_field.py`

### 步骤4: 记录详细信息

在记录字段变更时，确保：
- `scope` 明确标注（frontend/backend/both）
- `description` 清晰描述字段用途
- `frontend_path` 和 `backend_path` 准确（对于both类型必需）
- `related_fields` 列出相关联的字段
- `notes` 记录变更原因和背景

### 步骤5: 验证一致性

完成字段操作后，运行一致性检查：

```bash
python /home/ubuntu/skills/field-sync-tracker/scripts/check_consistency.py <项目名称>
```

如发现问题，主动提醒用户并提供修复建议。

## 数据结构

详细的字段记录数据结构定义，参考：
```
/home/ubuntu/skills/field-sync-tracker/references/field-schema.md
```

## 最佳实践

前后端字段管理的最佳实践和常见场景解决方案，参考：
```
/home/ubuntu/skills/field-sync-tracker/references/best-practices.md
```

## 模板文件

- **项目配置模板**: `/home/ubuntu/skills/field-sync-tracker/templates/project-config.json`
- **字段记录模板**: `/home/ubuntu/skills/field-sync-tracker/templates/field-record-template.json`

## 存储位置

所有字段记录存储在：
```
/home/ubuntu/field-sync-records/<项目名称>/field_records.json
```

## 注意事项

1. **先查询后操作**: 始终先查询字段现状，再进行增删改操作
2. **完整路径**: 对于标记为 `both` 的字段，务必记录前后端路径
3. **关联字段**: 修改字段时，检查并更新 `related_fields`
4. **定期检查**: 建议定期运行一致性检查，及时发现问题
5. **详细备注**: 在 `notes` 中记录充分的上下文信息

## 示例场景

### 场景1: 添加用户ID字段

```bash
# 1. 查询现有用户相关字段
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py myproject

# 2. 添加新字段
python /home/ubuntu/skills/field-sync-tracker/scripts/add_field.py myproject '{
  "field_name": "userId",
  "field_type": "string",
  "scope": "both",
  "description": "用户唯一标识符",
  "frontend_path": "src/types/user.ts",
  "backend_path": "models/user.model.js",
  "notes": "用户系统初始化"
}'

# 3. 检查一致性
python /home/ubuntu/skills/field-sync-tracker/scripts/check_consistency.py myproject
```

### 场景2: 修改字段类型

```bash
# 1. 查询字段当前状态
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py myproject userId

# 2. 更新字段类型
python /home/ubuntu/skills/field-sync-tracker/scripts/update_field.py myproject userId '{
  "field_type": "number",
  "notes": "改为数字类型以支持数据库自增ID"
}'

# 3. 检查一致性
python /home/ubuntu/skills/field-sync-tracker/scripts/check_consistency.py myproject
```

### 场景3: 删除废弃字段

```bash
# 1. 查询字段及其关联
python /home/ubuntu/skills/field-sync-tracker/scripts/query_fields.py myproject oldField

# 2. 删除字段
python /home/ubuntu/skills/field-sync-tracker/scripts/delete_field.py myproject oldField "功能重构，不再需要"

# 3. 检查一致性
python /home/ubuntu/skills/field-sync-tracker/scripts/check_consistency.py myproject
```

## 故障排查

如遇到问题，检查以下几点：

1. **项目未初始化**: 运行 `init_project.py` 初始化项目
2. **字段不存在**: 使用 `query_fields.py` 确认字段名称
3. **权限问题**: 确保对 `/home/ubuntu/field-sync-records/` 有写权限
4. **JSON格式错误**: 检查传入的JSON字符串格式是否正确

## 维护建议

- **每周**: 运行一次一致性检查
- **每月**: 审查已删除字段，清理不需要的历史记录
- **版本发布前**: 导出完整的字段记录作为文档
- **团队协作**: 在代码审查时检查字段变更是否已记录