# 轻记 iPhone 版

原生 SwiftUI 项目，面向 iOS / iPadOS 17.0 及以上。无第三方运行依赖，无需账号和后端。此交付物为源码项目，尚未编译、签名或真机运行，不是可直接安装的 IPA。

## 已实现的源码功能

- 收入、支出新增、编辑、确认删除；分类、备注、日期。
- 按月统计收入、支出、结余，支持类型、分类和备注筛选。
- 每月独立预算，剩余金额、超支和进度。
- 支出分类环形图、近六个月收支柱状图。
- JSON 完整备份及确认后恢复；按当前月份导出 CSV。
- 读取安卓轻记 `qingji-1` JSON 备份，保留金额、日期、分类、备注、来源及通知去重标记。金额使用整数分保存。
- App Intents「记一笔」，可添加到 iPhone 的快捷指令，接收用户提供的金额、类型、分类和备注。运行要求身份验证。
- 本地文件原子写入。账本损坏时保留原文件并锁定写入，可先导出原文件再显式恢复备份。

应用初始账本为空，不预置示例消费。账目存储在本机 Application Support，账本目录不参加系统自动备份；请定期另存 JSON。删除应用会删除本地数据。

## 微信／支付宝的 iOS 限制

iOS 没有为普通应用提供类似安卓 NotificationListenerService 的跨应用通知读取接口。苹果的通知扩展处理的是自己应用的通知，无法拿到微信、支付宝的支付消息。参考 [Apple 通知扩展说明](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension)。

所以此项目没有“监听支付通知”的开关，也不会宣称可以从微信／支付宝后台自动读取完整消费。支持迁移安卓轻记已记录的账目，并用快捷指令减少手动记账步骤。快捷指令的金额来自用户输入或用户自己配置的数据，不能自行获知付款金额。

## 用 Xcode 打开

1. 在 Mac 安装 Xcode 15 或更新版本，首次打开并安装 iOS 平台及模拟器。
2. 打开 `QingJi.xcodeproj`，选择 **QingJi** scheme。
3. 选择一个 iPhone 模拟器，点击 Run。无需开发者签名即可测试模拟器版本。
4. 在 **Product → Test** 运行 XCTest。或在本目录运行 `./check.sh`。

此 Mac 交付时没有安装 Xcode，只有语法解析及项目文件格式检查结果，不能据此认定编译已通过。测试代码已准备，但未执行。

## 安装到自己的 iPhone

1. Xcode → Settings → Accounts，登录你自己的 Apple Account。
2. Target **QingJi** → Signing & Capabilities，选择你的 Team，保持 Automatically manage signing。
3. 如果默认 Bundle Identifier 已占用，修改 `cn.qingji.ledger.ios` 为你自己的唯一标识。
4. 连接并信任 iPhone，按系统提示启用开发者模式，选择该设备后 Run。

参照 [Apple 真机运行说明](https://developer.apple.com/documentation/xcode/running-your-app-on-simulated-or-physical-devices)。可安装 IPA、TestFlight 或 App Store 发布还需要相应的签名及分发配置，不能把源码 ZIP 直接安装到手机。

## 从安卓迁移

1. 安卓轻记 → 我的 → 备份全部数据（JSON）。
2. 将 JSON 放到 iPhone 的“文件”中。
3. iPhone 轻记 → 我的 → 恢复备份／从安卓迁入，选择 JSON。
4. 查看笔数并确认替换。迁移后核对月份、金额及预算。

当前不直接导入微信／支付宝原始 CSV、Excel 或加密 ZIP。CSV 导出用于表格查阅，恢复必须使用轻记 JSON。单次备份上限 10MB、50,000 笔账目；人民币金额上限 999999999.99 元，最多两位小数。

## 快捷指令

安装并运行应用后，在“快捷指令”新建流程，搜索 **轻记 → 记一笔**，输入金额或连接“询问输入”动作，也可提供分类和备注。系统会执行身份验证并尝试保存账目。应用未编译运行过，系统动作发现、Siri 中文触发和锁屏行为仍需在设备上验证。

## 检查与 CI

- `QingJiTests/LedgerTests.swift` 包含金额、CSV、安卓备份迁移、异常备份、通知元数据、持久化和损坏文件保护的 XCTest。
- `check.sh` 先构建模拟器版本，再选择可用 iPhone 模拟器运行测试。
- `.github/workflows/ios.yml` 可在把本目录作为仓库根目录时用于 GitHub Actions。没有自动上传源码或建立仓库。

发布前应在实际 iPhone 上完成页面操作、文件导入导出、快捷指令和不同字体尺寸的验收。