refactor: overhaul UI for streamlined user experience

Redesign navigation, home overview, user portrait, and valuation pages with improved functionality and responsive design. Co-authored-by: null <4804959+fnvtk@users.noreply.github.com>
2025-07-18 13:47:12 +00:00
parent 440b310c6f
commit 2408d50cb0
316 changed files with 55785 additions and 0 deletions
--- a/开发文档/开发文档.md
+++ b/开发文档/开发文档.md
@@ -0,0 +1,41 @@
+# 开发文档
+
+## 项目概述
+
+*   项目名称: "神射手" 用户资产数字中台
+*   目标: 构建一个统一、灵活、高性能的用户数据中心，汇聚来自多个异构源系统的数据，形成可信的 360 度用户视图。
+*   核心价值: 打破数据孤岛，沉淀统一、全面的用户资产，提升数据驱动能力。
+
+## 迭代记录
+
+### V1.4 (2025-04-21)
+
+*   **需求分析与任务分解**
+  *   数据接入 (Ingestion)
+  *   数据存储与结构 (Storage & Schema)
+  *   数据查询 (Querying)
+  *   数据服务 (API Distribution)
+  *   身份识别与合并 (Identity Resolution)
+  *   分析支持
+*   **易用性改进**
+  *   将“设备管理”从二级菜单提升为一级菜单。
+
+## 开发架构
+
+### 数据库
+
+*   MongoDB
+
+### 服务
+
+*   IngestionService
+*   QueryService
+*   IdentityService
+
+### API
+
+*   /api/users
+*   /api/users/{userId}
+*   /api/ingest
+*   /api/users/{userId}/tags
+*   /api/users/{userId}/activity
--- a/开发文档/标签管理系统开发文档.md
+++ b/开发文档/标签管理系统开发文档.md
@@ -0,0 +1,143 @@
+# 标签管理系统开发文档
+
+## 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. 增加标签推荐功能
--- a/开发文档/需求文档.md
+++ b/开发文档/需求文档.md
@@ -0,0 +1,141 @@
+产品需求文档 (PRD): "神射手" 用户资产数字中台 V1.3
+
+1. 项目概述
+
+- 项目名称: "神射手" 用户资产数字中台 (对应 @神射手 项目)
+- 目标: 构建一个统一、灵活、高性能的用户数据中心，汇聚来自**多个异构源系统**（如截图所示 众多数据库，以及未来可能接入的其他内外部系统）的用户相关信息，形成 360 度用户视图。该平台通过 API 服务 (api/ 目录) 赋能其他业务系统（如“存客宝”），并可能包含内置管理界面 (app/ 等目录)。
+- 核心挑战: 处理源系统**数据结构差异巨大**、**字段繁多且命名不一**的问题（如 所有数据库所有字段.csv 所反映），将这些**多样化的数据**有效整合为统一的“用户资产”。
+- 核心价值: 打破数据孤岛，沉淀用户资产，提升数据驱动能力。通过标准化的服务层 (services/ 目录) 和 API 接口，支持精细化运营和个性化用户分析。
+
+2. 项目目标
+
+- 数据汇聚: 实现对各源数据库（覆盖截图中的 MySQL 库等）及其他渠道用户数据的统一接入和存储。
+- Schema 灵活性: 支持存储结构各异的数据，能动态适应不同来源、包含大量**非标准化字段**的数据。
+- 高性能查询: 实现对单个用户信息的毫秒级查询响应，**即使在数据模型复杂、数据量巨大的情况下**。
+- 统一用户资产视图: 将来自不同源系统、**各种不同字段**的数据，通过映射和关联，**统一成可理解、可使用的“用户资产”格式**，存储在中台数据库中。
+- 快速迭代: 采用模块化架构，支持业务需求的快速变化。
+- 统一服务: 提供稳定、标准的 API 接口 (api/ 路由驱动)，供内部系统调用。
+- 赋能应用: 使“存客宝”等应用能利用中台数据自定义用户分群、构建流量池规则。
+- 支持分析: 提供基础的用户画像分析能力，支持基于全量用户数据的查询和探索。
+
+3. 功能需求
+
+- 3.1 数据接入 (Ingestion)
+  - 数据源适配: 需要开发或配置数据同步/ETL 工具，能够连接不同的源数据库（如 MySQL）和 API，定期或实时抽取数据。
+  - API 端点: 提供 /api/ingest (或类似) 接口，用于接收实时推送的数据。
+  - 服务层处理 (**services/IngestionService**):
+    - 接收原始数据（包含来源 source 和 源ID source_user_id）。
+    - 核心步骤：数据映射与转换 - 根据预定义的 **数据字典和映射规则**（见 3.2.1），对原始数据进行初步处理：
+      - 识别关键字段（如姓名、手机、邮箱等）。
+      - 标准化某些字段值（如日期格式、地址格式）。
+      - 生成或关联全局唯一 userId（涉及身份识别逻辑）。
+      - 准备写入数据库的文档结构。
+  - 历史数据迁移: 需要制定计划，将源系统中的存量数据批量导入中台。
+
+- 3.2 数据存储与结构 (Storage & Schema)
+  - 数据库选型: **强烈推荐文档数据库 (如 MongoDB)**。理由：其灵活的 Schema 是处理源系统字段多样性（Caihong 中众多 shua_ 表，SG_ 库中各异的结构）的最佳方式，可以直接存储源系统的原始字段结构，避免了在关系型数据库中创建超宽表或大量关联表的复杂性。
+  - 数据模型 (示例):
+{
+  "userId": "global-unique-id-xyz", // 中台统一用户ID
+  "core_profile": { // 提取的核心/标准化字段
+    "name": "...",
+    "mobile": "...", // 脱敏存储
+    "email": "...",
+    // ... 其他核心字段
+  },
+  "unified_tags": ["高价值客户", "医疗行业", "辽宁负责人"], // 统一标签
+  "unified_attributes": { // 统一计算属性
+    "lifetime_value": 15000,
+    "last_active_days": 15
+  },
+  "source_profiles": [ // 存储各来源的详细档案
+    {
+      "source": "caihong_shua_users", // 来源标识 (更具体)
+      "source_user_id": "user_id_in_shua_users_table",
+      "original_data": { // 保留原始字段，无需所有字段都映射
+        "username": "...",
+        "level": 3,
+        "register_time": "...",
+        // ... shua_users 表中的所有字段
+      },
+      "ingestion_timestamp": "..."
+    },
+    {
+      "source": "sg_enterprise_directory",
+      "source_record_id": "record_id_in_sg_enterprise", // 源记录ID
+      // 可能基于 企业名称+负责人 关联到 userId
+      "original_data": {
+        "企业名称": "沈阳东北制药总厂",
+        "负责人": "张三", // 假设这个负责人也是中台的一个用户
+        "联系人": "李四",
+        "职位": "厂长",
+        "行政区划": "210106",
+        "地址": "沈阳市铁西区重工南街37号",
+        "区号": "024",
+        // ... SG_企业名录 中的所有字段
+      },
+       "ingestion_timestamp": "..."
+    },
+    // ... 其他来源 (SG_人才库, SG_投资, 抖音, 微信等)
+  ],
+  "createdAt": "...", // 中台记录创建时间
+  "updatedAt": "..."  // 中台记录更新时间
+}
+  - 3.2.1 数据字典与映射规则:
+    - 核心产出: 需要基于对 所有数据库所有字段.csv 及各源系统的分析，创建一份详细的**数据字典**。
+    - 内容:
+      - 定义中台的核心字段 (core_profile) 及其含义。
+      - 定义统一标签 (unified_tags) 和统一属性 (unified_attributes) 的生成规则。
+      - 建立**源系统字段**到**中台字段（核心字段或保留在 ****original_data**** 中）的映射关系**。
+      - 标识出 PII（个人身份信息）字段，明确其处理方式（存储、加密、脱敏、访问控制）。
+      - 标识出可用于**身份识别 (Identity Resolution)** 的关键字段（如手机号、邮箱、身份证号、微信 unionid 等）。
+    - 实现: 映射规则可以在 services/IngestionService 中通过代码实现，或配置在外部规则引擎中。
+
+- 3.3 数据查询 (Querying)
+  - API 端点 (**api/****):** 提供丰富的查询 API。
+  - 服务层逻辑 (**services/QueryService****):** 封装数据库查询逻辑。
+  - 查询能力:
+    - 基础查询: 按 userId, core_profile.email, core_profile.mobile 等快速获取用户。
+    - 关联查询: 按 source_profiles.source + source_profiles.source_user_id 查询。
+    - 复杂分析查询: 支持基于 core_profile, unified_tags, unified_attributes 以及 source_profiles.original_data **内部任意字段**的组合查询。例如：
+      - 查询 source_profiles.source 为 'sg_enterprise_directory' 且 original_data.负责人 为 '张三' 的所有用户。
+      - 查询 unified_tags 包含 '高价值客户' 且 source_profiles 中存在 source='caihong_shua_orders' 记录的用户。
+  - 性能: 必须为 userId, 核心字段, 以及 source_profiles 中经常用于查询的字段（如 source, source_user_id, original_data 内的关键业务字段）**建立数据库索引**。
+
+- 3.4 数据服务 (API Distribution)
+  - (与 V1.2 类似) 提供标准 API，重点强化查询 API 的过滤能力，满足存客宝等应用需求。
+
+- 3.5 (可能) 管理界面 (Management UI)
+  - (与 V1.2 类似) 提供界面用于查看统一后的用户视图、搜索用户、可能包含基础的数据质量监控。
+
+- 3.6 与存客宝 (**cunkebao 0420**) 集成场景
+  - 存客宝调用中台 API，获取 **经过整合和关联的全维度用户数据**，包括核心信息、统一标签、以及来自 Caihong, SG_* 等所有源系统的详细档案信息，用于构建复杂的流量池规则和执行精准营销。
+
+- 3.7 (重点) 身份识别与合并 (Identity Resolution)
+  - 必要性: 由于数据来自不同系统，必须有机制识别哪些记录属于同一个自然人。
+  - 策略: 需要在 services/ 中实现，基于数据字典中标识的关键字段（手机、邮箱、身份证等），采用确定性匹配（完全一致）和模糊匹配（相似度算法）相结合的方式，将不同 source_profiles 关联到同一个 userId。这是一个持续优化的过程。
+
+- 3.8 分析支持
+  - 中台 API 应能支持 BI 工具或数据分析平台进行数据查询和提取。
+  - (可选) 提供数据导出功能，将处理整合后的用户数据导出为宽表或其他格式，供离线分析使用。
+
+4. 非功能性需求
+
+- (与 V1.2 类似：性能、可扩展性、灵活性、可用性)
+- 4.5 安全性:
+  - 严禁存储明文密码或高度敏感凭证。 对于截图中可能存在的密码或敏感数据，在接入中台时必须**丢弃**或进行**不可逆的哈希处理**（如果中台需要校验密码，但这通常应由源系统或统一认证中心负责）。
+  - 严格遵守数据字典中定义的 PII 处理规则（加密、脱敏、访问控制）。
+  - API 访问控制要做到字段级别。
+
+5. 数据库选型推荐
+
+- 首选: **MongoDB**。其灵活的文档模型、强大的查询能力（支持嵌套文档查询和索引）、成熟的生态和良好的水平扩展性，非常适合应对当前描述的复杂数据源整合需求。
+
+6. 开放问题与后续步骤
+
+- 启动核心任务： **立即开始分析 ****所有数据库所有字段.csv**** 和各源数据库结构，着手制定 V1.0 的数据字典和映射规则。** 这是项目成功的关键。
+- 详细设计身份识别 (Identity Resolution) 的具体算法和流程。
+- 确定数据库部署方案（云服务 Atlas? 自建?）。
+- 与存客宝团队详细对接 API 需求，特别是复杂查询场景。
+- 确定管理界面的范围和优先级。
+- 制定历史数据迁移方案和数据质量校验计划。