180 lines
5.2 KiB
Markdown
180 lines
5.2 KiB
Markdown
# bps-schema
|
||
|
||
多尺度多性能协同数据模型。
|
||
|
||
## 仓库文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `schema-building.json` | 建筑几何 + 核心实体（Building, Floor, Room, Aperture, Boundary, Element, Shaft 等） |
|
||
| `schema-energy.json` | 能耗模拟领域（Material, Construction, RoomProgram, Schedule 等） |
|
||
|
||
## Schema 规则
|
||
|
||
### 1. JSON 为唯一真理源
|
||
|
||
所有类型定义以 JSON 文件为准。TypeScript / Python 等语言的绑定代码均从 JSON 生成，不得手工维护。
|
||
|
||
### 2. 不保存派生数据
|
||
|
||
Schema 只保存**原始定义数据**，不包含任何可从已有字段计算得出的值。
|
||
|
||
```
|
||
❌ area — 可由 region 计算
|
||
❌ volume — 可由 region + height 计算
|
||
❌ boundingBox — 可由子实体几何计算
|
||
✅ region — 房间轮廓点集
|
||
✅ height — 房间高度
|
||
```
|
||
|
||
### 3. 字段命名
|
||
|
||
| 规则 | 示例 |
|
||
|------|------|
|
||
| 使用 camelCase | `siteBasePoint`, `sillHeight`, `openRatio` |
|
||
| 避免缩写（广为人知的除外） | `identifier` 而非 `id`, `displayName` 而非 `name` |
|
||
| 布尔值用正面语义 | `operable` 而非 `nonOperable` |
|
||
| 枚举值用 snake_case | `exterior_wall`, `curtain_wall` |
|
||
|
||
### 4. 类型系统
|
||
|
||
**基础类型：**
|
||
- `string` — 字符串
|
||
- `number` — 浮点数
|
||
- `integer` — 整数
|
||
- `boolean` — 布尔值
|
||
- `object` — 任意对象
|
||
|
||
**复合类型：**
|
||
- `TypeName[]` — 数组，如 `Polyline3d` 的 `points` 字段类型为 `Point3d[]`
|
||
- `TypeName` — 引用自定义类型或实体
|
||
|
||
**自定义类型**定义在 `types` 段，描述纯数据结构，不是业务实体。例如 `Point3d`（三维点）、`Polyline3d`（多段线）、`TimePoint`（时刻点）。
|
||
|
||
### 5. 实体结构
|
||
|
||
```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": "子实体说明"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- `attributes` — 标量字段（string, number, boolean, enum, 自定义类型）
|
||
- `children` — 关联的子实体（1:1 或 1:N）
|
||
- `required: true` — 必填字段，序列化时必须存在
|
||
- `default` — 缺省值（可选字段未提供时使用）
|
||
- `unit` — 单位标注（仅文档用途）
|
||
|
||
### 6. 判别联合体（Discriminated Union）
|
||
|
||
当一个实体存在多种形态时，使用 `variants` 表达：
|
||
|
||
```json
|
||
"Room": {
|
||
"discriminator": "creationMethod",
|
||
"variants": {
|
||
"planar_extrude": { ... },
|
||
"mass_slice": { ... },
|
||
"manual": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
不同变体可包含不同的必填字段。判别字段的值决定了使用哪个变体。当前使用判别联合体的实体：
|
||
- `Room` — 判别字段 `creationMethod`，变体：`planar_extrude`、`mass_slice`、`manual`
|
||
- `Aperture` — 判别字段 `sourceType`，变体：`hosted`、`declarative`
|
||
|
||
### 7. 枚举
|
||
|
||
枚举定义在 `enums` 段，每个枚举列出所有允许值。
|
||
|
||
### 8. 尺度与模拟类型标签（tags）
|
||
|
||
每个字段可标注两个维度的标签：
|
||
|
||
**尺度（scale）：**
|
||
| 标签 | 说明 |
|
||
|------|------|
|
||
| `building` | 建筑尺度 |
|
||
| `community` | 社区/街区尺度 |
|
||
| `urban` | 城市尺度 |
|
||
|
||
**模拟类型（simulation）：**
|
||
| 标签 | 说明 |
|
||
|------|------|
|
||
| `energy` | 能耗模拟 |
|
||
| `daylight` | 采光分析 |
|
||
| `solar` | 日照分析 |
|
||
| `thermal_comfort` | 热舒适分析 |
|
||
| `carbon` | 碳排放核算 |
|
||
| `wind` | 风环境模拟 |
|
||
| `general` | 通用（不特定于某种模拟） |
|
||
|
||
标签用于快速筛选特定尺度或某类模拟分析所需的字段。例如：
|
||
|
||
```json
|
||
"northAngle": {
|
||
"type": "number",
|
||
"tags": { "simulation": ["energy", "daylight", "solar", "thermal_comfort", "wind"] }
|
||
}
|
||
```
|
||
|
||
表示 `northAngle` 对能耗、采光、日照、热舒适、风环境模拟均有影响。
|
||
|
||
```json
|
||
"embodiedCarbon": {
|
||
"type": "number",
|
||
"tags": { "scale": ["building", "community", "urban"], "simulation": ["carbon"] }
|
||
}
|
||
```
|
||
|
||
表示 `embodiedCarbon` 适用于建筑/社区/城市三个尺度，仅用于碳排放核算。
|
||
|
||
### 9. 只描述数据本身
|
||
|
||
Schema 只描述**建筑数据本身**，不描述数据的生成方式。
|
||
|
||
## 使用方式
|
||
|
||
各项目从 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
|
||
```
|
||
|
||
具体生成器暂时不在本仓库维护。
|
||
|
||
---
|
||
|
||
## TODO
|
||
|
||
- [ ] 定义 building / community / urban 每个尺度的最小字段集合
|
||
- [ ] 制定 `required` 与 `default` 的判定规则文档
|
||
- [ ] 梳理影响模拟性能的字段并标注影响等级
|
||
- [ ] 明确"智能优化"的定义和 scope（形态优化 vs 性能目标驱动）
|
||
- [ ] 确定优化变量、约束条件在 schema 中的表达方式
|
||
- [ ] 考察与 GSA Rules YAML 轨的复用可能性
|
||
- [ ] 完善 schema 的 tags 系统（如需新增 `minScale` / `maxScale` / `performanceImpact` / `optimizable` 等属性）
|