web-step-counter-pro 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# Web Step Counter API 文档
+
+`web-step-counter` 是一个专为移动端 Web 应用设计的高精度、防作弊步数统计组件。
+
+## 安装
+
+```bash
+# 如果发布到 npm (示例)
+npm install web-step-counter
+```
+
+或者直接引入 JS 文件：
+
+```javascript
+import { WebStepCounter } from './step-counter.js';
+```
+
+## 快速开始
+
+```javascript
+const counter = new WebStepCounter({
+    onStep: (steps) => console.log(`步数: ${steps}`),
+    onStatus: (msg, type) => console.log(`状态: ${msg}`),
+});
+
+// 必须在用户交互（点击事件）中调用
+document.getElementById('btn').onclick = () => {
+    counter.start();
+};
+```
+
+---
+
+## 配置项 (Configuration)
+
+初始化时可传入配置对象：`new WebStepCounter(config)`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `sensitivity` | Number | `12.0` | 加速度灵敏度阈值 (m/s²)。数值越小越灵敏，但也越容易误判。 |
+| `minStepInterval` | Number | `330` | 最小步频间隔 (ms)。小于此间隔视为震动干扰。 |
+| `maxStepInterval` | Number | `2000` | 最大步频间隔 (ms)。超过此间隔视为停顿。 |
+| `minConsecutiveSteps`| Number | `7` | 连续步数门槛。连续走满 N 步才开始计入总数，防止误触。 |
+| `cheatCheckInterval` | Number | `5000` | 防作弊检查周期 (ms)。每隔多久检查一次 GPS 和姿态。 |
+| `gpsAccuracyLimit` | Number | `20` | GPS 精度要求 (米)。精度低于此值时不进行 GPS 相关的防作弊判定。 |
+| `maxSpeed` | Number | `2.8` | 最大允许速度 (m/s)。约 10km/h，超过此速度不计步。 |
+| `debug` | Boolean | `false` | 是否在控制台打印详细调试日志。 |
+| `onStep` | Function | `null` | 步数更新回调 `(steps) => void` |
+| `onStatus` | Function | `null` | 状态/作弊回调 `(msg, type) => void` |
+| `onSensorData` | Function | `null` | 传感器原始数据回调 `(acc, orient) => void` |
+
+---
+
+## 方法 (Methods)
+
+### `start(): Promise<boolean>`
+初始化传感器并开始计步。
+*   **必须在用户点击事件中调用**（iOS 权限要求）。
+*   自动处理 iOS 13+ 的权限请求流程。
+*   返回 `true` 表示启动成功，`false` 表示被拒绝或出错。
+
+### `stop(): void`
+停止计步，移除所有传感器监听器，停止 GPS 轮询。
+
+### `reset(): void`
+重置步数、防作弊历史数据和内部缓冲区。
+
+### `requestOrientationPermission(): Promise<boolean>`
+手动请求设备方向权限的辅助方法。
+*   用于解决 iOS 上某些情况下 Orientation 权限未被正确授予的问题。
+*   建议在 UI 上提供一个“修复权限”按钮调用此方法。
+
+---
+
+## 状态与防作弊代码 (Status & Cheating Types)
+
+`onStatus(msg, type)` 回调会返回当前系统的运行状态或检测到的异常。
+
+### 状态类型 (`type`)
+
+| 类型 (Type) | 说明 | 示例消息 |
+| :--- | :--- | :--- |
+| `'success'` | 正常运行 | "正在运行", "GPS 验证正常" |
+| `'info'` | 一般信息 | "已停止", "已重置" |
+| `'warning'` | 警告/非阻断性问题 | "GPS 信号弱", "需手动授权 Orientation" |
+| `'error'` | 错误/阻断性问题 | "Motion 权限被拒绝", "必须使用 HTTPS" |
+| `'cheating'` | **检测到作弊行为** | 见下方作弊类型 |
+
+### 常见作弊/异常消息
+
+| 消息内容 | 触发原因 | 算法逻辑 |
+| :--- | :--- | :--- |
+| `"检测到剧烈摇晃"` | 陀螺仪检测到高频旋转 | `RotationRate > 300 deg/s` |
+| `"检测到机械节奏"` | 步频方差极低 (摇步机) | 最近 20 步的时间间隔标准差 `< 5ms` |
+| `"检测到原地运动 (GPS)"` | 步数增加但 GPS 未移动 | `StepsDiff > 15` 且 `GPSDistance < 3m` |
+| `"速度过快 (xx km/h)"` | 移动速度超过阈值 | `Speed > 10 km/h` (判定为骑车/开车) |
+| *(静默丢弃)* | 手机水平放置/拍桌子 | `Beta < 5°` 且 `Gamma < 5°` |
+
+---
+
+## 最佳实践
+
+1.  **HTTPS**: 必须在 HTTPS 环境下使用，否则现代浏览器拒绝访问传感器。
+2.  **iOS 权限**: 务必设计引导 UI，提示用户在弹窗中点击“允许”。
+3.  **UI 反馈**: 当 `type === 'cheating'` 时，建议在 UI 上显示醒目的红色警告，提示用户“步数可能无效”。
+

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "web-step-counter-pro", 
+  "version": "1.0.0",
+  "description": "A professional-grade web step counting library with advanced anti-cheat mechanisms (GPS, Gyroscope, Rhythm Analysis).",
+  "main": "step-counter.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "pedometer",
+    "step-counter",
+    "anti-cheat",
+    "gps",
+    "gyroscope",
+    "fitness",
+    "web-api"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "files": [
+    "step-counter.js",
+    "README.md",
+    "package.json"
+  ]
+}

