move software-mapping-workflow to skills/
This commit is contained in:
ringo
@@ -1,259 +0,0 @@
|
||||
# bps-schema 软件字段映射工作流
|
||||
|
||||
将目标 BPS 软件的数据模型映射至 bps-schema 多尺度多性能数据结构体的标准化流程。
|
||||
|
||||
参考案例详见 [`docs/cea-mapping.md`](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') # 或 geopandas 读 shapefile
|
||||
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` 引用建筑实体，不越界定义建筑内部的属性。
|
||||
Reference in New Issue
Block a user