# 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` 等属性）