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 补充：

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

ExpenseApplicationModel 补充：

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

OvertimeModel 补充：

double actualOtHours;          // 实际加班时长
DateTime? clockInTime;         // 上班打卡时间
DateTime? clockOutTime;        // 下班打卡时间
double mealDeductHours;        // 用餐扣除时长

VehicleModel 补充：

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 依赖清单

# 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 集成	替换主题 + 逐步替换组件	保持现有架构，渐进增强

2026-05-29-tboss-oa-design.md 18 KB Historia Raaka