# bps-schema

建筑性能模拟数据模型。所有类型定义以 draft-2020-12 标准 JSON Schema 为准。

## 文件架构

采用"尺度 × 模拟域"二维分文件架构。每个尺度按几何和模拟域拆分为独立文件。

### 建筑单体尺度

| 文件 | $id | defs | 说明 |
|------|-----|------|------|
| `schema-building.json` | bps/building | 30 | 建筑几何实体，对齐 HBJSON 几何层级 |
| `schema-energy.json` | bps/energy | 49 | EnergyPlus 能耗模拟参数 |
| `schema-radiance.json` | bps/radiance | 25 | Radiance 采光模拟参数 |
| `schema-cfd.json` | bps/cfd | 14 | CFD 建筑风环境模拟参数（AI 生成的示例文件，需人工审核后使用） |

### 社区尺度

| 文件 | $id | defs | 说明 |
|------|-----|------|------|
| `schema-community.json` | bps/community | 7 | 社区几何：Site / Terrain / Road / GreenSpace / WaterBody（AI 生成的示例文件，需人工审核后使用） |
| `schema-community-energy.json` | bps/community-energy | 8 | 区域能源：Plant / Network / Pipe / BuildingConnection（AI 生成的示例文件，需人工审核后使用） |
| `schema-community-cfd.json` | bps/community-cfd | 13 | 社区风环境：计算域 / 网格 / 湍流 / 边界条件 / 求解器（AI 生成的示例文件，需人工审核后使用） |
| `schema-community-microclimate.json` | bps/community-microclimate | 2 | 微气候：UHI 强度 / 风速修正 / 地表反照率（AI 生成的示例文件，需人工审核后使用） |

### 城市尺度

| 文件 | $id | defs | 说明 |
|------|-----|------|------|
| `schema-urban.json` | bps/urban | 3 | 城市几何：ClimateZone / LandUse（AI 生成的示例文件，需人工审核后使用） |
| `schema-urban-energy.json` | bps/urban-energy | 5 | 城市能源：需求聚合 / 可再生能源潜力 / 碳平衡（AI 生成的示例文件，需人工审核后使用） |
| `schema-urban-cfd.json` | bps/urban-cfd | 15 | 城市风环境：行人高度评估 / 街道峡谷 / 风舒适标准（AI 生成的示例文件，需人工审核后使用） |

### 聚合入口

| 文件 | $id | defs | 说明 |
|------|-----|------|------|
| `schema-all.json` | bps/all | 11 | 引用以上所有文件，提供完整验证入口 |

**合计**：11 个领域文件 + 1 个聚合文件，171 个类型定义。

## Schema 规范

