AIclinicalresearch/docs/03-业务模块/ADMIN-运营管理端/04-开发计划/04-运营监控系统MVP实施记录.md

运营监控系统 MVP 实施记录

文档版本：V1.0
实施日期：2026-01-25
基于文档：03-运营监控系统MVP开发计划.md
实施状态：✅ MVP 完成！

---

📋 实施概要

完成状态

任务类型	计划	完成	完成率
数据库设计	1	1	✅ 100%
后端服务	3	3	✅ 100%
埋点集成	7模块	7模块	✅ 100%
前端看板	1	1	✅ 100%
API测试	4端点	4端点	✅ 100%

总耗时：约 6 小时（含调试和问题修复）

---

1. 数据库实施 ✅

1.1 SimpleLog 表创建

Prisma Schema 位置：backend/prisma/schema.prisma

/// 极简运营日志表 (MVP) - V3.1 修订版
model SimpleLog {
  id         String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
  createdAt  DateTime @default(now()) @map("created_at")
  
  tenantId   String   @map("tenant_id") @db.VarChar(50)
  tenantName String?  @map("tenant_name") @db.VarChar(100)
  userId     String   @map("user_id") @db.Uuid
  userName   String?  @map("user_name") @db.VarChar(50)
  
  module     String   @db.VarChar(20)
  feature    String   @db.VarChar(50)
  action     String   @db.VarChar(20)
  
  info       String?  @db.Text
  
  @@index([createdAt])
  @@index([tenantId])
  @@index([userId])
  @@index([module, feature])
  @@index([action])
  @@map("simple_logs")
  @@schema("admin_schema")
}

迁移命令：

# 由于存在跨 schema 外键约束问题，使用 db push 代替 migrate
npx prisma db push

数据库备份：

• 备份文件：ai_clinical_research_backup_20260125.sql
• 备份时间：2026-01-25 实施前
• 备份命令：pg_dump -h localhost -U postgres -F p ai_clinical_research > backup.sql

---

2. 后端服务实施 ✅

2.1 ActivityService（埋点服务）

文件位置：backend/src/common/services/activity.service.ts

核心特性：

• ✅ 火烧即忘模式（Fire-and-Forget）
• ✅ 外层 try-catch 保护（永不抛出异常）
• ✅ 自动填充 tenantName 和 userName
• ✅ 静默失败，不影响业务逻辑

使用示例：

import { activityService } from '@/common/services/activity.service';

// 在业务逻辑中添加埋点（不阻塞主流程）
await activityService.log({
  userId: user.id,
  tenantId: user.tenantId,
  module: 'AIA',
  feature: '智能体对话',
  action: 'MESSAGE_SENT',
  info: `对话完成，tokens: ${tokens}`,
});

2.2 StatsController（统计控制器）

文件位置：backend/src/modules/admin/controllers/statsController.ts

API 端点：

端点	方法	说明
/api/admin/stats/overview	GET	获取 DAU/DAT/模块统计
/api/admin/stats/live-feed	GET	获取最近活动流
/api/admin/users/:id/overview	GET	获取用户360画像
/api/admin/stats/cleanup	POST	清理过期日志（180天）

2.3 StatsRoutes（路由配置）

文件位置：backend/src/modules/admin/routes/statsRoutes.ts

权限控制：

• 所有端点需要 stats:view 权限
• 使用 authenticate + requirePermission 中间件

---

3. 埋点集成实施 ✅

3.1 各模块埋点清单

模块	埋点位置	action 类型	状态
SYSTEM	auth.controller.ts	LOGIN	✅
AIA	conversationService.ts	MESSAGE_SENT	✅
PKB	knowledgeBaseService.ts	KB_CREATED, KB_DELETED	✅
PKB	ragService.ts	RAG_SEARCH	✅
ASL	screeningWorker.ts	SCREENING_COMPLETED	✅
DC	extractionWorker.ts (Tool B)	EXTRACTION_COMPLETED	✅
DC	AICodeService.ts (Tool C)	CODE_GENERATE, CODE_EXECUTE	✅
RVW	reviewWorker.ts	REVIEW_COMPLETED	✅
IIT	SyncManager.ts	POLL_STARTED, SYNC_COMPLETED	✅

3.2 埋点代码示例

登录埋点（auth.controller.ts）：

// 登录成功后记录
await activityService.log({
  userId: result.user.id,
  tenantId: result.user.tenantId,
  module: 'SYSTEM',
  feature: '用户登录',
  action: 'LOGIN',
  info: `用户 ${result.user.name} (${result.user.phone}) 登录成功`,
});

AIA 对话埋点（conversationService.ts）：

