junny_location_punch 1.5.2 copy "junny_location_punch: ^1.5.2" to clipboard
junny_location_punch: ^1.5.2 copied to clipboard

Published 5 days ago
SDKFlutter
PlatformAndroidiOS
→

Metadata

A Flutter package for location-based attendance tracking and punch-in management system.

More...

1.5.2 #

🛠 修复 #

  • fix[location_service]: 修复定位服务关闭时未阻止流程导致高德 SDK 持续报错的问题
    • 将 onHandleLocationServiceDisabled 回调默认值从 true 改为 false
    • 回调未配置时，检测到 GPS 关闭会直接阻止后续流程，避免 errorCode 12 刷屏

⚠️ 兼容性提示 #

  • feat[location_service]: 新增定位服务状态检查能力
    • LocationService 新增 checkLocationServiceStatus() 和 isLocationServiceEnabled() 方法
    • JunnyLocationMixin 新增 checkAndHandleLocationService() 方法
    • requestPermission 流程中新增定位服务检查步骤（步骤1）
  • feat[configs]: 新增定位服务不可用处理回调
    • JunnyPunchBasicConfig 新增 onHandleLocationServiceDisabled 回调
    • 宿主应用可通过该回调弹窗提示用户并跳转到系统定位设置
    • JunnyPunchLocalizationConfig 新增 locationServiceDisabledTips 和 goToSettings 翻译字段

📝 使用说明 #

当检测到设备定位服务（GPS 开关）未开启时，库会调用 onHandleLocationServiceDisabled 回调。宿主应用应配置该回调以引导用户开启定位服务。

Android 示例（使用 android_intent_plus 跳转系统定位设置）：

onHandleLocationServiceDisabled: (BuildContext context) async {
  final bool? confirmed = await JunnyDialogUtils.instance.showCommonDialog<bool>(
    title: JunnyPunchConfig.localization.locationServiceDisabledTips(),
    content: '请在系统设置中开启定位服务后重试',
    confirmText: JunnyPunchConfig.localization.goToSettings(),
    onConfirm: () async {
      final intent = AndroidIntent(
        action: 'android.settings.LOCATION_SOURCE_SETTINGS',
      );
      await intent.launch();
    },
  );
  return confirmed ?? false;
}

iOS 示例（只能显示引导文案，无法直接跳转系统定位设置）：

onHandleLocationServiceDisabled: (BuildContext context) async {
  await JunnyDialogUtils.instance.showCommonDialog<bool>(
    title: JunnyPunchConfig.localization.locationServiceDisabledTips(),
    content: '请前往「设置 → 隐私与安全性 → 定位服务」开启定位服务',
    confirmText: '知道了',
  );
  return false;
}

1.5.1 #

🛠 修复 #

  • fix[mixins/location]: 过滤定位成功回调，避免误显示错误提示弹窗
    • 在 JunnyLocationMixin 中添加 _isRealLocationError 方法，统一过滤 errorCode = 0 或 '0' 的定位成功回调
    • 双保险处理同时判断数字 0 和字符串 '0'，防止类型转换问题导致的误判
    • 所有使用该 mixin 的页面自动受益，无需单独处理

1.5.0 #

🛠 修复与加固 #

  • fix[clock_in_manager]: 静默打卡地址为空不再提交，返回 addressUnavailable 并引导手动打卡，避免产生“空地址”记录
  • fix[clock_in_manager]: 定位结果携带 SDK error 时中断流程并返回 locationUnavailable，避免误用异常坐标继续判断
  • fix[location_mixin]: 新增 onLocationError 钩子并兼容 location 对象携带 error 的场景，便于页面侧提示与兜底
  • fix[punch_card]: 手动打卡页定位异常弹窗仅展示 errorCode/errorInfo（无硬编码文案与 title），并对重复错误码做节流

⚠️ 兼容性提示 #

  • feat[check_result]: ClockInCheckResult 新增 addressUnavailable，若调用方对该枚举做穷举 switch 需补分支
  • feat[localization]: 新增 silentAddressUnavailableTips（可选，未配置时回退到 silentLocationUnavailableTips）

1.4.0 #

