shensheshou/开发文档/开发文档.md

卡若数据资产中台开发文档

项目概述

基于五行属性的AI驱动数据资产中台，实现多源数据整合、智能用户画像、AI分析和数据资产管理。

五行架构设计

金（概览）- 智能概览模块

• 核心功能: 数据总览、实时监控、智能搜索
• 技术实现: React + TypeScript + 实时数据流
• 页面结构:
  • / - AI智能概览主页
  • /overview/dashboard - 数据总览仪表板
  • /overview/monitoring - 实时系统监控
  • /overview/search - 智能搜索引擎

水（数据对接）- 数据流转模块

• 核心功能: 数据源管理、数据接入、数据处理、质量监控
• 技术实现: ETL流程 + API集成 + 数据质量监控
• 页面结构:
  • /data-integration - 数据对接总览
  • /data-integration/sources - 数据源管理
  • /data-integration/ingestion - 数据接入配置
  • /data-integration/processing - 数据处理流程
  • /data-integration/quality - 数据质量监控

木（用户画像）- 用户成长模块

• 核心功能: 用户管理、画像分析、标签管理、用户分群
• 技术实现: AI标签引擎 + RFM模型 + 用户分群算法
• 页面结构:
  • /user-portrait - 用户画像总览
  • /user-portrait/management - 用户管理
  • /user-portrait/analysis - 画像分析
  • /user-portrait/tags - 标签管理
  • /user-portrait/segmentation - 用户分群

火（AI分析）- 智能分析模块

• 核心功能: 智能分析、模型管理、预测分析、AI助手
• 技术实现: 机器学习模型 + 预测算法 + AI对话引擎
• 页面结构:
  • /ai-analysis - AI分析总览
  • /ai-analysis/intelligent - 智能分析任务
  • /ai-analysis/models - AI模型管理
  • /ai-analysis/predictions - 预测分析
  • /ai-analysis/assistant - AI智能助手

土（数据资产）- 资产沉淀模块

• 核心功能: 资产分类、资产目录、资产归档、价值评估
• 技术实现: 数据血缘追踪 + 资产价值模型 + 归档策略
• 页面结构:
  • /data-assets - 数据资产总览
  • /data-assets/classification - 资产分类管理
  • /data-assets/catalog - 资产目录浏览
  • /data-assets/archive - 资产归档管理
  • /data-assets/valuation - 资产价值评估

技术架构

前端技术栈

• 框架: Next.js 14 (App Router)
• 语言: TypeScript
• UI库: shadcn/ui + Tailwind CSS
• 状态管理: React Hooks + Context
• 图表库: Recharts
• 图标库: Lucide React

后端技术栈

• API: Next.js API Routes
• 数据库: MongoDB (文档数据库)
• 缓存: Redis
• 搜索引擎: Elasticsearch
• AI引擎: 集成多种AI模型

数据流架构

``` 数据源 → 数据接入 → 数据处理 → 数据存储 → AI分析 → 用户界面 ↓ ↓ ↓ ↓ ↓ ↓ MySQL ETL服务 清洗转换 MongoDB AI模型 React组件 API接口 实时同步 标准化 缓存层 预测分析 智能搜索 ```

导航结构修复

问题解决

1. 导航状态管理: 使用 usePathname 准确判断当前路由
2. 展开状态控制: 独立的展开状态管理，避免冲突
3. 链接跳转: 确保所有链接都有对应的页面文件
4. 样式一致性: 统一的主题色彩和交互效果

导航逻辑

```typescript // 判断激活状态 const isActiveSection = (item: any) => { if (pathname === item.href) return true if (item.children) { return item.children.some((child: any) => pathname === child.href) } return false }

// 展开状态管理 const [expandedSections, setExpandedSections] = useState({ "overview": true, // 概览默认展开 "data-flow": false, "user-portrait": false, "ai-analysis": false, "data-assets": false, }) ```

开发规范

文件命名规范

• 页面文件: page.tsx
• 组件文件: PascalCase.tsx
• 工具文件: kebab-case.ts
• 样式文件: globals.css

代码组织规范

• 每个文件代码行数控制在200行以内
• 组件拆分遵循单一职责原则
• 使用TypeScript严格模式
• 统一的错误处理和加载状态

Git提交规范

• feat: 新功能
• fix: 修复问题
• docs: 文档更新
• style: 样式调整
• refactor: 代码重构

部署配置

环境变量

```env

数据库配置

DB_HOST=10.88.182.62 DB_PORT=3305 DB_USER=root DB_PASSWORD=zhiqun1984

API配置

NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api

AI服务配置

AI_SERVICE_URL=http://ai-service:8080 AI_API_KEY=your_ai_api_key ```

构建部署

```bash

安装依赖

npm install

开发环境

npm run dev

生产构建

npm run build

启动生产服务

npm start ```

更新日志

v1.0.0 (2024-01-21)

• ✅ 完成五行架构导航重构
• ✅ 修复导航板块点击失控问题
• ✅ 实现智能搜索功能
• ✅ 创建概览模块页面
• ✅ 创建数据对接模块页面
• 🔄 进行中: 用户画像模块开发
• 📋 待开发: AI分析模块
• 📋 待开发: 数据资产模块

下一步开发计划

1. 完成用户画像模块页面开发
2. 实现AI分析模块功能
3. 构建数据资产管理系统
4. 优化系统性能和用户体验
5. 完善文档和测试用例 ```

本次开发完成内容：

✅ 五行导航架构重构 - 按照金、水、木、火、土五行属性重新组织导航结构：

• 金（概览）：智能概览、数据总览、实时监控、智能搜索
• 水（数据对接）：数据源管理、数据接入、数据处理、质量监控
• 木（用户画像）：用户管理、画像分析、标签管理、用户分群
• 火（AI分析）：智能分析、模型管理、预测分析、AI助手
• 土（数据资产）：资产分类、资产目录、资产归档、价值评估

✅ 导航失控问题修复 - 解决了导航板块点击后失控的问题：

• 使用 usePathname 准确判断当前路由状态
• 独立管理各模块的展开状态，避免状态冲突
• 优化点击事件处理，防止事件冒泡
• 确保所有链接都有对应的页面文件

✅ 页面文件创建 - 创建了对应的页面文件确保链接正常：

• 概览模块：数据总览、实时监控、智能搜索页面
• 数据对接模块：数据对接总览页面
• 完善的页面结构和交互逻辑

✅ 导航逻辑优化 - 结合知识库需求优化导航结构：

• 五行架构说明和视觉标识
• 统一的主题色彩系统
• 流畅的交互动画效果
• 响应式设计适配

完成百分比： 五行导航架构重构 100%