TBOSS OA 模块 — API 接口文档

版本：v1.0 | 日期：2026-06-04 | Base URL：https://{host}/api

1. 通用规范

1.1 请求头

Content-Type: application/json
Authorization: Bearer {token}    ← 由宿主 App 注入
X-User-Id: {erpUserId}           ← 当前登录用户 ERP ID

1.2 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1717401600
}

1.3 分页响应

{
  "code": 0,
  "data": {
    "items": [ ... ],
    "total": 128,
    "page": 1,
    "pageSize": 20
  }
}

1.4 错误码

code	含义	处理方式
0	成功	—
400	参数校验失败	Toast 提示具体字段错误
401	未授权 / Token 过期	触发宿主重新登录
403	无 OA 操作权限	Toast "无此操作权限"
404	资源不存在	TDEmpty 或 Toast
409	并发冲突 (CONCURRENCY_CONFLICT / APPROVAL_CONFLICT)	TDDialog 提示刷新
422	业务校验失败	展示具体错误信息
500	服务器内部错误	Toast "服务器繁忙，请稍后重试"
504	ERP 审批接口超时	Toast "审批服务暂不可用，请稍后重试"

1.5 枚举值

所有状态/类型字段使用英文标识字符串，前端负责国际化映射。完整枚举取值见 tboss-oa-database.md 第 6 节。

2. OA 权限 API

2.1 获取权限点列表

GET /api/oa/permissions

响应：

{
  "code": 0,
  "data": {
    "permissions": [
      {
        "id": 1,
        "code": "oa.expense.apply",
        "name": "发起报销",
        "module": "expense",
        "sortOrder": 1
      },
      {
        "id": 2,
        "code": "oa.expense.view_own",
        "name": "查看自己的报销单",
        "module": "expense",
        "sortOrder": 2
      }
    ]
  }
}

2.2 获取用户权限

GET /api/oa/user-permissions?userId={erpUserId}

响应：

{
  "code": 0,
  "data": {
    "userId": 1001,
    "permissions": ["oa.expense.apply", "oa.expense.view_own", "oa.announcement.view"],
    "presetRoles": ["employee"]
  }
}

2.3 保存用户权限

PUT /api/oa/user-permissions

请求：

{
  "userId": 1001,
  "permissionCodes": [
    "oa.expense.apply",
    "oa.expense.view_dept",
    "oa.expense.approve",
    "oa.outing_log.comment"
  ]
}

响应：

{
  "code": 0,
  "message": "权限已更新"
}

错误： | code | 场景 | |------|------| | 403 | 无 oa.admin.permissions 权限 | | 422 | 试图移除自己的管理员权限 / 移除最后一名管理员 |

2.4 权限变更日志

GET /api/oa/permission-changelog?userId={erpUserId}&page=1&pageSize=20

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "targetUserId": 1001,
        "operatorId": 2001,
        "operatorName": "管理员王五",
        "changeType": "assign",
        "beforePermissions": ["oa.expense.apply", "oa.expense.view_own"],
        "afterPermissions": ["oa.expense.apply", "oa.expense.view_own", "oa.expense.approve"],
        "createTime": "2026-06-03T10:30:00"
      }
    ],
    "total": 5,
    "page": 1
  }
}

3. 业务单据 API

3.1 通用说明

{bizType} 取值：expense-apply | expense | overtime | vehicle

3.2 提交单据（新建 + 发起审批）

POST /api/oa/{bizType}/submit

事前申请

请求：

{
  "id": null,
  "urgency": "normal",
  "expenseTypes": "travel,office",
  "purpose": "北京客户拜访差旅费预估",
  "projectId": 100,
  "budgetSubjectId": 5,
  "isTaxIncluded": false,
  "validUntil": "2026-07-03",
  "referenceNo": "HT-2026-0089",
  "applicationDate": "2026-06-03",
  "estimatedStartDate": "2026-06-10",
  "estimatedEndDate": "2026-06-12",
  "isOvernight": true,
  "transportType": "high_speed_rail",
  "entertainmentTarget": null,
  "entertainmentLevel": null,
  "guestCount": null,
  "companionCount": null,
  "venue": null,
  "details": [
    {
      "expenseCategory": "transport",
      "quantity": 2,
      "unitPrice": 550.00,
      "unit": "张",
      "remark": "往返高铁票",
      "sortOrder": 1
    },
    {
      "expenseCategory": "hotel",
      "quantity": 2,
      "unitPrice": 400.00,
      "unit": "晚",
      "remark": "住宿",
      "sortOrder": 2
    }
  ],
  "attachments": [
    { "fileName": "出差审批截图.png", "fileUrl": "https://oss/...", "fileType": "image", "fileSize": 204800 }
  ]
}

费用类型联动字段：仅当 expenseTypes 含对应类型时前端展示并必填。travel 时需 estimatedStartDate/EndDate/isOvernight/transportType；entertainment 时需 entertainmentTarget/Level/guestCount/companionCount/venue（校验 companionCount ≤ guestCount）；meeting 时需 estimatedStartDate/EndDate/venue。数据库全部 NULL 允许，应用层按 expenseTypes 动态校验。

响应：

{
  "code": 0,
  "data": {
    "id": 12345,
    "applicationNo": "BXSQ-20260603-001",
    "approvalInstanceId": "inst_erp_a_009832",
    "previousInstanceIds": []
  }
}

费用报销

请求：

{
  "id": null,
  "applicationMappings": [
    { "applicationId": 12300, "importedAmount": 5500.00 }
  ],
  "purpose": "北京客户拜访差旅费报销",
  "projectId": 100,
  "budgetSubjectId": 5,
  "costCenterId": 10,
  "applicationDate": "2026-06-03",
  "bankName": "中国工商银行",
  "accountName": "张三",
  "bankAccount": "6222021234567890123",
  "details": [
    {
      "expenseDate": "2026-06-10",
      "expenseType": "transport",
      "expenseDesc": "G123 北京南-上海虹桥",
      "amount": 523.58,
      "taxAmount": 26.42,
      "currencyCode": "CNY",
      "exchangeRate": 1.0000,
      "invoiceNo": "12345678",
      "invoiceCode": "011001900111",
      "invoiceType": "special",
      "taxRate": 0.0900,
      "sortOrder": 1
    }
  ],
  "attachments": [
    { "fileName": "高铁票.jpg", "fileUrl": "https://oss/...", "fileType": "image", "fileSize": 307200, "detailIndex": 0 }
  ]
}

