# TBOSS OA Module — 设计规格说明书

**日期：** 2026-05-29
**版本：** 1.0

---

## 1. 项目概述

在 `tboss_oa_module`（Flutter Add-to-App 模块）中实现完整的 OA 前端功能，嵌入现有 Android（Java/Kotlin）和 iOS（Objective-C）宿主应用。

### 约束条件
- Flutter 3.38.10 · Dart SDK ^3.10.9
- 主色 `#00ABF3` · UI 框架 TDesign Flutter 0.2.7
- 必须支持横竖屏自动适配
- iOS 宿主为 OC，禁止引入 Swift-only 依赖导致编译失败
- 后端接口将使用 .NET Framework 4.8 开发（本次仅前端）

---

## 2. 导航架构

采用 **3 Tab 底部导航**（消息 / 工作台 / 我的），使用 GoRouter + TDesign TabBar。

| Tab | 内容 | 图标 |
|-----|------|------|
| 消息 | 审批通知 + 系统公告提醒 | bell |
| 工作台 | 功能入口 + 待办统计 + 报表入口 | app |
| 我的 | 我发起的 + 我审批的 + 草稿箱 + 设置 | user |

---

## 3. 页面清单（24 页）

### 3.1 框架页（3 页）
| 页面 | 路由 | 说明 |
|------|------|------|
| AppShell | `/` | 3 Tab 外壳，包含底部导航 |
| 消息列表 | `/messages` | 审批通知 + 公告提醒聚合 |
| 我的 | `/profile` | 个人中心 |

### 3.2 报销单（3 页）
| 页面 | 路由 | 说明 |
|------|------|------|
| 报销单列表 | `/expense/list` | 状态筛选 + 卡片列表 + 左滑编辑 |
| 报销申请 | `/expense/apply?id=` | 分组表单 + 明细添加 + 存草稿/提交 |
| 报销单详情 | `/expense/detail/:id` | 信息展示 + 审批时间线 + 角色操作栏 |

### 3.3 报销申请单（3 页）
| 页面 | 路由 |
|------|------|
| 报销申请列表 | `/expense-apply/list` |
| 报销申请表单 | `/expense-apply/apply?id=` |
| 报销申请详情 | `/expense-apply/detail/:id` |

### 3.4 加班申请单（3 页）
| 页面 | 路由 |
|------|------|
| 加班列表 | `/overtime/list` |
| 加班申请 | `/overtime/apply?id=` |
| 加班详情 | `/overtime/detail/:id` |

### 3.5 用车申请单（3 页）
| 页面 | 路由 |
|------|------|
| 用车列表 | `/vehicle/list` |
| 用车申请 | `/vehicle/apply?id=` |
| 用车详情 | `/vehicle/detail/:id` |

### 3.6 业务员外出日志（3 页）
| 页面 | 路由 |
|------|------|
| 外出日志列表 | `/outing-log/list` |
| 外出日志创建 | `/outing-log/create` |
| 外出日志详情 | `/outing-log/detail/:id` |

### 3.7 公告（2 页）
| 页面 | 路由 |
|------|------|
| 公告列表 | `/announcement/list` |
| 公告详情 | `/announcement/detail/:id` |

### 3.8 报表（4 页）
| 页面 | 路由 |
|------|------|
| 报销明细报表 | `/report/expense-detail` |
| 报销申请明细报表 | `/report/expense-apply-detail` |
| 加班明细报表 | `/report/overtime-detail` |
| 用车明细报表 | `/report/vehicle-detail` |

---

## 4. 页面设计模式

### 4.1 列表页模式（6 个列表页共用）

```
┌─────────────────────────────┐
│  AppBar: 标题          [+]  │
├─────────────────────────────┤
│  [全部] [待审批] [已通过] [已拒绝]  ← 横向滚动状态筛选
├─────────────────────────────┤
│  ┌─────────────────────┐    │
│  │ BX-20240501-001  待审批 │    │  ← 卡片，点击进详情
│  │ 差旅费 · ¥2,380.00    │    │  ← 左滑露出编辑按钮
│  │ 张三 · 2024-05-01     │    │
│  └─────────────────────┘    │
│  ┌─────────────────────┐    │
│  │ BX-20240428-002  已通过 │    │
│  │ ...                    │    │
│  └─────────────────────┘    │
└─────────────────────────────┘
```

- 组件：TDChip（状态筛选）+ AppCard + flutter_slidable（左滑操作）
- 交互：下拉刷新 + 上拉加载更多
- 空态：EmptyState 组件

### 4.2 表单页模式（5 个申请页共用）

