7.3 KiB
7.3 KiB
name, description
| name | description |
|---|---|
| bps-schema-software-mapping | 将目标 BPS 软件的数据模型映射至 bps-schema 多尺度多性能数据结构体的标准化流程。从调研、运行测试案例、加入 schema 字段到完成字段映射文档，附带通用 Pitfalls 和经验总结。 |
bps-schema 软件字段映射工作流
将目标 BPS 软件的数据模型映射至 bps-schema 多尺度多性能数据结构体的标准化流程。
参考案例详见 docs/cea-mapping.md（CEA → bps-schema 完整映射记录）。
工作流概览
调研 → 运行测试案例 → 加入 schema 字段 → 完成字段映射
Research Run test cases Add schema fields Document mapping
一、调研（Research）
1.1 分析目标软件的数据模型
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 覆盖度
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 环境搭建
# 使用 conda/mamba 隔离环境
mamba create -n <tool-name> python=3.12 ...
mamba activate <tool-name>
典型环境问题：
- Python 版本约束
- 数值计算库版本兼容性（如 numpy 版本锁定）
- 平台特定问题（如 macOS arm64 上的预编译包缺失）
- 外部二进制依赖（如求解器、辐射引擎等）
2.2 执行最小化案例
优先运行软件内置的参考案例或最小的可执行示例：
mamba run -n <tool-name> <command>
验证要点：
- 从零开始：脚本应能从清空状态完整执行（clean state 验证）
- 输入文件结构：记录读取的输入文件路径及其字段定义
- 输出文件结构：记录输出的列名、类型、单位
- 错误恢复：遇到配置错误时分析根因并记录
2.3 数据格式理解
逐字段分析输入/输出文件：
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 模式：
"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 语法验证
每次修改后执行验证：
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：
# {软件} → bps-schema 字段映射
## 一、文件级映射
| bps-schema 文件 | 软件文件 | 说明 |
## 二、实体字段映射（按层级分节）
| bps-schema 字段 | 软件字段 | 来源文件 | 类型 | 说明 |
## 三、枚举值参考
| bps-schema 枚举 | 软件枚举 | 来源 |
## 四、完整示例
输入 + 输出的 JSON 示例
## 五、未覆盖项
已知缺口清单及建议归属
4.2 更新 README
在 README.md 顶部新增：
## 与 {软件} 的字段映射
详见 [docs/{software}-mapping.md](docs/{software}-mapping.md)。
五、工作流维护
完成一轮映射后执行以下操作：
- 记录典型问题：将列名大小写、版本兼容性、枚举来源等通用经验更新至本文档的 Pitfalls 节
- 存档脚本：将测试运行脚本和工具保存在
scripts/目录 - 留档案例：将完整映射记录写入
docs/{software}-mapping.md - 反哺仓库：将通用字段定义建议提交至 bps-schema 仓库
Pitfalls
-
列名大小写敏感：geopandas/pandas 读取 shapefile/DBF 时保留文件内的列名原始大小写，而代码可能使用小写。统一在数据导入时做列名归一化。
-
版本差异：同一软件的不同主版本间，字段名、文件格式、单位可能发生变更。以最新稳定版为准做映射，在文档中标注已废弃的旧字段。
-
枚举值来源：枚举值常存在于软件的内置数据库文件中，而非代码本身。需在文档附录中列出，不直接嵌入 schema 的
enum。 -
AI 生成内容的标注：未经实际软件测试验证的 schema 定义须标注"AI 生成，需人工审核"，以区分于经过验证的定义。
-
跨团队边界：不同尺度的 schema 可能由不同团队维护。社区级 schema 中通过
building_ref引用建筑实体，不越界定义建筑内部的属性。