# 供电所业务接口目录

本目录是接口文档的唯一维护入口，每个HTTP方法与路径分别维护一份Markdown。文档与接口代码同时更新，以需求规格确认书V2.4.1为业务依据。

测试API服务：`https://gdsapi-test.xinyilife.cn`；业务接口前缀`/api/v1`，设备接口按各文档使用`/device/v1`。在线文档入口：`https://gdsapi-test.xinyilife.cn/apidocs/`。

浏览器打开后端服务的 `/apidocs/` 阅读。所有文件随Java应用打包，阅读不依赖公网CDN；也可直接访问 `/apidocs/index.md` 获取Markdown原文。

## 通用约定

- 业务路径前缀：`/api/v1`；设备路径前缀：`/device/v1`。
- 业务会话连续30分钟没有有效用户请求即失效，同时保留8小时绝对期限。自动同步请求携带 `X-PS-Background: 1`，不刷新活动时间。
- 除健康检查和认证入口外，请求携带 `Authorization: Bearer <token>`。
- 写操作提交JSON对象，`Content-Type: application/json`；最大请求体128KiB。
- 响应为 `{"code":0,"message":"ok","data":{}}`，具体message以实际接口为准。错误同时使用HTTP状态码：401未登录、403权限不足、404记录不可访问、409版本或状态冲突、422参数错误、503外部服务尚未接入。
- 所属供电所和角色权限由服务端校验；页面菜单可见不代表具备写权限。
- 库存数量最多三位小数；更新须携带当前版本。审批记账遵循需求确认书，App差异由前端适配。
- 外部认证、文件平台、视频、集团数据和知识问答尚待联调，不以示例数据代表接通。

## 2026-10-29 统一登录

- [统一登录流程、登录态及前端接线说明](group-sso-guide.md)
- [GET /api/v1/auth/group/callback — 接收门户gk-token](get-auth-group-callback.md)
- [POST /api/v1/auth/group/exchange — 一次性交接并建立登录态](post-auth-group-exchange.md)
- [POST /api/v1/auth/group — 校验集团Token并建立登录态](post-auth-group.md)

## 2.4.0补充接口

- [GET /device/v1/types — 查询实际设备类型树](get-device-types.md)
- [POST /device/v1/types — 新增设备类型](post-device-type.md)
- [PUT /device/v1/types/{id} — 修改设备类型](put-device-type.md)
- [GET /device/v1/devices — 查询实际设备台账与统计](get-devices.md)
- [POST /device/v1/devices — 登记实际设备](post-device.md)
- [GET /device/v1/devices/{id} — 读取设备台账](get-device.md)
- [PUT /device/v1/devices/{id} — 编辑设备台账](put-device.md)
- [GET /device/v1/devices/{id}/runtime — 查询设备实时数据](get-device-runtime.md)
- [POST /api/v1/workorders/batch_actions — 批量办理工单](post-workorders-batch-actions.md)
- [POST /api/v1/people/status — 批量启用或停用人员](post-people-status.md)
- [GET /api/v1/workorder_templates/dictionaries — 读取模板可关联字典](get-workorder-template-dictionaries.md)
- [GET /api/v1/reports/{id}/revision — 检查报表协作版本](get-report-revision.md)
- [POST /api/v1/reports/{id}/edits — 提交报表协作修改](post-report-edits.md)
- [POST /api/v1/reports/calculate — 计算表格公式预览](post-report-calculate.md)

## 接口列表

以下为当前已实现接口；测试范围以阶段验收报告为准，外部预留入口不可视为已接通。

