API接口文档

编写人：刘洋

系统与版本：行政协同平台 V1.2

环境与日期：测试环境 0000-00-00

状态：已发布

一、接口概述

行政协同平台为员工在浏览器里办理会议室预订、请假、访客登记和用品申领提供统一接口，并为直属主管与行政同事提供审批和确认接口。本文登记 V1.2 在测试环境开放的 8 个接口，路径前缀为 /api/v1。刘洋于 9月8日冻结字段命名，陈静于 9月12日对照四个页面核对 28 个字段，差异为 0。周敏于 9月15日用行政账号抽查访客确认与用品扣减，返回结果与门岗登记簿、库存台账一致。

二、调用约定

请求体使用 UTF-8 编码的 JSON。完整日期写作 0000-00-00，时刻写作 00:00，时区为东八区。查询参数 page 从 1 起算，pageSize 默认 20、上限 50。写接口在请求头放置 Idempotency-Key，同一键在 10 分钟内重复提交只保留第一条成功记录，并返回原先的单据号。

1. 访问令牌放在 Authorization 头，格式为 Bearer 加令牌原文，有效期 2 小时。
2. 成功时 HTTP 状态为 200，且响应体 code 为 0。
3. 业务失败时 HTTP 状态多数仍为 200，调用方以 code 区分原因。
4. 网关为每次请求生成 requestId，调用方在排障材料中保留 7 天。

三、接口清单

下表为 V1.2 测试环境清单。已发布接口可供前端按字段联调，联调中接口仅对行政账号开放，待发布接口计划在 9月30日打开。

四、预订与请假

预订会议室时，员工提交 roomId、date、start、end 和 subject，subject 最长 40 个字。时段已被占用时返回业务码 40021，记录不入库，页面提示改选时间。9月18日张伟预订 3 楼东侧会议室 14:00 至 15:00，返回单据号 BK-0000-118，占用表与页面一致。同一幂等键再次提交，仍返回该单据号。

请假接口接收 type、startDate、endDate 和 reason。type 取年假、事假、病假三种，reason 为 10 至 200 字。提交后状态为处理中，并向直属主管发送待办。主管以 action 提交同意或驳回，驳回时 opinion 必填。9月19日陈静提交事假 1 天，张伟于 16:40 同意，状态在 26 分钟内变为已完成。

预订请求示例

五、访客与用品

访客登记由员工提交 visitorName、visitDate、company 和 purpose，purpose 为 8 至 80 字。登记后状态为待确认，由周敏在行政待办中确认。9月15日抽查 6 条，其中 5 条确认成功，1 条因来访日期早于当天返回业务码 40041。用品申领提交 skuId 与 quantity，quantity 为 1 至 5 的整数。库存足够时扣减并返回单据号，状态为已完成。

1. 9月16日张伟申领中性笔 2 支，库存由 46 支降至 44 支，单据号为 SP-0000-077。
2. 库存不足时返回业务码 40051，库存数量保持原值，页面展示剩余支数。
3. 周敏于 9月20日复核用品流水 4 笔，与库房台账差额为 0。

六、统一响应

响应体包含 code、message、data 和 requestId。code 为 0 时 message 为「成功」。40001 表示令牌缺失或过期，前端引导重新登录。40021 表示会议室时段冲突。40031 表示请假结束日期早于开始日期。40041 表示来访日期不在可登记范围。40051 表示用品库存不足。50000 表示服务内部错误，调用方记下 requestId 后由刘洋查日志。message 面向用户，页面可直接展示；服务端另记英文原因，供值班检索。

七、联调记录

1. 张伟于 9月18日完成预订、查询占用和我的申请三条链路，新增缺陷 0 条，平均响应 160 毫秒。
2. 陈静于 9月19日完成请假提交与审批，主路径 4 步全部通过，最慢一步为通知发送，耗时 1.2 秒。
3. 周敏于 9月20日完成访客确认 6 条、用品申领 4 条，库存与台账差额为 0。
4. 刘洋于每周三 18:00 至 18:30 重启测试环境，期间网关返回 503，前端展示维护提示约 30 分钟。

我的申请接口计划在 9月30日随前端列表页一并开放。刘洋在开放前 2 个工作日把最终路径和示例发给陈静，版本号由 V1.2 升至 V1.3。