湿空气物性计算 API

基于 FastAPI + CoolProp。给定任意 2 个状态参数，一次返回该状态点的全部湿空气物性，由调用方按需取用。

一、调用规则

1. 请求方式：HTTP GET（单点）或 POST（批量），均返回 JSON。
2. 查询参数名直接使用属性代码（见第三节），值为该属性的数值。
3. 必须且只能提供 2 个状态参数（多 1 或少 1 → 400）；同义代码（如 T 与 Tdb）不能同时出现（→ 400）。
4. 输入越界直接返回 400：P 50000 ~ 110000 Pa；温度类 −100 ~ 200 ℃；R 0 ~ 1；W 0 ~ 0.1；H −100 ~ 500 kJ/kg。
5. 限流：每个 IP 每分钟合计 60 次（/chart/hd 单独每分钟 10 次），超出返回 429。默认按直连地址计数，伪造 X-Forwarded-For 不能换配额。只有部署时设置 TRUST_PROXY=1 或 TRUST_PROXY_HOPS≥1，才按该头从右数第 N 个地址限流；地址不够 N 个时仍按直连地址。
6. 压力 P 是可选参数，缺省 101325 Pa（标准大气压）；如需非标压（高原、加压舱等）显式传入即可。
7. 响应中 state 字段包含该状态点的全部物性，前端自取所需字段。
8. 温度统一 ℃，焓统一 kJ/(kg 干空气)，相对湿度 0~1（小数）。

URL 结构拆解

含义：在标准大气压、干球温度 25 ℃、相对湿度 50% 下，求湿空气全部物性。

二、单点调用 GET /ha

请求格式

GET /ha?<键1>=<值1>&<键2>=<值2>[&P=<Pa>]

响应格式

{
  "inputs":   { "<键1>": <值1>, "<键2>": <值2> },
  "pressure": { "P": 101325, "default": true },   // default=true 表示用了缺省值
  "state": {
    "T": ..., "Twb": ..., "Tdp": ...,
    "R": ..., "W": ...,
    "H": ..., "V": ...,
    "S": ..., "Y": ...
  }
}

state 中个别字段若 CoolProp 解算失败，会返回 null，不会阻断其他字段。

示例 1：标准大气下，已知 T + R

GET /ha?T=25&R=0.5

{
  "inputs":   { "T": 25, "R": 0.5 },
  "pressure": { "P": 101325, "default": true },
  "state": {
    "T":   25.00,
    "Twb": 17.88,
    "Tdp": 13.87,
    "R":   0.50,
    "W":   0.00993,
    "H":   50.42,
    "V":   0.8578,
    "S":   180.76,
    "Y":   0.01571
  }
}

示例 2：非标压（高原 80 kPa）

GET /ha?T=25&R=0.5&P=80000

响应中 pressure.default 为 false，表示已被显式覆盖。

示例 3：已知干球 + 湿球温度

GET /ha?T=30&Twb=22

示例 4：已知比焓 + 含湿量（焓湿图反查）

GET /ha?H=50&W=0.01

curl 调用

curl "https://your-host/ha?T=25&R=0.5"

三、参数（属性代码）含义

下表中同义代码任选其一。P 为可选项，其余均为状态参数。

四、批量调用 POST /ha/batch

用于一次计算多个状态点（绘焓湿图、批量工况扫描等）。每个点独立解析、独立容错。单次最多 500 个点，超过返回 400。

请求格式

POST /ha/batch
Content-Type: application/json

{
  "points": [
    { "T": 20, "R": 0.5 },
    { "T": 25, "R": 0.5 },
    { "T": 30, "R": 0.5, "P": 80000 }
  ]
}

响应格式

{
  "count": 3,
  "results": [
    {
      "index": 0,
      "inputs": { "T": 20, "R": 0.5 },
      "pressure": { "P": 101325, "default": true },
      "state": { "T": 20.00, "Twb": 13.78, ... },
      "status": "success"
    },
    ...
    {
      "index": 2,
      "inputs": { "T": 30, "R": 0.5 },
      "pressure": { "P": 80000, "default": false },
      "state": { ... },
      "status": "success"
    }
  ]
}

