# iPhone截图记账与补传：v2.1手工配置

后台已于2026-10-29部署到 https://book.caomiao.top 。服务端真实微信身份验证、设备上传、防重、回执与作废均已验证；用户已在iPhone小程序扫码预览中确认金额和明细按“0元 → 0.01元测试支出 → 作废后0元”同步变化。自动快捷指令配置、签名／导入模板以及截图OCR、断网暂存、锁屏补传等iPhone快捷指令真机验证仍按此前决定延期；本文提供手动搭建步骤，不能把服务端或小程序验收当作快捷指令已在手机安装并验证。

流程：背面双击 → 本机截图／OCR → 确认金额 → 当场选分类、填备注 → 本机保存每笔JSON → 立即提交 → 按匹配回执分流。

## 1. 微信登录与本人设备配置

在「果冻的技术小屋」小程序用自己的微信登录家庭账本。首次管理员使用服务端一次性激活信息绑定，家人输入管理员生成的一次性邀请码；已绑定成员直接微信登录。

进入「我的 → 我的设备与上传授权」：

- 新手机／新逻辑设备：填设备名，点「新增设备并生成上传凭证」。
- 之前已有设备，仅凭证遗失、轮换或恢复快照：选择原设备「恢复原设备 / 轮换凭证」，保留原逻辑device_id。
- 复制一次显示的dev_设备上传凭证及设备配置；离开页面后无法还原原明文，遗失时重新轮换。
- 已停用设备须先由管理员核实启用，再由原成员恢复凭证，普通成员不能绕过停用。

新建「家庭截图记账」，用「文本」和「设定变量」手工设置：

| 变量 | 来源 |
|---|---|
| 账本地址 | 设备配置baseURL，目标 https://book.caomiao.top，不带末尾斜杠 |
| 成员编号 | member_id，逐字复制 |
| 设备编号 | device_id，原始UUID，逐字复制 |
| 恢复标识 | epoch，逐字复制 |
| 上传凭证 | 单独显示的dev_…，与设备配置分开保存 |

小程序复制的设备配置为baseURL、member_id、device_id、epoch，不含上传凭证，凭证需另外保存。不要用成员会话ses_…、旧原型共用成员Token、微信密码或AppSecret代替。

设备凭证只允许本人本设备提交支出和查询本设备回执，不能查全家流水、修改／作废历史记录、退款或管理成员。凭证只放Authorization请求头，不写入账目JSON或URL。分享模板前清空凭证。

## 2. 本机目录与归属隔离

优先在「文件 → 我的iPhone」中选择快捷指令可持续访问的文件夹，为每个成员和设备分别建立：

~~~text
家庭账本/<成员编号>/<设备编号>/
  待提交/
  云端待核对/
  需人工处理/
  已提交/
  终态留存/
~~~

每笔独立、不可变JSON；配置和凭证独立保存。首次在存储、读目录、移动文件动作中手工选定位置并完成授权；必须验证能写入、读回、转为词典。保存失败就停止提交并提示「未保存」。

iCloud Drive可选，但会同步收支，按需下载和同步状态会影响离线／锁屏访问；不能未经验证就作为可靠本机队列。优先已授权本机目录，保留手动补传入口。锁屏、重启后未解锁、文件保护和首次权限均属于延期真机验证范围。

换成员时隔离旧队列，不把妈妈文件改成爸爸身份上传；新增设备也不能自动接管原device_id队列。

## 3. 截图、本机OCR与金额确认

首个业务操作加入「拍摄截屏」，结果设为「本次截图」。直接使用该动作结果，不从照片取最新图片，以免误取旧图。加入系统图像文字提取动作（名称可能为「从图像中提取文本」），输入选本次截图，结果设为识别文字。

不加入图片上传或云端OCR，只上传确认后的结构化字段。系统截图及图像动作如何处理原图需真机核对，本文不承诺截图必定不进相册。

「匹配文本」可用以下付款标签候选规则：

~~~regex
(?:实付金额|实际付款|实付款|实付|付款金额|支付金额)[：:\s]*[¥￥]?[ \t]*([0-9]{1,7}(?:\.[0-9]{1,2})?)(?![0-9.])
~~~

有候选时用「从列表中选取」展示完整标签与金额，如「实付 ￥38.50」，关闭多选。本人选中后才从该候选取数字；不能取全文第一个数字。无可靠候选时手工输入。只有支付成功与孤立金额、OCR分行等页面可能没有匹配，首版允许手输，不能宣称该规则覆盖全部微信／支付宝／银行页面。