✨ 新增 #

  • feat[services]: 新增静默打卡服务层（ClockInManager/ClockInService/LocationService/ClockInCheckResult），支持静默检测、自动打卡、时间窗口校验与成功回调
  • feat[configs]: 添加 AutoClockTimeWindow、SilentClockResult 及静默回调 onSilentClockSuccess，默认通过库入口导出 services
  • feat[localization]: 补充静默打卡相关国际化文案及 selectMonth 可选标题
  • feat[record/page]: 日历头部支持月份选择器，非当月显示“返回今天”按钮

🧹 优化 #

  • refactor[location_mixin]: 复用 LocationService 单例，统一权限请求、初始化与连续定位

🧾 文档 #

  • docs[README]: 增补静默打卡用法、时间窗口配置与国际化字段示例

1.3.4 #

🛠 修复 #

  • fix[utils/getPunchStatus]: 上下班边界统一为“早于上班/下班时间才迟到/早退，等于及以上视为正常；超过下班时间未打卡判缺卡”，修复 18:30 等于配置时间被误判早退的问题

1.3.3 #

🛠 修复与加固 #

  • fix[punch_card/dialog]: 禁用遮罩点击与系统/手势返回关闭，外勤打卡弹窗增加“双保险”
    • 弹出配置：clickMaskDismiss: false、backType: SmartBackType.block
    • 组件加固：外层使用 PopScope(canPop: false)，同时消除 WillPopScope 废弃告警并兼容 Android 预测性返回

🧹 代码风格 #

  • style[record/page]: 调整 _formatWorkDuration 调用参数换行，提升可读性

1.3.2 #

🛠 修复 #

  • fix[punch_card/page]: 修复“早退更新”在已到下班时间仍提示早退的问题；record 场景改用 updateClocking(true) 统一时间判定与确认逻辑。
  • fix[record]: 切换日期时“迟到/早退”标签闪动；新增加载标志，调整为先切换日期再并发拉取数据，并在加载中隐藏异常标签以避免闪动。

✨ 优化 #

  • refactor[record]: 工时本地化与展示优化。
    • 仅使用“时/分”拼装，避免时区换算导致的偏移；
    • CJK（中文/日文/韩文）与非 CJK 语种分隔规则；
    • 小时为 0 不展示“小时”段，分钟为 0 不展示“分钟”段；两者皆为 0 展示“0分钟/0 min”；
    • 动态获取本地化对象与稳健的语种解析，语言切换实时生效。

🔒 兼容性 #

  • 为非破坏式更新，接口与对外 API 不变；仅前端展示与交互优化。

1.3.1 #

🛠 修复与优化 #

  • fix[record]: 修正非选中日期的工作日判定为“非周末即工作日”，修复日历 marker 颜色异常
  • fix[utils]: 为 getPunchStatus 提供默认工作日函数兜底，避免误用；增强 availableSettings 获取逻辑
  • fix[punch_card]: 外勤弹窗改用页面级 navigatorContext 进行导航；availableSettings 读取与 utils 保持一致

✨ 功能与体验 #

  • feat[record]: 在记录列表为异常打卡（迟到/早退）新增标签，文案走国际化、颜色随状态

📦 依赖 #

  • chore(pubspec): 放宽 fl_amap、maps_toolkit 版本约束为 any

1.3.0 #

