# 标签管理系统开发文档

## 1. 系统概述

标签管理系统是用户数据资产中台的核心组件之一，用于管理和组织用户标签体系，支持用户画像的构建和应用。系统包括标签管理、标签规则引擎等功能模块，为企业提供完整的用户标签生命周期管理能力。

## 2. 系统架构

### 2.1 总体架构

标签管理系统采用前后端分离架构，前端使用 React + Next.js 开发，后端使用 Node.js + MySQL 开发。系统主要包括以下几个部分：

- 标签管理：负责标签的创建、编辑、删除等基础管理功能
- 标签规则引擎：负责标签生成规则的定义和执行
- 标签分析：提供标签使用情况的统计和分析功能
- 标签关系图谱：展示标签之间的关联关系

### 2.2 数据模型

#### 标签表 (tags)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，标签ID |
| name | varchar(100) | 标签名称 |
| category | varchar(50) | 标签分类 |
| type | enum | 标签类型：系统、自定义、衍生 |
| source | varchar(100) | 数据来源 |
| coverage | decimal(5,2) | 覆盖率 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

#### 标签规则表 (tag_rules)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，规则ID |
| name | varchar(100) | 规则名称 |
| description | text | 规则描述 |
| target_tag_id | varchar(36) | 目标标签ID |
| condition | text | 规则条件 |
| sql | text | SQL语句 |
| status | enum | 状态：活跃、非活跃、草稿 |
| priority | int | 优先级 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

#### 规则执行历史表 (rule_executions)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，执行ID |
| rule_id | varchar(36) | 规则ID |
| execution_time | datetime | 执行时间 |
| duration | int | 执行耗时（秒） |
| status | enum | 状态：成功、失败、执行中 |
| affected_users | int | 影响用户数 |
| executed_by | varchar(50) | 执行人 |
| log | text | 执行日志 |

#### 用户标签关联表 (user_tags)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| user_id | varchar(36) | 用户ID |
| tag_id | varchar(36) | 标签ID |
| created_at | datetime | 创建时间 |
| rule_execution_id | varchar(36) | 规则执行ID |

## 3. 功能模块

### 3.1 标签管理

标签管理模块提供标签的基础管理功能，包括：

- 标签列表：展示所有标签，支持搜索、筛选和排序
- 标签创建：创建新标签，设置标签名称、分类、类型等信息
- 标签编辑：修改标签信息
- 标签删除：删除不需要的标签
- 标签分析：展示标签的使用情况和分布情况
- 标签关系图谱：展示标签之间的关联关系

### 3.2 标签规则引擎

标签规则引擎负责标签生成规则的定义和执行，包括：

- 规则列表：展示所有规则，支持搜索、筛选和排序
- 规则创建：创建新规则，设置规则名称、描述、目标标签、条件等信息
- 规则编辑：修改规则信息
- 规则执行：手动执行规则，为符合条件的用户打标签
- 规则调度：设置规则的自动执行计划
- 执行历史：查看规则的执行历史和结果

## 4. 开发流程

### 4.1 标签管理模块开发

1. 创建标签管理页面 (app/tag-management/page.tsx)
2. 实现标签列表展示功能
3. 实现标签创建、编辑、删除功能
4. 实现标签分类分布图表 (components/tag-management/tag-category-chart.tsx)
5. 实现标签使用统计图表 (components/tag-management/tag-usage-stats.tsx)
6. 实现标签关系图谱 (components/tag-management/tag-relationship-graph.tsx)

### 4.2 标签规则引擎开发

1. 创建标签规则引擎页面 (app/tag-rules/page.tsx)
2. 实现规则列表展示功能
3. 实现规则创建、编辑、删除功能
4. 实现规则编辑器 (components/tag-rules/rule-editor.tsx)
5. 实现规则执行历史查看功能 (components/tag-rules/rule-execution-history.tsx)

## 5. 接口设计

### 5.1 标签管理接口

- GET /api/tags - 获取标签列表
- POST /api/tags - 创建标签
- GET /api/tags/:id - 获取标签详情
- PUT /api/tags/:id - 更新标签
- DELETE /api/tags/:id - 删除标签
- GET /api/tags/stats - 获取标签统计信息
- GET /api/tags/relationships - 获取标签关系图谱数据

### 5.2 标签规则引擎接口

- GET /api/tag-rules - 获取规则列表
- POST /api/tag-rules - 创建规则
- GET /api/tag-rules/:id - 获取规则详情
- PUT /api/tag-rules/:id - 更新规则
- DELETE /api/tag-rules/:id - 删除规则
- POST /api/tag-rules/:id/execute - 执行规则
- GET /api/tag-rules/executions - 获取规则执行历史
- GET /api/tag-rules/executions/:id - 获取规则执行详情

## 6. 后续计划

1. 实现标签规则的自动调度功能
2. 增加标签导入导出功能
3. 增加标签权限管理功能
4. 增加标签版本管理功能
5. 增加标签质量评估功能
6. 增加标签推荐功能