curl 调用

curl -X POST https://your-host/ha/batch \
  -H "Content-Type: application/json" \
  -d '{"points":[{"T":25,"R":0.5},{"T":30,"R":0.6}]}'

五、焓湿图 GET /chart/hd

生成国标样式 h-d 焓湿图（斜角坐标：横轴含湿量 d，等温线近水平、等焓线向右下斜交约 135°），可直接在浏览器打开或嵌入报告。所有曲线数值与 /ha 同源（CoolProp）。

GET /chart/hd
GET /chart/hd?fmt=svg&points=25,0.5;30,0.6
GET /chart/hd?points=25,0.5;35,0.3&connect=1
GET /chart/hd?p=80000&t_min=0&t_max=35&d_max=25&lang=en

预览（标注 25 ℃ / 50%，落在 d ≈ 9.93 g/kg、h ≈ 50.4 kJ/kg）：

网页计算器 GET /ui 与过程链

打开计算器可以做两件事：填任意两个状态参数查全量物性并在图上标一个点；或者维护最多 10 个有序状态点（手填或按过程生成），一次请求带 connect=1 的焓湿图。相对湿度在页面上填百分数，提交前除以 100。点落在图外时，调整 t_min、t_max 或 d_max。

过程在浏览器里多次调用 /ha 完成，没有单独的过程接口。脚本或 AI 按同样的步骤编排即可。等湿是指含湿量 W（kg/kg 干空气）不变。下面是等湿加热：

# 1) 起点，读 state.W 与 state.R
GET /ha?T=25&R=0.5
# 2) 终点：W 不变，干球改为目标温度
GET /ha?T=35&W=<上一步的 state.W>
# 3) 用两点各自的 T 与 R 连线
GET /chart/hd?points=25,0.5;<T2>,<R2>&connect=1

其余过程同样只用 /ha：等湿冷却要求终点干球不低于起点露点；等温加湿保持干球、提高相对湿度或含湿量；绝热加湿优先固定湿球温度（B / Twb）并提高相对湿度，若这次调用失败再改用等焓（H 不变）；冷却除湿取盘管出风干球和相对湿度（缺省 0.95），可选再按含湿量不变再热；两风混合按干空气质量分数对 W 和 H 线性加权，再用 H+W 反查。这些折线用于教学和估算，不是法规冷负荷计算。

六、辅助接口

GET /ha/keys

返回服务端支持的全部状态参数代码、输出字段列表与单位说明，便于客户端动态构造表单。

GET /health

返回服务名与版本号，用于探活。

{ "status": "ok", "service": "CoolProp API", "version": "2.0.0" }

七、错误响应

// 状态参数个数不是 2
HTTP 400
{ "detail": "需要且仅需 2 个状态参数（除 P 之外），当前提供了 1 个" }

// 属性代码非法
HTTP 400
{ "detail": "存在无效的属性代码: ['XYZ']。有效代码见 /ha/keys" }

// 参数值不是合法数字
HTTP 400
{ "detail": "参数 T 的值 'abc' 不是有效的数字" }

// 输入越界
HTTP 400
{ "detail": "参数 R 的值 1.5 超出允许范围 [0, 1]" }

// 同义参数冲突
HTTP 400
{ "detail": "参数 T 与 Tdb 为同义参数，不能同时提供" }

// batch 超过 500 点
HTTP 400
{ "detail": "批量点数 501 超过上限 500" }

// 请求过于频繁
HTTP 429
{ "detail": "请求过于频繁，请稍后再试（限制：60 per 1 minute/IP）" }

// CoolProp 内部错误（输入组合不一致 / 越界等）
HTTP 500
{ "detail": "计算错误: ..." }

属性代码定义参考：CoolProp HumidAir 文档