1. 初始需求与产品范围#

最初目标是开发一个可以直接编译、安装和使用的个人上下班打卡工具，而不只是界面演示。首版范围包括：

• 每天分别记录一次上班、下班打卡，附带可选照片和备注。
• 显示当天状态，提供月历、历史筛选、搜索和记录详情。
• 设置上下班本地通知，选择提醒时间及生效星期。
• 修改、补录和删除记录前确认，导出 CSV，清除本机数据。
• 处理权限拒绝、保存失败、照片不可用及首次启动空状态。
• 使用简体中文、原生组件、系统颜色，适配深色模式、Dynamic Type 和 VoiceOver。
• 提供单元、持久化和 UI 测试，完成真机安装验证。

产品定位是个人记录工具。打卡时间来自设备系统时钟，用户可以补录和修改内容，因此不作为企业防篡改考勤认证或历史地点证明。

2. 工程搭建与架构选择#

工程采用 SwiftUI + ViewModel + Repository / Service 的分层结构，尽量把界面、业务规则、持久化和系统能力分开。通知、照片存储、数据仓库与定位提供可替换接口，便于测试成功和失败场景。

1
签到打卡/
2
├── WorkPunch.xcodeproj/           Xcode 工程与共享 Scheme
3
├── WorkPunch/
4
│   ├── App/                      App 入口、依赖组装、通知路由
5
│   ├── Core/
6
│   │   ├── Models/               打卡、位置、提醒、节假日模型
7
│   │   ├── Repositories/         仓库接口与 SwiftData 实现
8
│   │   ├── Services/             打卡事务、照片文件与 CSV
9
│   │   └── Utilities/            日期、月历、筛选等规则
10
│   ├── ViewModels/               今日、日历、记录、设置与编辑逻辑
11
│   ├── Views/                    四个标签页与编辑、详情、隐私页面
12
│   ├── Services/                 通知、节假日、定位与图片处理
13
│   ├── Components/               相机、记录行、图片查看与分享面板
14
│   └── Resources/                权限、隐私清单、图标、节假日资源
15
├── WorkPunchTests/               单元与 SwiftData 集成测试
16
├── WorkPunchUITests/             真机交互流程测试
17
├── Scripts/                      工程生成、检查、编译与测试脚本
18
├── TestResults/                  编译日志、测试摘要、截图和验证报告
19
├── Package.swift                 可在 Mac 上测试的共享业务代码
20
├── README.md                     工程入口说明
21
└── 开发记录与使用说明.md          本文

主要技术选择及作用如下：

Swift 6 并发检查用于约束线程访问。界面、相机和主 ModelContext 的操作在主 Actor 执行，图片解码压缩、导出等耗时工作放到后台任务。工程将编译警告视为错误。

3. 数据和核心业务实现#

PunchRecord 除了 UUID、类型、打卡时间、备注、照片路径、创建时间和更新时间，还保存以下信息：

• dayKey、timeZoneID：记录打卡时的当地日期和时区，避免切换时区后历史记录换到另一日期。
• uniquenessKey：日期与打卡类型组成唯一键，配合业务检查防止同一天同类型重复保存。
• isManual：标记经过确认的补录记录。
• 可选位置字段：纬度、经度、水平精度、采集时间和地址。

图片最长边压缩到 1800 像素，使用 JPEG 质量 0.78；缩略图单独降采样。处理时移除原图的 EXIF 和原始定位等元数据。用户主动附加的打卡位置作为独立记录字段保存。

保存新照片后如果数据库提交失败，会回滚记录并清理新文件。删除记录后同步清理无引用照片；清理异常会显示说明，并在后续加载时重试。提醒设置使用 Codable 编码后保存在 UserDefaults 中。

相关代码：数据模型、打卡业务、照片存储。

4. 首次编译和真机安装#

开发开始时，命令行环境未找到可用的完整 Xcode。随后确认 Xcode 已安装，并完成 Apple 许可确认与首次组件安装；编译命令显式选择完整 Xcode 的 Developer 目录。

真机通过数据线连接后，依次完成解锁、信任电脑、签名安装及开发者 App 信任。安装初期系统曾拒绝启动尚未信任的开发者应用，完成信任后继续验证。真机测试期间也遇到设备锁定导致无法启动的情况，解锁后恢复测试。

首版留存的真机测试摘要为 22 / 22 通过，无运行时警告。证据见 首版测试摘要。这只代表该阶段测试覆盖的范围；后续用户实际使用反馈又发现并推动修复了相机和通知问题。

5. 1.1：修复闪退并完善提醒和节假日#

用户反馈点击拍照闪退、点击通知进入应用闪退，同时希望提醒持续保留、每小时再提醒，并跟随中国节假日和调休。处理过程如下。

