# 运营监控系统 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`

```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")
}
```

**迁移命令**：

```bash
# 由于存在跨 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
- ✅ 静默失败，不影响业务逻辑

**使用示例**：

```typescript
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）：

```typescript
// 登录成功后记录
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）：

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

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

```typescript
// 创建知识库
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 函数**：

```typescript
// 获取运营概览
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*