148 lines
6.9 KiB
Markdown
148 lines
6.9 KiB
Markdown
# 智念商家端 (zhinian_manage)
|
||
|
||
智念酒店景区管理端 —— 面向度假酒店与景区运营人员的一体化移动管理 App，覆盖 AI 助手、订单核销、工单流转、事件发布、扫码核销与门店运营等场景。
|
||
|
||
- 应用名：智念商家端
|
||
- Bundle ID：`com.lishaohua.zhinianManage.dev`
|
||
- 包名：`com.lishaohua.zhinian_manage`
|
||
- 版本：`1.0.0+1`
|
||
|
||
## 技术栈
|
||
|
||
| 分类 | 选型 |
|
||
| --- | --- |
|
||
| 框架 | 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`。
|
||
|
||
## 环境准备
|
||
|
||
1. **Flutter SDK**:3.41.9(channel stable);项目 SDK 约束 `>=3.0.0 <4.0.0`。
|
||
2. **iOS**:Xcode 15+、CocoaPods、苹果开发者账号(Team `UBDH3YTVFW`,仅用于真机调试签名)。Vosk 的 `vosk_flutter.xcframework` 已在 `ios/` 下,执行 `pod install` 即可。
|
||
3. **Android**:Android SDK + platform-tools(`adb`)。已知 `adb` 不在用户 PATH,实际使用 `~/Library/Android/sdk/platform-tools/adb` 全路径。
|
||
4. **国内网络**:GitHub/CDN 不稳,Flutter / pub / Homebrew / Ruby 镜像配置参考全局笔记。
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
flutter pub get
|
||
|
||
# 生成本地化代码(如修改了 .arb)
|
||
flutter gen-l10n
|
||
|
||
# iOS Pod
|
||
cd ios && pod install && cd ..
|
||
|
||
# 任意已连接设备调试
|
||
flutter run
|
||
```
|
||
|
||
## 构建与部署
|
||
|
||
### iOS 真机(已使用过的命令)
|
||
|
||
```bash
|
||
# Release 构建
|
||
flutter build ios --release
|
||
|
||
# 用 devicectl 持久化安装(不会随 flutter run 退出而卸载)
|
||
xcrun devicectl device install app \
|
||
--device 00008110-001055D92183401E \
|
||
build/ios/iphoneos/Runner.app
|
||
```
|
||
|
||
### Android 真机(vivo 75b8114)
|
||
|
||
```bash
|
||
# 只构建 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` 中开启。
|