```
┌─────────────────────────────┐
│  AppBar: 标题         草稿  │
├─────────────────────────────┤
│  ┌─ 基本信息 ─────────────┐ │
│  │ 报销类型    差旅费  ›   │ │  ← FormFieldRow，点击弹出选择
│  │ 报销金额    ¥2,380.00  │ │
│  │ 备注       选填      ›  │ │
│  └────────────────────────┘ │
│  ┌─ 报销明细      +添加 ──┐ │
│  │  机票        ¥1,308 ✕  │ │  ← 明细行，可删除
│  │  酒店住宿     ¥848  ✕  │ │
│  └────────────────────────┘ │
├─────────────────────────────┤
│  [存草稿]     [提交审批]     │  ← 底部固定操作栏
└─────────────────────────────┘
```

- 组件：FormSection + FormFieldRow + TDDatePicker + TDPicker（底部弹出选择）
- 明细行支持动态添加/删除/金额自动汇总

### 4.3 详情页模式（6 个详情页共用）

```
┌─────────────────────────────┐
│  AppBar: 标题              │
├─────────────────────────────┤
│      ┌───────┐             │
│      │  ⏳   │  待审批      │  ← 状态头部（颜色随状态变）
│      │ 当前审批人：王经理  │
│      └───────┘             │
│  ┌─ 基本信息 ─────────────┐ │
│  │ 报销单号  BX-...       │ │  ← 键值对展示
│  │ 申请人    张三·销售部  │ │
│  │ 总金额    ¥2,380.00    │ │
│  └────────────────────────┘ │
│  ┌─ 审批进度 ─────────────┐ │
│  │  ● 提交申请  张三 5/1  │ │  ← 时间线
│  │  ● 经理审批  王经理    │ │
│  │  ○ 财务审批  待处理    │ │
│  └────────────────────────┘ │
├─────────────────────────────┤
│  [通过]           [拒绝]    │  ← 按角色显示不同按钮
└─────────────────────────────┘
```

- 组件：StatusTag + TDTimeline/自定义时间线 + 动态底部操作栏
- 底部按钮根据角色 + 单据状态动态渲染

### 4.4 报表页模式（4 个报表页共用）

```
┌─────────────────────────────┐
│  [日期范围 ▼] [类型 ▼] [部门 ▼] [查询] │  ← 筛选栏
├─────────────────────────────┤
│  ┌──────┐  ┌──────┐        │
│  │总金额 │  │总笔数 │        │  ← 汇总卡片
│  │¥12.8万│  │  86  │        │
│  └──────┘  └──────┘        │
│  ┌─ 费用趋势 ─────────────┐ │
│  │    📊 柱状图/折线图     │ │  ← fl_chart
│  └────────────────────────┘ │
│  ┌─ 明细列表 ─────────────┐ │
│  │ 差旅费  ¥35,200  28笔  │ │
│  │ 办公用品 ¥12,800  15笔  │ │
│  └────────────────────────┘ │
└─────────────────────────────┘
```

- 组件：TDDropdownMenu/TDPicker（筛选器）+ fl_chart（图表）+ 汇总卡片 + 分类列表
- 图表类型：柱状图（趋势）+ 饼图（分类占比，可选）

---

## 5. 数据模型

### 5.1 模型总览

| 模型 | 字段数 | 状态 | 需补充 |
|------|--------|------|--------|
| ExpenseModel（报销单） | 22 | 缺3字段 | invoiceImages, paymentStatus, voucherNo |
| ExpenseDetailModel（报销明细） | 15 | ✅ 完善 | — |
| ExpenseApplicationModel（报销申请单） | 11 | 缺4字段 | estimatedStartDate, estimatedEndDate, urgency, projectId/Name, budgetSubjectId |
| ExpenseAppDetailModel（报销申请明细） | 5 | ✅ 基本够用 | — |
| OvertimeModel（加班申请单） | 16 | 缺3字段 | actualOtHours, clockInTime, clockOutTime, mealDeductHours |
| VehicleModel（用车申请单） | 19 | 缺4字段 | actualMileage, actualCost, startOdometer, endOdometer, returnTime, passengers[] |
| OutingLogModel（外出日志） | 30+ | ✅ 完善 | — |
| AnnouncementModel（公告） | 18 | ✅ 完善 | — |

共享模型：
- **ApprovalRecord**：审批记录（id, bizId, bizType, approverId/Name, approvalLevel, action, opinion, approvalTime）
- **ApprovalStatus**：枚举（draft/pending/approved/rejected/withdrawn）
- **PaginatedData\<T\>**：分页数据

