API 参考已发布

RAILWISE-OS REST API 参考

RAILWISE-OS 完整 REST API 端点参考，包含项目、任务、数据、报告等模块的接口说明

复核 2026-07-09入门公开可引用RailWise 技术团队

API 参考

RAILWISE-OS REST API 参考

AI语义标签: #RESTAPI #API参考 #端点文档 #开发者 #接口规范

1. API 概述

1.1 Base URL

环境	Base URL
生产环境	`https://api.os.railwise.cn/v3`
沙箱环境	`https://sandbox-api.os.railwise.cn/v3`
私有化部署	`https://<your-domain>/api/v3`

1.2 请求格式

所有请求和响应均使用 JSON 格式，编码为 UTF-8。

请求头要求：

Content-Type: application/json
Accept: application/json
X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 或
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

1.3 响应格式

成功响应：

{
  "code": 200,
  "message": "success",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2026-07-08T12:00:00Z"
  }
}

错误响应：

{
  "code": 400001,
  "message": "请求参数错误",
  "data": {
    "field": "project_name",
    "detail": "项目名称不能为空"
  },
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2026-07-08T12:00:00Z"
  }
}

1.4 分页参数

列表接口默认支持分页：

参数	类型	必填	说明	默认值
`page`	integer	否	页码（从1开始）	1
`page_size`	integer	否	每页数量	20
`sort`	string	否	排序字段	`created_at`
`order`	string	否	排序方向：`asc` / `desc`	`desc`

分页响应：

{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 156,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}

2. 项目模块 (Projects)

2.1 获取项目列表

GET /projects

查询参数：

参数	类型	必填	说明
`status`	string	否	项目状态：`active`, `completed`, `archived`
`type`	string	否	项目类型：`foundation`, `tunnel`, `bridge`, `track`
`manager_id`	string	否	项目负责人ID
`client_id`	string	否	客户ID
`keyword`	string	否	关键词搜索（项目名称/编号）
`start_date_from`	string	否	开始日期起始（ISO 8601）
`start_date_to`	string	否	开始日期截止（ISO 8601）

请求示例：

curl -X GET "https://api.os.railwise.cn/v3/projects?status=active&page=1&page_size=10" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

响应示例：

{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "proj_abc123",
        "code": "RW-2026-BJ-001",
        "name": "北京地铁3号线盾构监测项目",
        "status": "active",
        "type": "track",
        "contract_amount": 850000.00,
        "start_date": "2026-03-15",
        "end_date": "2026-12-31",
        "manager": {
          "id": "user_001",
          "name": "张三",
          "phone": "138****1234"
        },
        "client": {
          "id": "client_001",
          "name": "北京轨道交通建设管理有限公司"
        },
        "location": {
          "province": "北京市",
          "city": "北京市",
          "address": "朝阳区某路段"
        },
        "progress": 45.5,
        "created_at": "2026-03-10T08:00:00Z",
        "updated_at": "2026-07-08T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 23,
      "total_pages": 3
    }
  }
}

2.2 获取项目详情

GET /projects/{project_id}

路径参数：

参数	类型	必填	说明
`project_id`	string	是	项目ID

2.3 创建项目

POST /projects

请求体：

{
  "name": "宁波绕城高速管廊监测项目",
  "type": "track",
  "contract_amount": 1200000.00,
  "start_date": "2026-07-01",
  "end_date": "2027-06-30",
  "manager_id": "user_002",
  "client_id": "client_003",
  "location": {
    "province": "浙江省",
    "city": "宁波市",
    "address": "鄞州区某路段",
    "coordinates": [121.550, 29.817]
  },
  "description": "轨道交通3号线控制保护区自动化监测"
}

响应示例：

{
  "code": 200,
  "data": {
    "id": "proj_new123",
    "code": "RW-2026-NB-045",
    "name": "宁波绕城高速管廊监测项目",
    "status": "active",
    "created_at": "2026-07-08T12:00:00Z"
  }
}

2.4 更新项目

PUT /projects/{project_id}

2.5 删除项目

DELETE /projects/{project_id}

注意：删除项目将级联删除关联的任务、数据、报告，请谨慎操作。

3. 任务模块 (Tasks)

3.1 获取任务列表

GET /tasks

查询参数：

参数	类型	必填	说明
`project_id`	string	否	所属项目ID
`status`	string	否	任务状态：`pending`, `assigned`, `in_progress`, `completed`, `cancelled`
`assignee_id`	string	否	执行人ID
`type`	string	否	任务类型：`survey`, `inspection`, `data_collection`, `report`
`due_date_from`	string	否	截止日期起始
`due_date_to`	string	否	截止日期截止

3.2 创建任务

POST /tasks

请求体：

{
  "project_id": "proj_abc123",
  "name": "3号线K12+350断面自动化监测",
  "type": "data_collection",
  "priority": "high",
  "assignee_ids": ["user_003", "user_004"],
  "due_date": "2026-07-15",
  "description": "使用自动化全站仪进行4小时高频监测",
  "checklist": [
    { "item": "检查全站仪状态", "required": true },
    { "item": "确认监测点完好", "required": true },
    { "item": "上传监测数据", "required": true }
  ],
  "location": {
    "address": "宁波市鄞州区",
    "coordinates": [121.550, 29.817]
  }
}

3.3 更新任务状态

PATCH /tasks/{task_id}/status

请求体：

{
  "status": "completed",
  "remark": "监测数据已上传，无异常"
}

3.4 任务统计

GET /tasks/statistics

响应示例：

{
  "code": 200,
  "data": {
    "total": 156,
    "by_status": {
      "pending": 12,
      "assigned": 28,
      "in_progress": 45,
      "completed": 68,
      "cancelled": 3
    },
    "overdue_count": 8,
    "completion_rate": 43.6
  }
}