- [GET /api/v1/report_folders — 查询报表目录](get-report-folders.md)
- [POST /api/v1/report_folders — 新增报表目录](post-report-folder.md)
- [PUT /api/v1/report_folders/{id} — 修改报表目录](put-report-folder.md)
- [GET /api/v1/reports — 查询报表与概览](get-reports.md)
- [GET /api/v1/reports/{id} — 读取报表与协作动态](get-report.md)
- [POST /api/v1/reports — 创建报表](post-report.md)
- [PUT /api/v1/reports/{id} — 保存报表内容](put-report.md)
- [PUT /api/v1/reports/{id}/collaborators — 设置报表协作者](put-report-collaborators.md)
- [POST /api/v1/reports/archive — 批量归档报表](post-reports-archive.md)
- [POST /api/v1/reports/import — 批量导入结构化报表](post-reports-import.md)
- [GET /api/v1/reports/export — 批量导出报表](get-reports-export.md)
- [GET /api/v1/roles — 查询角色列表](get-roles.md)
- [GET /api/v1/roles/permissions — 读取菜单页面按钮权限树](get-role-permissions.md)
- [GET /api/v1/roles/{id} — 读取角色授权详情](get-role.md)
- [POST /api/v1/roles — 新增自定义角色](post-role.md)
- [PUT /api/v1/roles/{id} — 修改角色权限及范围](put-role.md)
- [PUT /api/v1/roles/{id}/people — 替换角色已授权人员](put-role-people.md)
- [GET /api/v1/health — 业务服务健康检查](get-health.md)
- [GET /api/v1/auth/options — 查询本机测试身份](get-auth-options.md)
- [POST /api/v1/auth/local — 本机测试登录](post-auth-local.md)
- [POST /api/v1/auth/group — 集团Token验证与本系统会话](post-auth-group.md)
- [GET /api/v1/auth/me — 读取当前身份](get-auth-me.md)
- [POST /api/v1/auth/logout — 退出当前会话](post-auth-logout.md)
- [GET /api/v1/lookups — 读取基础选择项](get-lookups.md)
- [GET /api/v1/dashboard — 业务概览](get-dashboard.md)
- [GET /api/v1/stations — 查询供电所列表](get-stations.md)
- [POST /api/v1/stations — 新增供电所](post-stations.md)
- [PUT /api/v1/stations/{id} — 修改供电所](put-stations-id.md)
- [GET /api/v1/areas — 查询台区列表](get-areas.md)
- [POST /api/v1/areas — 新增台区](post-areas.md)
- [PUT /api/v1/areas/{id} — 修改台区](put-areas-id.md)
- [GET /api/v1/materials — 查询物资档案列表](get-materials.md)
- [POST /api/v1/materials — 新增物资档案](post-materials.md)
- [PUT /api/v1/materials/{id} — 修改物资档案](put-materials-id.md)
- [GET /api/v1/knowledge — 查询知识列表及学习状态](get-knowledge.md)
- [POST /api/v1/knowledge — 新增知识条目](post-knowledge.md)
- [PUT /api/v1/knowledge/{id} — 修改知识条目](put-knowledge-id.md)
- [GET /api/v1/feedback — 查询问题反馈列表](get-feedback.md)
- [POST /api/v1/feedback — 新增问题反馈](post-feedback.md)
- [PUT /api/v1/feedback/{id} — 修改问题反馈](put-feedback-id.md)
- [GET /api/v1/workorders — 查询工单与待办](get-workorders.md)
- [POST /api/v1/workorders — 创建人工或模板工单](post-workorders.md)
- [GET /api/v1/workorders/{id} — 读取工单与审批快照](get-workorders-id.md)
- [POST /api/v1/workorders/{id}/actions — 办理工单](post-workorders-actions.md)
- [GET /api/v1/materials/{id} — 物资详情](get-materials-id.md)
- [GET /api/v1/materials/{id}/ledger — 库存流水](get-materials-ledger.md)
- [GET /api/v1/stock_documents — 兼容单行出入库单列表](get-stock-documents.md)
- [GET /api/v1/stock_documents/{id} — 兼容单行单据详情](get-stock-documents-id.md)
- [POST /api/v1/stock_documents — 兼容单行出入库申请](post-stock-documents.md)
- [POST /api/v1/stock_documents/{id}/review — 兼容单行单据审核](post-stock-documents-review.md)
- [GET /api/v1/audit_logs — 审计日志组合查询](get-audit-logs.md)
- [GET /api/v1/audit_logs/export — 导出审计日志](get-audit-export.md)
- [GET /api/v1/audit_logs/months — 审计日志按月归档目录](get-audit-months.md)
- [GET /device/v1/health — 设备应用健康检查](get-device-health.md)
- [GET /device/v1/catalog — 硬件对接计划与状态](get-device-catalog.md)
- [GET /api/v1/warehouses — 查询库房](get-warehouses.md)
- [POST /api/v1/warehouses — 创建库房](post-warehouses.md)
- [PUT /api/v1/warehouses/{id} — 更新库房](put-warehouses-id.md)
- [GET /api/v1/material_categories — 查询物资分类](get-material-categories.md)
- [POST /api/v1/material_categories — 创建物资分类](post-material-categories.md)
- [PUT /api/v1/material_categories/{id} — 更新物资分类](put-material-categories-id.md)
- [GET /api/v1/material_tags — 查询RFID标签](get-material-tags.md)
- [POST /api/v1/material_tags — 创建RFID标签](post-material-tags.md)
- [PUT /api/v1/material_tags/{id} — 更新RFID标签](put-material-tags-id.md)
- [GET /api/v1/materials/{id}/settings — 读取物资设置](get-materials-settings.md)
- [PUT /api/v1/materials/{id}/settings — 更新分类与库存阈值](put-materials-settings.md)
- [GET /api/v1/materials/alerts — 库存与到期预警](get-materials-alerts.md)
- [GET /api/v1/materials/overview — 物资总览](get-materials-overview.md)
- [GET /api/v1/inventory_documents — 多明细物资单列表](get-inventory-documents.md)
- [GET /api/v1/inventory_documents/{id} — 多明细物资单详情](get-inventory-documents-id.md)
- [POST /api/v1/inventory_documents — 创建多明细物资业务单](post-inventory-documents.md)
- [POST /api/v1/inventory_documents/{id}/actions — 审核、调拨确认与盘点](post-inventory-documents-actions.md)
- [GET /api/v1/inventory_documents/export — 导出物资单据列表](get-inventory-documents-export.md)
- [GET /api/v1/inventory_documents/{id}/export — 导出物资明细与盘点报告](get-inventory-documents-detail-export.md)
- [GET /api/v1/code_rules — 读取编码规则与预览](get-code-rules.md)
- [PUT /api/v1/code_rules/{kind} — 修改全局编码规则](put-code-rules.md)
- [GET /api/v1/consumable_usages — 查询小件物资出库登记](get-consumable-usages.md)
- [POST /api/v1/consumable_usages — 登记小件物资出库](post-consumable-usages.md)
- [GET /api/v1/notifications — 读取本人站内通知](get-notifications.md)
- [POST /api/v1/notifications/{id}/read — 标记通知已读](post-notifications-read.md)
- [POST /api/v1/notifications/refresh — 立即检查物资预警](post-notifications-refresh.md)
- [GET /api/v1/organizations — 组织机构树](get-organizations.md)
- [POST /api/v1/organizations — 新增组织机构](post-organizations.md)
- [PUT /api/v1/organizations/{id} — 修改组织机构](put-organizations.md)
- [GET /api/v1/people — 人员档案列表](get-people.md)
- [POST /api/v1/people — 新增人员业务映射](post-people.md)
- [PUT /api/v1/people/{id} — 更新人员档案与状态](put-people.md)
- [GET /api/v1/knowledge/{id} — 读取知识详情与个人学习状态](get-knowledge-detail.md)
- [GET /api/v1/knowledge/summary — 个人知识学习统计](get-knowledge-summary.md)
- [POST /api/v1/knowledge/{id}/learn — 标记当前版本已学习](post-knowledge-learn.md)
- [POST /api/v1/knowledge/{id}/delete — 删除知识条目](post-knowledge-delete.md)
- [GET /api/v1/knowledge_categories — 查询知识分类树](get-knowledge-categories.md)
- [POST /api/v1/knowledge_categories — 新增知识分类](post-knowledge-categories.md)
- [PUT /api/v1/knowledge_categories/{id} — 修改知识分类](put-knowledge-categories.md)
- [POST /api/v1/people/import — 批量导入人员业务映射](post-people-import.md)
- [GET /api/v1/people/export — 导出人员档案](get-people-export.md)
- [GET /api/v1/dictionaries — 查询字典分类](get-dictionaries.md)
- [POST /api/v1/dictionaries — 新增字典分类](post-dictionaries.md)
- [PUT /api/v1/dictionaries/{id} — 修改字典分类名称](put-dictionaries.md)
- [GET /api/v1/dictionaries/{id}/items — 查询字典下拉选项](get-dictionary-items.md)
- [POST /api/v1/dictionaries/{id}/items — 新增字典项](post-dictionary-items.md)
- [PUT /api/v1/dictionaries/{id}/items/{itemId} — 修改字典项](put-dictionary-items.md)
- [POST /api/v1/dictionaries/{id}/actions — 批量启停或删除字典项](post-dictionary-actions.md)
- [GET /api/v1/workorder_categories — 工单分类树与筛选](get-workorder-categories.md)
- [POST /api/v1/workorder_categories — 新增工单分类](post-workorder-categories.md)
- [PUT /api/v1/workorder_categories/{id} — 修改工单分类](put-workorder-categories.md)
- [POST /api/v1/workorder_categories/actions — 批量启停删除工单分类](post-workorder-category-actions.md)
- [GET /api/v1/workorder_templates — 工单模板列表与新建候选](get-workorder-templates.md)
- [GET /api/v1/workorder_templates/{id} — 模板草稿与当前发布版](get-workorder-template.md)
- [POST /api/v1/workorder_templates — 创建模板草稿或直接发布](post-workorder-templates.md)
- [PUT /api/v1/workorder_templates/{id} — 保存模板新草稿或发布新版](put-workorder-templates.md)
- [POST /api/v1/workorder_templates/actions — 批量发布启停删除模板](post-workorder-template-actions.md)
- [POST /api/v1/workorders/batch_assign — 批量派工](post-workorders-batch-assign.md)
- [GET /api/v1/assets — 实物资产与计量台账查询统计](get-assets.md)
- [GET /api/v1/assets/{id} — 实物资产详情与追溯](get-asset.md)
- [POST /api/v1/assets — 登记单件资产](post-assets.md)
- [POST /api/v1/assets/{id}/actions — 检定安装拆回及换标](post-asset-actions.md)
- [GET /api/v1/stations/{id} — 供电所配置详情](get-station.md)
- [GET /api/v1/runtime_statistics — 系统运行账号与在线统计](get-runtime-statistics.md)

