From 944ad2a59cd0ac05ab4e2d722c2dc495c5ddbf3d Mon Sep 17 00:00:00 2001 From: lishaohua <381890123@qq.com> Date: Thu, 21 May 2026 14:25:55 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=87=E6=A1=A3=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 141 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 722eb8e..e81a901 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,147 @@ -# zhinian_manage +# 智念商家端 (zhinian_manage) -A new Flutter project. +智念酒店景区管理端 —— 面向度假酒店与景区运营人员的一体化移动管理 App，覆盖 AI 助手、订单核销、工单流转、事件发布、扫码核销与门店运营等场景。 -## Getting Started +- 应用名：智念商家端 +- Bundle ID：`com.lishaohua.zhinianManage.dev` +- 包名：`com.lishaohua.zhinian_manage` +- 版本：`1.0.0+1` -This project is a starting point for a Flutter application. +## 技术栈 -A few resources to get you started if this is your first Flutter project: +| 分类 | 选型 | +| --- | --- | +| 框架 | 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 | -- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) +## 目录结构 -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +``` +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` 中开启。