@wq-hook/anti-cheating-monitor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anti-Cheating Monitor Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,332 @@
+# 🛡️ Anti-Cheating Monitor
+
+[![npm version](https://badge.fury.io/js/anti-cheating-monitor.svg)](https://badge.fury.io/js/anti-cheating-monitor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18.0+-61dafb.svg)](https://reactjs.org/)
+
+基于阿里云视觉智能平台的实时反作弊监控系统，提供人脸检测、异常行为分析和完整的在线监考解决方案。
+
+## ✨ 特性
+
+- 🎯 **实时监控** - 基于摄像头的持续行为分析
+- 🧠 **智能检测** - 多维度异常行为识别
+- ☁️ **云端处理** - 阿里云 VIAPI 高精度分析
+- 📊 **数据统计** - 完整的监控数据和性能指标
+- 🔒 **安全可靠** - 完善的错误处理和资源管理
+- 🚀 **高性能** - 节流控制和优化策略
+- 📱 **响应式** - 适配各种设备和屏幕尺寸
+- ⚙️ **可配置** - 灵活的阈值配置和热更新
+- 📝 **审计日志** - 完整的配置变更追踪
+- 🎣 **Hook集成** - 现代React Hook API
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 使用 npm
+npm install anti-cheating-monitor
+
+# 使用 yarn
+yarn add anti-cheating-monitor
+
+# 使用 pnpm
+pnpm add anti-cheating-monitor
+```
+
+### 基础用法
+
+```tsx
+import React from 'react';
+import { useAntiCheatingMonitor } from 'anti-cheating-monitor';
+
+const ExamMonitor = () => {
+  const {
+    videoRef,
+    canvasRef,
+    startMonitoring,
+    stopMonitoring,
+    isMonitoring,
+    latestResult,
+    stats,
+    config,
+    updateConfig
+  } = useAntiCheatingMonitor({
+    credentials: {
+      accessKeyId: process.env.VITE_ACCESS_KEY_ID!,
+      accessKeySecret: process.env.VITE_ACCESS_KEY_SECRET!,
+      securityToken: process.env.VITE_SECURITY_TOKEN,
+    },
+    config: {
+      checkInterval: 3000,           // 检测间隔（毫秒）
+      detectMultiplePeople: true,     // 检测多人
+      detectDeviceUsage: true,        // 检测设备使用
+      detectAbsence: true,            // 检测离席
+      resolution: { width: 640, height: 480 },
+    },
+    onViolation: (violation) => {
+      console.log('检测到违规:', violation);
+      // 处理违规行为，如记录日志、发送通知等
+    },
+    onDetectionResult: (result) => {
+      console.log('检测结果:', result);
+      if (result.violations.length > 0) {
+        // 处理异常行为
+        // 使用更友好的通知方式替代 alert
+        console.warn(`检测到异常: ${result.violations.map(v => v.description).join(', ')}`);
+        // 这里可以集成通知组件库，如 antd 的 message 或 notification
+        // message.error(`检测到异常: ${result.violations.map(v => v.description).join(', ')}`);
+      }
+    },
+    onError: (error) => {
+      console.error('监控错误:', error);
+    },
+  });
+
+  return (
+    <div className="monitor-container">
+      <video
+        ref={videoRef}
+        autoPlay
+        muted
+        playsInline
+        className="monitor-video"
+      />
+      <canvas ref={canvasRef} style={{ display: 'none' }} />
+      
+      <div className="control-panel">
+        <button
+          onClick={startMonitoring}
+          disabled={isMonitoring}
+          className="btn btn-primary"
+        >
+          {isMonitoring ? '监控中...' : '开始监控'}
+        </button>
+        
+        <button
+          onClick={stopMonitoring}
+          disabled={!isMonitoring}
+          className="btn btn-secondary"
+        >
+          停止监控
+        </button>
+      </div>
+      
+      {isMonitoring && (
+        <div className="stats-panel">
+          <div>检测次数: {stats.checkCount}</div>
+          <div>异常次数: {stats.abnormalCount}</div>
+          <div>网络延迟: {stats.latency}ms</div>
+          <div>网络质量: {stats.networkQuality}</div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ExamMonitor;
+```
+
+## 📖 API 文档
+
+### useAntiCheatingMonitor
+
+核心 Hook，提供完整的反作弊监控功能。
+
+#### 参数
+
+```typescript
+interface UseAntiCheatingMonitorProps {
+  credentials: AntiCheatingCredentials;  // 阿里云凭证
+  config?: Partial<DetectionConfig>;     // 配置选项
+  onViolation?: (violation: CheatingViolation) => void;  // 违规回调
+  onDetectionResult?: (result: DetectionResult) => void;  // 检测结果回调
+  onError?: (error: Error) => void;     // 错误回调
+  onConfigChange?: (config: DetectionConfig) => void;  // 配置变更回调
+}
+```
+
+#### 返回值
+
+```typescript
+interface UseAntiCheatingMonitorReturn {
+  videoRef: React.RefObject<HTMLVideoElement | null>;  // 视频元素引用
+  canvasRef: React.RefObject<HTMLCanvasElement | null>; // 画布元素引用
+  startMonitoring: () => Promise<void>;                // 开始监控
+  stopMonitoring: () => void;                          // 停止监控
+  forceCheck: () => Promise<void>;                     // 强制检测
+  isMonitoring: boolean;                               // 监控状态
+  latestResult: DetectionResult | null;                // 最新检测结果
+  stats: MonitorStats;                                 // 统计信息
+  config: DetectionConfig;                              // 当前配置
+  updateConfig: (config: Partial<DetectionConfig>) => Promise<{success: boolean, errors?: string[]}>; // 更新配置
+  getConfigManager: () => ConfigManager;                // 获取配置管理器
+}
+```
+
+### 检测配置
+
+```typescript
+interface DetectionConfig {
+  checkInterval: number;                    // 检测间隔（毫秒）
+  detectMultiplePeople: boolean;            // 是否检测多人
+  detectDeviceUsage: boolean;               // 是否检测设备使用
+  detectAbsence: boolean;                  // 是否检测离席
+  resolution: { width: number; height: number }; // 视频分辨率
+  type: number;                           // 检测类型
+  earphoneThreshold: number;               // 耳机检测阈值
+  cellphoneThreshold: number;              // 手机检测阈值
+  headPoseThreshold: {                    // 头部姿态阈值
+    pitch: number;  // 俯仰角
+    roll: number;   // 翻滚角
+    yaw: number;    // 偏航角
+  };
+  faceCompletenessThreshold: number;       // 人脸完整度阈值
+  centeringThreshold: number;             // 人脸居中阈值
+  movementThreshold: number;              // 可疑移动阈值
+}
+```
+
+### 违规类型
+
+```typescript
+enum CheatingType {
+  PERSON_COUNT_ANOMALY = "PERSON_COUNT_ANOMALY",    // 人数异常
+  EARPHONE_DETECTED = "EARPHONE_DETECTED",            // 检测到耳机
+  CELLPHONE_DETECTED = "CELLPHONE_DETECTED",          // 检测到手机
+  HEAD_POSTURE_ABNORMAL = "HEAD_POSTURE_ABNORMAL",    // 头部姿态异常
+  FACE_MISSING = "FACE_MISSING",                      // 人脸缺失
+  FACE_OCCLUDED = "FACE_OCCLUDED",                    // 人脸被遮挡
+  NO_FACE_DETECTED = "NO_FACE_DETECTED",              // 未检测到人脸
+  MULTIPLE_FACES_DETECTED = "MULTIPLE_FACES_DETECTED", // 检测到多张人脸
+  NOT_CENTERED = "NOT_CENTERED",                     // 未居中
+  SUSPICIOUS_MOVEMENT = "SUSPICIOUS_MOVEMENT"        // 可疑移动
+}
+```
+
+## 🔧 高级配置
+
+### 配置管理
+
+```typescript
+import { ConfigManager } from 'anti-cheating-monitor';
+
+// 获取配置管理器实例
+const configManager = new ConfigManager();
+
+// 更新配置
+const result = configManager.updateConfig({
+  checkInterval: 5000,
+  detectMultiplePeople: true
+}, {
+  source: 'local',
+  operator: 'admin'
+});
+
+if (result.success) {
+  console.log('配置更新成功');
+} else {
+  console.error('配置更新失败:', result.errors);
+}
+
+// 获取审计日志
+const auditLogs = configManager.getAuditLogs();
+console.log('配置变更历史:', auditLogs);
+```
+
+### 检测引擎
+
+```typescript
+import { DetectionEngine } from 'anti-cheating-monitor';
+
+const engine = new DetectionEngine(config, credentials);
+
+// 执行检测
+const result = await engine.detect(imageData);
+console.log('检测结果:', result);
+
+// 获取统计信息
+const stats = engine.getDetectionStats();
+console.log('检测统计:', stats);
+```
+
+## 🔒 安全最佳实践
+
+### 1. 凭证管理
+
+```typescript
+// ❌ 不推荐：硬编码凭证
+const credentials = {
+  accessKeyId: "LTAI5t...",
+  accessKeySecret: "secretpassword"
+};
+
+// ✅ 推荐：使用环境变量
+const credentials = {
+  accessKeyId: process.env.VITE_ACCESS_KEY_ID!,
+  accessKeySecret: process.env.VITE_ACCESS_KEY_SECRET!,
+  securityToken: process.env.VITE_SECURITY_TOKEN, // STS 临时凭证
+};
+```
+
+### 2. STS 临时凭证
+
+```typescript
+// 获取 STS 临时凭证
+const getTemporaryCredentials = async () => {
+  const response = await fetch('/api/sts-token');
+  return await response.json();
+};
+
+// 在组件中使用
+const [credentials, setCredentials] = useState();
+
+useEffect(() => {
+  getTemporaryCredentials().then(setCredentials);
+}, []);
+```
+
+## 🌍 浏览器支持
+
+- Chrome >= 88
+- Firefox >= 85
+- Safari >= 14
+- Edge >= 88
+
+## 📦 依赖
+
+### Peer Dependencies
+
+- React >= 18.0.0
+- React-DOM >= 18.0.0
+
+### Dependencies
+
+- ali-oss: 阿里云对象存储SDK
+
+## 🤝 贡献
+
+欢迎贡献代码！请查看 [贡献指南](../docs/CONTRIBUTING.md) 了解详细信息。
+
+## 📄 许可证
+
+本项目采用 [MIT 许可证](./LICENSE)。
+
+## 🙏 致谢
+
+- [阿里云视觉智能开放平台](https://vision.aliyun.com/) - 提供强大的人脸识别和行为分析能力
+- [React](https://reactjs.org/) - 用户界面构建
+- [Vite](https://vitejs.dev/) - 现代化构建工具
+- [TypeScript](https://www.typescriptlang.org/) - 类型安全的 JavaScript
+
+## 📞 支持
+
+- 📧 邮箱: 819049639@qq.com
+- 🐛 问题反馈: [GitHub Issues](https://github.com/coding-daily-wq/anti-cheating-monitor/issues)
+- 💬 讨论: [GitHub Discussions](https://github.com/coding-daily-wq/anti-cheating-monitor/discussions)
+- 📖 文档: [在线文档](https://coding-daily-wq.github.io/anti-cheating-monitor)
+
+---
+
+⭐ 如果这个项目对您有帮助，请给我们一个 Star！