卡迹是一款本地优先的交通卡收藏管理应用。它以 Drift/SQLite 和 App 私有图片目录为 唯一的本地事实来源;没有账号、没有网络或没有配置同步服务时,建卡、整理、统计、 备份与恢复仍可完整使用。
- 首页、收藏、拍摄、统计、我的五入口;手机使用底部导航,宽屏使用侧边导航。
- 亮色/暗色主题、首次启动三屏引导、主题与诊断设置持久化、Android 双击返回退出。
- 新建与编辑卡片,支持名称、城市、机构、发行日期、编号、备注、数量、品相、发行量、 发售价、入手日期、标签、自定义字段、套卡和集卡册归属。
- 新建卡片时名称与城市必填;已有卡片可继续补充资料。中国城市使用省/市/县区选择, 县区可省略,国外地址可手动填写。
- 系统相机和相册导入、单卡最多 20 张图片、正反面/包装/编号/细节等用途、排序与封面。
- 拍照后直接进入资料页;用户主动编辑图片时再使用系统相册式裁剪、缩放和旋转,并可 调整亮度、对比度和清晰度。原图保持不变,编辑结果单独保存。
- 已接入卡面 OCR 平台桥接、资料候选确认和内置/远程资料库接口;当前 OCR 运行时仍不可用, 需完成诊断与 Android/iOS 真机验收后才能作为交付能力使用。
- 多卡批量录入、共享资料、草稿中断恢复、相册批量导入正面图、保存前一次性汇总确认, 以及自动关联套卡和集卡册。
- 套卡成员、整套张数、封面、已拥有/缺失/重复张数和完成度;集卡册可同时收纳卡片与套卡。
- 标签、自定义字段、全文搜索、组合筛选、重复卡/待完善/本月入手筛选和稳定排序。
- 卡片录入与编辑内直接维护人民币“卡片金额 + 运费”;首页展示全时期活跃收藏净消费。
- 首页收藏摘要、最近录入、即将集齐、待补资料;六维数量分布、消费趋势、消费日历与下钻。
- 卡片软删除、恢复、永久删除、7/30/90 天保留期、级联可见性和持久文件清理队列。
- 版本化 ZIP 完整备份、校验、空库恢复、仅新增合并,以及 UTF-8 BOM CSV 导出。
- 可选邮箱账号和本地优先同步:安全会话、持久 outbox、增量游标、附件校验、重试与冲突副本; App 回到前台或周期到点时自动补一次到期同步(不含系统级后台任务)。
- 数据库启动失败时保留原文件并提供重试;启动时重放清理队列并删除未引用图片。
未注入服务地址时 App 保持纯本地模式。测试/生产同步服务通过 HTTPS 地址注入:
flutter run --dart-define=CARD_FOLIO_API_BASE_URL=https://sync.example.com远程交通卡资料库是可选能力:
flutter run --dart-define=CARD_FOLIO_CATALOG_BASE_URL=https://catalog.example.com自建同步服务的实现、Supabase 迁移和 Docker/Nginx 部署步骤见 server/README.md。服务端密钥不得编译进 App。
同步网关变更需额外运行:
cd server
npm ci
npm test
npm run check
npm run check:docs需要 Flutter 3.44.0、Dart 3.12+、JDK 21 和 Android SDK。Windows 使用 Flutter 插件时需先开启 开发者模式以允许创建符号链接。在项目根目录依次运行:
flutter pub get
dart run build_runner build --delete-conflicting-outputs
dart format --output=none --set-exit-if-changed lib test integration_test
flutter analyze --fatal-infos --fatal-warnings
flutter test test/drift/app/migration_test.dart test/features/cards/data/card_database_migration_test.dart
flutter test --concurrency=1
flutter build apk --debug
flutter runNote
Android Studio 应打开项目根目录,而不是只打开 android/。JDK 21 可用于运行 Gradle,
Android Java/Kotlin 字节码目标仍统一为 17。
运行持久化集成测试时,请指定一个已连接设备:
flutter devices
flutter test -d <device-id> integration_test/card_persistence_test.dart构建 Android debug APK:
flutter build apk --debug输出文件位于 build/app/outputs/flutter-apk/app-debug.apk。Release APK 对应
build/app/outputs/flutter-apk/app-release.apk。
完整质量门禁和最近一次验证结果见工程基线;当前限制见 已知问题。
首轮验收目标是 Android 模拟器或真机。核心路径包括:
- 首次启动三屏引导、首页和亮暗主题;
- 取消系统相册/相机,确认不生成卡片;
- 录入名称、城市、数量、正反面和成本,连续点击保存仍只生成一张卡;
- 编辑图片,验证裁剪、旋转、亮度/对比度以及原图保留;
- 批量录入多张卡,验证草稿恢复、标签、套卡和集卡册归属;
- 强制停止并重启,确认卡片、关联、成本、图片和主题仍存在;
- 删除并恢复卡片,核对集卡册、统计和消费金额随活跃状态变化;
- 导出 ZIP 后在空库恢复,再导出 CSV 检查中文与特殊字符;
- 在 360/393/430dp、200% 字体及 TalkBack/VoiceOver 下完成核心流程。
生产 Dart 代码和插件配置保持 iOS 兼容;macOS/iOS 构建与真机验证需在 macOS 环境补充。
数据库和图片保存在平台提供的应用支持目录下。数据库仅记录受管图片的相对路径, 不会依赖系统相册中的原文件持续存在。数据库打开失败时应用不会自动删除或重建 现有数据。
更完整的产品、架构与测试资料见 docs/README.md。