fmq/DriftLedger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2e73b5a2c6
DriftLedger/docs/ui-redesign-design.md
fengmengqi 2e73b5a2c6 feat: UI 全面重设计（Bento 明亮风）+ 记一笔 NumpadSheet + 管理页模板 + OCR v5→v6 升级 
UI 重设计（P1-P5）：
- 主题从靛蓝 accent 切换为近黑白单色（#111318），品牌感靠排版与财务语义色
- 暗色模式适配 OLED 纯黑，财务色整体提亮一档保证对比度
- 圆角体系新增 xl(24)，卡片/弹窗统一大圆角
- 移除 Caveat/Quicksand 自定义字体，切换为系统字体
- 新增 display(34/800) 字阶用于净资产等大数字展示
- 分类/标签/渠道颜色统一到 palette.ts 色板（12 色循环 + FNV 哈希）
记一笔 NumpadSheet（P3 录入闭环）：
- 全新计算器风格录入面板：方向 chip → 大金额 → 账户 chip → 分类快捷行 → 数字键盘
- 支持表达式输入（20+15-5.5）与字符串十进制求值，避免浮点精度问题
- 高级模式保留多行分录编辑器，简单模式自动推断双腿
- postingLegs.ts 实现 buildPostings 的逆操作（编辑/草稿预填）
- 未保存守卫：整页 beforeRemove + modal 脏状态上报
- 全局弹层（NumpadSheetHost）由＋按钮唤起，可通过设置开关
Tab 栏重构：
- AppTabBar 替换默认 tab bar，中央＋按钮唤起全局记账面板
- Tab 从 5 个精简为 4 个（首页/交易/报表/设置），＋按钮独立
管理页模板 ManagementScreen：
- 统一「列表 + 新增 + 点按编辑 + 长按删除 + FormModal」模式
- 预算/分类/标签/信用卡等管理页消除手写样板
其他：
- OCR 模型从 PP-OCRv5 升级到 v6（det/rec/dict 全部替换）
- GBK 解码器 import 修复（text-encoding-gbk ESM 兼容）
- 批量确认失败数计算修正（用 failedPayees.length 替代 store 快照差值）
- 新增 diagnostics 诊断页、TodoStrip 首页待办条、SwipeableTransactionCard 左滑操作
- periodNav.ts 报表周期导航（anchor+period 统一状态管理，本地时区运算）
- 测试覆盖 numpadExpression/postingLegs/periodNav/palette/search/transactionGroups/categoryIcons/dateGrid
2026-07-22 13:33:29 +08:00

11 KiB
Raw Blame History

Beancount Mobile 前端 UI 全面重设计 Spec

  • 日期：2026-07-21
  • 状态：已确认（经逐节评审）
  • 范围：src/app、src/components、src/theme、design-system/；不动 src/domain、src/storage、src/services、plugins/

1. 背景与问题

对现有 UI 的摸底发现以下问题（按严重度）：

  1. 品牌色混乱：代码主题 accent = 靛蓝 #4F46E5，design-system/beancount-mobile/MASTER.md 规定 CTA = 绿 #059669、背景深蓝 #0F172A（代码暗色实为 OLED 纯黑 #040508）。设计文档与实现脱节。
  2. 图标体系三套并存：Ionicons（主力）+ emoji 分类图标（CategoryPicker）+ MASTER.md 要求的 Lucide/Heroicons（未落地）。
  3. 硬编码颜色绕过 token：首页 Hero 卡片写死白字；CATEGORY_COLORS、标签默认色 #2196F3、渠道色 #1677FF/#07C160/#E53935。
  4. 样式重复爆炸：40+ 处 StyleSheet.create；header 样式在 ~15 个页面重复；8 个管理页（账户/分类/标签/预算/周期/规则/信用卡/备注模板）是同一"列表+FormModal"模式却各自实现。
  5. 录入流程偏长：方向 chip → 金额 → 账户 → 分类网格 → 折叠详情，不是金额优先；无 KeyboardAvoidingView；日期靠手输 YYYY-MM-DD。
  6. 信息架构问题：设置页 13 入口平铺；报表页周/月/年三套独立状态；年报内嵌月报与月 Tab 重复；AI/导出图标无文字标签。
  7. Header 策略不统一：二级页手写返回栏，唯独 transaction/new 用原生 header。

2. 已确认的关键决策

决策点 结论
重设计深度 全面重做（所有页面）
视觉方向 明亮 Bento 现代风：浅色为主 + 大圆角黑白对比，财务语义色点缀
暗色模式 完整保留（OLED 纯黑，与浅色对等）
记一笔交互 金额优先数字键盘面板（NumpadSheet）
底部导航 中央凸起 ＋，4 个内容 Tab（首页/交易/报表/我的）
实施策略 设计系统先行，逐页替换（5 个阶段）

3. 视觉语言（Design Tokens）

3.1 色板

浅色（默认）：

