feat: add CFD/radiance/urban/community schema files, pres, docs

2026-05-28 15:06:30 +08:00
parent 9f730223ce
commit 68bb9e2181
40 changed files with 11373 additions and 686 deletions
@@ -1,178 +1,226 @@
 # bps-schema

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

-## 仓库文件
+## 文件架构

-| 文件 | 说明 |
-|------|------|
-| `schema-building.json` | 建筑几何 + 核心实体（Building, Floor, Room, Aperture, Boundary, Element, Shaft 等） |
-| `schema-energy.json` | 能耗模拟领域（Material, Construction, RoomProgram, Schedule 等） |
+采用"尺度 × 模拟域"二维分文件架构。每个尺度按几何和模拟域拆分为独立文件。

-## Schema 规则
+### 建筑单体尺度

-### 1. JSON 为唯一真理源
+| 文件 | $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 生成的示例文件，需人工审核后使用） |

-所有类型定义以 JSON 文件为准。TypeScript / Python 等语言的绑定代码均从 JSON 生成，不得手工维护。
+### 社区尺度

-### 2. 不保存派生数据
+| 文件 | $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 生成的示例文件，需人工审核后使用） |

-Schema 只保存**原始定义数据**，不包含任何可从已有字段计算得出的值。
+### 城市尺度

-```
-❌ area        — 可由 region 计算
-❌ volume      — 可由 region + height 计算
-❌ boundingBox — 可由子实体几何计算
-✅ region      — 房间轮廓点集
-✅ height      — 房间高度
-```
+| 文件 | $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 生成的示例文件，需人工审核后使用） |

-### 3. 字段命名
+### 聚合入口

-| 规则 | 示例 |
-|------|------|
-| 使用 camelCase | `siteBasePoint`, `sillHeight`, `openRatio` |
-| 避免缩写（广为人知的除外） | `identifier` 而非 `id`, `displayName` 而非 `name` |
-| 布尔值用正面语义 | `operable` 而非 `nonOperable` |
-| 枚举值用 snake_case | `exterior_wall`, `curtain_wall` |
+| 文件 | $id | defs | 说明 |
+|------|-----|------|------|
+| `schema-all.json` | bps/all | 11 | 引用以上所有文件，提供完整验证入口 |

-### 4. 类型系统
+**合计**：11 个领域文件 + 1 个聚合文件，171 个类型定义。

-**基础类型：**
- `string` — 字符串
- `number` — 浮点数
- `integer` — 整数
- `boolean` — 布尔值
- `object` — 任意对象
+## Schema 规范