6. 1.2：附带当前位置与修复删除布局#

第二轮新增需求是打卡时附带当前位置，并修复删除操作位置过高、布局不正常的问题。

7. 实际验证结果与边界#

1.2 唯一失败的 UI 断言假定新文字一定追加在备注末尾，而自动化点击后的光标实际位于其他位置。将断言改为核对编辑框的实际输入与保存结果一致后，该用例单独复测通过。这里没有将两次结果写成一次完整的 52 / 52 全绿运行。

测试覆盖打卡保存、重复判断、日历状态、月份与闰年、历史筛选、CSV 转义、通知日程、节假日调休、照片删除、SwiftData 持久化和位置迁移。UI 覆盖无照片打卡、日历、筛选、修改提醒时间、位置保存与保留、关闭定位、删除弹窗、相机打开取消，以及通知后台点击与冷启动。

真机实际取得当前位置的流程已验证，但获取后取消，未保存真实位置或附加真实坐标截图。普通 UI 测试使用独立数据目录和虚构位置，不清除正常使用的记录。相机自动化只验证打开和取消，未拍摄用户环境；每小时间隔由固定时钟单元测试覆盖，没有声称完成长期每小时实际等待测试。

不同屏幕尺寸、横屏、深色模式、全部大字号和 VoiceOver 组合没有逐一完成真机验收。后台刷新执行时间、长期通知送达和专注模式／摘要的各种组合由系统影响，不作保证。

完整证据：当前验证报告、1.2 完整运行摘要、定向复测摘要、Mac 测试日志。

1. 首次打开与四个页面#

无需登录。底部四个标签的作用如下：

首次没有记录时会显示空状态，这是正常情况。完成第一条打卡后，各页面会同步显示。

默认上班时间为 08<50>，下班时间为 18<00>，普通工作日为周一至周五。上下班提醒初始都关闭；“每小时追提醒”和“同步中国节假日与调休”默认开启，但需要先开启相应的上下班提醒才会安排正式通知。

2. 完成一次上班或下班打卡#

1. 打开“今日”，点击“上班打卡”或“下班打卡”。
2. 确认页面会尝试获取当前位置；首次使用时按系统提示允许“使用 App 期间”定位。如果不需要位置，关闭“附带位置”。
3. 可点击“拍照”调用相机，也可点击“从相册选择”。照片选填，拍照时首次需要相机授权。
4. 在“备注”中填写说明，也可以留空。
5. 点击“确认打卡”。实时打卡以保存时的设备时间记录。
6. 成功后页面关闭，显示“打卡已保存”并给出触觉反馈；今日状态更新。

同一天每种类型最多一条。已经完成的项目会显示记录和“查看或修改记录”，不会再次新增相同类型的打卡。照片处理中、定位中或保存中需要等待；如果开启了附带位置却没有取得位置，可重试，也可主动关闭开关后继续保存。

3. 使用打卡位置#

位置记录包括地址（如果查询成功）、经纬度、定位精度和实际采集时间。允许近似位置时，会保存系统提供的近似结果；精度受权限、信号和设备状态影响。

• 保留原位置：编辑已有记录时默认保留，修改备注不会自动把位置替换为当前所在地。
• 重新采集：在编辑页点击“重新获取当前位置”，确认保存后替换原位置。
• 不带位置或移除位置：关闭“附带位置”。编辑已有记录时，确认保存会移除该记录的位置。
• 没有地址：只要取得有效坐标，即使地址查询失败，也可以保存坐标。
• 授权失败：按页面提示打开定位设置，或从“设置 → 权限 → 打开系统设置”调整权限，再返回重试。

应用不在后台持续定位。补录时取得的是此刻的位置，不代表所补录时刻的历史地点。

4. 在日历查看和补录#

点击“日历”，用左右箭头切换月份；右上角“今天”返回当天。点击某一天，下面显示该日记录和可用操作。

“休／班”表示已知的节假日安排，实际是否按它安排提醒取决于设置中的节假日开关；普通周末不会因此都标成“休”。

补录步骤：选择今天或过去日期 → 点击缺少的“补录上班打卡”或“补录下班打卡” → 调整时间，填写可选内容 → 保存 → 在二次确认框确认。未来日期不提供补录操作；补录记录会有补录标记，默认不附带当前位置。

点击照片缩略图可全屏查看，支持捏合缩放、双击缩放，点击“完成”关闭。若照片损坏或丢失，会显示“照片不可用”，可去详情替换。

5. 搜索、筛选、修改和删除#

