initial commit: schema-building.json and schema-energy.json

2026-05-21 21:52:31 +08:00
commit 58097e4d12
4 changed files with 767 additions and 0 deletions
@@ -0,0 +1,172 @@
+# archgen-schema
+
+统一建筑数据模型（Unified Building Design 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 中不出现特定软件、工具或 DSL 的名称（如 GSA、AML、BSS、ant-model）。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
+```
+
+具体生成器不在本仓库维护，由各消费项目自行管理。
+
+
+建筑/社区尺度最小化的字段需要确定一个规则。默认或者非默认需要有个判定。 可能有md/skill来规范化操作。
+影响性能的要素需要捋清楚
+什么是智能优化？形态优化，还是需要性能目标？