日报：FSI Deutsch App 首次运行 · 环境搭建与 Debug — 2026年3月22日

为什么我想做这个 App？

最近在研究德语学习方法的时候，我了解到了 FSI（Foreign Service Institute，美国外交学院） 的语言课程体系。FSI 是美国国务院下属的培训机构，专门为外交官提供高强度语言训练，其课程覆盖数十种语言，以严谨、系统著称。FSI 德语课程的核心训练方式之一就是 替换练习（Substitution Drills）——在一个固定的句型框架中，不断替换词汇或语法成分，通过大量重复让正确的语法形式成为条件反射，最终实现脱口而出。

这种训练方式非常适合我当前的需求：语法框架基本掌握，但口语输出时总是犹豫、出错。市面上没有找到好用的 App 来做这种练习，于是我决定自己动手，用 Flutter 做一个 FSI Deutsch——一个专注于德语替换训练的 iOS App，帮助自己系统地提高德语输出能力。

工作内容

1. 项目初始化

  • 通过 flutter create 创建 Flutter 项目骨架
  • 导入预先编写好的源码（lib/、pubspec.yaml、analysis_options.yaml）和练习数据（5 个 JSON 文件，A1–C1 共 1,692 题）
  • 执行 flutter pub get 安装 69 个依赖包
  • 执行 pod install 安装 iOS 原生依赖

2. 快速启动指南重写

对原有的快速启动指南进行了大幅改写：

  • 引入 $SOURCE 变量机制，让路径配置一目了然
  • 所有命令改为绝对路径，避免 cd 出错
  • 增加验证步骤和常见问题排查表
  • 补充完整操作速查（一次性复制粘贴版）

3. Debug 过程

Bug #1：CardTheme API 变更

现象：编译失败，Xcode 报错 Could not build the application for the simulator。

原因：Flutter 新版本中 CardTheme 更名为 CardThemeData，但从源码目录复制过来的 theme.dart 仍使用旧 API。

修复：将 lib/config/theme.dart 中两处 CardTheme( 替换为 CardThemeData(，并同步回源码目录。

Bug #2：词汇提示显示错误内容

现象：练习界面的「词汇提示」卡片显示的是 prompt_zh（中文提示）而非 template（德语词汇列表）。

排查过程：

  1. _buildVocabCard → 读取 item.template，逻辑正确 ✓
  2. DrillItem model JSON 解析 → 字段映射正确 ✓
  3. DatabaseHelper 数据库读取 → 列映射正确 ✓
  4. loadSeedData → 发现问题：检测到已有数据就直接返回，不会更新

根本原因：模拟器上已有旧版数据库（version 1），template 字段存储的是旧格式数据。loadSeedData 发现已有数据就跳过，导致新数据无法写入。

修复：

  • constants.dart：dbVersion 从 1 → 2
  • database_helper.dart：增加 onUpgrade 回调，触发时删除旧表并重建
  • 完整重启应用（非热重载），数据库自动升级并重新加载 JSON 数据

运行截图

App 在 iOS 模拟器上成功运行，B1 语法分类页面展示如下：

FSI Deutsch App — B1 语法分类页面

当前状态

  • ✅ App 已在 iOS 模拟器上成功运行
  • ✅ 词汇提示正确显示 template 内容
  • ✅ 快速启动指南已更新完毕
  • ✅ 源码目录与开发目录已同步

明日计划

  • 真机测试（iPhone 推送 + 签名验证）
  • 功能走查：各级别练习流程、进度追踪、答案反馈
  • 继续修改排版和内容/词汇提示的显示问题