进入“记录”，默认按日期倒序展示全部记录。可选择“月份”，通过“打卡类型”选择“全部、上班、下班、异常”，并在搜索栏输入备注关键字。这些条件可以组合使用。

“异常”指过去日期只完成一次打卡，或者记录本身带有补录标记。整天没有任何打卡时，不会自动生成缺勤记录，也不会出现在异常列表中；今天尚未下班而只有上班记录，不因这一点立即判为异常。

修改记录：

1. 点击记录进入“打卡详情”。
2. 点击“修改备注、照片或位置”。
3. 修改内容后点击“保存修改”，再确认保存。
4. 原始打卡时间不变，今日、日历、记录页面同步更新。

删除记录：进入详情 → 点击“删除记录” → 在居中的系统弹窗选择“取消”或“删除记录及照片”。确认后移除本条记录、位置及对应照片，无法在应用内撤销。

6. 开启和修改每日提醒#

1. 打开“设置”，分别开启“启用上班提醒”和／或“启用下班提醒”。
2. 首次启用时，允许系统通知权限。
3. 点击“上班提醒时间”或“下班提醒时间”，选择小时、分钟并点击“保存”。
4. 在“提醒生效的星期”勾选需要的日期；星期选择同时用于两类提醒。
5. 根据需要保留或关闭“同步中国节假日与调休”“每小时追提醒”。
6. 在“测试与提醒状态”查看“下一次提醒”“已安排至”和待发送数量。

修改时间后，应用取消旧日程并安排新日程，使用稳定标识避免重复通知。首次开启或修改时间时，如果当天时间已经过去，会从下一个有效日期开始，不补发启用前的通知。

通知文案分别是“上班时间快到了，别忘记打卡”和“准备下班了，记得完成下班打卡”。点击通知进入相应打卡页；已有对应记录时进入编辑流程，不会直接新增重复记录，也不会自动保存。

7. 立即测试通知#

不用等到上班时间，也不用更改手机时间：

1. 进入“设置 → 测试与提醒状态”。
2. 点击“发送上班测试通知（10 秒）”或“发送下班测试通知（10 秒）”。
3. 如有授权提示，允许通知，然后返回桌面等待。
4. 收到后点击通知，确认进入对应打卡页面。

测试通知不受所选星期和节假日限制，不会自动保存打卡，也不会替你开启正式的上下班提醒。系统专注模式、通知摘要或其他设置可能延迟它，约 10 秒是安排时间，不是必达承诺。

8. 每小时追提醒、停止本轮与彻底关闭#

开启“每小时追提醒”后，每类提醒从首次到点开始按小时继续，可能跨夜；休息日暂停。进入 App 或完成打卡都不会自动停止，需要明确操作。

明确停止本轮会清理对应已送达通知并取消当天后续追提醒。系统向应用回传单条通知清除操作时也会停止；“清除全部”不保证回传，因此推荐使用明确的停止按钮。

应用最多滚动预排 60 条正式通知，这是两类合计的队列，不是保证 60 天。返回应用或系统允许后台刷新时会续排；长期不开应用可能耗尽队列，请留意“已安排至”。

iOS 不允许第三方 App 强制通知常驻且不可清除。系统中的“持续横幅”也不等于永久锁定通知中心条目。专注模式、通知摘要、后台刷新、低电量及强制退出等都会影响提醒表现。

9. 中国节假日与调休#

在“设置 → 节假日”开启“同步中国节假日与调休”，可点击“立即同步节假日”，并查看同步状态和时间。

提醒生效顺序为：

1. 已公布的放假日：不提醒，即使落在选中的周一至周五。
2. 已公布的调休上班日：提醒，即使是原本未选中的周末。
3. 其他日期：按“提醒生效的星期”判断。

例如内置 2026 年安排中，10 月 1—7 日休息，10 月 10 日调休上班。因此在国庆期间正式提醒没有出现，可能是休息日规则正常生效；可用 10 秒测试通知检查通知能力。

如果未选择任何普通星期但开启了节假日跟随，已公布的调休上班日仍会提醒。关闭节假日跟随后，仅按所选星期判断。节假日只影响提醒安排，不限制休息日手动打卡。

离线时继续使用内置或缓存数据。某年数据尚未取得时，不会猜测放假安排，而是暂按所选星期提醒并显示说明。数据依据国务院通知整理，但单位实际排班可能不同，需要自行决定是否启用。

10. 导出 CSV#

进入“设置 → 数据 → 导出打卡记录（CSV）”，在系统分享面板选择“存储到‘文件’”或其他需要的目标。

导出文件名为 上下班打卡记录.csv，包含全部历史记录，不受“记录”页面当前筛选条件限制。字段为：日期、打卡类型、时间、备注、补录、时区、位置地址、纬度、经度、定位精度（米）、定位时间。没有位置的旧记录对应字段留空。