### 5.2 待补充字段详情

**ExpenseModel 补充：**
```dart
List<String> invoiceImages;   // 发票/附件图片URL列表
String paymentStatus;         // 未付款/已付款/付款中
String voucherNo;             // 财务凭证号
```

**ExpenseApplicationModel 补充：**
```dart
DateTime? estimatedStartDate;  // 预计费用开始日期
DateTime? estimatedEndDate;    // 预计费用结束日期
String urgency;                // 普通/紧急/特急
String projectId;              // 关联项目ID
String projectName;            // 关联项目名称
String budgetSubjectId;        // 预算科目ID
```

**OvertimeModel 补充：**
```dart
double actualOtHours;          // 实际加班时长
DateTime? clockInTime;         // 上班打卡时间
DateTime? clockOutTime;        // 下班打卡时间
double mealDeductHours;        // 用餐扣除时长
```

**VehicleModel 补充：**
```dart
double actualMileage;          // 实际里程
double actualCost;             // 实际费用
double startOdometer;          // 起始里程表读数
double endOdometer;            // 结束里程表读数
DateTime? returnTime;          // 实际还车时间
List<String> passengers;       // 同行人员姓名列表
```

---

## 6. 用户角色与权限

### 6.1 角色定义

| 角色 | 权限范围 | 标识 |
|------|---------|------|
| 普通员工 | 发起申请、查看自己的数据、查看公告 | employee |
| 审批人（经理） | 审批下属申请 + 员工所有权限 | approver |
| 财务人员 | 全公司报销数据、确认付款、报表 | finance |
| 系统管理员 | 发布公告、全部数据、系统设置 | admin |

### 6.2 页面级权限对照

| 页面 | 员工 | 审批人 | 财务/管理员 |
|------|------|--------|------------|
| 工作台 | 我的申请统计 | +待我审批区块 | +全公司概览 |
| 列表页 | 自己的数据 | 下属+自己的 | 全部数据 |
| 详情页-按钮 | [编辑][撤回][删除] | [通过][拒绝] | [确认付款][关闭] |
| 报表 | 自己的统计 | 本部门 | 全公司 |
| 我的Tab | 我发起的+草稿 | +我审批的 | +我审批的 |

### 6.3 权限实现策略

| 层级 | 实现方 | 机制 |
|------|--------|------|
| 数据范围 | 后端 | API 根据 token 角色返回不同数据，前端不感知 |
| UI 可见性 | 前端 | 根据 `currentUser.role` 和单据状态条件渲染 |
| 报表筛选选项 | 混合 | 部门列表由后端返回可选范围，数据由后端按权限过滤 |

---

## 7. 报表筛选设计

### 7.1 公共维度
日期范围（起止日期）、部门、状态、申请人

### 7.2 各报表独有维度

| 报表 | 独有筛选维度 |
|------|------------|
| 报销明细表 | 报销类型、项目、预算科目、发票类型 |
| 报销申请明细表 | 申请类型、紧急程度、项目 |
| 加班明细表 | 加班类型、补偿方式 |
| 用车明细表 | 车辆类型、驾驶员、自驾/配驾 |

### 7.3 报表操作
重置筛选、应用筛选、数据导出（后端实现）

---

## 8. 技术架构

### 8.1 依赖清单

```yaml
# pubspec.yaml 核心依赖
tdesign_flutter: ^0.2.7     # TDesign UI 组件库（新增）
flutter_riverpod: ^2.6.1     # 状态管理
go_router: ^14.8.1           # 路由
dio: ^5.7.0                  # 网络请求
json_annotation: ^4.9.0      # JSON 序列化
intl: ^0.19.0                # 国际化/日期格式化
flutter_slidable: ^3.1.1     # 列表左滑操作
fl_chart: ^0.69.2             # 图表（报表用）
shimmer: ^3.0.0              # 骨架屏加载
```

### 8.2 目录结构

