Deploy API Server / build-and-deploy (push) Failing after 20s

Details

feat: M-API-ADMIN-INFO admin backend complete (21/21)

- Admin dashboard + query endpoints (reading-events/sessions/progress/daily-activities/records)
- Diagnostic (user-timeline/diagnose/material-diagnose/anomalies/temporary-materials)
- Operations (recalculate/export)
- Admin API design doc

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-09 21:42:47 +08:00

3.4 KiB

Raw Blame History

学习信息后台接口总设计

API-ADMIN-INFO-000 | v1.0 | 2026-06-09

1. 概述

基于 M8 核心数据表（ReadingEvent / LearningSession / MaterialReadingProgress / DailyLearningActivity / LearningRecord / TemporaryReadingMaterial），为 Admin Dashboard 提供管理查询、诊断、操作接口。

路由前缀

/admin/learning/*

鉴权

所有接口需要 AdminJwtGuard
角色要求：ADMIN 或 SUPER_ADMIN
审计日志记录操作人和时间

2. 接口总览

查询接口

方法	路径	说明
GET	`/admin/learning/dashboard`	Dashboard 概览
GET	`/admin/learning/reading-events`	ReadingEvent 列表/详情
GET	`/admin/learning/reading-events/:id`	ReadingEvent 详情
GET	`/admin/learning/reading-events/failed`	失败/警告/重复事件
GET	`/admin/learning/sessions`	LearningSession 列表
GET	`/admin/learning/sessions/:id`	LearningSession 详情
GET	`/admin/learning/progress`	MaterialReadingProgress 列表
GET	`/admin/learning/progress/:id`	资料进度详情
GET	`/admin/learning/daily-activities`	DailyLearningActivity 列表
GET	`/admin/learning/records`	LearningRecord 列表
GET	`/admin/learning/records/:id`	LearningRecord 详情
GET	`/admin/learning/user-timeline?userId=`	用户学习时间线
GET	`/admin/learning/user-diagnose?userId=`	单用户诊断
GET	`/admin/learning/material-diagnose?materialId=`	单资料诊断
GET	`/admin/learning/anomalies`	异常数据查询
GET	`/admin/learning/sessions/interrupted`	中断 session 列表
GET	`/admin/learning/temporary-materials`	临时资料列表

操作接口

方法	路径	说明
POST	`/admin/learning/reading-events/:id/reprocess`	重处理单事件
POST	`/admin/learning/reading-events/reprocess-batch`	批量重处理
POST	`/admin/learning/recalculate`	重算学习数据
GET	`/admin/learning/export`	导出学习数据
PUT	`/admin/learning/event-config`	事件处理配置

3. 分页/筛选/排序规范

interface PaginationQuery {
  page?: number;       // default 1
  limit?: number;      // default 20, max 100
  sortBy?: string;     // 排序字段
  order?: 'asc' | 'desc';  // default desc
}

interface EventFilter extends PaginationQuery {
  userId?: string;
  materialId?: string;
  readingTargetType?: string;
  eventType?: string;
  status?: string;
  startDate?: string;
  endDate?: string;
}

4. Dashboard 数据结构

interface AdminDashboard {
  overview: {
    totalEvents: number;
    todayEvents: number;
    failedEvents: number;
    duplicateEvents: number;
  };
  sessions: {
    active: number;
    interrupted: number;
    completed: number;
    total: number;
  };
  users: {
    activeToday: number;
    totalWithEvents: number;
  };
  materials: {
    totalRead: number;
    totalMarkedRead: number;
  };
}

5. 审计日志

每个管理操作记录：

action: 操作类型 (READ/WRITE/DELETE/EXPORT)
resource: 资源路径
adminId: 操作人
timestamp: 时间
details: 详情（查询参数/操作结果摘要）

6. 错误码

码	含义
`ADMIN_ACCESS_DENIED`	非管理员
`INVALID_DATE_RANGE`	日期范围无效
`EXPORT_LIMIT_EXCEEDED`	导出超限
`RECALCULATE_IN_PROGRESS`	重算进行中

3.4 KiB Raw Blame History Unescape Escape

学习信息后台接口 总设计