导入申请：applicationMappings 非必填，传入时项目/科目/成本中心自动从申请带入。直接新建时不传，需手动填写 projectId/budgetSubjectId。costCenterId 可选（ERP 无数据时不传）。currencyCode 默认 CNY，选外币时 exchangeRate 由服务端从 ERP 查询后填入，前端只传 currencyCode。totalAmount（价税合计）= amount + taxAmount 由服务端计算。baseAmount = totalAmount × exchangeRate 由服务端计算。

响应：

{
  "code": 0,
  "data": {
    "id": 12348,
    "reportNo": "BX-20260603-001",
    "approvalInstanceId": "inst_erp_a_009834",
    "previousInstanceIds": []
  }
}

加班申请

请求：

{
  "id": null,
  "otType": "workday",
  "compensationType": "overtime_pay",
  "compLeaveRatio": null,
  "startTime": "2026-06-03T18:00:00",
  "endTime": "2026-06-03T22:00:00",
  "reason": "紧急上线支持，需加班完成部署"
}

混合模式：compensationType=mixed 时 compLeaveRatio 必填，范围 0.10~0.90（步长 0.10），如 0.30 表示 30% 调休 + 70% 加班费。NetOtHours 由服务端自动扣除午休(12:00-13:00)和晚餐(18:00-18:30)盲区后计算。applicationDate 由服务端填写提交当日。

响应：

{
  "code": 0,
  "data": {
    "id": 12346,
    "applicationNo": "JB-20260603-001",
    "netOtHours": 3.5,
    "approvalInstanceId": "inst_erp_a_009833",
    "previousInstanceIds": []
  }
}

用车申请

请求：

{
  "id": null,
  "vehicleId": 3,
  "purpose": "business",
  "reason": "前往客户现场演示产品",
  "origin": "公司总部",
  "originLongitude": 121.473701,
  "originLatitude": 31.230416,
  "destination": "客户公司",
  "destLongitude": 121.510000,
  "destLatitude": 31.250000,
  "startTime": "2026-06-05T09:00:00",
  "endTime": "2026-06-05T17:00:00",
  "passengerCount": 3,
  "passengers": [
    { "userId": 1002, "passengerName": "李四" },
    { "userId": null, "passengerName": "客户代表" }
  ]
}

排期冲突检测：提交前应调 GET /api/oa/vehicle/check-collision 异步校验。冲突时前端锁死提交按钮。applicationDate 由服务端填写提交当日。

响应：同其他单据。

3.3 存草稿

PUT /api/oa/{bizType}/draft

请求体与提交相同，id 为已有草稿 ID（编辑已有草稿）或 null（新建草稿）。不触发审批。

响应：

{
  "code": 0,
  "data": { "id": 12347 }
}

3.4 列表查询

GET /api/oa/expense-apply/list?status=pending&page=1&pageSize=20
GET /api/oa/expense/list?status=all&page=1
GET /api/oa/overtime/list?status=approved&page=1
GET /api/oa/vehicle/list?status=all&page=1

参数：

参数	类型	必填	说明
status	string	否	审批单据：all / draft / pending / approved / rejected / withdrawn。报销额外：unpaid / paid。用车额外：returned
page	int	否	默认 1
pageSize	int	否	默认 20
scope	string	否	own(默认) / dept / all — 根据权限自动限定

响应（以报销列表为例）：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 100,
        "reportNo": "BX-20260603-001",
        "totalAmount": 1580.00,
        "purpose": "差旅费报销",
        "applicationDate": "2026-06-03",
        "status": "approved",
        "paymentStatus": "unpaid",
        "applicantName": "张三",
        "deptName": "销售部",
        "createTime": "2026-06-03T10:00:00"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20
  }
}

事前申请列表响应（增量字段）：

{
  "id": 200,
  "applicationNo": "BXSQ-20260603-001",
  "estimatedAmount": 1900.00,
  "purpose": "差旅费预估",
  "expenseTypes": "travel,office",
  "applicationDate": "2026-06-03",
  "status": "pending",
  "usageStatus": "unused",
  "applicantName": "张三",
  "deptName": "销售部",
  "createTime": "2026-06-03T09:00:00"
}

加班列表响应（增量字段）：

{
  "id": 300,
  "applicationNo": "JB-20260603-001",
  "otType": "workday",
  "netOtHours": 3.5,
  "compensationType": "overtime_pay",
  "compLeaveRatio": null,
  "reason": "紧急上线支持",
  "applicationDate": "2026-06-03",
  "status": "approved",
  "applicantName": "张三",
  "deptName": "销售部",
  "createTime": "2026-06-03T18:30:00"
}

用车列表响应（增量字段）：

{
  "id": 400,
  "applicationNo": "YC-20260603-001",
  "vehicleId": 3,
  "licensePlate": "粤B12345",
  "purpose": "business",
  "origin": "公司总部",
  "destination": "客户公司",
  "startTime": "2026-06-05T09:00:00",
  "status": "approved",
  "applicantName": "张三",
  "deptName": "销售部",
  "createTime": "2026-06-03T11:00:00"
}

3.5 详情查询

GET /api/oa/expense-apply/detail/12345
GET /api/oa/expense/detail/100
GET /api/oa/overtime/detail/12346
GET /api/oa/vehicle/detail/200

事前申请详情响应：

