tboss_oa_module

TBOSS OA Module

基于 Flutter 3.38.10 的 OA 办公自动化模块，以 Add-to-App 方式嵌入现有 Android（Java/Kotlin）和 iOS（Objective-C）宿主应用。

功能模块

模块	说明
报销单	实报实销，事后报销，含发票明细
报销申请单	事前费用申请，预估金额审批
加班申请单	加班事前/事后申请，支持加班费/调休
用车申请单	车辆使用申请，含里程预估/实际
业务员外出日志	销售外勤签到/签退，客户拜访记录
公告通知	公司通知公告，置顶/已读/确认
报销明细报表	报销数据多维度汇总报表
加班明细报表	加班数据汇总报表
用车明细报表	用车数据汇总报表
报销申请明细报表	报销申请数据汇总报表

技术栈

技术	版本	用途
Flutter	3.38.10	跨平台框架
Dart SDK	^3.10.9	语言运行时
TDesign Flutter	^0.2.7	腾讯 TDesign UI 组件库
Riverpod	^2.6.1	状态管理
GoRouter	^14.8.1	路由导航
Dio	^5.7.0	网络请求
fl_chart	^0.69.2	报表图表
flutter_slidable	^3.1.1	列表滑动操作

项目结构

tboss_oa_module/
├── lib/
│   ├── main.dart                    # 入口，初始化 Flutter 引擎
│   ├── app.dart                     # MaterialApp + Router + Provider
│   ├── core/
│   │   ├── auth/                    # 认证（MethodChannel 通信）
│   │   ├── network/                 # Dio 网络层 + Mock 拦截器
│   │   ├── router/                  # GoRouter 路由配置（Shell 路由）
│   │   ├── theme/                   # TDesign + Material3 主题
│   │   └── utils/                   # 工具类（日期、验证、响应式）
│   ├── features/
│   │   ├── shell/                   # 3 Tab 导航外壳
│   │   ├── home/                    # 工作台首页
│   │   ├── messages/                # 消息 Tab
│   │   ├── profile/                 # 我的 Tab
│   │   ├── expense/                 # 报销单
│   │   ├── expense_application/     # 报销申请单
│   │   ├── overtime/                # 加班申请单
│   │   ├── vehicle/                 # 用车申请单
│   │   ├── outing_log/              # 业务员外出日志
│   │   ├── announcement/            # 公告
│   │   └── report/                  # 报表
│   └── shared/
│       ├── models/                  # 共享数据模型
│       └── widgets/                 # 共享 UI 组件
├── pubspec.yaml                     # Flutter 依赖配置
├── docs/superpowers/specs/          # 设计文档
└── docs/superpowers/plans/          # 实现计划

开发环境要求

工具	版本要求
Flutter SDK	3.38.10
Dart SDK	3.10.9+
Android Studio	Hedgehog (2023.1.1)+
Android SDK	API 35+
Android Gradle Plugin	8.13.0+
Gradle	8.5+
JDK	17+
Xcode	14.2+（仅 iOS）
macOS	Monterey 12.7.6+（仅 iOS）
CocoaPods	最新版（仅 iOS）

---

一、初始化

# 1. 进入 Flutter module 目录
cd tboss_oa_module

# 2. 安装 Flutter 依赖
flutter pub get

---

## 二、Android 编译运行

### 2.1 宿主项目结构

Android/ # 宿主 Android 项目根目录 ├── app/ # 主 App 模块 │ ├── build.gradle # App 构建配置 │ └── src/main/ │ ├── AndroidManifest.xml # 已声明 FlutterActivity ├── tboss_oa_module/ # Flutter module（本目录） │ └── .android/ # Flutter 生成的 Android 壳工程 ├── build.gradle # 根构建配置 └── settings.gradle # 含 Flutter module 引用

### 2.2 编译步骤

