265 lines
7.3 KiB
Markdown
265 lines
7.3 KiB
Markdown
---
|
||
name: bps-schema-software-mapping
|
||
description: "将目标 BPS 软件的数据模型映射至 bps-schema 多尺度多性能数据结构体的标准化流程。从调研、运行测试案例、加入 schema 字段到完成字段映射文档，附带通用 Pitfalls 和经验总结。"
|
||
---
|
||
|
||
# bps-schema 软件字段映射工作流
|
||
|
||
将目标 BPS 软件的数据模型映射至 bps-schema 多尺度多性能数据结构体的标准化流程。
|
||
|
||
参考案例详见 [`docs/cea-mapping.md`](../../docs/cea-mapping.md)（CEA → bps-schema 完整映射记录）。
|
||
|
||
---
|
||
|
||
## 工作流概览
|
||
|
||
```
|
||
调研 → 运行测试案例 → 加入 schema 字段 → 完成字段映射
|
||
Research Run test cases Add schema fields Document mapping
|
||
```
|
||
|
||
---
|
||
|
||
## 一、调研（Research）
|
||
|
||
### 1.1 分析目标软件的数据模型
|
||
|
||
```bash
|
||
git clone <repo-url>
|
||
cd <repo-name>
|
||
|
||
# 统计代码语言和规模
|
||
pip install --break-system-packages pygount
|
||
pygount --format=summary --folders-to-skip=".git,node_modules,venv" .
|
||
```
|
||
|
||
调研要点：
|
||
|
||
- **文件结构**：输入文件格式（CSV/DBF/JSON/YAML）和目录组织方式
|
||
- **核心实体**：建筑、社区、管网、气候等实体定义及其关系
|
||
- **关键字段**：实体属性、类型、单位、枚举值
|
||
- **配置参数**：模拟器配置项（求解器选择、精度、时间步长等）
|
||
- **输出格式**：结果文件结构（年度汇总、逐时序列、逐月统计）
|
||
- **枚举字典**：使用类型、构造标准、系统编码等受控词表
|
||
|
||
### 1.2 评估现有 bps-schema 覆盖度
|
||
|
||
```bash
|
||
python3 -c "
|
||
import json, os
|
||
for f in sorted(os.listdir('.')):
|
||
if f.endswith('.json') and f != 'schema-all.json':
|
||
with open(f) as fh:
|
||
s = json.load(fh)
|
||
print(f'{f:45s} {len(s.get(chr(36)+\"defs\",{}))} defs')
|
||
"
|
||
```
|
||
|
||
用以下标记标注每个实体的覆盖状态：
|
||
|
||
| 标记 | 含义 |
|
||
|------|------|
|
||
| √ | 已有对应定义 |
|
||
| △ | 需补充新定义 |
|
||
| — | 不在此次映射范围内 |
|
||
|
||
---
|
||
|
||
## 二、运行测试案例（Run Test Cases）
|
||
|
||
### 2.1 环境搭建
|
||
|
||
```bash
|
||
# 使用 conda/mamba 隔离环境
|
||
mamba create -n <tool-name> python=3.12 ...
|
||
mamba activate <tool-name>
|
||
```
|
||
|
||
典型环境问题：
|
||
|
||
- Python 版本约束
|
||
- 数值计算库版本兼容性（如 numpy 版本锁定）
|
||
- 平台特定问题（如 macOS arm64 上的预编译包缺失）
|
||
- 外部二进制依赖（如求解器、辐射引擎等）
|
||
|
||
### 2.2 执行最小化案例
|
||
|
||
优先运行软件内置的参考案例或最小的可执行示例：
|
||
|
||
```bash
|
||
mamba run -n <tool-name> <command>
|
||
```
|
||
|
||
验证要点：
|
||
|
||
- **从零开始**：脚本应能从清空状态完整执行（clean state 验证）
|
||
- **输入文件结构**：记录读取的输入文件路径及其字段定义
|
||
- **输出文件结构**：记录输出的列名、类型、单位
|
||
- **错误恢复**：遇到配置错误时分析根因并记录
|
||
|
||
### 2.3 数据格式理解
|
||
|
||
逐字段分析输入/输出文件：
|
||
|
||
```bash
|
||
python3 -c "
|
||
import pandas as pd
|
||
df = pd.read_csv('path/to/file.csv')
|
||
print(list(df.columns))
|
||
print(df.dtypes)
|
||
print(df.head(3))
|
||
"
|
||
```
|
||
|
||
关键记录项：
|
||
- 列名大小写约定
|
||
- 数值单位（kW vs kWh、W/m² vs W 等）
|
||
- 枚举值范围
|
||
- 默认值和缺失值处理策略
|
||
|
||
---
|
||
|
||
## 三、加入 schema 字段（Add Schema Fields）
|
||
|
||
### 3.1 分层决策
|
||
|
||
根据调研结果，确定新增字段归属的 bps-schema 层级：
|
||
|
||
```
|
||
scale domain
|
||
─────────────────────────────────
|
||
building geometry / energy / radiance / cfd
|
||
community geometry / energy / cfd / microclimate
|
||
urban geometry / energy / cfd
|
||
```
|
||
|
||
**决策原则**：
|
||
- 社区级只**引用**建筑实体（通过 `building_ref`），不定义建筑内部的属性
|
||
- 建筑级属性（围护构造、HVAC 系统、内部负荷等）归 `schema-building.json`
|
||
- 社区级特定属性（气象、模拟配置、建筑类型学汇总）归 `schema-community*.json`
|
||
- 跨团队职责边界的字段在文档中明确标注归属
|
||
|
||
### 3.2 新增 def 模板
|
||
|
||
遵循现有 schema 的 `allOf` 模式：
|
||
|
||
```json
|
||
"NewEntity": {
|
||
"type": "object",
|
||
"allOf": [
|
||
{ "$ref": "#/$defs/_IdentifiedObject" },
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"type": { "const": "NewEntity" },
|
||
"field_name": {
|
||
"type": "string",
|
||
"description": "字段说明"
|
||
},
|
||
"numeric_field": {
|
||
"type": "number",
|
||
"exclusiveMinimum": 0,
|
||
"description": "单位"
|
||
},
|
||
"enum_field": {
|
||
"type": "string",
|
||
"enum": ["VAL_A", "VAL_B"]
|
||
}
|
||
},
|
||
"required": ["type", "field_name"],
|
||
"additionalProperties": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.3 字段映射规则
|
||
|
||
| 情况 | 处理方式 |
|
||
|------|---------|
|
||
| 软件字段名直接可用 | 保留原名，统一为 kebab-case |
|
||
| 需聚合计算 | 定义派生字段，文档说明计算方式 |
|
||
| 需拆分语义 | 拆分为多个原子字段 |
|
||
| 软件无对应字段 | 设 default 值，description 注明"暂未对应" |
|
||
| 字段是代码引用 | 保留 code 字符串，文档注明来源数据库 |
|
||
|
||
### 3.4 JSON 语法验证
|
||
|
||
每次修改后执行验证：
|
||
|
||
```bash
|
||
python3 -c "
|
||
import json
|
||
with open('schema-xxx.json') as f:
|
||
json.load(f)
|
||
print('valid JSON')
|
||
"
|
||
```
|
||
|
||
---
|
||
|
||
## 四、完成字段映射（Document Mapping）
|
||
|
||
### 4.1 映射文档结构
|
||
|
||
在 `docs/` 下创建 `{software}-mapping.md`：
|
||
|
||
```markdown
|
||
# {软件} → bps-schema 字段映射
|
||
|
||
## 一、文件级映射
|
||
|
||
| bps-schema 文件 | 软件文件 | 说明 |
|
||
|
||
## 二、实体字段映射（按层级分节）
|
||
|
||
| bps-schema 字段 | 软件字段 | 来源文件 | 类型 | 说明 |
|
||
|
||
## 三、枚举值参考
|
||
|
||
| bps-schema 枚举 | 软件枚举 | 来源 |
|
||
|
||
## 四、完整示例
|
||
|
||
输入 + 输出的 JSON 示例
|
||
|
||
## 五、未覆盖项
|
||
|
||
已知缺口清单及建议归属
|
||
```
|
||
|
||
### 4.2 更新 README
|
||
|
||
在 `README.md` 顶部新增：
|
||
|
||
```markdown
|
||
## 与 {软件} 的字段映射
|
||
|
||
详见 [docs/{software}-mapping.md](docs/{software}-mapping.md)。
|
||
```
|
||
|
||
---
|
||
|
||
## 五、工作流维护
|
||
|
||
完成一轮映射后执行以下操作：
|
||
|
||
1. **记录典型问题**：将列名大小写、版本兼容性、枚举来源等通用经验更新至本文档的 Pitfalls 节
|
||
2. **存档脚本**：将测试运行脚本和工具保存在 `scripts/` 目录
|
||
3. **留档案例**：将完整映射记录写入 `docs/{software}-mapping.md`
|
||
4. **反哺仓库**：将通用字段定义建议提交至 bps-schema 仓库
|
||
|
||
---
|
||
|
||
## Pitfalls
|
||
|
||
1. **列名大小写敏感**：geopandas/pandas 读取 shapefile/DBF 时保留文件内的列名原始大小写，而代码可能使用小写。统一在数据导入时做列名归一化。
|
||
|
||
2. **版本差异**：同一软件的不同主版本间，字段名、文件格式、单位可能发生变更。以最新稳定版为准做映射，在文档中标注已废弃的旧字段。
|
||
|
||
3. **枚举值来源**：枚举值常存在于软件的内置数据库文件中，而非代码本身。需在文档附录中列出，不直接嵌入 schema 的 `enum`。
|
||
|
||
4. **AI 生成内容的标注**：未经实际软件测试验证的 schema 定义须标注"AI 生成，需人工审核"，以区分于经过验证的定义。
|
||
|
||
5. **跨团队边界**：不同尺度的 schema 可能由不同团队维护。社区级 schema 中通过 `building_ref` 引用建筑实体，不越界定义建筑内部的属性。
|