{
  "code": 0,
  "data": {
    "id": 12345,
    "applicationNo": "BXSQ-20260603-001",
    "applicantId": 1001,
    "applicantName": "张三",
    "deptId": 10,
    "deptName": "销售部",
    "applicationDate": "2026-06-03",
    "urgency": "normal",
    "expenseTypes": "travel,office",
    "purpose": "北京客户拜访差旅费预估",
    "projectId": 100,
    "projectName": "华东市场拓展",
    "budgetSubjectId": 5,
    "budgetSubjectName": "差旅费",
    "estimatedAmount": 1900.00,
    "isTaxIncluded": false,
    "validUntil": "2026-07-03",
    "referenceNo": "HT-2026-0089",
    "estimatedStartDate": "2026-06-10",
    "estimatedEndDate": "2026-06-12",
    "isOvernight": true,
    "transportType": "high_speed_rail",
    "entertainmentTarget": null,
    "entertainmentLevel": null,
    "guestCount": null,
    "companionCount": null,
    "venue": null,
    "status": "pending",
    "usageStatus": "unused",
    "approvalInstanceId": "inst_erp_a_009832",
    "previousInstanceIds": [],
    "details": [
      {
        "id": 600,
        "expenseCategory": "transport",
        "expenseCategoryName": "交通费",
        "quantity": 2,
        "unitPrice": 550.00,
        "unit": "张",
        "estimatedAmount": 1100.00,
        "remark": "往返高铁票",
        "sortOrder": 1
      },
      {
        "id": 601,
        "expenseCategory": "hotel",
        "expenseCategoryName": "住宿费",
        "quantity": 2,
        "unitPrice": 400.00,
        "unit": "晚",
        "estimatedAmount": 800.00,
        "remark": "住宿",
        "sortOrder": 2
      }
    ],
    "attachments": [
      { "id": 20, "fileName": "出差审批截图.png", "fileUrl": "https://oss/...", "fileType": "image", "fileSize": 204800 }
    ],
    "createTime": "2026-06-03T09:00:00",
    "updateTime": "2026-06-03T09:00:00"
  }
}

费用报销详情响应：

{
  "code": 0,
  "data": {
    "id": 100,
    "reportNo": "BX-20260603-001",
    "applicantId": 1001,
    "applicantName": "张三",
    "deptId": 10,
    "deptName": "销售部",
    "applicationDate": "2026-06-03",
    "projectId": 100,
    "projectName": "华东市场拓展",
    "budgetSubjectId": 5,
    "budgetSubjectName": "差旅费",
    "costCenterId": 10,
    "costCenterName": "销售部-华东区",
    "totalAmount": 1580.00,
    "purpose": "差旅费报销",
    "bankName": "中国工商银行",
    "accountName": "张三",
    "bankAccount": "6222021234567890123",
    "isInvoiceVerified": false,
    "isTaxIdMatched": false,
    "isCategoryCompliant": false,
    "bankTransferNo": null,
    "voucherNo": null,
    "status": "approved",
    "paymentStatus": "unpaid",
    "approvalInstanceId": "inst_erp_a_009832",
    "previousInstanceIds": [],
    "applicationMappings": [
      {
        "applicationId": 12300,
        "applicationNo": "BXSQ-20260520-003",
        "importedAmount": 5500.00
      }
    ],
    "details": [
      {
        "id": 500,
        "expenseDate": "2026-06-10",
        "expenseType": "transport",
        "expenseTypeName": "交通费",
        "expenseDesc": "G123 高铁票",
        "amount": 523.58,
        "taxAmount": 26.42,
        "totalAmount": 550.00,
        "currencyCode": "CNY",
        "exchangeRate": 1.0000,
        "baseAmount": 550.00,
        "invoiceNo": "12345678",
        "invoiceCode": "011001900111",
        "invoiceType": "special",
        "taxRate": 0.0900,
        "sortOrder": 1
      }
    ],
    "attachments": [
      { "id": 10, "fileName": "高铁票.jpg", "fileUrl": "https://oss/...", "fileType": "image", "fileSize": 307200, "detailId": 500 }
    ],
    "createTime": "2026-06-03T10:00:00",
    "updateTime": "2026-06-03T15:30:00"
  }
}

加班详情响应：

{
  "code": 0,
  "data": {
    "id": 12346,
    "applicationNo": "JB-20260603-001",
    "applicantId": 1001,
    "applicantName": "张三",
    "deptId": 10,
    "deptName": "销售部",
    "otType": "workday",
    "compensationType": "overtime_pay",
    "compLeaveRatio": null,
    "startTime": "2026-06-03T18:00:00",
    "endTime": "2026-06-03T22:00:00",
    "netOtHours": 3.5,
    "reason": "紧急上线支持，需加班完成部署",
    "status": "approved",
    "approvalInstanceId": "inst_erp_a_009833",
    "previousInstanceIds": [],
    "createTime": "2026-06-03T18:30:00",
    "updateTime": "2026-06-03T18:30:00"
  }
}

用车详情响应：

{
  "code": 0,
  "data": {
    "id": 200,
    "applicationNo": "YC-20260603-001",
    "applicantId": 1001,
    "applicantName": "张三",
    "deptId": 10,
    "deptName": "销售部",
    "vehicleId": 3,
    "licensePlate": "粤B12345",
    "vehicleType": "sedan",
    "brand": "丰田凯美瑞",
    "purpose": "business",
    "reason": "前往客户现场演示产品",
    "origin": "公司总部",
    "originLongitude": 121.473701,
    "originLatitude": 31.230416,
    "destination": "客户公司",
    "destLongitude": 121.510000,
    "destLatitude": 31.250000,
    "passengerCount": 3,
    "passengers": [
      { "userId": 1002, "passengerName": "李四" },
      { "userId": null, "passengerName": "客户代表" }
    ],
    "startTime": "2026-06-05T09:00:00",
    "endTime": "2026-06-05T17:00:00",
    "actualReturnTime": null,
    "startOdometer": null,
    "endOdometer": null,
    "actualCost": null,
    "costRemark": null,
    "status": "approved",
    "approvalInstanceId": "inst_erp_a_009835",
    "previousInstanceIds": [],
    "createTime": "2026-06-03T11:00:00",
    "updateTime": "2026-06-03T11:00:00"
  }
}

3.6 删除单据

DELETE /api/oa/expense/100
DELETE /api/oa/{bizType}/{id}

约束：仅 draft 状态可删除。软删除（IsDeleted=1）。

响应：

{ "code": 0, "message": "已删除" }

错误： | code | 场景 | |------|------| | 422 | 非 draft 状态不可删除 |

3.7 事前申请导入候选

GET /api/oa/expense-apply/import-candidates?applicantId=1001