较完整的优先级可参考[capture/amount-rules.json](capture/amount-rules.json)，依次考虑实付标签、支付成功附近、货币符号候选。文件pattern为JSON转义形式，手工填入“匹配文本”前需还原转义，不能直接复制JSON里的双反斜杠。候选始终人工确认。该规则的本机参考程序会做NFKC全角归一化；iOS原生动作的等效处理和真实截图准确率尚未验证，合成文本测试不能当作真实OCR效果。

「请求输入」提示「确认金额，单位元，可修改，只填数字和英文小数点」，类型选文本；候选金额作默认值，无候选留空。结果为金额。先按以下格式匹配，再检查数值大于0：

~~~regex
^(?:0|[1-9][0-9]{0,6})(?:\.[0-9]{1,2})?$
~~~

允许38、38.5、38.50；不接受货币符号、千位逗号、地区小数逗号、负数或三位小数。仍以文本传输金额，不使用可能添加地区分隔符的数字格式化。取消确认则不入账。

## 4. 当场分类与备注

列表八项：餐饮、买菜、交通、购物、住房、医疗、娱乐、其他。用「从列表中选取」关闭多选，保存分类。再用「请求输入」填写可空、单行、最多200字符备注。不要把整段OCR文字当备注上传。

截图首版只记录本人支出；不传paid_by、refund_of或退款type。代记和退款由小程序成员会话处理。

## 5. 离线时间与请求编号

这里不访问/api/meta。设备配置完成后断网也能生成完整文件。

1. 「当前日期」只取一次，保存本次时间。
2. 同一个时间用自定义格式yyyy-MM-dd'T'HH:mm:ssXXX生成captured_at，如2026-10-28T16:30:45+08:00。也可使用系统ISO8601格式，但要先确认带Z或±HH:mm，不传无时区时间。
3. 同一个时间用yyyy-MM-dd作默认业务日期；显示该日期并提供修改入口，最终结果存date。date决定月份，按北京时间理解。
4. 手机时区为北京／上海时默认日期可直接采用；旅行时须手工确认北京时间日期，不能把语言／区域中文当作时区转换，也不假设每版日期动作都有时区参数。captured_at仍保留真实采集瞬间和偏移。
5. 从device_id用「替换文本」去掉减号得到32位编号前缀；JSON的device_id保持原始UUID，不去减号。
6. 同一本次时间用yyyyMMddHHmmss得时间编号，小写yyyy是日历年，不用大写周历年YYYY。
7. 两次「随机数」，范围各为10000000～99999999，不加千位分隔符。
8. 拼接capture-[编号前缀]-[时间编号]-[随机数一]-[随机数二]为request_id。

每笔新账生成一次，重试不改。编号只防重，不授权、不等于平台订单号，再次截同一付款页仍可能是新编号。

## 6. 先存完整JSON并读回

建立词典，schema_version必须是数字1，其余字段值为文本；不要放凭证或截图。

| 字段 | 内容 |
|---|---|
| schema_version | 数字1，不是文本或布尔值 |
| request_id | 本次固定请求编号 |
| member_id | 配置中的成员UUID |
| device_id | 配置中的原始逻辑设备UUID |
| epoch | 录入当时配置中的恢复标识 |
| amount | 确认后的金额文本 |
| category | 已选分类 |
| date | 确认后的业务日期 |
| note | 本人填写备注 |
| captured_at | 带时区的采集时间 |

可选字段：platform、transaction_no、merchant。仅可靠识别交易号时填写transaction_no，同时必填platform。字段是transaction_no，不是tradeNo。

转JSON文本，以request_id命名保存本成员本设备待提交文件夹。读回同一文件转词典核对后，以文件内容提交。某些提供方可能调整扩展名，补传按内容读取，不仅筛.json后缀。ID与epoch以下仅展示格式，真实配置须替换：

~~~json
{
  "schema_version": 1,
  "request_id": "capture-22222222222242228222222222222222-20261028163045-12345678-87654321",
  "member_id": "11111111-1111-4111-8111-111111111111",
  "device_id": "22222222-2222-4222-8222-222222222222",
  "epoch": "33333333-3333-4333-8333-333333333333",
  "amount": "38.50",
  "category": "餐饮",
  "date": "2026-10-28",
  "note": "午饭",
  "captured_at": "2026-10-28T16:30:45+08:00"
}
~~~

## 7. 上传与严格回执校验

「获取URL内容」：POST [账本地址]/api/captures，Authorization为「Bearer 」拼接dev_上传凭证，Bearer后有半角空格。JSON体逐项取已存文件，schema_version仍是数字，金额仍为文本；Content-Type为application/json。

旧/api/transactions和transaction.id成功判断不适用于设备截图上传。新回执：

~~~json
{
  "request_id": "capture-22222222222242228222222222222222-20261028163045-12345678-87654321",
  "status": "committed",
  "transaction_id": "44444444-4444-4444-8444-444444444444",
  "reason": "",
  "duplicate": false
}
~~~