package/step-counter.js

@@ -0,0 +1,348 @@
+/**
+ * WebStepCounter - 专业级 Web 步数统计与防作弊组件
+ */
+export class WebStepCounter {
+    /**
+     * 状态类型枚举
+     * @readonly
+     * @enum {string}
+     */
+    static StatusType = {
+        SUCCESS: 'success',
+        INFO: 'info',
+        WARNING: 'warning',
+        ERROR: 'error',
+        CHEATING: 'cheating'
+    };
+
+    /**
+     * 错误/状态码枚举
+     * @readonly
+     * @enum {string}
+     */
+    static StatusCode = {
+        // 正常
+        RUNNING: 'RUNNING',
+        GPS_OK: 'GPS_OK',
+        
+        // 错误
+        HTTPS_REQUIRED: 'HTTPS_REQUIRED',
+        PERMISSION_DENIED: 'PERMISSION_DENIED',
+        GPS_ERROR: 'GPS_ERROR',
+        
+        // 作弊/异常
+        CHEAT_SHAKING: 'CHEAT_SHAKING',         // 剧烈摇晃 (陀螺仪)
+        CHEAT_MECHANICAL: 'CHEAT_MECHANICAL',   // 机械节奏 (摇步机)
+        CHEAT_STATIONARY: 'CHEAT_STATIONARY',   // 原地踏步 (GPS)
+        CHEAT_OVERSPEED: 'CHEAT_OVERSPEED',     // 速度过快 (开车)
+        INVALID_ORIENTATION: 'INVALID_ORIENTATION' // 姿态无效 (拍桌子)
+    };
+
+    constructor(config = {}) {
+        // ... (保持原有构造函数逻辑，但推荐使用常量)
+        this.config = {
+            sensitivity: 12.0,
+            minStepInterval: 330,
+            maxStepInterval: 2000,
+            minConsecutiveSteps: 7,
+            cheatCheckInterval: 5000,
+            gpsAccuracyLimit: 20,
+            maxSpeed: 2.8,
+            debug: false,
+            onStep: null,
+            onStatus: null,
+            onSensorData: null,
+            ...config
+        };
+
+        // 内部状态
+        this.stepCount = 0;
+        this.isTracking = false;
+        this.candidateSteps = 0;
+        this.lastStepTime = 0;
+        this.lastCandidateStepTime = 0;
+        
+        this.accBuffer = [];
+        this.timestampBuffer = [];
+        this.windowSize = 50;
+
+        this.lastCheckTime = 0;
+        this.lastCheckStepCount = 0;
+        this.lastCheckLat = null;
+        this.lastCheckLon = null;
+        this.stepIntervalHistory = [];
+        this.gyroCheating = false;
+        this.orientationValid = true;
+        
+        this.orientationData = { alpha: 0, beta: 0, gamma: 0 };
+
+        this.handleMotion = this.handleMotion.bind(this);
+        this.handleOrientation = this.handleOrientation.bind(this);
+        this.handleGeolocation = this.handleGeolocation.bind(this);
+    }
+
+    async start() {
+        if (this.isTracking) return;
+
+        if (location.protocol !== 'https:' && location.hostname !== 'localhost' && location.hostname !== '127.0.0.1') {
+            this._reportStatus("必须使用 HTTPS 协议", WebStepCounter.StatusType.ERROR, WebStepCounter.StatusCode.HTTPS_REQUIRED);
+            return false;
+        }
+
+        this._reportStatus("正在请求传感器权限...", WebStepCounter.StatusType.INFO);
+
+        const permissionGranted = await this._requestPermissions();
+        if (!permissionGranted) return false;
+
+        if ("geolocation" in navigator) {
+            this.watchId = navigator.geolocation.watchPosition(
+                this.handleGeolocation, 
+                (err) => this._reportStatus(`GPS 错误: ${err.message}`, WebStepCounter.StatusType.WARNING, WebStepCounter.StatusCode.GPS_ERROR), 
+                { enableHighAccuracy: true, timeout: 5000, maximumAge: 0 }
+            );
+        }
+
+        this.isTracking = true;
+        this._reportStatus("正在运行", WebStepCounter.StatusType.SUCCESS, WebStepCounter.StatusCode.RUNNING);
+        return true;
+    }
+
+    stop() {
+        this.isTracking = false;
+        window.removeEventListener('devicemotion', this.handleMotion);
+        window.removeEventListener('deviceorientation', this.handleOrientation);
+        window.removeEventListener('deviceorientationabsolute', this.handleOrientation);
+        
+        if (this.watchId) {
+            navigator.geolocation.clearWatch(this.watchId);
+        }
+        this._reportStatus("已停止", WebStepCounter.StatusType.INFO);
+    }
+
+    reset() {
+        this.stepCount = 0;
+        this.candidateSteps = 0;
+        this.accBuffer = [];
+        this.stepIntervalHistory = [];
+        this.lastCheckLat = null;
+        this._triggerStepUpdate();
+        this._reportStatus("已重置", WebStepCounter.StatusType.INFO);
+    }
+
+    async requestOrientationPermission() {
+        if (typeof DeviceOrientationEvent !== 'undefined' && typeof DeviceOrientationEvent.requestPermission === 'function') {
+            try {
+                const permission = await DeviceOrientationEvent.requestPermission();
+                if (permission === 'granted') {
+                    window.addEventListener('deviceorientation', this.handleOrientation);
+                    window.addEventListener('deviceorientationabsolute', this.handleOrientation);
+                    return true;
+                }
+            } catch (e) {
+                console.error(e);
+            }
+        }
+        return false;
+    }
+
+    // --- Internal ---
+
+    async _requestPermissions() {
+        if (typeof DeviceMotionEvent !== 'undefined' && typeof DeviceMotionEvent.requestPermission === 'function') {
+            try {
+                const motionPerm = await DeviceMotionEvent.requestPermission();
+                if (motionPerm !== 'granted') {
+                    this._reportStatus("Motion 权限被拒绝", WebStepCounter.StatusType.ERROR, WebStepCounter.StatusCode.PERMISSION_DENIED);
+                    return false;
+                }
+                window.addEventListener('devicemotion', this.handleMotion);
+
+                if (typeof DeviceOrientationEvent !== 'undefined' && typeof DeviceOrientationEvent.requestPermission === 'function') {
+                    try {
+                        const orientPerm = await DeviceOrientationEvent.requestPermission();
+                        if (orientPerm === 'granted') {
+                            window.addEventListener('deviceorientation', this.handleOrientation);
+                            window.addEventListener('deviceorientationabsolute', this.handleOrientation);
+                        } else {
+                            this._reportStatus("需手动授权 Orientation", WebStepCounter.StatusType.WARNING, WebStepCounter.StatusCode.PERMISSION_DENIED);
+                        }
+                    } catch (e) {
+                        this._reportStatus("需手动授权 Orientation", WebStepCounter.StatusType.WARNING);
+                    }
+                }
+            } catch (e) {
+                this._reportStatus(`权限请求出错: ${e.message}`, WebStepCounter.StatusType.ERROR);
+                return false;
+            }
+        } else {
+            window.addEventListener('devicemotion', this.handleMotion);
+            if (window.DeviceOrientationEvent) {
+                window.addEventListener('deviceorientation', this.handleOrientation);
+            }
+            if ('ondeviceorientationabsolute' in window) {
+                window.addEventListener('deviceorientationabsolute', this.handleOrientation);
+            }
+        }
+        return true;
+    }
+
+    handleMotion(event) {
+        const acc = event.accelerationIncludingGravity;
+        const rotation = event.rotationRate;
+        if (!acc) return;
+
+        if (this._checkGyroCheating(rotation)) {
+            this._reportStatus("检测到剧烈摇晃", WebStepCounter.StatusType.CHEATING, WebStepCounter.StatusCode.CHEAT_SHAKING);
+            return;
+        }
+
+        if (!this._checkOrientationValidity()) {
+            // 静默丢弃，不频繁刷日志
+            return;
+        }
+
+        if (this.config.onSensorData) {
+            this.config.onSensorData({ x: acc.x, y: acc.y, z: acc.z }, this.orientationData);
+        }
+
+        const magnitude = Math.sqrt(acc.x*acc.x + acc.y*acc.y + acc.z*acc.z);
+        this._processGait(magnitude, Date.now());
+    }
+
+    handleOrientation(event) {
+        this.orientationData = {
+            alpha: event.alpha || 0,
+            beta: event.beta || 0,
+            gamma: event.gamma || 0
+        };
+    }
+
+    handleGeolocation(position) {
+        const { latitude, longitude, accuracy, speed } = position.coords;
+        this._checkAntiCheatGPS(latitude, longitude, accuracy, speed);
+    }
+
+    _processGait(magnitude, now) {
+        this.accBuffer.push(magnitude);
+        this.timestampBuffer.push(now);
+
+        if (this.accBuffer.length > this.windowSize) {
+            this.accBuffer.shift();
+            this.timestampBuffer.shift();
+        }
+        if (this.accBuffer.length < 15) return;
+
+        let min = Infinity, max = -Infinity;
+        for (let val of this.accBuffer) {
+            if (val < min) min = val;
+            if (val > max) max = val;
+        }
+        const range = max - min;
+        if (range < 2.0) return; 
+
+        const currentThreshold = (min + max) / 2;
+        const midIndex = Math.floor(this.accBuffer.length / 2);
+        const midVal = this.accBuffer[midIndex];
+        const midTime = this.timestampBuffer[midIndex];
+
+        if (midVal >= currentThreshold && 
+            midVal > this.accBuffer[midIndex-1] && 
+            midVal > this.accBuffer[midIndex+1]) {
+            
+            const timeSinceLast = midTime - this.lastCandidateStepTime;
+
+            if (timeSinceLast > this.config.minStepInterval && 
+                timeSinceLast < this.config.maxStepInterval) {
+                
+                if (this._checkMechanicalRhythm(timeSinceLast)) {
+                    this._reportStatus("检测到机械节奏", WebStepCounter.StatusType.CHEATING, WebStepCounter.StatusCode.CHEAT_MECHANICAL);
+                    return;
+                }
+
+                this.candidateSteps++;
+                this.lastCandidateStepTime = midTime;
+
+                if (this.candidateSteps === this.config.minConsecutiveSteps) {
+                    this.stepCount += this.config.minConsecutiveSteps;
+                    this._triggerStepUpdate();
+                } else if (this.candidateSteps > this.config.minConsecutiveSteps) {
+                    this.stepCount++;
+                    this._triggerStepUpdate();
+                }
+
+            } else if (timeSinceLast > this.config.maxStepInterval) {
+                this.candidateSteps = 1;
+                this.lastCandidateStepTime = midTime;
+                this.stepIntervalHistory = [];
+            }
+        }
+    }
+
+    _checkGyroCheating(rotation) {
+        if (!rotation) return false;
+        const mag = Math.sqrt(rotation.alpha**2 + rotation.beta**2 + rotation.gamma**2);
+        return mag > 300; 
+    }
+
+    _checkOrientationValidity() {
+        const { beta, gamma } = this.orientationData;
+        return !(Math.abs(beta) < 5 && Math.abs(gamma) < 5);
+    }
+
+    _checkMechanicalRhythm(interval) {
+        this.stepIntervalHistory.push(interval);
+        if (this.stepIntervalHistory.length > 20) this.stepIntervalHistory.shift();
+        if (this.stepIntervalHistory.length < 20) return false;
+
+        const avg = this.stepIntervalHistory.reduce((a,b)=>a+b,0) / 20;
+        const variance = this.stepIntervalHistory.reduce((a,b)=>a+Math.pow(b-avg,2),0) / 20;
+        return Math.sqrt(variance) < 5; 
+    }
+
+    _checkAntiCheatGPS(lat, lon, accuracy, speed) {
+        const now = Date.now();
+
+        if (speed && speed > this.config.maxSpeed) {
+            this._reportStatus(`速度过快 (${(speed*3.6).toFixed(1)}km/h)`, WebStepCounter.StatusType.CHEATING, WebStepCounter.StatusCode.CHEAT_OVERSPEED);
+            this.lastCheckLat = lat; this.lastCheckLon = lon; this.lastCheckTime = now;
+            return;
+        }
+
+        if (this.lastCheckLat === null) {
+            this.lastCheckLat = lat; this.lastCheckLon = lon; 
+            this.lastCheckTime = now; this.lastCheckStepCount = this.stepCount;
+            return;
+        }
+
+        if (now - this.lastCheckTime > this.config.cheatCheckInterval) {
+            const stepsDiff = this.stepCount - this.lastCheckStepCount;
+            const dist = this._getDist(this.lastCheckLat, this.lastCheckLon, lat, lon);
+            
+            if (stepsDiff > 15 && dist < 3.0 && accuracy < this.config.gpsAccuracyLimit) {
+                this._reportStatus("检测到原地运动 (GPS)", WebStepCounter.StatusType.CHEATING, WebStepCounter.StatusCode.CHEAT_STATIONARY);
+            } else {
+                this._reportStatus("GPS 验证正常", WebStepCounter.StatusType.SUCCESS, WebStepCounter.StatusCode.GPS_OK);
+            }
+
+            this.lastCheckLat = lat; this.lastCheckLon = lon; 
+            this.lastCheckTime = now; this.lastCheckStepCount = this.stepCount;
+        }
+    }
+
+    _getDist(lat1, lon1, lat2, lon2) {
+        const R = 6371000; 
+        const dLat = (lat2-lat1) * Math.PI/180;
+        const dLon = (lon2-lon1) * Math.PI/180;
+        const a = Math.sin(dLat/2)**2 + Math.cos(lat1*Math.PI/180)*Math.cos(lat2*Math.PI/180) * Math.sin(dLon/2)**2;
+        return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+    }
+
+    _triggerStepUpdate() {
+        if (this.config.onStep) this.config.onStep(this.stepCount);
+    }
+
+    _reportStatus(msg, type, code) {
+        if (this.config.debug) console.log(`[WebStepCounter] ${msg} [${code || type}]`);
+        if (this.config.onStatus) this.config.onStatus(msg, type, code);
+    }
+}