-**复合类型：**
- `TypeName[]` — 数组，如 `Polyline3d` 的 `points` 字段类型为 `Point3d[]`
- `TypeName` — 引用自定义类型或实体
+所有文件均遵循 [JSON Schema draft-2020-12](https://json-schema.org/draft/2020-12/release-notes)：

-**自定义类型**定义在 `types` 段，描述纯数据结构，不是业务实体。例如 `Point3d`（三维点）、`Polyline3d`（多段线）、`TimePoint`（时刻点）。
+- `$defs` — 所有类型、枚举、实体的定义区
+- `$ref` — 类型引用，使用 JSON Schema 标准 `$ref` 机制
+- `oneOf` — 判别联合体（如边界条件的 5 种类型）
+- `allOf` — 实体组合（`_IdentifiedObject` + 具体属性）
+- `const` / `enum` — 类型判别字段和枚举值
+- `required` — 必填字段
+- `default` — 缺省值
+- `minimum` / `maximum` / `exclusiveMinimum` — 数值约束
+- `pattern` / `minLength` / `maxLength` — 字符串约束
+- `additionalProperties: false` — 严格模式，禁止额外字段

-### 5. 实体结构
+## schema-building.json：建筑几何

-```json
-"EntityName": {
-  "description": "中文说明",
-  "tags": { "scale": ["building"], "simulation": ["energy"] },
-  "attributes": {
-    "fieldName": {
-      "type": "string",
-      "required": true,
-      "unit": "m",
-      "default": 0,
-      "description": "字段说明",
-      "tags": { "scale": ["building"], "simulation": ["energy", "daylight"] }
-    }
-  },
-  "children": {
-    "childName": {
-      "type": "ChildEntity",
-      "multiple": true,
-      "description": "子实体说明"
-    }
-  }
-}
-```
+对齐 [honeybee-schema](https://github.com/ladybug-tools/honeybee-schema) 几何层级，覆盖 Model → Room → Face → Aperture/Door → Shade 层级。

- `attributes` — 标量字段（string, number, boolean, enum, 自定义类型）
- `children` — 关联的子实体（1:1 或 1:N）
- `required: true` — 必填字段，序列化时必须存在
- `default` — 缺省值（可选字段未提供时使用）
- `unit` — 单位标注（仅文档用途）
+### 几何原语

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

-当一个实体存在多种形态时，使用 `variants` 表达：
+### 边界条件

-```json
-"Room": {
-  "discriminator": "creationMethod",
-  "variants": {
-    "planar_extrude": { ... },
-    "mass_slice": { ... },
-    "manual": { ... }
-  }
-}
-```
+- `Outdoors` / `Surface` / `Ground` / `Adiabatic` / `OtherSideTemperature`
+- Aperture/Door 仅支持 Outdoors 和 Surface 两种

-不同变体可包含不同的必填字段。判别字段的值决定了使用哪个变体。当前使用判别联合体的实体：
- `Room` — 判别字段 `creationMethod`，变体：`planar_extrude`、`mass_slice`、`manual`
- `Aperture` — 判别字段 `sourceType`，变体：`hosted`、`declarative`
+### 标识符规范

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

-枚举定义在 `enums` 段，每个枚举列出所有允许值。
+## schema-energy.json：能耗模拟参数

-### 8. 尺度与模拟类型标签（tags）
+覆盖 HBJSON energy properties 核心实体：材料、构造、时间表、负荷、HVAC、构造集、程序类型。

-每个字段可标注两个维度的标签：
+### 材料

-**尺度（scale）：**
-| 标签 | 说明 |
-|------|------|
-| `building` | 建筑尺度 |
-| `community` | 社区/街区尺度 |
-| `urban` | 城市尺度 |
+- `EnergyMaterial` — 有质量材料
+- `EnergyMaterialNoMass` — 无质量材料
+- `EnergyMaterialVegetation` — 植被材料
+- `EnergyWindowMaterialGlazing` / `Gas` / `GasCustom` / `GasMixture` / `SimpleGlazSys` — 窗材料
+- `EnergyWindowMaterialBlind` / `Shade` — 百叶/遮阳
+- `EnergyWindowFrame` — 窗框

-**模拟类型（simulation）：**
-| 标签 | 说明 |
-|------|------|
-| `energy` | 能耗模拟 |
-| `daylight` | 采光分析 |
-| `solar` | 日照分析 |
-| `thermal_comfort` | 热舒适分析 |
-| `carbon` | 碳排放核算 |
-| `wind` | 风环境模拟 |
-| `general` | 通用（不特定于某种模拟） |
+### 构造

-标签用于快速筛选特定尺度或某类模拟分析所需的字段。例如：
+- `OpaqueConstruction` / `WindowConstruction` / `AirBoundaryConstruction` / `ShadeConstruction`
+- 各自 Abridged 版本（identifier 引用）
+- `WindowConstructionShade` / `WindowConstructionDynamic` — 含动态遮阳的窗构造

-```json
-"northAngle": {
-  "type": "number",
-  "tags": { "simulation": ["energy", "daylight", "solar", "thermal_comfort", "wind"] }
-}
-```
+### 时间表

-表示 `northAngle` 对能耗、采光、日照、热舒适、风环境模拟均有影响。
+- `ScheduleTypeLimit` / `ScheduleDay` / `ScheduleFixedInterval` / `ScheduleRulesetAbridged` / `ScheduleRule`

-```json
-"embodiedCarbon": {
-  "type": "number",
-  "tags": { "scale": ["building", "community", "urban"], "simulation": ["carbon"] }
-}
-```
+### 负荷与设定值

-表示 `embodiedCarbon` 适用于建筑/社区/城市三个尺度，仅用于碳排放核算。
+- `PeopleAbridged` / `LightingAbridged` / `ElectricEquipmentAbridged` / `GasEquipmentAbridged`
+- `ServiceHotWaterAbridged` / `InfiltrationAbridged` / `VentilationAbridged`
+- `SetpointAbridged` / `InternalMassAbridged` / `ProcessAbridged`

-### 9. 只描述数据本身
+### 程序类型 / 构造集 / HVAC

-Schema 只描述**建筑数据本身**，不描述数据的生成方式。
+- `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` — 含行人高度加密层

 ## 使用方式

-各项目从 JSON schema 生成对应语言的类型代码：
+### 数据验证

 ```bash
-# TypeScript（示例）
-python3 scripts/gen-ts.py schema-building.json > dist/building.d.ts
-
-# Python Pydantic（示例）
-python3 scripts/gen-py.py schema-building.json > archgen_schema/building.py
+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
+```

-## TODO
+### Python Pydantic 生成

- [ ] 定义 building / community / urban 每个尺度的最小字段集合
- [ ] 制定 `required` 与 `default` 的判定规则文档
- [ ] 梳理影响模拟性能的字段并标注影响等级
- [ ] 明确"智能优化"的定义和 scope（形态优化 vs 性能目标驱动）
- [ ] 确定优化变量、约束条件在 schema 中的表达方式
- [ ] 完善 schema 的 tags 系统（如需新增 `minScale` / `maxScale` / `performanceImpact` / `optimizable` 等属性）
+```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
+```