先要求request_id与当前文件完全一致，再分流：

| 结果 | 处理 |
|---|---|
| committed且transaction_id非空 | 才提示已记账，只归档这一笔原文件 |
| pending_review | 已收到未入账，不计月报；保存回执关联，原文件移到云端待核对，提示在小程序处理 |
| rejected | 明确不入账终态；原文件和回执终态留存，不自动重传或换号 |
| voided | 原账已作废，留存终态，不恢复旧值或另建账 |
| 错配编号、未知状态、缺必要字段 | 结果不明，原文件保留，不显示成功 |
| 断网、超时、5xx、解析失败 | 保留待提交，原号原载荷补传 |
| 401／403 | 保留文件，暂停本轮，恢复本人原设备授权 |
| 400坏参数／坏文件 | 转本机需人工处理；修改前核对原回执，不让坏文件反复堵队列 |
| 409内容／归属冲突 | 本机保留并核对，不改号、改成员或改epoch绕过 |

回执单独留存，不向已发JSON添加状态或更改原载荷。HTTP200、duplicate:true、任意id都不能单独代表成功。云端确认后本机归档失败时保留并报告，下一次原样查询／提交返回同一状态，不覆盖小程序改动。

rejected和voided即使没有正式transaction_id，也可以归档为处理终态；通知应为“不入账／已作废”，不能显示“已记账”。pending_review只能进入云端待核对，不能当成已提交流水。

系统网络动作可能直接中断整个快捷指令；请求前落盘是恢复保障，不能承诺所有失败后续动作都运行。

## 8. 补传与回执查询

新建无交互「家庭账本补传」，使用同一设备配置和凭证。每轮限少量文件，如20笔，不截图、不OCR、不询问业务字段，不取新日期或编号。

逐笔读取本成员本设备待提交JSON，校验版本、必要字段和归属。损坏／归属不符转需人工处理，保留原文件；不补默认值。原完整载荷POST /api/captures，逐笔按回执分流，只归档当前文件，不最后统一清空目录。

结果不明时可先GET /api/captures/receipt?request_id=[原编号]，请求头仍是本人设备凭证。仅本人本设备可查；404只是当前没有对应回执，不等于能换身份／编号／epoch重建，仍原号原载荷提交，由服务决定入账或待核对。

云端待核对目录只查询回执：pending_review继续保留，committed才转已提交，rejected／voided留存终态。查询失败不假报处理完成。

401／403暂停本轮；断网允许结束本轮，剩余文件保留。400坏文件隔离，不堵其他能处理的记录。实际网络错误是否终止整轮，仍需延期真机验证。

## 9. 恢复原设备与旧epoch

- 同一成员仅凭证遗失／轮换：小程序恢复原逻辑device_id，使用新dev_继续原队列；原文件字段全部不改。
- 停用设备：管理员核实启用后，原成员仍需恢复设备轮换凭证；启用本身不会复活旧凭证。
- 恢复旧数据库快照：先维护、重认成员与设备。新配置带新epoch，供新记录使用；旧文件保留旧epoch。旧epoch中没有明确历史回执的记录进入待核对，不能改成新epoch绕过。
- 换成员：旧队列继续隔离，不把旧member_id改成新成员；由原成员恢复原设备处理。

## 10. iOS27系统配置与延期边界

背面双击：设置 → 辅助功能 → 触控 → 轻点背面 → 轻点两下，选择整个「家庭截图记账」，不是只选系统截屏。[Apple说明](https://support.apple.com/zh-cn/111772)

目标手机iPhone13 Pro Max、iPhone16 Pro Max，用户提供iOS27。先手动测试，再验证背面触发抓到目标付款页。

iOS27官方自动化入口：打开已有「家庭账本补传」→ 编辑 → 自动化，添加特定时间触发；编辑 → 信息 → 隐私检查允许锁屏时运行，个别动作可能还要单独允许自动运行。不要直接套用旧版自动化标签页／运行前询问路径。[官方iOS27说明](https://support.apple.com/guide/shortcuts/add-automations-apdfbdbd7123/10.0/ios/27)

每台手机分别配置，如每天22:00。服务器无法主动读取手机目录；小程序也看不到未上传文件。锁屏、重启未解锁、首次授权、蜂窝／Wi-Fi切换、真实OCR及文件操作已延期，不承诺后台准点必成。保留手动补传与本机待提交／需处理数量检查入口。

首版以接口、状态模拟和小程序编译验证为主；模拟不等于真机通过。一键配置、免手填、模板签名／导入和两台手机实测均不能标为通过，不部署或正式发布。协议见[CAPTURE-PROTOCOL.md](CAPTURE-PROTOCOL.md)、[API-V2.md](API-V2.md)。