From be94269c8c820cf0698a7d570d0a039db93fb688 Mon Sep 17 00:00:00 2001
From: ringo <ringo.arch@gmail.com>
Date: Fri, 29 May 2026 14:49:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E8=BD=AF=E4=BB=B6?=
 =?UTF-8?q?=E5=AD=97=E6=AE=B5=E6=98=A0=E5=B0=84=E5=B7=A5=E4=BD=9C=E6=B5=81?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

覆盖从调研、测试、加入 schema 字段到完成映射文档的完整流程，含通用 Pitfalls 和经验总结。
---
 docs/software-mapping-workflow.md | 259 ++++++++++++++++++++++++++++++
 1 file changed, 259 insertions(+)
 create mode 100644 docs/software-mapping-workflow.md

diff --git a/docs/software-mapping-workflow.md b/docs/software-mapping-workflow.md
new file mode 100644
index 0000000..42060fc
--- /dev/null
+++ b/docs/software-mapping-workflow.md
@@ -0,0 +1,259 @@
+# 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` 引用建筑实体，不越界定义建筑内部的属性。