# 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` 引用建筑实体，不越界定义建筑内部的属性。