Token 值 用途
bgPrimary #F6F7F9 页面背景
bgSecondary #FFFFFF 卡片
bgTertiary #EFF1F4 输入框/chip
fgPrimary #111318 主文字
fgSecondary #6B7280 次要文字
fgInverse #FFFFFF 反色文字
accent #111318 近黑，按钮/选中态
accentLight / accentDark 重定义为中性色阶：accentLight = accent 8% 透明度的底色（选中高亮），accentDark = accent 的按压加深态 高亮背景/按压态
financial.income #10B981 收入
financial.expense #EF4444 支出
financial.transfer #3B82F6 转账

暗色（OLED，完整对等）：

Token 值
bgPrimary #040508
bgSecondary #101218
bgTertiary #1A1D24
fgPrimary / accent #F3F4F6（accent 反转为白）
fgSecondary #9CA3AF
financial.income #34D399（提亮）
financial.expense #F87171（提亮）
financial.transfer #60A5FA（提亮）

原则：accent 从靛蓝改为近黑白单色，品牌感靠排版与财务语义色表达；对比度 ≥ 4.5:1；暗色下用 1px 半透边框代替阴影。

3.2 字体 / 圆角 / 阴影 / 图标

  • 移除 Caveat/Quicksand 自定义字体，改系统字体（iOS SF / Android Roboto），消除字体加载失败风险；删除 _layout.tsx 字体加载代码。
  • 金额数字统一 fontVariant: ['tabular-nums']。
  • 字阶：display 34 / h1 28 / h2 22 / h3 17 / body 16 / bodySmall 14 / caption 12。
  • 圆角：sm 8 / md 12 / lg 16 / xl 24（卡片默认） / full。
  • 阴影减重：浅色 2–12px 弥散阴影；暗色以边框代替。
  • 图标统一 Ionicons；全部 emoji 图标替换为 CategoryIcon（Ionicon + 圆形彩色底）。
  • 硬编码分类色收归 theme.categoryPalette（12 色循环）；渠道色、标签默认色等一并 token 化。
  • design-system/beancount-mobile/MASTER.md 重写以匹配实现，结束"两份宪法"。

4. 核心交互：NumpadSheet 记一笔面板

4.1 结构（一屏完成 90% 记账）

自上而下：方向 chip（支出/收入/转账） → 大金额显示（等宽数字） → 账户 chip 行 → 分类快捷网格（4 列，常用分类 + "全部"） → 内嵌数字键盘（0-9、小数点、⌫、＋/－ 连续计算（如 20+15 直接出 35）、"今天"日期键、完成键）。下滑展开"更多"抽屉：备注、标签、日期、高级模式（PostingEditor）入口。原 SpeedDial 的 OCR/导入入口移入面板顶部工具行。

4.2 两个账户（复式记账的"两条腿"）

方向 腿 1 腿 2
支出 资金来源账户（Assets/Liabilities，账户 chip 行，"从"） 分类账户（Expenses:*，分类网格）
收入 分类账户（Income:*，分类网格） 到账账户（Assets，账户 chip 行，"到"）
转账 转出账户（chip 行） 转入账户（第二 chip 行 + ⇅ 互换按钮），分类网格隐藏

配套规则：

  • 账户 chip 行显示最常用的 3~4 个 Assets/Liabilities 账户（按使用频率排序），默认选中上次使用的账户（settingsStore 持久化），分类同理；"⋯"弹出全部账户树。
  • 转账双方限定 Assets/Liabilities 账户（与 transferRecognizer 校验一致）；还信用卡 = 转账到 Liabilities 账户，天然支持。
  • 落账走 buildAndSaveTransaction() → BillPipeline，与手动/自动渠道完全一致，不产生第二套写入逻辑。
  • 无 Assets 账户时 chip 行显示"去创建账户"引导，不死锁。
  • 完成键上方可选显示分录预览 Assets:招行 → Expenses:餐饮 ¥35（可在设置关闭）。
  • 编辑模式按 posting 方向回填两条腿。
  • P3 阶段先在设置加"新版录入"开关灰度，稳定后默认开启。

5. 导航

自定义 AppTabBar（替换 expo-router 默认 tabBar）：4 个内容 Tab（首页/交易/报表/我的）+ 中央凸起 ＋。＋ 不是路由，在任何页面唤起全局 Modal（NumpadSheet），不丢失上下文。SpeedDial 退役。

6. 核心组件库（P2 交付物）

新增：

  • NumpadSheet — 见第 4 节
  • AppTabBar — 见第 5 节
  • ScreenHeader — 统一二级页头（返回 + 标题 + 右操作位），替换十几份手写返回栏；transaction/new 的原生 header 一并撤掉
  • StatCard — "标题 + 大数字 + caption"统计卡（首页/报表/年报共用）
  • ManagementScreen — 管理页模板（ScreenHeader+＋ / 可选分组 Tab / FlatList / 删除确认 / FormModal），8 个管理页共用，各页只声明字段配置 + 数据读写 hooks
  • DatePickerField — 日历选择器，终结手输 YYYY-MM-DD
  • FilterSheet — 底部弹层高级筛选（账户/日期/金额区间）
  • CategoryIcon — Ionicon + 彩色圆底，替换 emoji