```
lib/
├── main.dart
├── app.dart                          # App入口 + Provider初始化
├── core/
│   ├── auth/auth_service.dart        # 认证（MethodChannel通信）
│   ├── network/
│   │   ├── api_client.dart           # Dio封装
│   │   ├── api_exception.dart
│   │   ├── api_response.dart
│   │   ├── mock_data.dart            # Mock数据
│   │   └── mock_interceptor.dart
│   ├── router/app_router.dart        # GoRouter配置（含Shell路由）
│   ├── theme/
│   │   ├── app_colors.dart           # 颜色常量
│   │   └── app_theme.dart            # TDesign + Material3主题
│   └── utils/
│       ├── date_utils.dart
│       ├── responsive.dart           # 横竖屏/宽屏适配
│       └── validators.dart
├── features/
│   ├── home/                         # 工作台
│   ├── messages/                     # 消息Tab（新增）
│   ├── profile/                      # 我的Tab（新增）
│   ├── expense/                      # 报销单
│   ├── expense_application/          # 报销申请单
│   ├── overtime/                     # 加班申请单
│   ├── vehicle/                      # 用车申请单
│   ├── outing_log/                   # 外出日志
│   ├── announcement/                 # 公告
│   └── report/                       # 报表
└── shared/
    ├── models/
    │   ├── approval_status.dart
    │   └── pagination_model.dart
    └── widgets/
        ├── app_card.dart
        ├── empty_state.dart
        ├── form_field_row.dart
        ├── form_section.dart
        ├── loading_widget.dart
        └── status_tag.dart
```

### 8.3 iOS 兼容性注意事项

- TDesign Flutter 0.2.7 基于纯 Dart + Flutter，不依赖 Swift
- 不使用任何 Swift-only 插件（如某些相机/定位插件可能有 Swift 依赖）
- MethodChannel 通信使用 OC 端调用
- `iosBundleIdentifier: com.amtxts.tbossOaModule` 已配置
- 执行 `cd ios && pod install` 后编译验证

---

## 9. 后端 API 接口规划（.NET Framework 4.8）

### 9.1 通用规范

- Base URL: `https://<host>/api`
- 认证: Bearer Token（Header: `Authorization: Bearer <token>`）
- 响应格式: `{ "code": 0, "message": "ok", "data": ... }`
- 分页: `{ "list": [], "page": 1, "size": 20, "total": 100 }`
- code=0 表示成功，其他值为业务错误码

### 9.2 接口列表

**认证**
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | 登录获取token |
| GET | /auth/current-user | 获取当前用户信息（含角色） |

**工作台**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /home/summary | 首页统计数据 |

**报销单**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /expense/list?status=&page=&size= | 报销单列表 |
| GET | /expense/detail/:id | 报销单详情 |
| POST | /expense/apply | 提交报销单 |
| PUT | /expense/draft | 保存草稿 |
| PUT | /expense/approve | 审批操作 |

**报销申请单**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /expense-apply/list | 列表 |
| GET | /expense-apply/detail/:id | 详情 |
| POST | /expense-apply/submit | 提交 |
| PUT | /expense-apply/draft | 草稿 |
| PUT | /expense-apply/approve | 审批 |

**加班申请单**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /overtime/list | 列表 |
| GET | /overtime/detail/:id | 详情 |
| POST | /overtime/apply | 提交 |
| PUT | /overtime/draft | 草稿 |
| PUT | /overtime/approve | 审批 |

**用车申请单**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /vehicle/list | 列表 |
| GET | /vehicle/detail/:id | 详情 |
| POST | /vehicle/apply | 提交 |
| PUT | /vehicle/draft | 草稿 |
| PUT | /vehicle/approve | 审批 |

**外出日志**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /outing-log/list | 列表 |
| GET | /outing-log/detail/:id | 详情 |
| POST | /outing-log/create | 创建 |

**公告**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /announcement/list | 列表 |
| GET | /announcement/detail/:id | 详情 |
| POST | /announcement/publish | 发布（管理员） |

**报表**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /report/expense-detail?startDate=&endDate=&... | 报销明细报表 |
| GET | /report/expense-apply-detail?... | 报销申请明细报表 |
| GET | /report/overtime-detail?... | 加班明细报表 |
| GET | /report/vehicle-detail?... | 用车明细报表 |

**消息**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /messages/list | 消息通知列表 |
| PUT | /messages/:id/read | 标记已读 |

---

## 10. 设计决策记录

| 决策 | 选择 | 理由 |
|------|------|------|
| 导航模式 | 3 Tab（消息/工作台/我的） | 参考钉钉，职责清晰 |
| 列表样式 | 卡片式 + 状态筛选 | 钉钉/企业微信标准，现有代码兼容 |
| 表单样式 | 分组表单 + 底部操作栏 | OA 行业惯例，FormSection 已有 |
| 详情页 | 双角色同页 | 减少页面数，审批流程内嵌 |
| 报表 | 筛选+汇总卡+图表+列表 | fl_chart 已引入 |
| 权限 | 后端控数据 + 前端控 UI | 安全 + 灵活 |
| TDesign 集成 | 替换主题 + 逐步替换组件 | 保持现有架构，渐进增强 |