说明：费用报销表单中"导入已通过的事前申请"的数据源。返回当前用户已通过且尚有可用额度（UsageStatus IN ('unused', 'partially_used')）的申请列表。

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 12300,
        "applicationNo": "BXSQ-20260520-003",
        "estimatedAmount": 10000.00,
        "usedAmount": 4500.00,
        "availableAmount": 5500.00,
        "expenseTypes": "travel",
        "purpose": "北京出差预估",
        "projectId": 100,
        "projectName": "华东市场拓展",
        "budgetSubjectId": 5,
        "budgetSubjectName": "差旅费"
      }
    ]
  }
}

3.8 用车排期冲突检测

GET /api/oa/vehicle/check-collision?vehicleId=3&startTime=2026-06-05T09:00:00&endTime=2026-06-05T17:00:00&excludeId=

参数：

参数	类型	必填	说明
vehicleId	long	✅	车牌 ID
startTime	datetime	✅	出车时间
endTime	datetime	✅	还车时间
excludeId	long	否	编辑已有申请时排除自身 ID

响应（无冲突）：

{ "code": 0, "data": { "hasCollision": false } }

响应（有冲突）：

{
  "code": 0,
  "data": {
    "hasCollision": true,
    "conflictApplicationNo": "YC-20260604-002",
    "conflictTimeRange": "2026-06-05 08:00 ~ 2026-06-05 12:00"
  }
}

3.9 还车登记

POST /api/oa/vehicle/200/return

权限：申请人本人。

请求：

{
  "actualReturnTime": "2026-06-05T16:30:00",
  "startOdometer": 45678.50,
  "endOdometer": 45712.30,
  "actualCost": 85.00,
  "costRemark": "停车费30元，高速通行费55元"
}

校验：

endOdometer ≥ startOdometer
仅 status=approved 可还车

响应：

{
  "code": 0,
  "data": {
    "status": "returned",
    "mileage": 33.80,
    "actualCost": 85.00
  }
}

后端操作：更新 Vehicle 表还车字段 → Status='returned' → 车辆恢复 SysVehicle.Status='idle'。

3.10 财务核销

PUT /api/oa/expense/100/write-off

权限：需要 oa.expense.mark_paid 权限。

请求：

{
  "isInvoiceVerified": true,
  "isTaxIdMatched": true,
  "isCategoryCompliant": true,
  "bankTransferNo": "BT20260603001",
  "voucherNo": "PZ-2026-0603-0015"
}

校验：

三项合规检查必须全部为 true
bankTransferNo 和 voucherNo 必填
仅 status=approved 且 paymentStatus=unpaid 可核销

响应：

{
  "code": 0,
  "data": {
    "paymentStatus": "paid",
    "message": "核销完成，已归档"
  }
}

错误： | code | 场景 | |------|------| | 422 | 合规检查未全部勾选 / 流水号或凭证号为空 | | 422 | 单据状态不满足核销条件 |

3.11 退回修改

POST /api/oa/expense/100/return-for-revision

权限：需要 oa.expense.mark_paid 权限。

请求：

{
  "returnTo": "applicant",
  "reason": "发票验真未通过，请核实后重新提交"
}

returnTo 取值：applicant（退回员工重填）/ approver（退回经理重审）。

响应：

{ "code": 0, "message": "已退回修改" }

4. 外勤日志 API

4.1 外勤日志列表

GET /api/oa/outing-log/list?status=all&page=1&pageSize=20

参数：

参数	类型	必填	说明
status	string	否	all / draft / completed
page	int	否	默认 1
pageSize	int	否	默认 20
scope	string	否	own(默认) / dept / all — 根据权限自动限定

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 300,
        "visitNo": "VST-20260603-001",
        "salespersonId": 1001,
        "salespersonName": "张三",
        "deptName": "销售部",
        "customerId": 5001,
        "customerName": "北京科技有限公司",
        "checkInAddress": "北京市朝阳区建国路88号",
        "visitSummary": "与客户CTO进行了产品演示...",
        "status": "completed",
        "hasNewComment": true,
        "createTime": "2026-06-03T14:00:00"
      }
    ],
    "total": 15,
    "page": 1,
    "pageSize": 20
  }
}

hasNewComment：Comment.CreateTime > COALESCE(LastViewedTime, '1900-01-01') 且评论者≠本人时为 true，前端展示橙色"新点评"标记。

4.2 外勤日志详情

GET /api/oa/outing-log/detail/300

响应：

{
  "code": 0,
  "data": {
    "id": 300,
    "visitNo": "VST-20260603-001",
    "salespersonId": 1001,
    "salespersonName": "张三",
    "deptId": 10,
    "deptName": "销售部",
    "customerId": 5001,
    "customerName": "北京科技有限公司",
    "contactId": 6001,
    "contactName": "王总",
    "checkInLongitude": 116.407526,
    "checkInLatitude": 39.904030,
    "checkInAddress": "北京市朝阳区建国路88号",
    "visitSummary": "与客户CTO进行了产品演示，讨论了定制化需求...",
    "nextPlan": "下周三前送出详细方案和报价",
    "status": "completed",
    "attachments": [
      { "id": 30, "fileName": "现场_20260603_143021.jpg", "fileUrl": "https://oss/...", "fileType": "sign_in_photo", "fileSize": 2048000, "sortOrder": 1 }
    ],
    "comments": [
      {
        "id": 400,
        "commenterId": 2001,
        "commenterName": "王经理",
        "ratingStars": 4,
        "commentText": "拜访记录详实，客户需求梳理清晰。建议补充技术方案的可行性分析。",
        "createTime": "2026-06-03T16:00:00"
      }
    ],
    "createTime": "2026-06-03T14:00:00",
    "updateTime": "2026-06-03T14:00:00"
  }
}

4.3 存草稿

PUT /api/oa/outing-log/draft

请求体与提交相同（见 §4.4），id 为已有草稿 ID 或 null。不校验 GPS 和照片。

响应：

{ "code": 0, "data": { "id": 301 } }

4.4 提交外勤日志

PUT /api/oa/outing-log/submit

请求：

{
  "id": null,
  "customerId": 5001,
  "customerName": "北京科技有限公司",
  "checkInLongitude": 116.407526,
  "checkInLatitude": 39.904030,
  "checkInAddress": "北京市朝阳区建国路88号",
  "visitSummary": "与客户CTO进行了产品演示，讨论了定制化需求...",
  "nextPlan": "下周三前送出详细方案和报价",
  "attachments": [
    { "fileName": "现场_20260603_143021.jpg", "fileUrl": "https://oss/...", "fileType": "sign_in_photo", "fileSize": 2048000 }
  ]
}

