86 lines
10 KiB
Markdown
86 lines
10 KiB
Markdown
# 2026-10-02 更新验收与使用
|
||
|
||
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
|
||
|
||
## 本次范围
|
||
|
||
按主目录 `update.md` 的要求完成 13 项代码更新，包括执行期间追加的红色金额和收支日历；完成时间为 2026-10-02 17:37（Asia/Hong_Kong）。
|
||
|
||
- 资产账户转出余额不足时允许透支。原币、8 位小数和双方事务不变；16 位整数范围改为检查金额绝对值。还款/收款超过剩余债务仍拒绝。
|
||
- 欠款在债务列表、详情、选择器和历史中显示负数，内部仍保存正的剩余本金并通过 side 参与净资产计算；债务详情只显示对应方向的“还款”或“收款”。
|
||
- 欠债、负债、负余额和支出金额使用红色。金额显示采用 ¥、HK$、US$、€、£、JP¥ 等符号；选择币种时仍保留代码。
|
||
- 新增/编辑账户可输入自定义分组。账户页按分组筛选；转账和借贷的账户选择使用可搜索弹窗，支持全部账户与分组视图。
|
||
- 账户页“快速记账”开启后，点击未归档账户直接编辑当前余额。保存新增历史，退出该模式恢复账户详情导航。
|
||
- 净资产轨迹裁掉第一条可见余额之前的日期；已有记录的零余额日期保留，空空间返回空轨迹。
|
||
- 新增定时支出/转账，支持一次性或每 N 天重复、暂停、删除。打开账户页或点击“执行到期计划”按需处理，每批最多 20 项；较长欠执行期可分批补记。一次性计划完成后不能重新启用。
|
||
- 新增独立“收支日历”入口：上方月历展示每日收入/支出，下方展示所选日期明细，默认今天。支持历史月份、未来日期不可选。
|
||
- 调整余额、债务方向与记录时间的文案，新增文案有 English 和繁体翻译。
|
||
- 内置图库从 20 扩充至 31：汇丰香港、恒生、渣打香港、东亚、星展香港、花旗香港、中银香港，以及 Binance、Gate、Bybit、Bitget。图标来自公开品牌站点，记录来源与下载摘要；PNG 已入库文件，页面无需访问品牌网站。
|
||
|
||
## 计划与收支的统计口径
|
||
|
||
计划只记账，不调用银行或交易所，不执行真实资金划转。一次执行写入当前业务分钟，备注保留原到期时间；不向既有余额历史中插入过去的支出，避免覆盖当前余额。重复计划按原到期时间加固定天数推进，尚未补完时下一批继续；每月不是固定天数，请按需要选择间隔。
|
||
|
||
每项计划在 Serializable 事务内锁定计划行，然后按固定顺序锁定账户；余额记录、转账记录和计划推进同事务提交。确定的“计划 ID + 到期时间”执行标识及完成状态用于防重复执行。失败不推进计划，保留错误提示供重试。隐藏账户未解锁时不显示/执行有关计划；归档账户计划执行失败并保留。所有资源按会话用户隔离。
|
||
|
||
现有数据保存的是余额快照，日历因此采用“账户余额变动估算”口径，不能视为完整交易流水：资产账户增加为收入、减少为支出，负债账户相反。只统计 balance/correction/scheduled_expense；初始余额（包括被更正的第一条记录）、估值、账户内部转账和借贷本金配对变化不计入。手动更新欠款减少也会被估算为收入，页面已注明负债账户反向计算；精确的经营收入/消费统计需要后续显式收支记录模型。
|
||
|
||
按变动发生日的可用历史汇率换算，保留十进制精度后汇总至两位小数；缺少汇率则该日标记不完整，不把外币当本位币。月查询只重放该月历史并为每个账户读取月前最后余额；点击日期只读取该日记录，避免为每次点击重复传整月明细。
|
||
|
||
## 数据与备份
|
||
|
||
迁移 `20261002000400_groups_schedules` 增加 Position.groupName 与 Schedule，不更改既有迁移。备份 ZIP manifest 升为 v7，新增 schedules.json，账户分组与计划余额/进度一并导出。旧 v3/v4/v5/v6 ZIP 和 JSON 仍支持；恢复时重映射计划账户 ID，一次性已完成计划不会再次扣款。备份后清空同时删除当前用户计划，财务数据/计划变化会使旧清空确认凭据失效。
|
||
|
||
应用本工作树更新后，在配置好数据库的环境执行：
|
||
|
||
```powershell
|
||
pnpm install --frozen-lockfile
|
||
pnpm db:generate
|
||
pnpm db:migrate
|
||
pnpm build
|
||
pnpm --filter @worthpath/api icons:seed
|
||
pnpm test
|
||
pnpm test:integration
|
||
```
|
||
|
||
初始化图库仅按既有的固定内置图标 ID 追加/更新，不覆盖上传图标。
|
||
|
||
## 已验证与边界
|
||
|
||
- 前后端 `pnpm typecheck` 与生产 `pnpm build` 通过。
|
||
- `pnpm test` 28 项通过：透支/负转入余额、债务超额还款拒绝、请求去重、金额范围、债务符号/币种、轨迹裁剪、计划完成/重复/失败推进、日历口径/小数汇总/缺汇率、ZIP v7 分组计划往返及旧版兼容。
|
||
- 浏览器使用明确的模拟数据检查分组弹窗切换、转账选择和月历默认今天/日期切换/上下布局及红色支出，未操作真实用户财务数据。
|
||
- 新增 `test/update-integration.test.ts`，覆盖真实 MySQL 中计划并发执行一次、透支、补记、分组恢复、隐藏账户与日历隔离，纳入 `pnpm test:integration`。
|
||
- 首轮连接数据库发生 `PROTOCOL_CONNECTION_LOST` 时，数据库验收暂未执行；该阻塞已在下面的补充验收中解决。
|
||
|
||
## 数据库恢复后的补充验收（2026-10-02 17:54）
|
||
|
||
- 已确认 MySQL 连接恢复并通过 SELECT 1；增量应用 `20261002000400_groups_schedules` 成功，`pnpm db:status` 确认全部 12 个迁移完成，schema 最新。
|
||
- 已生成 Prisma 客户端并编译后端，运行图库初始化；数据库检查确认 31 个固定内置图标 ID 均有图片数据且为共享图标。
|
||
- 在独立端口 3101 启动当前工作树后端，`pnpm test:integration` 9 项全部通过。测试使用随机验收账号，测试结束按对应 ID/用户名清理自己的数据，未使用真实用户账号执行记账或清空。
|
||
- 新增专项进一步验证：定时支出/转账并发只记一次、透支后的精确余额、归档账户执行失败保留到期时间和余额、21 项到期计划按 20 + 1 分批处理、内部转账不计日历收支、ZIP 分组/计划状态恢复及隐藏账户隔离。
|
||
- 修复债务集成测试中仍断言 manifest v6 的旧预期，当前应为 v7。连续重跑触发临时服务的正常登录限流后，重启本次临时测试服务再执行，未修改限流规则。
|
||
- 本轮 `pnpm test` 28 项通过，`pnpm typecheck` 通过；后端编译通过，前端生产构建在此前实现验收已通过，本轮未修改前端代码。
|
||
- 上一轮遗留的数据库迁移、图标初始化及真实 MySQL 集成验收现已完成。浏览器布局验收仍沿用此前模拟数据结果，没有新增真实浏览器端到端验收。
|
||
|
||
## 页面精简、记录编辑与补充图库（2026-10-02 18:43）
|
||
|
||
- 定时计划移到独立菜单页面，支持添加、暂停、删除及执行到期计划。账户页继续按需执行到期计划，计划页面仅点击执行才运行。设置支持隐藏日历与定时计划入口。
|
||
- 页面展示文字不可选，输入框与备注保留选字及编辑能力。账户选择弹窗只显示一个切换按钮，文字表示下一种视图。账户/资产/债务卡片缩小间距与图标，总览突出净资产，筛选移入趋势区域，最近记录展示六条，变化归因默认折叠。
|
||
- 余额历史可更正和删除；资金往来可修改金额、到账金额、手续费、日期和备注，或整笔删除。账户与操作类型保持原绑定，若需更换请删除后重建。转账及借贷配对记录禁止单侧更正或删除，历史入口可跳转资金往来；删除前有确认。
|
||
- `replay.ts` 在 Serializable 事务中按固定顺序锁定相关项目并重放历史。手动余额/估值保留为绝对金额锚点；资金往来按本金与手续费更新双方，定时支出保留原增量。更正定时支出记录时，填写的新金额转为绝对余额锚点。后续真实余额快照不会随更早的转账修改被平移。
|
||
- 债务为负、金额溢出或首笔资金操作失去前置余额锚点时，整个修改回滚。隐藏项目须解锁，归档项目须恢复；跨用户操作返回不存在。日历、历史与总览读取保存后的统一记录，成功操作刷新当前页面，进入日历重新查询。
|
||
- 日历沿用账户余额差额估算口径，内部转账和借贷本金不作为收支；删除或更正余额历史会改变对应日期估算值。删除定时计划已生成的记录不会回退计划进度或再次执行。
|
||
- 新增 ZA BANK 众安银行、大象银行 EleBank、微众银行 WeBank，共 34 个内置图标。ZA 使用官网公开品牌资源，微众从官网页眉资源获取真实 logo，大象使用官方 App Store 当前应用图标。PNG 与来源清单随代码保存，固定 ID 初始化不覆盖上传图标。
|
||
- 注释迁移 `20261002000500_schedule_comments` 已应用，补齐 Schedule 表及字段注释，13 个迁移状态最新。新增 `node scripts/check-comments.cjs`（在 apps/api 执行）核验 9 张业务表、88 个字段均有注释，并更新 `docs/database-comments.json`。
|
||
|
||
### 验证与边界
|
||
|
||
类型检查、生产构建及 28 项单元测试通过。新增 `test/record-edit.test.ts` 真实数据库专项，覆盖双边余额编辑/删除、早期余额更正、定时支出增量与更正、日期调整、绝对余额锚点、八位小数与负手续费、债务原子回滚、跨用户/隐藏账户隔离、日历联动及起始锚点保护。
|
||
|
||
浏览器使用本轮专用虚构账号检查卡片、总览层级/对比度、全部/分组的单按钮切换、定时计划独立页面。虚构账号已精确清理；未验证真实手机硬件、外网隧道或正式部署。
|
||
|
||
沙箱内 Node 系统用户查询返回 ENOMEM；测试、迁移及临时服务在获准的宿主环境运行成功。连续完整验收触发临时服务内存登录限流（429），重启该临时服务后再次执行，不修改限流规则。用户原有 Vite 配置保留，本轮提交不包含该文件；按 update.md 仅做本地提交，不 push。
|
||
|
||
最终完整数据库回归：2026-10-02 18:44，10 项全部通过。临时服务与预览资源已清理；仅保留本轮新增代码、文档和图库。
|