分类	选型
框架	Flutter 3.41.9 / Dart 3.11
状态管理	flutter_riverpod + hooks_riverpod + flutter_hooks
路由	go_router
网络	dio
本地存储	hive / hive_flutter / shared_preferences
国际化	flutter_localizations + intl(中文 / 英文 / 泰语)
Markdown 渲染	flutter_markdown(自封装 `MarkdownMessage`)
图表	fl_chart
图片	cached_network_image / image_picker
扫码	mobile_scanner
语音	speech_to_text (iOS) + vosk_flutter_service (Android 离线中文)
权限	permission_handler
动效	flutter_animate / lottie / shimmer

目录结构

zhinian_app/
├── android/                 Android 原生工程(含 vivo 真机部署配置)
├── ios/                     iOS 原生工程(含 Vosk xcframework、Pod 配置)
├── assets/
│   ├── logo.png
│   └── models/vosk-model-small-cn-0.22.zip  离线中文语音模型
├── lib/
│   ├── main.dart            入口、Riverpod ProviderScope、go_router
│   ├── theme.dart           AppColors / 全局主题
│   ├── l10n/                app_zh.arb / app_en.arb / app_th.arb
│   ├── models/              user / message / event / order / work_order
│   ├── providers/           auth / chat / event / order / settings / work_order
│   ├── services/
│   │   ├── api_service.dart        统一 mock API + AI 回复路由
│   │   ├── storage_service.dart    Hive 封装
│   │   └── vosk_voice_service.dart 离线语音识别封装
│   ├── widgets/
│   │   ├── markdown_message.dart   自封装的 Markdown 渲染(表格、图片)
│   │   ├── chart_block.dart        ```chart``` 代码块渲染为 fl_chart
│   │   └── skeleton.dart           骨架屏
│   └── pages/               17 个业务页面(登录、首页、订单、工单、事件、扫码、门店、报表、设置等)
└── pubspec.yaml

关键架构说明

1. AI 聊天 + 富文本渲染

聊天内容统一走 Markdown,但 flutter_markdown 对块级标签(pre、table)不会调用注册的 builder,会无脑用 styleSheet.codeblockDecoration 包裹。为此 widgets/markdown_message.dart 做了两层处理:

表格:在进入 MarkdownBody 之前用正则把 Markdown 切成「文本段」和「表格段」,表格段交给自定义 _ScrollableTable(基于 Table + IntrinsicColumnWidth + 横向滚动)渲染,避免裁切。
代码块/图表:在 MarkdownStyleSheet 上把 codeblockDecoration 设为透明、codeblockPadding 设为零;chart 代码块由 ChartCodeBuilder 拦截 inline code 元素,解析 key: value 行后用 fl_chart 绘制柱状图/折线图/饼图,数据多于可视宽度时同样支持横向滚动。
图片:MarkdownBody.imageBuilder 返回 _MarkdownImage,点击进入 _ImageViewer(PageRouteBuilder + Hero + InteractiveViewer,最大缩放 4 倍);打开/关闭时显式 FocusManager.instance.primaryFocus?.unfocus(),避免输入框抢焦点弹出键盘。

2. AI 关键词路由

services/api_service.dart 的 sendMessage 按顺序匹配关键词,命中后返回固定 mock 数据,演示三类富文本:

触发词	返回
表格 / 列表 / 清单 / 明细	`_tableReport()` 订单明细 + 汇总两张表
图片 / 照片 / 图像 / 实景 / 环境照 / 相册	`_imageGallery()` 三张 picsum 实景图
报表 / 数据 / 营收 / 趋势 / 占比 / 图表 / 统计 / 分析	`_chartReport()` 柱/折/饼三张图表

未命中时随机返回一条短文本,用于演示普通对话。

3. 语音输入

iOS 走 speech_to_text,需要在 Info.plist 声明 NSMicrophoneUsageDescription / NSSpeechRecognitionUsageDescription。
Android 走 vosk_flutter_service + 内置离线模型 assets/models/vosk-model-small-cn-0.22.zip,首次运行解压到沙盒。
麦克风入口位于聊天输入框的 suffixIcon:无边框、纯图标 InkWell,激活时图标变色并做呼吸缩放动画。

4. 国际化

通过 flutter gen-l10n 生成,默认中文,Settings 页可切换。新增文案需同步更新 lib/l10n/app_*.arb。

环境准备

Flutter SDK:3.41.9(channel stable);项目 SDK 约束 >=3.0.0 <4.0.0。
iOS:Xcode 15+、CocoaPods、苹果开发者账号(Team UBDH3YTVFW,仅用于真机调试签名)。Vosk 的 vosk_flutter.xcframework 已在 ios/ 下,执行 pod install 即可。
Android:Android SDK + platform-tools(adb)。已知 adb 不在用户 PATH,实际使用 ~/Library/Android/sdk/platform-tools/adb 全路径。
国内网络:GitHub/CDN 不稳,Flutter / pub / Homebrew / Ruby 镜像配置参考全局笔记。

运行

# 安装依赖
flutter pub get

# 生成本地化代码(如修改了 .arb)
flutter gen-l10n

# iOS Pod
cd ios && pod install && cd ..

# 任意已连接设备调试
flutter run

构建与部署

iOS 真机(已使用过的命令)

# Release 构建
flutter build ios --release

# 用 devicectl 持久化安装(不会随 flutter run 退出而卸载)
xcrun devicectl device install app \
  --device 00008110-001055D92183401E \
  build/ios/iphoneos/Runner.app

Android 真机(vivo 75b8114)

# 只构建 arm64 加快速度
flutter build apk --target-platform=android-arm64 --release

# 安装到指定设备
~/Library/Android/sdk/platform-tools/adb -s 75b8114 install -r \
  build/app/outputs/flutter-apk/app-release.apk

若 adb devices 不显示设备,先 adb kill-server && adb start-server,然后在手机上重新确认 USB 调试授权。

Git 仓库

远端:git.nianxx.cn/lishaohua/zhinian_app.git(私有 Gitea)
凭证:首次 git push 需要在交互式 shell 输入用户名/密码,macOS keychain 之后会记住。

常见问题

图表/表格出现灰色背景 → 检查 MarkdownStyleSheet.codeblockDecoration 是否设置为 Colors.transparent;pre/table 是块级标签,builder 不生效。
图表/表格被裁切 → 内置横向滚动,直接拖动即可;数据列太多时会按 56px/项延展。
点击图片后输入框弹出键盘 → 已通过 FocusManager.unfocus() + rootNavigator: true + HitTestBehavior.opaque 解决,若复现请检查 _MarkdownImage 的 GestureDetector 实现。
Android 启动报麦克风崩溃 → 检查 AndroidManifest.xml 是否声明 RECORD_AUDIO,以及 permission_handler 的 PERMISSION_MICROPHONE 预处理标志是否在 ios/Podfile 中开启。

README.md Unescape Escape

智念商家端 (zhinian_manage)

技术栈