响应：

{
  "code": 0,
  "data": {
    "id": 300,
    "visitNo": "VST-20260603-001",
    "status": "completed"
  }
}

校验：

GPS 定位不能为空
至少 1 张现场照片
客户名为空时自动创建 ERP 客户

4.5 标记已查看

PUT /api/oa/outing-log/300/view

无请求体。更新 LastViewedTime = NOW()，使列表页"新点评"红点消失。

4.6 主管点评

POST /api/oa/outing-log/300/comment

请求：

{
  "ratingStars": 4,
  "commentText": "拜访记录详实，客户需求梳理清晰。建议补充技术方案的可行性分析。"
}

权限：需要 oa.outing_log.comment 权限。

响应：

{
  "code": 0,
  "data": {
    "id": 400,
    "commenterId": 2001,
    "commenterName": "王经理",
    "ratingStars": 4,
    "commentText": "拜访记录详实，客户需求梳理清晰。建议补充技术方案的可行性分析。",
    "createTime": "2026-06-03T16:00:00"
  }
}

4.7 删除外勤日志

DELETE /api/oa/outing-log/{id}

约束：仅 draft 状态可删除。软删除（IsDeleted=1）。级联软删除附件。

响应：

{ "code": 0, "message": "已删除" }

5. 审批代理 API

5.1 待审批列表

GET /api/oa/approval/pending?userId=2001&bizType=&page=1&pageSize=20

参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | userId | long | ✅ | 审批人 ERP 用户 ID | | bizType | string | 否 | 为空时返回所有类型 | | page | int | 否 | | | pageSize | int | 否 | |

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "bizType": "expense",
        "bizId": 100,
        "bizNo": "BX-20260603-001",
        "amount": 1580.00,
        "summary": "差旅费报销",
        "submitTime": "2026-06-03T10:00:00",
        "applicantId": 1001,
        "applicantName": "张三",
        "deptName": "销售部",
        "approvalLevel": 1
      },
      {
        "bizType": "overtime",
        "bizId": 12346,
        "bizNo": "JB-20260603-001",
        "amount": 3.5,
        "summary": "紧急上线支持",
        "submitTime": "2026-06-03T18:30:00",
        "applicantId": 1002,
        "applicantName": "李四",
        "deptName": "技术部",
        "approvalLevel": 2
      }
    ],
    "total": 8,
    "page": 1
  }
}

5.2 待审批数量

GET /api/oa/approval/pending-count?userId=2001

响应：

{ "code": 0, "data": { "count": 8 } }

5.3 审批时间线

GET /api/oa/approval/timeline?bizType=expense&bizId=100

响应：

{
  "code": 0,
  "data": {
    "bizType": "expense",
    "bizId": 100,
    "currentStatus": "pending",
    "currentApproverName": "王经理",
    "nodes": [
      {
        "level": 0,
        "action": "submit",
        "approverName": "张三",
        "opinion": null,
        "approvalTime": "2026-06-03T10:00:00",
        "isValid": true
      },
      {
        "level": 1,
        "action": "pending",
        "approverName": "王经理",
        "opinion": null,
        "approvalTime": null,
        "isValid": true
      }
    ]
  }
}

5.4 审批动作

POST /api/oa/approval/action

请求（同意）：

{
  "instanceId": "inst_erp_a_009832",
  "action": "approve",
  "opinion": "同意报销"
}

请求（拒绝）：

{
  "instanceId": "inst_erp_a_009832",
  "action": "reject",
  "opinion": "发票金额与申请金额不符，请核实后重新提交"
}

响应：

{
  "code": 0,
  "message": "审批成功",
  "data": { "newStatus": "approved" }
}

校验：

action=reject 时 opinion 必填且 ≥5 个汉字
action=transfer 时 transferToUserId 必填

5.5 撤回申请

POST /api/oa/approval/withdraw

请求：

{
  "bizType": "expense",
  "bizId": 100,
  "instanceId": "inst_erp_a_009832"
}

响应：

{ "code": 0, "message": "已撤回" }

后端操作：.NET 服务端调 ERP 撤回 → OA 更新 Status='withdrawn'，旧 ApprovalInstanceId 追加到 PreviousInstanceIds。

5.6 下属单据列表（经理版）

GET /api/oa/approval/subordinates?approverId=2001&bizType=expense&status=pending&page=1

响应：结构与列表查询相同，额外返回申请人姓名/部门。

6. 公告 API

6.1 公告列表

GET /api/oa/announcement/list?type=all&page=1&pageSize=20

参数：

参数	类型	必填	说明
type	string	否	all / notice / policy / activity。管理员额外支持 `draft`（我的草稿）
page	int	否	默认 1
pageSize	int	否	默认 20

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 50,
        "title": "关于2026年端午节放假安排的通知",
        "type": "activity",
        "status": "published",
        "publisherId": 2001,
        "publisherName": "管理员王五",
        "deptName": "行政部",
        "publishTime": "2026-06-03T14:00:00",
        "isTop": true,
        "isRead": false,
        "isExpired": false,
        "expiryDate": "2026-06-22T00:00:00"
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20
  }
}

排序：isTop 优先 → 未过期按 publishTime 倒序 → 已过期置灰垫底。isRead 来自 AnnouncementReadLog.IsRead，isExpired = expiryDate < NOW()。

6.2 公告详情

GET /api/oa/announcement/detail/50

响应：

{
  "code": 0,
  "data": {
    "id": 50,
    "title": "关于2026年端午节放假安排的通知",
    "content": "<h2>放假时间</h2><p>6月19日（周五）至6月21日（周日）...</p>",
    "type": "activity",
    "status": "published",
    "publisherId": 2001,
    "publisherName": "管理员王五",
    "deptName": "行政部",
    "publishTime": "2026-06-03T14:00:00",
    "isTop": true,
    "privateLevel": 0,
    "expiryDate": "2026-06-22T00:00:00",
    "isExpired": false,
    "attachments": [
      { "id": 40, "fileName": "放假安排.pdf", "fileUrl": "https://oss/...", "fileType": "pdf", "fileSize": 512000 }
    ],
    "createTime": "2026-06-03T13:00:00",
    "updateTime": "2026-06-03T14:00:00"
  }
}

