bf04400852
OCR 模型按需下载（P8 瘦身）： - 移除 plugins/ppocr/assets/ 内置模型（det 9.8MB + rec 21MB + dict），APK 减包 ~31MB - 新增 modelDownloader.ts：优先从 HuggingFace/CDN 下载，兜底从 APK assets 拷贝 - OcrModule.kt 新增 setModelDir，支持从 filesystem 加载模型，回退 assets 兼容旧用户 - settingsStore 持久化 ocrModelVersion / ocrModelDir - 自动化页集成模型状态检查与一键下载 UI OCR 三层独立控制： - OcrProcessorConfig 从单一 aiVisionEnabled 拆分为 layer1/2/3 三个独立开关 - 设置页可按层启停（L1 正则规则 / L2 本地 OCR / L3 AI Vision） - OCR 处理增加耗时与字符数日志 日志系统升级： - logger.ts 新增 LogFileBackend 抽象，支持磁盘持久化（按日期 app-YYYY-MM-DD.log） - 新增 logBackend.ts（ExpoLogFileBackend）+ 日志中心页 settings/logs.tsx - 日志中心：实时缓冲 + 历史文件、4 级过滤、Tag/关键词搜索、JSON 展开、分享导出、7 天过期清理 - _layout.tsx 启动时初始化文件后端 + 日志脱敏（验证码/卡号） 原生浮层 UI 主题同步（P6）： - 新增 floatingUiConfig.ts：JS 侧从 theme tokens + i18n 构建 FloatingUiConfig 推送原生 - 新增 FloatingUiConfigStore.kt：SharedPreferences 存储，三浮层组件读取 - FloatingBillView 重设计：颜色/文案走配置、新增币种 chip、金额校验改 BigDecimal - FloatingHelper / FloatingTip 同步适配 - _layout.tsx 新增 FloatingUiConfigSyncer，主题/语言切换自动推送 UI 与组件增强： - FormModal 新增 select/dropdown 控件、行内布局（row/flex）、联动回调 onValuesChange - 新增 Touchable 通用触摸组件、AccountCreateModal 快速建账弹窗 - 信用卡页展示账单周期/到期还款日/本期应还/剩余可用额度，关联账户改下拉选择 - AI 设置页重做：OpenAI/Gemini/DeepSeek 预设 + 默认 URL/模型 - 引导页新增 Android 权限检查步骤（无障碍/通知/短信/存储/悬浮窗） 去重优化： - 对手方匹配改为模糊包含（includes），双方均无对手方时判定低置信度重复 - DedupResult 新增 matchedItem 返回匹配对比项 文档重构： - README.md 重写为入口索引（品牌更新 + 模块概览 + 文档导航表） - 新增 AGENTS.md（AI 助手贡献指南）、docs/architecture.md（Mermaid 数据流/分层/OCR 级联图） - 新增 docs/development.md（环境/命令/编码规范/测试/提交规范）、plugins/README.md - UI 重设计文档（design spec + p1-p8）移入 docs/design/ 其他： - i18n 新增权限/信用卡详情/日志中心/AI 设置等翻译键 - ppocr Config Plugin 修复 import 注入去重；size-optimization 增强 - 新增测试：logger.test.ts、floating-ui-config.test.ts
184 lines
11 KiB
Markdown
184 lines
11 KiB
Markdown
# 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/存储/同步层；平板/桌面布局适配。
|