Skip to content

API.md

Latest commit

 

History

History
437 lines (344 loc) · 7.82 KB

API.md

File metadata and controls

437 lines (344 loc) · 7.82 KB
Raw

API 文档

本文档描述养老机构运营北极星指标系统 Lite版 (NHOM) 的API接口。

基础信息

  • 基础URL: http://localhost:8000/api/v1
  • API文档: http://localhost:8000/docs (Swagger UI)
  • 内容类型: application/json

认证

当前版本暂不需要认证，后续版本将添加JWT认证。

接口列表

看板接口

获取看板汇总数据

GET /dashboard/summary

参数

参数名 类型 必填 说明
institution_id string 是 机构ID
year integer 是 年份
month integer 是 月份 (1-12)

响应示例

{
  "institution_id": "uuid-string",
  "institution_name": "颐养苑",
  "period": "2023-06",
  "north_star_metrics": [
    {
      "code": "revenue",
      "name": "营业收入",
      "value": 502.5,
      "unit": "万元",
      "target": null,
      "yoy_change": null,
      "mom_change": 3.2,
      "trend": "up"
    }
  ],
  "financial_summary": [...],
  "operational_summary": [...],
  "service_summary": [...],
  "hr_summary": [...]
}

获取指标趋势

GET /dashboard/trends

参数

参数名 类型 必填 说明
institution_id string 是 机构ID
metric_codes array 是 指标编码列表
start_year integer 是 开始年份
start_month integer 是 开始月份
end_year integer 是 结束年份
end_month integer 是 结束月份

响应示例

[
  {
    "metric_code": "revenue",
    "metric_name": "营业收入",
    "unit": "万元",
    "data": [
      {"period": "2023-01", "value": 485.2},
      {"period": "2023-02", "value": 492.1},
      ...
    ]
  }
]

获取多机构对比

GET /dashboard/comparison

参数

参数名 类型 必填 说明
institution_ids array 是 机构ID列表
metric_code string 是 指标编码
year integer 是 年份
month integer 是 月份

机构接口

获取机构列表

GET /institutions

参数

参数名 类型 必填 默认值 说明
skip integer 否 0 跳过数量
limit integer 否 20 返回数量

响应示例

{
  "items": [
    {
      "id": "uuid-string",
      "code": "INST-A",
      "name": "颐养苑",
      "type": "apartment",
      "region": "华北区",
      "total_beds": 320,
      "total_rooms": 280,
      "single_rooms": 80,
      "double_rooms": 200,
      "building_area": 18500,
      "status": "active",
      "created_at": "2026-04-03T10:00:00",
      "updated_at": "2026-04-03T10:00:00"
    }
  ],
  "total": 3
}

获取机构详情

GET /institutions/{institution_id}

创建机构

POST /institutions

请求体

{
  "code": "INST-D",
  "name": "新机构",
  "type": "institution",
  "region": "华东区",
  "total_beds": 200,
  "total_rooms": 150,
  "single_rooms": 50,
  "double_rooms": 100,
  "building_area": 12000
}

更新机构

PUT /institutions/{institution_id}

删除机构

DELETE /institutions/{institution_id}

指标接口

获取月度指标列表

GET /metrics/monthly

参数

参数名 类型 必填 说明
institution_id string 是 机构ID
skip integer 否 跳过数量
limit integer 否 返回数量

获取月度指标详情

GET /metrics/monthly/{metric_id}

根据期间获取月度指标

GET /metrics/monthly/by-period

参数

参数名 类型 必填 说明
institution_id string 是 机构ID
year integer 是 年份
month integer 是 月份

创建月度指标

POST /metrics/monthly

请求体

{
  "institution_id": "uuid-string",
  "year": 2023,
  "month": 7,
  "revenue": 520.0,
  "operating_cost": 240.0,
  "operating_profit": 280.0,
  "cash_flow": 320.0,
  "total_beds": 320,
  "occupied_beds": 315,
  "total_elderly": 310,
  "care_level_count": 155,
  "total_staff": 85,
  "care_staff": 45,
  "labor_cost": 120.0,
  "satisfaction_rate": 96.5,
  "service_completion_rate": 97.2
}

更新月度指标

PUT /metrics/monthly/{metric_id}

删除月度指标

DELETE /metrics/monthly/{metric_id}

提交指标表单

POST /metrics/monthly/form

请求体

{
  "institution_id": "uuid-string",
  "year": 2023,
  "month": 7,
  "revenue": 520.0,
  "operating_cost": 240.0,
  "operating_profit": 280.0,
  "cash_flow": 320.0,
  "total_beds": 320,
  "occupied_beds": 315,
  "total_elderly": 310,
  "care_level_count": 155,
  "total_staff": 85,
  "care_staff": 45,
  "labor_cost": 120.0,
  "satisfaction_rate": 96.5,
  "service_completion_rate": 97.2
}

指标编码说明

财务指标

编码 名称 单位
revenue 营业收入 万元
operating_cost 营业成本 万元
operating_profit 营业利润 万元
profit_margin 营业利润率 %
cash_flow 现金净流量 万元

运营指标

编码 名称 单位
occupancy_rate 期末入住率 %
avg_occupancy_rate 平均入住率 %
care_level_ratio 等级照护比例 %
net_beds 净增床位 床

服务指标

编码 名称 单位
satisfaction_rate 住户满意率 %
service_completion_rate 服务完成率 %
infection_rate 院感发生率 %

人力指标

编码 名称 单位
total_staff 员工总数 人
hr_efficiency 人效 -
labor_cost_ratio 人力费用占比 %
turnover_rate 员工离职率 %

错误处理

错误响应格式

{
  "detail": "错误描述信息"
}

常见错误码

HTTP状态码 说明
200 成功
400 请求参数错误
404 资源不存在
422 验证错误
500 服务器内部错误

数据模型

Institution (机构)

interface Institution {
  id: string;
  code: string;
  name: string;
  type: 'apartment' | 'institution';
  region: string;
  total_beds: number;
  total_rooms: number;
  single_rooms: number;
  double_rooms: number;
  building_area: number;
  status: string;
  created_at: string;
  updated_at: string;
}

MonthlyMetrics (月度指标)

interface MonthlyMetrics {
  id: string;
  institution_id: string;
  year: number;
  month: number;
  
  // 财务指标
  revenue: number;
  operating_cost: number;
  operating_profit: number;
  profit_margin: number;
  cash_flow: number;
  
  // 运营指标
  occupancy_rate: number;
  avg_occupancy_rate: number;
  care_level_ratio: number;
  
  // 人力指标
  total_staff: number;
  care_staff: number;
  hr_efficiency_with_outsource: number;
  labor_cost_ratio: number;
  
  // 服务指标
  satisfaction_rate: number;
  service_completion_rate: number;
  
  // 效率指标
  revenue_per_bed: number;
  profit_per_bed: number;
  space_efficiency: number;
  
  created_at: string;
  updated_at: string;
}

测试

使用curl测试API：

# 获取机构列表
curl http://localhost:8000/api/v1/institutions

# 获取看板数据
curl "http://localhost:8000/api/v1/dashboard/summary?institution_id=xxx&year=2023&month=6"

# 创建月度指标
curl -X POST http://localhost:8000/api/v1/metrics/monthly \
  -H "Content-Type: application/json" \
  -d '{
    "institution_id": "xxx",
    "year": 2023,
    "month": 7,
    "revenue": 520.0,
    "operating_cost": 240.0,
    "operating_profit": 280.0
  }'