6.3 存草稿

PUT /api/oa/announcement/draft

请求体与发布相同（见 §6.4），不校验必填项。Status='draft'，仅创建者和管理员可见。

响应：

{ "code": 0, "data": { "id": 51 } }

6.4 发布公告

POST /api/oa/announcement/publish

请求（新建发布）：

{
  "id": null,
  "title": "关于2026年端午节放假安排的通知",
  "content": "<h2>放假时间</h2><p>6月19日（周五）至6月21日（周日）...</p>",
  "type": "activity",
  "isTop": false,
  "expiryDate": "2026-06-22T00:00:00",
  "privateLevel": 0,
  "targets": []
}

请求（按部门发布）：

{
  "id": null,
  "title": "销售部Q2业绩考核通知",
  "content": "<p>...</p>",
  "type": "notice",
  "isTop": true,
  "privateLevel": 1,
  "targets": [
    { "targetType": "dept", "targetId": 10 }
  ]
}

请求（按指定用户发布）：

{
  "id": null,
  "title": "销售部Q3考核安排",
  "content": "<p>...</p>",
  "type": "notice",
  "isTop": false,
  "privateLevel": 2,
  "targets": [
    { "targetType": "user", "targetId": 1001 },
    { "targetType": "user", "targetId": 1002 }
  ]
}

响应：

{
  "code": 0,
  "data": {
    "id": 50,
    "status": "published",
    "publishTime": "2026-06-03T14:00:00",
    "targetCount": 156
  }
}

后端操作：发布时异步初始化 AnnouncementReadLog（IsRead=0）。

6.5 标记已读

POST /api/oa/announcement/50/read

无请求体。停留 ≥2s 时调用。无权限要求。

6.6 DING 催办

POST /api/oa/announcement/50/ding

权限：需要 oa.announcement.manage 权限。

响应：

{
  "code": 0,
  "data": { "urgedCount": 5 }
}

后端操作：查 AnnouncementReadLog WHERE IsRead=0 → 更新 IsUrged=1 → 调消息模块推送。

6.7 已读/未读统计

GET /api/oa/announcement/read-stats/50

响应：

{
  "code": 0,
  "data": {
    "readCount": 45,
    "unreadCount": 5,
    "readUsers": [
      { "userId": 1001, "userName": "张三", "deptName": "销售部", "readTime": "2026-06-03T14:05:00" }
    ],
    "unreadUsers": [
      { "userId": 1005, "userName": "赵六", "deptName": "技术部" }
    ]
  }
}

7. 报表 API

7.1 通用格式

GET /api/oa/report/{type}?range=month&startDate=2026-06-01&endDate=2026-06-30&userId={erpUserId}&deptId={deptId}

通用参数：

参数	类型	必填	说明
range	string	否	month / quarter / year。与 startDate+endDate 互斥，优先使用自定义日期
startDate	string	否	自定义开始日期 YYYY-MM-DD
endDate	string	否	自定义结束日期 YYYY-MM-DD
userId	long	否	个人报表时传入；部门/全公司报表时不传
deptId	long	否	部门报表时传入
scope	string	否	own(默认) / dept / all — 根据角色权限自动限定

type 取值：expense-apply | expense | overtime | vehicle | outing-log

数据来源：数值卡片和图表均来自 OA 本地业务表，.NET 按角色权限 + 时间范围聚合。审批状态统计通过 ERP 实时查询补充。预置时间段（month/quarter/year）缓存 5 分钟，自定义日期实时查询。

通用响应结构：

{
  "code": 0,
  "data": {
    "cards": { ... },
    "chart": { ... },
    "memberBreakdown": [ ... ],
    "detailList": {
      "items": [ ... ],
      "total": 0,
      "page": 1
    }
  }
}

memberBreakdown 仅经理角色返回（部门横向对比柱状图数据）。detailList 仅经理/财务/管理员返回（底部明细列表，分页）。

7.2 事前申请明细报表

GET /api/oa/report/expense-apply?range=year&userId=1001

专属参数：

参数	类型	必填	说明
status	string	否	all / approved / rejected / withdrawn

响应：

{
  "code": 0,
  "data": {
    "cards": {
      "yearTotalAmount": 28500.00,
      "monthCount": 3,
      "approvedCount": 2,
      "approvedAmount": 15000.00
    },
    "chart": {
      "labels": ["2025-07", "2025-08", "...", "2026-06"],
      "appliedAmounts": [1200, 3400, 0, 0, 5600, 2300, 4500, 1800, 2900, 0, 3800, 2000],
      "approvedAmounts": [1200, 3000, 0, 0, 0, 2300, 4000, 1800, 2900, 0, 3800, 2000]
    },
    "memberBreakdown": [
      { "userId": 1001, "userName": "张三", "appliedAmount": 15000.00, "approvedAmount": 12000.00 },
      { "userId": 1002, "userName": "李四", "appliedAmount": 8000.00, "approvedAmount": 8000.00 }
    ],
    "detailList": {
      "items": [
        {
          "id": 12345,
          "applicationNo": "BXSQ-20260603-001",
          "applicantName": "张三",
          "deptName": "销售部",
          "estimatedAmount": 1900.00,
          "expenseTypes": "travel,office",
          "status": "pending",
          "createTime": "2026-06-03T09:00:00"
        }
      ],
      "total": 42,
      "page": 1
    }
  }
}

7.3 费用报销明细报表

GET /api/oa/report/expense?range=year&userId=1001

专属参数：

参数	类型	必填	说明
status	string	否	all / approved / rejected
paymentStatus	string	否	all / unpaid / paid

响应：

{
  "code": 0,
  "data": {
    "cards": {
      "yearTotalPaid": 28500.00,
      "monthCount": 3,
      "pendingCount": 1,
      "approvedUnpaidCount": 2
    },
    "chart": {
      "labels": ["2025-07", "2025-08", "...", "2026-06"],
      "appliedAmounts": [1200, 3400, 0, 0, 5600, 2300, 4500, 1800, 2900, 0, 3800, 2000],
      "approvedAmounts": [1200, 3000, 0, 0, 5600, 2300, 4000, 1800, 2900, 0, 3800, 2000]
    },
    "memberBreakdown": [
      { "userId": 1001, "userName": "张三", "appliedAmount": 12000.00, "approvedAmount": 12000.00 }
    ],
    "detailList": {
      "items": [ { "id": 100, "reportNo": "BX-20260603-001", "...": "..." } ],
      "total": 42,
      "page": 1
    }
  }
}