4. 数据模块 (Data)

4.1 获取监测数据

GET /data/monitoring

查询参数：

参数	类型	必填	说明
`project_id`	string	是	项目ID
`point_id`	string	否	监测点ID
`sensor_type`	string	否	传感器类型：`total_station`, `level`, `gnss`, `inclinometer`
`start_time`	string	否	数据起始时间（ISO 8601）
`end_time`	string	否	数据截止时间（ISO 8601）
`include_abnormal`	boolean	否	是否包含异常数据

响应示例：

{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "data_001",
        "project_id": "proj_abc123",
        "point_id": "point_k12_350_01",
        "point_name": "K12+350-1#",
        "sensor_type": "total_station",
        "measured_at": "2026-07-08T08:00:00Z",
        "values": {
          "x": 395123.456,
          "y": 2812345.678,
          "z": 15.234,
          "dx": 0.5,
          "dy": -0.3,
          "dz": 0.1
        },
        "unit": "mm",
        "status": "normal",
        "quality_flag": "valid",
        "created_at": "2026-07-08T08:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total": 2880
    }
  }
}

4.2 批量写入监测数据

POST /data/monitoring/batch

请求体：

{
  "project_id": "proj_abc123",
  "records": [
    {
      "point_id": "point_k12_350_01",
      "sensor_type": "total_station",
      "measured_at": "2026-07-08T08:00:00Z",
      "values": {
        "x": 395123.456,
        "y": 2812345.678,
        "z": 15.234
      }
    },
    {
      "point_id": "point_k12_350_02",
      "sensor_type": "total_station",
      "measured_at": "2026-07-08T08:00:00Z",
      "values": {
        "x": 395124.567,
        "y": 2812346.789,
        "z": 15.345
      }
    }
  ]
}

响应示例：

{
  "code": 200,
  "data": {
    "total": 2,
    "success": 2,
    "failed": 0,
    "details": [
      {
        "point_id": "point_k12_350_01",
        "status": "success",
        "data_id": "data_001"
      },
      {
        "point_id": "point_k12_350_02",
        "status": "success",
        "data_id": "data_002"
      }
    ]
  }
}

4.3 获取数据趋势

GET /data/trends

查询参数：

参数	类型	必填	说明
`project_id`	string	是	项目ID
`point_ids`	string	是	监测点ID列表（逗号分隔）
`metric`	string	是	指标：`x`, `y`, `z`, `dx`, `dy`, `dz`, `settlement`
`interval`	string	否	聚合间隔：`hour`, `day`, `week`
`start_time`	string	是	起始时间
`end_time`	string	是	截止时间

响应示例：

{
  "code": 200,
  "data": {
    "point_id": "point_k12_350_01",
    "metric": "settlement",
    "unit": "mm",
    "statistics": {
      "min": -2.5,
      "max": 1.8,
      "mean": -0.3,
      "std": 0.8
    },
    "trend": [
      {
        "time": "2026-07-01T00:00:00Z",
        "value": -0.5,
        "status": "normal"
      },
      {
        "time": "2026-07-02T00:00:00Z",
        "value": -0.8,
        "status": "warning"
      }
    ]
  }
}

5. 报告模块 (Reports)

5.1 获取报告列表

GET /reports

5.2 生成报告

POST /reports/generate

请求体：

{
  "project_id": "proj_abc123",
  "template_id": "tpl_foundation_daily",
  "name": "2026年7月8日监测日报",
  "period": {
    "start_date": "2026-07-08",
    "end_date": "2026-07-08"
  },
  "options": {
    "include_charts": true,
    "include_photos": true,
    "format": "pdf",
    "watermark": "RailWise 内部资料"
  }
}

响应示例：

{
  "code": 200,
  "data": {
    "report_id": "rpt_001",
    "status": "generating",
    "estimated_time": 30,
    "poll_url": "/reports/rpt_001/status"
  }
}

5.3 查询报告生成状态

GET /reports/{report_id}/status

响应示例：

{
  "code": 200,
  "data": {
    "report_id": "rpt_001",
    "status": "completed",
    "progress": 100,
    "download_url": "https://cdn.os.railwise.cn/reports/rpt_001.pdf?token=xxx",
    "expires_at": "2026-07-15T12:00:00Z"
  }
}

6. 系统模块 (System)

6.1 获取当前用户信息

GET /system/user/me

6.2 获取组织成员列表

GET /system/organization/members

6.3 获取权限列表

GET /system/permissions

7. 完整端点索引

端点	方法	描述	权限要求
`/projects`	GET	获取项目列表	`project:read`
`/projects`	POST	创建项目	`project:write`
`/projects/{id}`	GET	获取项目详情	`project:read`
`/projects/{id}`	PUT	更新项目	`project:write`
`/projects/{id}`	DELETE	删除项目	`project:write`
`/tasks`	GET	获取任务列表	`task:read`
`/tasks`	POST	创建任务	`task:write`
`/tasks/{id}`	GET	获取任务详情	`task:read`
`/tasks/{id}/status`	PATCH	更新任务状态	`task:write`
`/data/monitoring`	GET	获取监测数据	`data:read`
`/data/monitoring/batch`	POST	批量写入数据	`data:write`
`/data/trends`	GET	获取数据趋势	`data:read`
`/reports`	GET	获取报告列表	`report:read`
`/reports/generate`	POST	生成报告	`report:write`
`/reports/{id}/status`	GET	查询报告状态	`report:read`
`/system/user/me`	GET	当前用户信息	`system:read`
`/system/organization/members`	GET	组织成员列表	`system:read`
`/system/permissions`	GET	权限列表	`system:read`

8. 相关文档

文档版本: v3.2.0 | 最后更新: 2026-07-08 | API版本: v3