# PunchHelper
**Repository Path**: pineapplecat/punch-helper
## Basic Information
- **Project Name**: PunchHelper
- **Description**: 打卡小助手APP
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-04-07
- **Last Updated**: 2025-04-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# **打卡小助手 Android-v2.0 Release Candidate**
基于 HMS Core 推送服务和华为云数据库服务，实现向用户推送消息通知并在客户端一键设置系统闹钟，提醒用户打卡
---
## 功能性需求（Functional Requirements）
### FR-1 客户端基础能力
| ID | 需求描述 | 验收标准 |
| ------ | ------------------------------------------------------------ | -------------------------------------------------------- |
| FR-1.1 | 系统在设备熄屏/亮屏等状态变化时，【华为设备】通过HMS Core推送服务触发打卡通知，【非华为设备】通过华为云数据库变更触发本地通知 | 【分设备类型测试各10次状态切换，对应推送触发成功率≥99%】 |
| FR-1.2 | 应用基础属性需满足：
• 应用图标为自定义Logo
• 显示名称为"打卡助手"
• 包名固定为`com.zjhw.punchhelper` | 通过APK反编译验证属性一致性 |
| FR-1.3 | 在网络可用时，提供"获取Token"按钮：
• 【华为设备】通过HMS Core获取推送Token
• 【非华为设备】生成设备唯一标识并注册到华为云数据库 | 按钮点击后3秒内显示请求状态（成功/失败） |
| FR-1.4 | 在网络可用时，提供"测试Push"按钮：
• 【华为设备】使用Push Kit发送测试通知
• 【非华为设备】触发本地数据库变更事件 | 测试通知需在5秒内到达且内容符合预设模板 |
| FR-1.5 | 在应用界面中明文展示当前设备的【华为推送Token或设备唯一标识】 | 标识显示区域需支持横向滚动查看完整内容 |
| FR-1.6 | 提供"复制标识"按钮，点击后将【Token/设备ID】写入系统剪贴板 | 剪贴板内容需与界面显示标识完全一致 |
### FR-2 服务管理能力
| ID | 需求描述 | 验收标准 |
| ------ | ------------------------------------------------------------ | ----------------------------------- |
| FR-2.1 | 支持解析管理员上传的Excel文件，提取字段：
• 时间周期（开始日期、结束日期）
• 人员身份（讲师/班主任等）
• 【设备类型（华为/非华为）】 | 解析含100条记录的Excel文件耗时≤10秒 |
| FR-2.2 | 根据人员身份自动映射对应的【华为设备Token或非华为设备数据库ID】 | 身份-设备映射准确率100% |
| FR-2.3 | 通过【双通道推送机制】：
• 华为设备使用Push Kit API批量推送
• 非华为设备触发云数据库定时任务 | 每1000条记录的推送完成时间≤45秒 |
| FR-2.4 | 支持基于时间周期创建循环打卡任务（如每周一8:00推送），【华为设备采用系统级推送，非华为设备采用应用内本地通知】 | 任务调度误差不超过±1分钟 |
---
## 非功能性需求（Non-Functional Requirements）
| 类型 | 需求描述 | 测试方法 |
| ------ | ------------------------------------------------------------ | -------------------------------- |
| 性能 | Excel解析时间≤10秒（1000行数据以内） | 使用性能分析工具监控解析耗时 |
| 可靠性 | 【双通道推送】整体到达率≥98%（网络正常时） | 分设备类型统计1000次推送到达情况 |
| 安全性 | 【华为通道】采用HTTPS加密，【数据库通道】采用Token签名验证 | 通过安全审计工具验证双通道机制 |
| 兼容性 | 支持：
• HMS Core 5.0+
• 华为云数据库最新API
• 【Android 8.0+系统】 | 使用不同品牌设备进行交叉验证 |
---
## 新增系统架构说明
### 设备识别逻辑
```mermaid
graph TD
A[设备启动] --> B{华为设备？}
B -->|是| C[集成HMS Core SDK]
B -->|否| D[生成设备唯一ID]
C --> E[获取Push Token]
D --> F[注册到云数据库]
E & F --> G[服务端设备信息同步]
```
### 双通道推送流程
```mermaid
sequenceDiagram
管理员->>服务端: 上传排班表
服务端->>服务端: 解析设备类型
alt 华为设备
服务端->>HMS服务器: 批量推送请求
HMS服务器->>设备: 系统级推送
else 其他设备
服务端->>华为云数据库: 写入触发记录
华为云数据库->>设备: 数据变更通知
设备->>设备: 触发本地通知
end
```
---
## 历史版本
- v1.0-Release：完成系统主界面，实现获取、显示、复制HMS token的基础功能，有些手机可能无法正常收到推送
- v1.1-Beta：更换HMS Core为友盟推送API，优化了主页UI显示效果，增加手动添加闹钟页面，后续在此基础上进行开发
- v1.2-Alpha：添加统一设置闹钟功能，客户端可以自行向用户推送通知
- v1.3-Alpha：完善闹钟功能，可以调用系统闹钟进行统一添加
- v1.4-Beta：基本功能完成，实现通过JSON数据统一设置闹钟卡片功能，推送到主分支，后续在此基础上进行开发
- v1.5-Alpha：1、调整项目结构，采用MVP架构，将功能和界面从原MyActivity.kt文件中解耦；2、将加载JSON数据、本地保存时间、设置系统闹钟的函数使用coroutineScope协程处理；3、设置统一颜色风格，美化UI界面；4、对所有分支进行合并，客户端获取HMS token，服务端使用云数据库对客户端发送JSON数据，客户端解析后实现一键设置闹钟
- v2.0-Release：优化设置闹钟冲突的bug
- v2.1-Alpha：修改闹钟逻辑为每天都响
- v2.2-Alpha：优化了添加闹钟的逻辑
- v2.3-Beta：进行公测，修改了一些文本