改造/退役：Button/Card/Chip/SearchBar 按新 token 重刷；CategoryPicker 改底部弹层网格并 Ionicon 化；FormModal 的 "✕" 字符换 Ionicons；transaction/new 整页重写为 NumpadSheet 宿主（编辑模式复用同面板）。

7. 逐页重设计要点

7.1 首页：从"数据墙"到"今日视角"

  • 顶部：日期 + 问候语（替代应用名标题）。
  • 净资产卡：去 accent 底色改白卡 + tabular 大数字，下方一行小字：本月支出 / 收入 / 预算剩余。
  • 新增待办条：周期记账到期、信用卡还款提醒、未确认自动账单——首页回答"今天我要做什么"。
  • 最近 5 条交易 + "查看全部 →"。
  • 月度趋势卡（TrendLine 重刷新色板）。
  • 账户余额树下沉到「我的」页。

7.2 交易页：搜索优先 + 分组时间线

  • 搜索框常驻；方向筛选 chip 保留；高级筛选收进 FilterSheet。
  • 列表按日期分组（今天/昨天/具体日期），组头显示当日收支小计。
  • TransactionCard 重刷：CategoryIcon 圆底图标 + 商户/备注 + 账户小字 + 右侧等宽金额（支出黑色、收入绿色带 + 号，降低色彩噪音）。
  • 左滑卡片：快捷"再记一笔（复制）/ 删除"。
  • 解析诊断从页面底部移入设置 → 数据组。

7.3 报表页：统一时间导航 + 去重

  • 周/月/年 Tab 保留；三套独立状态（viewYear/viewMonth/viewWeekDate）合并为单一 anchor 日期 + 周期类型，左右箭头统一切换。
  • 删除年报内嵌的 MonthlyReport（与月 Tab 重复）；年报只留：年度收支汇总、月度节奏迷你图、Top 分类。
  • AI 总结/导出入口加文字标签，收进 "⋯" 菜单。
  • CalendarView 保留在月 Tab，配色收归 token；热力图用 expense 色 5 级透明度。
  • CategoryPie / StatCard / NetWorthChart 统一新 token。

7.4 设置 →「我的」：4 分组重构

  • 账户与分类：账户树（含余额，从首页移来）、分类、标签、信用卡、备注模板。
  • 记账自动化：规则、周期记账、自动记账通道（无障碍/通知/短信）、导入。
  • 数据：同步（WebDAV/Git/iCloud）、备份恢复、导出、解析诊断。
  • 偏好：主题、语言、应用锁、AI 设置、每日提醒、关于。
  • 每组一张 Bento 卡，条目 = 图标 + 名称 + 右箭头；所有二级页用统一 ScreenHeader。

7.5 管理页模板化

账户/分类/标签/预算/周期/规则/信用卡/备注模板 8 页统一套 ManagementScreen，预计删除上千行重复代码。

8. 阶段计划

阶段 内容 验收
P1 设计系统 新 tokens → 双主题 presets → 移除自定义字体 → categoryPalette → 重写 MASTER.md typecheck 通过；token 名不变只改值，旧组件接口兼容
P2 组件库 ScreenHeader / StatCard / AppTabBar / CategoryIcon / DatePickerField / FilterSheet / ManagementScreen 组件调试页可逐个查看；纯逻辑单测
P3 录入闭环 NumpadSheet + 双腿账户选择 + 全局＋ + transaction/new 重写 + SpeedDial 退役；"新版录入"开关灰度 手动记账/编辑/转账/还款全走面板；pipeline 集成测试不回归
P4 四个 Tab 首页（待办条）/ 交易（时间线+左滑）/ 报表（anchor 统一）/ 我的（4 分组） 逐页替换，每页替换后全量测试
P5 管理页+收尾 8 页套模板；图表重刷；emoji 清零；硬编码色清零（grep 审计）；无障碍标签补全 #[0-9A-Fa-f]{6} 在 src/ 下只剩 presets.ts 与 categoryPalette

9. 测试策略

  • 不动 domain 层：billPipeline/dedup/rules 等纯逻辑零改动，现有 30+ 单测是安全网，必须保持全绿。
  • 新增纯逻辑单测：numpad 表达式求值（＋/－ 连续计算）、双腿账户解析（方向 → posting 映射）、anchor 日期导航（周/月/年加减）。
  • 每阶段结束跑 npm test + npm run typecheck；UI 层靠深浅双主题手工走查清单。
  • 硬编码色审计：grep 全量扫描。

10. 风险与 YAGNI

风险对策：

  • 主题切换过渡期"半新半旧" → P1 保持 token 名不变只改值，组件接口向后兼容。
  • NumpadSheet 全新交互 → 设置开关灰度后再默认开启。
  • 移除字体无数据迁移，删加载代码即可。

明确不做：自定义主题编辑器（保留 light/dark/system 三档）；迁移图标库到 Lucide；改 domain/存储/同步层；平板/桌面布局适配。