7.4 加班明细报表

GET /api/oa/report/overtime?range=year&deptId=10

专属参数：

参数	类型	必填	说明
otType	string	否	all / workday / weekend / holiday

响应：

{
  "code": 0,
  "data": {
    "cards": {
      "monthTotalHours": 42.5,
      "monthCount": 8,
      "compLeaveHours": 24.0,
      "overtimePayCount": 3
    },
    "chart": {
      "labels": ["2025-07", "...", "2026-06"],
      "workdayHours": [10, 8, 12, 5, 0, 8, 15, 6, 0, 10, 4, 8],
      "weekendHours": [5, 0, 8, 0, 0, 0, 0, 4, 0, 0, 8, 0],
      "holidayHours": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "memberBreakdown": [
      { "userId": 1001, "userName": "张三", "totalHours": 18.5 },
      { "userId": 1002, "userName": "李四", "totalHours": 24.0 }
    ],
    "detailList": {
      "items": [ { "id": 12346, "applicationNo": "JB-20260603-001", "...": "..." } ],
      "total": 15,
      "page": 1
    }
  }
}

7.5 用车明细报表

GET /api/oa/report/vehicle?range=year&deptId=10

专属参数：

参数	类型	必填	说明
vehicleId	long	否	按车牌筛选
purpose	string	否	all / reception / business / official

响应：

{
  "code": 0,
  "data": {
    "cards": {
      "monthCount": 5,
      "totalMileage": 1250.80,
      "tollParkingCost": 385.00,
      "unreturnedCount": 1
    },
    "chart": {
      "labels": ["2025-07", "...", "2026-06"],
      "tripCounts": [3, 2, 5, 1, 4, 2, 6, 3, 0, 2, 5, 4],
      "costs": [120, 80, 250, 50, 180, 90, 300, 150, 0, 100, 220, 180]
    },
    "memberBreakdown": [
      { "userId": 1001, "userName": "张三", "tripCount": 8, "totalCost": 450.00 }
    ],
    "detailList": {
      "items": [ { "id": 200, "applicationNo": "YC-20260603-001", "...": "..." } ],
      "total": 25,
      "page": 1
    }
  }
}

7.6 外勤日志明细报表

GET /api/oa/report/outing-log?range=year&deptId=10

专属参数：

参数	类型	必填	说明
customerName	string	否	客户名模糊搜索

响应：

{
  "code": 0,
  "data": {
    "cards": {
      "monthVisitCount": 12,
      "uniqueCustomerCount": 8,
      "avgRatingStars": 4.2,
      "uncommentedCount": 3
    },
    "chart": {
      "labels": ["2025-07", "...", "2026-06"],
      "visitCounts": [5, 8, 12, 6, 10, 7, 15, 9, 4, 11, 8, 12],
      "avgRatings": [4.0, 4.5, 3.8, 4.2, 4.0, 4.3, 3.9, 4.5, 4.0, 4.1, 4.2, 4.2]
    },
    "memberBreakdown": [
      { "userId": 1001, "userName": "张三", "visitCount": 25, "avgRating": 4.0 }
    ],
    "detailList": {
      "items": [ { "id": 300, "visitNo": "VST-20260603-001", "...": "..." } ],
      "total": 80,
      "page": 1
    }
  }
}

7.7 导出 Excel

POST /api/oa/report/{type}/export

权限：需要 oa.report.export 权限（财务/管理员角色）。

请求：

{
  "range": "quarter",
  "startDate": "2026-04-01",
  "endDate": "2026-06-30",
  "deptId": 10,
  "status": "all",
  "paymentStatus": "all"
}

参数与对应报表查询接口一致。range 与 startDate+endDate 互斥。

响应：Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，二进制文件流。Flutter 收到后通过 MethodChannel 唤起系统分享面板。

8. 工作台 API

8.1 工作台汇总数据

GET /api/oa/home/summary

说明：工作台首页的快捷看板数据。根据当前用户 OA 权限自动判定角色，返回对应数据范围（本人/本部门/全公司）。

权限：登录即可访问，数据范围按角色自动限定。

响应（员工版）：

{
  "code": 0,
  "data": {
    "role": "employee",
    "banners": [
      { "id": 1, "imageUrl": "https://oss/...", "title": "Q2优秀员工表彰", "linkUrl": "tboss://oa/announcement/detail/50", "sortOrder": 1 }
    ],
    "cards": {
      "monthTotalPaid": 28500.00,
      "monthSubmitCount": 5
    }
  }
}

响应（经理版）：

{
  "code": 0,
  "data": {
    "role": "manager",
    "banners": [ "..." ],
    "pendingApprovalCount": 8,
    "cards": {
      "monthTotalPaid": 128500.00,
      "monthSubmitCount": 42,
      "deptPendingCount": 8
    }
  }
}

响应（财务/管理员版）：

{
  "code": 0,
  "data": {
    "role": "finance",
    "banners": [ "..." ],
    "cards": {
      "monthTotalPaid": 525000.00,
      "unpaidTotal": 185000.00,
      "weekRejectedCount": 3
    }
  }
}

数据缓存 5 分钟。管理员版额外在金刚区展示"发布公告"入口（由前端根据 role 或权限判断）。员工/经理/财务/管理员角色判定优先级见 PRD §3.2。

9. ERP 集成 API（.NET 服务端转发）

9.1 预算查询

GET /api/oa/budget/balance?projectId=100&subjectId=5

响应：

{ "code": 0, "data": { "hasBudget": true, "availableAmount": 150000.00, "frozenAmount": 20000.00 } }

ERP 无预算时返回 { "hasBudget": false }，OA 前端隐藏预算区块。

9.2 项目/科目/成本中心

GET /api/oa/projects              # 项目列表
GET /api/oa/subjects?projectId=   # 某项目下的预算科目
GET /api/oa/cost-centers          # 成本中心列表

9.3 汇率查询

GET /api/oa/exchange-rate?currencyCode=USD

响应：

{ "code": 0, "data": { "currencyCode": "USD", "rate": 7.2456, "date": "2026-06-03" } }

10. 基础数据 API

10.1 费用类别字典

GET /api/oa/cost-categories?bizScope=both&expenseType=travel

参数：

参数	类型	必填	说明
bizScope	string	否	expense_apply / expense / both（默认 both）
expenseType	string	否	按费用大类过滤（travel/entertainment/office 等），不传返回全部

说明：事前申请和费用报销表单中"费用类别"下拉的数据源。返回启用的叶子节点（ParentId IS NOT NULL），ExpenseType 用于联动过滤（如事前申请选了"差旅费"大类，则仅返回绑定了 travel 的费用小类）。

响应：

{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": 10,
        "categoryName": "交通费",
        "categoryCode": "transport",
        "parentId": 1,
        "expenseType": "travel",
        "sortOrder": 1
      },
      {
        "id": 11,
        "categoryName": "住宿费",
        "categoryCode": "hotel",
        "parentId": 1,
        "expenseType": "travel",
        "sortOrder": 2
      },
      {
        "id": 20,
        "categoryName": "办公用品",
        "categoryCode": "office_supplies",
        "parentId": 5,
        "expenseType": "office",
        "sortOrder": 1
      }
    ]
  }
}