所有文件均遵循 [JSON Schema draft-2020-12](https://json-schema.org/draft/2020-12/release-notes)：

- `$defs` — 所有类型、枚举、实体的定义区
- `$ref` — 类型引用，使用 JSON Schema 标准 `$ref` 机制
- `oneOf` — 判别联合体（如边界条件的 5 种类型）
- `allOf` — 实体组合（`_IdentifiedObject` + 具体属性）
- `const` / `enum` — 类型判别字段和枚举值
- `required` — 必填字段
- `default` — 缺省值
- `minimum` / `maximum` / `exclusiveMinimum` — 数值约束
- `pattern` / `minLength` / `maxLength` — 字符串约束
- `additionalProperties: false` — 严格模式，禁止额外字段

## schema-building.json：建筑几何

对齐 [honeybee-schema](https://github.com/ladybug-tools/honeybee-schema) 几何层级，覆盖 Model → Room → Face → Aperture/Door → Shade 层级。

### 几何原语

- `Point3D` — 三维坐标 (x, y, z)
- `Face3D` — 平面多边形（boundary + holes + plane）
- `Mesh3D` — 三角/四边形网格（vertices + faces + colors）
- `Plane` — 平面（法线 n + 原点 o + x 轴）
- `Color` — RGBA 颜色

### 边界条件

- `Outdoors` / `Surface` / `Ground` / `Adiabatic` / `OtherSideTemperature`
- Aperture/Door 仅支持 Outdoors 和 Surface 两种

### 标识符规范

- `identifier`：`^[.A-Za-z0-9_-]+$`，1-100 字符
- `display_name`：无限制（仅用于 UI 展示）
- `user_data`：可选字典

## schema-energy.json：能耗模拟参数

覆盖 HBJSON energy properties 核心实体：材料、构造、时间表、负荷、HVAC、构造集、程序类型。

### 材料

- `EnergyMaterial` — 有质量材料
- `EnergyMaterialNoMass` — 无质量材料
- `EnergyMaterialVegetation` — 植被材料
- `EnergyWindowMaterialGlazing` / `Gas` / `GasCustom` / `GasMixture` / `SimpleGlazSys` — 窗材料
- `EnergyWindowMaterialBlind` / `Shade` — 百叶/遮阳
- `EnergyWindowFrame` — 窗框

### 构造

- `OpaqueConstruction` / `WindowConstruction` / `AirBoundaryConstruction` / `ShadeConstruction`
- 各自 Abridged 版本（identifier 引用）
- `WindowConstructionShade` / `WindowConstructionDynamic` — 含动态遮阳的窗构造

### 时间表

- `ScheduleTypeLimit` / `ScheduleDay` / `ScheduleFixedInterval` / `ScheduleRulesetAbridged` / `ScheduleRule`

### 负荷与设定值

- `PeopleAbridged` / `LightingAbridged` / `ElectricEquipmentAbridged` / `GasEquipmentAbridged`
- `ServiceHotWaterAbridged` / `InfiltrationAbridged` / `VentilationAbridged`
- `SetpointAbridged` / `InternalMassAbridged` / `ProcessAbridged`

### 程序类型 / 构造集 / HVAC

- `ProgramTypeAbridged` / `ConstructionSetAbridged`
- `DefaultProgramTypesAbridged` / `DefaultConstructionSetAbridged`
- `IdealAirSystemAbridged`

## schema-radiance.json：采光模拟参数

兼容 HBJSON radiance properties，覆盖 Radiance 材质、构造集、传感器网格、视角。

### 材质（Modifiers）

- `Plastic` — 塑料材质（RGB 反射率 + 镜面度 + 粗糙度）
- `Metal` — 金属材质（继承 Plastic，镜面度默认 0.9）
- `Trans` — 半透明材质（透射漫反射比 + 透射镜面比）
- `Glass` — 玻璃材质（RGB 透射率 + 折射率）
- `Mirror` — 镜面材质（RGB 反射率）
- `Light` / `Glow` — 发光材质（RGB 发射率）
- `BSDF` — 双向散射分布函数材质（BSDF XML 数据 + 朝向）
- `Void` — 空材质

### 材质集（Modifier Sets）

- `WallModifierSetAbridged` / `FloorModifierSetAbridged` / `RoofCeilingModifierSetAbridged`
- `ApertureModifierSetAbridged` / `DoorModifierSetAbridged` / `ShadeModifierSetAbridged`
- `ModifierSet` — 材质集聚合

### 传感器与视角

- `Sensor` / `SensorGrid` — 传感器网格
- `View` — Radiance 视角（6 种视角类型）

## schema-cfd.json：CFD 风环境模拟

独立领域（非 HBJSON），覆盖 CFD 建筑风环境分析的完整参数体系。

### 核心参数

- `WindProfile` — 风剖面（4 种剖面 + 地形类别 + 风向）
- `CFDDomain` — 计算域定义
- `MeshParameters` — 网格设置（基础网格 + 局部加密 + 壁面层）
- `TurbulenceParameters` — 湍流设置（6 种模型 + 壁面函数）
- `BoundaryConditions` — 进出口/顶部/侧面/地面/建筑墙面边界类型
- `SolverSettings` — 求解器设置（稳态/瞬态 + SIMPLE/PISO + 收敛准则）

## schema-community*.json：社区尺度

### 几何（schema-community.json）

- `Site` — 场地顶级实体，含 2D 边界
- `TerrainGrid` / `TerrainTIN` — 高程网格或三角网
- `Road` / `GreenSpace` / `WaterBody` — 基础设施

### 区域能源（schema-community-energy.json）

- `DistrictEnergy` — 区域能源系统顶级实体
- `Plant` — 源站（CHP / Boiler / HeatPump / Chiller / PV 等）
- `Network` — 管网（CHW / HW / Steam / Electricity）
- `Pipe` / `BuildingConnection` — 管段与建筑接入

### 风环境（schema-community-cfd.json）

- `CFDDomain` — 社区尺度计算域
- `MeshParameters` — 含局部加密区域
- `SolverSettings` / `TurbulenceParameters` / `BoundaryConditions`

## schema-urban*.json：城市尺度

### 几何（schema-urban.json）

- `ClimateZone` — 气候分区（边界 + 气候区代码 + 度日数）
- `LandUse` — 用地性质（边界 + 用地类型 + 容积率 + 建筑密度）

### 能源（schema-urban-energy.json）

- `UrbanEnergyDemand` — 各用地类型年度能耗
- `RenewablePotential` — 屋顶/立面/地面可再生能源潜力
- `UrbanEnergyBalance` — 城市能源平衡（自给率 / 碳排放 / EUI）

### 风环境（schema-urban-cfd.json）

- `UrbanCFDSettings` — 城市级 CFD 设置
- `WindComfortAssessment` — 行人风舒适评估（Laws / NEN_8100 / COST_732 标准）
- `MeshParameters` — 含行人高度加密层

## 使用方式

### 数据验证

```bash
pip install jsonschema
python3 -c "
import json, jsonschema
with open('schema-building.json') as f:
    schema = json.load(f)
with open('model.hbjson') as f:
    data = json.load(f)
jsonschema.validate(data, schema)
"
```

### TypeScript 类型生成

```bash
npx quicktype schema-building.json -o dist/building.d.ts --lang typescript
npx quicktype schema-energy.json -o dist/energy.d.ts --lang typescript
npx quicktype schema-radiance.json -o dist/radiance.d.ts --lang typescript
npx quicktype schema-cfd.json -o dist/cfd.d.ts --lang typescript
```

### Python Pydantic 生成

```bash
pip install datamodel-code-generator
datamodel-codegen --input schema-building.json --output dist/building.py --output-model-type pydantic_v2.BaseModel
datamodel-codegen --input schema-energy.json --output dist/energy.py --output-model-type pydantic_v2.BaseModel
```