```bash
# 1. 确保 Flutter module 依赖已安装
cd tboss_oa_module
flutter pub get

# 2. 进入宿主 Android 项目
cd ../Android

# 3. 编译 Debug APK
./gradlew assembleDebug

# 4. 编译 Release APK
./gradlew assembleRelease

# 5. 安装到设备
adb install app/build/outputs/apk/debug/Tboss_debug.apk

2.3 运行调试

在 Android Studio 中：

1. 打开 Android/ 目录作为已有项目
2. 同步 Gradle（File → Sync Project with Gradle Files）
3. 选择 Run → Run 'app'
4. 进入 App 后，通过"首页 → 我的 → 检查更新"启动 Flutter OA 模块

2.4 Flutter 模块热重载

# 在 tboss_oa_module 目录下启动 Flutter attach
cd tboss_oa_module
flutter attach

然后在已连接的设备上打开 Flutter OA 模块页面，终端会显示同步信息，按 r 热重载。

---

三、iOS 编译运行

3.1 宿主项目结构

ios/                              # 宿主 iOS 项目
├── Podfile                       # CocoaPods 配置（需引入 Flutter module）
└── ...
tboss_oa_module/                  # Flutter module（本目录）
└── .ios/                         # Flutter 生成的 iOS 壳工程

3.2 Podfile 配置

宿主 iOS 项目的 Podfile 需添加 Flutter module 引用：

# 在宿主 iOS 项目的 Podfile 中添加
flutter_application_path = '../tboss_oa_module'
load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')

target 'YourApp' do
  use_frameworks!
  
  install_all_flutter_pods(flutter_application_path)
  
  # ... 其他 pods
end

post_install do |installer|
  flutter_post_install(installer) if defined?(flutter_post_install)
end

3.3 编译步骤

# 1. 确保 Flutter module 依赖已安装
cd tboss_oa_module
flutter pub get

# 2. 进入宿主 iOS 项目
cd ../ios

# 3. 安装 CocoaPods 依赖
pod install

# 4. 打开 Xcode workspace（注意是 .xcworkspace 不是 .xcodeproj）
open YourApp.xcworkspace

# 5. 在 Xcode 中选择目标设备，Product → Build（⌘B）
# 6. Product → Run（⌘R）

3.4 iOS 编译注意事项

• 必须使用 .xcworkspace 打开项目（CocoaPods 要求）
• 宿主 iOS 项目使用 Objective-C，Flutter module 的 iosBundleIdentifier 为 com.amtxts.tbossOaModule
• 确保 Deployment Target ≥ 12.0
• 编译前确认 tboss_oa_module/.ios/ 目录存在（由 flutter pub get 生成）
• 如果 Pod 安装失败，尝试： bash cd ios pod cache clean --all pod deintegrate pod install

---

四、Mock 数据模式

项目内置 Mock 数据拦截器，在无后端的情况下可独立运行和调试：

// lib/app.dart
final apiClientProvider = Provider<ApiClient>((ref) {
  const useMock = true;  // 改为 false 切换到真实 API
  // ...
});

• useMock: true — 使用 MockInterceptor 返回模拟数据
• useMock: false — 请求真实后端 API

Mock 数据涵盖所有功能模块：报销单、加班、用车、外出日志、公告、报表等。

---

五、后端 API 对接

后端 API 基于 .NET Framework 4.8，接口规范：

• Base URL: https://<host>/api
• 认证: Bearer Token（Header: Authorization: Bearer <token>）
• 响应格式: { "code": 0, "message": "ok", "data": {...} }
• 分页: { "list": [], "page": 1, "size": 20, "total": 100 }

完整接口文档见 docs/superpowers/specs/2026-05-29-tboss-oa-database.md。

对接时修改 lib/app.dart 中的 baseUrl 并将 useMock 改为 false。

---

六、已知问题

6.1 Flutter 3.38 插件兼容性（Android）

flutter pub get 后，部分 Flutter 插件引用了已移除的 flutter.compileSdkVersion，需手动 patch：

# 将 flutter.compileSdkVersion 替换为 35
sed -i 's/flutter\.compileSdkVersion/35/g' \
  ~/.pub-cache/hosted/pub.flutter-io.cn/flutter_plugin_android_lifecycle-*/android/build.gradle.kts \
  ~/.pub-cache/hosted/pub.flutter-io.cn/image_picker_android-*/android/build.gradle

# 将 minSdk 24 替换为 21（如有冲突）
sed -i 's/minSdk = 24/minSdk = 21/g' \
  ~/.pub-cache/hosted/pub.flutter-io.cn/flutter_plugin_android_lifecycle-*/android/build.gradle.kts

这些 patch 在每次执行 flutter pub get 后需要重新执行。待相关插件发布新版本后可移除。

6.2 Android minSdkVersion

宿主 App 的 minSdkVersion 已从 19 调整为 21，以兼容 Flutter 插件要求。如需恢复 19，需同时修改所有使用到 Flutter 插件的 minSdk 声明。

---

七、设计文档

• 设计规格说明书
• 数据库表字段设计
• 实现计划