chore: auto release commit (2026-07-14 11:56:45)

references/SCHEMA.md

@@ -73,6 +73,45 @@ metadata:
 
 不要把「外部来源只读」错误理解成「技能本地数据库一定只读」。技能通过 `_jiangchang_tables.readonly` 与 `_jiangchang_columns.editable` 声明本地表的实际写权限。
 
+## 标准数据同步语义（外源 → 本地库）
+
+适用于「同步 / refresh / collect」类能力。使用通用名称表述，勿把具体平台表名写进模板实现。
+
+| 要求 | 说明 |
+|------|------|
+| 外部来源默认只读 | 技能不得修改外源 |
+| 本地 SQLite 可事务写入 | 写入走 repository + 事务 |
+| 幂等 | 同一业务键重复同步结果稳定 |
+| 稳定唯一业务键 | 明确 upsert / 匹配字段 |
+| 全量或增量 | 在实现与文档中显式声明 |
+| 完整快照才提交 | 完整性校验通过后再 commit；调用方**必须显式提供**完整性状态（如 keyword-only 必填的 `snapshot_complete`），**禁止**默认视为完整，**禁止**靠数据条数猜测 |
+| 空结果 / 读取失败保护 | 读取失败、分页不完整或不可信空结果（`snapshot_complete=False`）**不得**清库或误删；仅当完整快照**显式确认**为空（`snapshot_complete=True` 且结果为空）时，才可按全量失效策略处理旧数据 |
+| 全量失效策略 | 物理删除、`removed`/`is_active` 标记、或保留历史——必须三选一并写清 |
+| 部分失败 | 不得伪装成整体成功 |
+| 半成品 | 事务失败不得留下可见不一致状态 |
+
+建议统一返回统计：
+
+```json
+{
+  "total": 100,
+  "inserted": 10,
+  "updated": 20,
+  "unchanged": 65,
+  "removed": 5
+}
+```
+
+### 同步数据 vs 导出当前数据表 vs 特殊业务报告
+
+| 能力 | 语义 | 负责方 |
+|------|------|--------|
+| **同步数据** | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
+| **导出当前数据表** | 本地库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
+| **生成特殊业务报告** | 多表合并、特殊排版或附加计算 | 仅当系统导出无法满足时，才提供独立 `export-*` |
+
+同步型 Action 默认只写库、不生成导出文件。兼容旧 export 命令需要刷新时，必须调用同一 sync 内核。可复用测试范式见 `tests/samples/test_sync_contract.py.sample`。
+
 ## 元数据表（宿主兼容）
 
 宿主读取字段（与匠厂 `metadata-resolver` 一致）：