文件使用 UTF-8 BOM、标准 CSV 引号转义和 CRLF 行结束，支持中文、逗号、双引号和备注内换行。照片本体不在 CSV 中。分享结束后应用清理临时导出文件，已另存或发出的副本由使用者管理。

当前没有 CSV 导入或恢复功能，因此 CSV 是可阅读的记录导出，不能作为含照片的完整应用备份。

11. 清除所有数据#

进入“设置 → 数据 → 清除所有数据”，阅读提示并确认“清除全部记录和照片”。此操作删除应用内记录（包括位置）、照片及临时导出文件，关闭提醒并恢复默认提醒设置，不能撤销。

需要保留记录时先导出。外部已保存的 CSV 不会随应用清除而删除；系统是否备份应用文件取决于自己的 iPhone 备份设置。卸载应用也会移除本机应用数据。

12. 权限、网络与隐私#

照片、备注、打卡记录和位置保存在本机，开发者不会收集或上传这些资料，不包含广告和分析 SDK。应用不会主动进行 iCloud 同步。

两项系统／网络行为需要区分：节假日同步从公开托管源下载 JSON，不携带打卡数据，托管方仍可看到 IP 等基础请求信息；地址查询由系统 Apple 地图服务处理坐标。核心打卡和本机记录查看不需要后端，网络不可用时节假日依赖缓存，地址查询可能退回坐标显示。

13. 常见问题#

1. 在 Xcode 中运行#

1. 安装带 iOS 27 SDK 的完整 Xcode，首次打开完成许可和所需组件安装。
2. 打开 WorkPunch.xcodeproj，选择共享 Scheme WorkPunch。
3. 模拟器运行时选择已安装的 iOS 27 iPhone 模拟器；真机运行时连接手机、解锁并信任电脑，按系统要求开启开发者模式。
4. 真机需在 Xcode 的 Accounts 登录 Apple ID，并在 App Target 的 Signing & Capabilities 中选择可用 Team。给自己的新安装使用唯一 Bundle Identifier；更新当前安装并保留旧数据时，应保持原应用身份和可用签名。
5. 按 ⌘R 编译运行。若手机提示开发者未信任，按系统指引在“设置 → 通用 → VPN 与设备管理”完成信任。

个人开发签名的可用期限受 Apple 当前规则约束，到期后可能需要重新签名安装；不要为了更新而先卸载已有应用，以免删除本机记录。

2. 运行项目检查和测试#

在项目根目录的终端执行：

1
# 检查工程结构、资源和权限配置
2
python3 Scripts/validate_project.py
3

4
# Mac 上的共享核心与 SwiftData 测试
5
bash Scripts/test_core.sh
6

7
# 已安装 iOS 27 模拟器的构建与测试
8
bash Scripts/verify.sh
9

10
# 列出连接设备，取得需要测试的设备标识
11
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun devicectl list devices
12

13
# 将占位内容替换为上一步设备标识；测试期间保持手机解锁
14
bash Scripts/verify_device.sh <IPHONE_UDID>

也可在 Xcode 中按 ⌘U。脚本会选择完整 Xcode 并把结果写入 TestResults/。真机测试会操作测试 App；Debug 的 --uitesting 使用独立数据和设置，普通 UI 用例注入虚构位置，--live-location 用例才请求实际定位，Release 不包含测试定位实现。

3. 手动回归建议#

每次涉及系统能力或签名的更新后，建议在真机完成以下检查：

1. 无照片打卡、有照片打卡，重启应用确认记录仍在。
2. 相机授权、打开、取消和实际拍摄；相册选择并查看全屏照片。
3. 定位允许、拒绝、不带位置保存，以及修改备注后位置保持。
4. 10 秒测试通知，分别验证后台点击和应用终止后的通知启动。
5. 修改提醒时间、停止本轮、关闭某类提醒，并查看重新安排后的状态。
6. 节假日同步失败时保留缓存、调休工作日及普通星期规则。
7. 删除弹窗取消与确认、日历状态和历史列表同步。
8. 含中文、引号、逗号和换行备注的 CSV 导出。
9. 深色模式、大字号、VoiceOver 和目标屏幕尺寸下的可读性。

4. 维护入口和参考材料#

新增文件后可在 Xcode 中加入相应 Target，或运行 python3 Scripts/generate_project.py 重新生成工程。生成器保留现有签名 Team 和 Bundle Identifier，并固定相机、相册和定位权限说明。改动系统权限后应同时检查源码配置与最终安装包。

节假日参考来源：国务院 2026 年放假通知、NateScarlet/holiday-cn（MIT 许可）。