10.2 车辆管理

GET    /api/oa/vehicles              # 列表
POST   /api/oa/vehicles              # 添加
PUT    /api/oa/vehicles/3            # 修改

GET 响应：

{
  "code": 0,
  "data": {
    "vehicles": [
      {
        "id": 1,
        "licensePlate": "粤B12345",
        "vehicleType": "sedan",
        "brand": "丰田凯美瑞",
        "seats": 5,
        "driverName": "陈司机",
        "status": "idle",
        "isActive": true
      }
    ]
  }
}

10.3 轮播图

GET /api/oa/banners

响应：

{
  "code": 0,
  "data": {
    "banners": [
      {
        "id": 1,
        "imageUrl": "https://oss/...",
        "title": "2026年Q2优秀员工表彰",
        "linkUrl": "tboss://oa/announcement/detail/50",
        "sortOrder": 1
      }
    ]
  }
}

10.4 文件上传

POST /api/oa/upload
Content-Type: multipart/form-data

说明：统一文件上传端点。文件上传至云端对象存储（OSS），返回绝对 URL。前端拿到 URL 后在提交表单时写入 attachments 数组。

参数：

字段	类型	必填	说明
file	file	✅	文件本体
bizType	string	✅	expense_apply / expense / outing_log / announcement

校验：

bizType	数量限制	类型限制	大小限制
expense_apply	≤9	图片/PDF	图片≤10MB, PDF≤20MB
expense	≤9	图片	≤10MB
outing_log	1~9	仅图片	≤10MB
announcement	≤5	PDF/图片/Word/Excel	≤20MB

数量限制由前端在上传入口处控制（满额隐藏上传按钮），后端做二次校验。

响应：

{
  "code": 0,
  "data": {
    "fileUrl": "https://oss.example.com/oa/2026/06/abc123.jpg",
    "fileName": "现场_20260603_143021.jpg",
    "fileType": "image",
    "fileSize": 2048000
  }
}

错误： | code | 场景 | |------|------| | 422 | 文件大小超限 / 类型不支持 / 数量超限 |

11. 复用已有 API（参考）

以下 API 为 .NET 服务端已有，OA 模块直接调用。此处仅列接口签名，详细文档见原系统。

方法	URL	说明	关键参数
GET	`/api/user/{id}`	用户信息	id: ERP 用户 ID
GET	`/api/user/search?q=&page=`	用户搜索	q: 姓名/工号
GET	`/api/dept/tree`	部门树	—
PUT	`/api/user/avatar`	上传头像	multipart/form-data
GET	`/api/customer/search?q=`	客户联想	q: 客户名称
GET	`/api/messages?page=`	消息列表	page
GET	`/api/messages/unread-count`	未读消息数	—
PUT	`/api/messages/:id/read`	标记已读	id
POST	`/api/messages/read-all`	全部已读	—
DELETE	`/api/messages/:id`	删除消息	id
GET	`/api/dict/banks`	银行列表	—
GET	`/api/dict/cost-categories`	费用类别	—

文档版本：v1.0 | 日期：2026-06-04

tboss-oa-api.md 45 KB Historie Surový

TBOSS OA 模块 — API 接口文档

1. 通用规范

1.1 请求头

1.2 统一响应格式

1.3 分页响应

1.4 错误码

1.5 枚举值

2. OA 权限 API

2.1 获取权限点列表

2.2 获取用户权限

2.3 保存用户权限

2.4 权限变更日志

3. 业务单据 API

3.1 通用说明

3.2 提交单据（新建 + 发起审批）

事前申请

费用报销

加班申请

用车申请

3.3 存草稿

3.4 列表查询

3.5 详情查询

3.6 删除单据

3.7 事前申请导入候选

3.8 用车排期冲突检测

3.9 还车登记

3.10 财务核销

3.11 退回修改

4. 外勤日志 API

4.1 外勤日志列表

4.2 外勤日志详情

4.3 存草稿

4.4 提交外勤日志

4.5 标记已查看

4.6 主管点评

4.7 删除外勤日志

5. 审批代理 API

5.1 待审批列表

5.2 待审批数量

5.3 审批时间线

5.4 审批动作

5.5 撤回申请

5.6 下属单据列表（经理版）

6. 公告 API

6.1 公告列表

6.2 公告详情

6.3 存草稿

6.4 发布公告

6.5 标记已读

6.6 DING 催办

6.7 已读/未读统计

7. 报表 API

7.1 通用格式

7.2 事前申请明细报表

7.3 费用报销明细报表

7.4 加班明细报表

7.5 用车明细报表

7.6 外勤日志明细报表

7.7 导出 Excel

8. 工作台 API

8.1 工作台汇总数据

9. ERP 集成 API（.NET 服务端转发）

9.1 预算查询

9.2 项目/科目/成本中心

9.3 汇率查询

10. 基础数据 API

10.1 费用类别字典

10.2 车辆管理

10.3 轮播图

10.4 文件上传

11. 复用已有 API（参考）

tboss-oa-api.md 45 KB

Historie Surový