// 在流式对话完成后记录
await activityService.log({
  userId,
  tenantId: user.tenantId,
  module: 'AIA',
  feature: `智能体对话: ${conversation.agentId}`,
  action: 'MESSAGE_SENT',
  info: `对话 ${conversationId} 消息发送完成，tokens: ${aiMessage.tokens}`,
});

PKB 知识库埋点（knowledgeBaseService.ts）：

// 创建知识库
await activityService.log({
  userId,
  tenantId: user.tenantId,
  module: 'PKB',
  feature: '知识库管理',
  action: 'KB_CREATED',
  info: `创建知识库: ${name} (ID: ${knowledgeBase.id})`,
});

---

4. 前端看板实施 ✅

4.1 Admin Dashboard 更新

文件位置：frontend-v2/src/pages/admin/AdminDashboard.tsx

功能特性：

• ✅ DAU/DAT 实时统计卡片
• ✅ 模块使用分布图表
• ✅ 最近活动实时流
• ✅ 自动刷新（基于 React Query）

4.2 API 调用层

文件位置：frontend-v2/src/modules/admin/api/statsApi.ts

API 函数：

// 获取运营概览
export const getOverview = async (): Promise<StatsOverview> => {
  const response = await apiClient.get('/api/admin/stats/overview');
  return response.data.data;
};

// 获取实时活动流
export const getLiveFeed = async (limit?: number): Promise<LiveFeedItem[]> => {
  const response = await apiClient.get('/api/admin/stats/live-feed', {
    params: { limit },
  });
  return response.data.data;
};

---

5. 测试验证 ✅

5.1 API 测试

测试脚本位置：backend/src/modules/admin/__tests__/test-stats-api.ps1

测试结果：

测试项	结果
登录获取 Token	✅ 通过
GET /overview	✅ 返回 DAU/DAT
GET /live-feed	✅ 返回活动列表
用户 360 画像	✅ 返回资产统计

5.2 前端测试

• ✅ 运营管理端 Dashboard 正常显示
• ✅ 实时数据刷新正常
• ✅ 权限控制正常（仅 SUPER_ADMIN 可访问）

---

6. 问题与解决

6.1 Prisma 迁移失败

问题：prisma migrate dev 报错 P3006（shadow database 问题）

原因：存在跨 schema 外键约束

解决：使用 prisma db push 直接推送 schema 变更（仅添加新表，安全）

6.2 TypeScript 编译错误

问题：添加埋点后多处 TypeScript 错误

修复内容：

• 修正 Prisma 模型名称（如 prisma.reviewTask 代替 prisma.review_tasks）
• 添加类型注解（reduce 函数参数）
• 添加 .js 扩展名到 ESM 导入

6.3 DC Tool C 上传 401

问题：文件上传返回 401 Unauthorized

原因：后端服务未重启，新代码未生效

解决：重启后端服务后正常

---

7. 文件变更清单

新增文件

文件	说明
backend/src/common/services/activity.service.ts	埋点服务
backend/src/modules/admin/controllers/statsController.ts	统计控制器
backend/src/modules/admin/routes/statsRoutes.ts	统计路由
frontend-v2/src/modules/admin/api/statsApi.ts	前端 API 层

修改文件

文件	修改内容
backend/prisma/schema.prisma	添加 SimpleLog 模型
backend/src/index.ts	注册 statsRoutes
backend/src/common/auth/auth.controller.ts	登录埋点
backend/src/modules/aia/services/conversationService.ts	AIA 对话埋点
backend/src/modules/pkb/services/knowledgeBaseService.ts	PKB 知识库埋点
backend/src/modules/pkb/services/ragService.ts	PKB RAG 埋点
backend/src/modules/asl/services/screeningWorker.ts	ASL 筛选埋点
backend/src/modules/dc/tool-b/workers/extractionWorker.ts	DC Tool B 埋点
backend/src/modules/dc/tool-c/services/AICodeService.ts	DC Tool C 埋点
backend/src/modules/rvw/workers/reviewWorker.ts	RVW 审查埋点
backend/src/modules/iit-manager/services/SyncManager.ts	IIT 同步埋点
frontend-v2/src/pages/admin/AdminDashboard.tsx	运营看板 UI

---

8. 后续优化建议

P2 优先级

• 添加更多埋点：Protocol Agent 一键生成、Word 导出
• 图表可视化：使用 ECharts 展示趋势图
• 定时任务：每日 00:00 自动清理 180 天前日志

P3 优先级

• 用户行为路径分析
• 漏斗分析功能
• 导出统计报表

---

9. 总结

✅ 运营监控系统 MVP 已完成核心功能：

• 数据采集：7 个模块埋点全部完成
• 数据存储：SimpleLog 表结构稳定
• 数据展示：Admin Dashboard 实时展示
• API 接口：4 个核心端点全部可用

MVP 阶段目标达成，可支持基本的运营数据分析需求。

---

文档完成时间：2026-01-25