✨ 主要变更 #

  • feat(cross-day): 新增跨天逻辑管理器 CrossDayLogicManager

    • 将所有与跨天打卡相关的计算（如跨天时间点、查询日期、API标志位等）统一封装到 CrossDayLogicManager 类中。
    • 解决了之前散落在不同文件中的跨天判断逻辑不一致的问题，提高了代码的可维护性和可靠性。

  • refactor(punch): 重构打卡页面逻辑 punch_card/logic.dart

    • 全面采用 CrossDayLogicManager 来处理跨天业务，简化了 getCrossDayRecords 和 submit 方法的实现。
    • 引入了定时器监听 _timerListener，用于在跨天临界点自动刷新工作日状态，优化了 API 调用。
    • 将外勤打卡弹窗的 UI 和逻辑抽离到独立的 OutsideClockingDialog 组件，使主逻辑文件更聚焦于核心业务流程。

  • feat(ui): 增加外勤打卡独立对话框 OutsideClockingDialog

    • 创建了 outside_clocking_dialog.dart 文件，提供了一个独立的、可复用的外勤打卡组件。
    • 优化了外勤打卡的用户交互，包括照片上传和备注填写。

  • refactor(record): 优化记录页面逻辑 record/logic.dart

    • 增加了 _updateCrossDayTime 和 _mergeOrCreateRecord 辅助方法，用于更健壮地处理和合并月度打卡记录，特别是跨天的数据。
    • 提升了日历页面展示数据的准确性。

  • feat(config): 增强了模块的可配置性

    • 在 basic_config.dart 中增加了 isCrossDayEnabled 开关，使跨天功能可配置。
    • 在 repository_config.dart 中新增了 isTodayWorkday 和 rangedDatesRecords 接口，以支持新功能。
    • 在 basic_config.dart 中新增 punchRequestParamsBuilder 和 attachmentParamProcessor，允许调用方自定义提交的参数，增强了灵活性。

  • fix(utils): 提升工具方法的健壮性 utils.dart

    • 新增 safeParseTime 和 safeParseDate，用于安全地解析多种格式的日期和时间字符串。
    • 重构了 getAttendanceTeamInfo 和 getRealClockingRecordTime 方法，使其能更好地处理各种边界和异常情况。

  • fix(location): 增强了定位处理的稳定性 location_mixin.dart

    • 在请求定位权限前，增加了对高德 Key 的校验。
    • 优化了定位服务的启动流程和单次定位的获取逻辑。

📈 影响 #

  • 提升了代码质量：通过逻辑封装和重构，代码结构更清晰，更易于维护。
  • 增强了功能稳定性：对跨天、定位、数据解析等多个环节增加了保护和校验，减少了潜在的 bug。
  • 优化了用户体验：打卡流程中的状态判断更精确，UI 交互更友好，并对早退等情况增加了二次确认。

1.2.6 #

✨ 新增功能 #

  • 新增 CrossDayLogicManager 跨天逻辑管理类，统一管理所有跨天相关计算
  • 新增 OutsideClockingDialog 外勤打卡对话框组件，提高代码复用性
  • 新增打卡页面业务流程图和数据流程图文档

🐛 问题修复 #

  • 重要修复：解决凌晨时段（00:00-06:00）打卡功能异常问题 • 修复跨天逻辑不一致导致的API调用参数错误 • 修复时间监听器在凌晨时段频繁触发不必要API调用的问题 • 修复跨天标志计算与记录查询逻辑不匹配的问题

🔧 代码重构 #

  • 打卡页面重构：提取跨天逻辑到独立管理类，重构外勤打卡弹窗组件
  • 记录页面重构：优化方法命名，提取时间处理逻辑，重构日历UI构建逻辑
  • 文档完善：添加详细的业务流程文档注释和 Mermaid 流程图

🔒 兼容性保证 #

  • 严格保持所有现有业务功能不变，确保API调用参数和时机完全一致

1.2.5 #

  • ✨ 优化定位检查逻辑，确保地址信息完整才能打卡
  • 🆕 新增定位错误提示文本配置
  • 📝 更新组件注释，提高代码可读性
  • 📦 升级依赖：fl_amap 从 3.4.2 升级到 3.4.3

1.2.4 #

  • 修复外勤打卡时无法拍照的问题

1.2.3 #

  • 依赖版本升级

1.2.2 #

  • 优化打卡逻辑，在未获取到经纬度时，打卡按钮禁用
  • 依赖版本升级

1.2.1 #

  • 优化头像部分显示，固定为 80dp 宽高

1.2.0 #

  • 优化打卡逻辑，非工作日上下班打卡时间不判断迟到和早退

1.1.0 #

  • 去除dev-kit的依赖，替换为widgets和utils两个依赖
  • 添加新的可配置选项

1.0.4 #

  • 修复iOS定位没有地理位置信息的问题

1.0.3 #

  • 修复打卡记录未获取完整问题

1.0.2 #

  • 替换坐标系转换功能为高德地图API

1.0.1 #

  • 添加坐标系转换功能

1.0.0 #

  • Initial version.

← Metadata

0
likes
130
points
274
downloads

Publisher

unverified uploader

Weekly Downloads

Metadata

A Flutter package for location-based attendance tracking and punch-in management system.

Repository (GitHub)

Documentation

API reference

License

MIT (license)

Dependencies

dio, fl_amap, flutter, junny_utils, junny_widget, maps_toolkit, timeline_tile

More

Packages that depend on junny_location_punch

Back