web-step-counter-pro 1.0.4 → 1.0.5

package/README.md

@@ -35,18 +35,46 @@ document.getElementById('btn').onclick = () => {
 
 初始化时可传入配置对象：`new WebStepCounter(config)`
 
+### 参数优化说明
+
+默认参数基于市面上通用步行检测标准优化：
+- **正常步行**：60-120步/分钟（1-2步/秒），步间隔500-1000ms
+- **快走/慢跑**：120-180步/分钟（2-3步/秒），步间隔330-500ms
+- **慢走场景**：支持最慢0.67步/秒的步速
+
+这些参数能够有效支持：
+✅ 手机放在口袋里走路（任意姿态，包括平放）
+✅ 手机拿在手里走路（竖握/平握/斜握）
+✅ 室内/地下等弱GPS信号场景
+✅ 快走、慢走、正常步行等多种步速
+
+### 智能姿态检测
+
+采用**姿态变化检测**算法，精准区分正常走路和作弊行为：
+
+| 场景 | 姿态特征 | 判定结果 |
+|------|---------|---------|
+| 🚶 口袋走路 | 水平放置 + 姿态持续波动 | ✅ 正常计步 |
+| 🤚 手持走路 | 任意角度 + 姿态持续波动 | ✅ 正常计步 |
+| 🎯 拍桌子作弊 | 水平放置 + 姿态几乎静止 | ❌ 静默过滤 |
+
+**核心原理**：真实走路时，即使手机水平放置，由于身体晃动也会产生持续的姿态变化；而拍桌子时手机姿态几乎不变。
+
 | 属性 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
 | `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 相关的防作弊判定。 |
+| `minStepInterval` | Number | `300` | 最小步频间隔 (ms)。对应最快3.3步/秒，覆盖快走和慢跑场景。 |
+| `maxStepInterval` | Number | `1500` | 最大步频间隔 (ms)。对应最慢0.67步/秒，适应慢走场景。 |
+| `minConsecutiveSteps`| Number | `4` | 连续步数门槛。连续走满 N 步才开始计入总数，防止误触。 |
+| `cheatCheckInterval` | Number | `15000` | 防作弊检查周期 (ms)。每隔15秒检查一次 GPS，减少对正常运动的干扰。 |
+| `gpsAccuracyLimit` | Number | `150` | GPS 精度要求 (米)。兼容室内、地下等弱信号场景。 |
+| `accelerationThreshold` | Number | `1.2` | 加速度变化阈值 (m/s²)。匹配正常步行的垂直加速度变化范围。 |
 | `maxSpeed` | Number | `2.8` | 最大允许速度 (m/s)。约 10km/h，超过此速度不计步。 |
+| `orientationVarianceThreshold` | Number | `3.0` | 姿态变化方差阈值。用于区分"拍桌子"和"口袋走路"，方差越小越可能是静止作弊。 |
 | `debug` | Boolean | `false` | 是否在控制台打印详细调试日志。 |
+| `autoPauseOnBackground` | Boolean | `true` | Capacitor 环境下切后台时自动暂停传感器以省电。 |
 | `onStep` | Function | `null` | 步数更新回调 `(steps) => void` |
-| `onStatus` | Function | `null` | 状态/作弊回调 `(msg, type) => void` |
+| `onStatus` | Function | `null` | 状态/作弊回调 `(msg, type, code) => void` |
 | `onSensorData` | Function | `null` | 传感器原始数据回调 `(acc, orient) => void` |
 
 ---
@@ -68,7 +96,7 @@ document.getElementById('btn').onclick = () => {
 ### `requestOrientationPermission(): Promise<boolean>`
 手动请求设备方向权限的辅助方法。
 *   用于解决 iOS 上某些情况下 Orientation 权限未被正确授予的问题。
-*   建议在 UI 上提供一个“修复权限”按钮调用此方法。
+*   建议在 UI 上提供一个"修复权限"按钮调用此方法。
 
 ---
 
@@ -94,13 +122,17 @@ document.getElementById('btn').onclick = () => {
 | `"检测到机械节奏"` | 步频方差极低 (摇步机) | 最近 20 步的时间间隔标准差 `< 5ms` |
 | `"检测到原地运动 (GPS)"` | 步数增加但 GPS 未移动 | `StepsDiff > 15` 且 `GPSDistance < 3m` |
 | `"速度过快 (xx km/h)"` | 移动速度超过阈值 | `Speed > 10 km/h` (判定为骑车/开车) |
-| *(静默丢弃)* | 手机水平放置/拍桌子 | `Beta < 5°` 且 `Gamma < 5°` |
+| *(静默丢弃)* | 拍桌子作弊 | 水平放置 + 姿态方差 `< 3.0` (姿态几乎静止) |
 
 ---
 
 ## 最佳实践
 
 1.  **HTTPS**: 必须在 HTTPS 环境下使用，否则现代浏览器拒绝访问传感器。
-2.  **iOS 权限**: 务必设计引导 UI，提示用户在弹窗中点击“允许”。
-3.  **UI 反馈**: 当 `type === 'cheating'` 时，建议在 UI 上显示醒目的红色警告，提示用户“步数可能无效”。
+2.  **iOS 权限**: 务必设计引导 UI，提示用户在弹窗中点击"允许"。
+3.  **UI 反馈**: 当 `type === 'cheating'` 时，建议在 UI 上显示醒目的红色警告，提示用户"步数可能无效"。
+4.  **姿态检测**: 智能姿态检测算法已内置，无需额外配置。它能自动区分"拍桌子"和"口袋走路"，支持手机在任意姿态下正常计步。
+5.  **参数调优**: 若在特殊场景下出现误判，可适当调整 `orientationVarianceThreshold` 参数（默认3.0）：
+    - 增大该值（如5.0）：更严格，可能误判部分缓慢行走场景
+    - 减小该值（如1.5）：更宽松，可能漏过部分拍桌子作弊
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-step-counter-pro",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A professional-grade web step counting library with advanced anti-cheat mechanisms (GPS, Gyroscope, Rhythm Analysis).",
   "main": "step-counter.js",
   "type": "module",

package/step-counter.js

@@ -39,17 +39,21 @@ export class WebStepCounter {
     };
 
     constructor(config = {}) {
-        // ... (保持原有构造函数逻辑，但推荐使用常量)
+        // 基于市面上通用步行检测标准优化的参数
+        // 正常步行：60-120步/分钟（1-2步/秒），步间隔500-1000ms
+        // 快走/慢跑：120-180步/分钟（2-3步/秒），步间隔330-500ms
         this.config = {
-            sensitivity: 12.0,
-            minStepInterval: 330,
-            maxStepInterval: 2000,
-            minConsecutiveSteps: 7,
-            cheatCheckInterval: 5000,
-            gpsAccuracyLimit: 20,
-            maxSpeed: 2.8,
+            sensitivity: 12.0,           // 灵敏度，匹配正常步行的加速度变化（0.8-2.0 m/s²）
+            minStepInterval: 300,        // 最小步间隔300ms，对应最快3.3步/秒，覆盖快走和慢跑场景
+            maxStepInterval: 1500,       // 最大步间隔1500ms，对应最慢0.67步/秒，适应慢走场景
+            minConsecutiveSteps: 4,      // 连续4步才开始计数，避免误触和抖动
+            cheatCheckInterval: 15000,   // 延长检查间隔到15秒，减少对正常运动的干扰
+            gpsAccuracyLimit: 150,       // GPS精度限制150米，兼容室内、地下等弱信号场景
+            accelerationThreshold: 1.2,  // 加速度阈值1.2 m/s²，匹配正常步行的垂直加速度变化
+            maxSpeed: 2.8,               // 最大允许速度2.8 m/s（约10 km/h）
+            orientationVarianceThreshold: 3.0, // 姿态变化阈值：方差小于此值视为姿态静止（可能是拍桌子）
             debug: false,
-            autoPauseOnBackground: true, // 新增: Capacitor 环境下切后台自动暂停传感器
+            autoPauseOnBackground: true, // Capacitor 环境下切后台自动暂停传感器
             onStep: null,
             onStatus: null,
             onSensorData: null,
@@ -77,6 +81,7 @@ export class WebStepCounter {
         this.orientationValid = true;
         
         this.orientationData = { alpha: 0, beta: 0, gamma: 0 };
+        this.orientationHistory = []; // 用于检测姿态变化
 
         // 节流控制
         this._lastUiUpdate = 0;
@@ -252,6 +257,7 @@ export class WebStepCounter {
             return;
         }
 
+        // 智能姿态检测：区分"拍桌子"和"口袋走路"
         if (!this._checkOrientationValidity()) {
             // 静默丢弃，不频繁刷日志
             return;
@@ -294,7 +300,7 @@ export class WebStepCounter {
             if (val > max) max = val;
         }
         const range = max - min;
-        if (range < 2.0) return; 
+        if (range < this.config.accelerationThreshold) return; 
 
         const currentThreshold = (min + max) / 2;
         const midIndex = Math.floor(this.accBuffer.length / 2);
@@ -342,7 +348,50 @@ export class WebStepCounter {
 
     _checkOrientationValidity() {
         const { beta, gamma } = this.orientationData;
-        return !(Math.abs(beta) < 5 && Math.abs(gamma) < 5);
+        
+        // 记录最近的姿态数据（最多保存20个样本，约1秒的数据）
+        this.orientationHistory.push({ beta, gamma, timestamp: Date.now() });
+        if (this.orientationHistory.length > 20) {
+            this.orientationHistory.shift();
+        }
+        
+        // 样本不足时，暂不判断
+        if (this.orientationHistory.length < 10) {
+            return true;
+        }
+        
+        // 检查当前姿态是否接近水平（可能是桌面放置）
+        const isHorizontal = Math.abs(beta) < 15 && Math.abs(gamma) < 15;
+        
+        if (!isHorizontal) {
+            // 手机明显倾斜，肯定不是平放拍桌子，直接通过
+            return true;
+        }
+        
+        // 手机接近水平状态，需要进一步判断是"拍桌子"还是"口袋走路"
+        // 计算姿态变化的方差
+        const betaValues = this.orientationHistory.map(o => o.beta);
+        const gammaValues = this.orientationHistory.map(o => o.gamma);
+        
+        const betaVariance = this._calculateVariance(betaValues);
+        const gammaVariance = this._calculateVariance(gammaValues);
+        const totalVariance = betaVariance + gammaVariance;
+        
+        // 如果姿态几乎不变化（方差很小），且处于水平位置，则可能是拍桌子
+        if (totalVariance < this.config.orientationVarianceThreshold) {
+            // 姿态静止 + 水平放置 = 疑似拍桌子作弊
+            return false;
+        }
+        
+        // 姿态有变化，说明人在走动，允许计步
+        return true;
+    }
+    
+    _calculateVariance(values) {
+        if (values.length === 0) return 0;
+        const mean = values.reduce((a, b) => a + b, 0) / values.length;
+        const variance = values.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / values.length;
+        return variance;
     }
 
     _checkMechanicalRhythm(interval) {