# 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） |

---

## 一、初始化

```bash
# 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 模块热重载

```bash
# 在 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 引用：

```ruby
# 在宿主 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 编译步骤

```bash
# 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 数据拦截器，在无后端的情况下可独立运行和调试：

```dart
// 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：

```bash
# 将 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` 声明。

---

## 七、设计文档

- [设计规格说明书](docs/superpowers/specs/2026-05-29-tboss-oa-design.md)
- [数据库表字段设计](docs/superpowers/specs/2026-05-29-tboss-oa-database.md)
- [实现计划](docs/superpowers/plans/2026-05-29-tboss-oa-implementation.md)