## 2026-10-24 报表接口对接

[报表统一契约与前端对接说明](reports-guide.md)。本轮不修改前端页面，接口按现有报表清单实现。

- [GET /api/v1/report_folders/{id}/permissions — 读取目录权限配置](get-report-folder-permissions.md)
- [PUT /api/v1/report_folders/{id}/permissions — 保存目录权限配置](put-report-folder-permissions.md)
- [GET /api/v1/reports/overview — 查询报表概览与协同动态](get-reports-overview.md)
- [DELETE /api/v1/reports/{id} — 软删除报表](delete-report.md)
- [POST /api/v1/reports/delete — 批量软删除报表](post-reports-delete.md)
- [GET /api/v1/reports/{id}/export — 导出单份报表](get-report-export.md)
- [GET /api/v1/reports/{id}/collaborators — 读取协同和链接设置](get-report-collaborators.md)
- [GET /api/v1/report_shares/{token} — 验证分享链接并读取报表](get-report-shared.md)
- [GET /api/v1/reports/collaboration-targets — 搜索人员、部门和角色](get-report-collaboration-targets.md)
- [GET /api/v1/reports/{id}/tasks — 查询报表填报任务](get-report-tasks.md)
- [POST /api/v1/reports/{id}/tasks — 派发报表填报任务](post-report-tasks.md)
- [POST /api/v1/reports/tasks/{id}/actions — 完成或取消填报任务](post-report-task-actions.md)
- [POST /api/v1/files — 报表图片上传接入边界](post-files.md)