# RxnSeek → iSynth 接入选择 / Integration choices

本说明供 RxnSeek 维护者评估接入，不要求改变 RxnSeek 内部存储。本次更新仅在 iSynth 侧实施。规范、离线工具和传输协议是三个不同的契约。

## 1. 已有原始数据通道 / Existing source-preserving bridge

推荐继续使用现有的原始数据通道。RxnSeek 将用户选定、已有权限访问的记录保存为来源快照，导出 `reactions_source.csv`；`rs_reaction_json` 保存选定的子反应，`rs_source_json` 保存完整上级原始记录，`rs_molecules_json` 保存已有分子信息。未展开的反应组仍是来源记录，不假装是多条完整反应。

来源列保持原样；只对有明确对应关系的列选择 iSynth 字段。列选择读取 `/api/integrations/v1/schema` 的 `submission_form.column_mapping`，不要复制维护一份静态字段表。作者、许可、来源和文件信息也读取同一 `submission_form`。iSynth 保留来源，解析已支持的字段，并报告哪些记录进入了科学事实库。来源保存成功不代表所有多步过程都已结构化。

RxnSeek currently prepares a source-preserving CSV from a permission-checked source snapshot. Preserve its source JSON and original columns; the receiver converts supported facts. The existing `submission_form` supplies column choices and metadata rules. This route already exists and remains supported. Saving source text is distinct from successfully extracting searchable scientific facts.

## 2. 标准化 Reaction 通道 / Structured Reaction route

当 RxnSeek 能完整地表示投料、顺序阶段、条件和测量时，可选用标准化导出。每次实验生成一条 Reaction，序列化到 CSV 的 `reaction_record` 单元格。JSONL 可作本地交换文件；上传文件使用共同的 CSV 传输封装。

1. 读取 `/api/reaction-contract?view=object`：完整字段、JSON Schema、语义约定与科学契约指纹。普通文献可使用同一规范的 `view=extraction` 子集。
2. 用 `/schemas/isynth-python-toolkit.zip` 构建、校验及读写；也可在 Go/TypeScript 内构建 JSON，并调用 iSynth 校验接口。JSON Schema 结构校验不替代结构、单位与编号引用的语义校验。
3. 保存规范版本及科学指纹。经过校验、原文核对后，生成 `reaction_record` CSV；来源快照及行对应关系单独保留。
4. 仍通过现有授权的 `/api/integrations/v1/imports` 系列接口提交；外层清单版本和指纹使用集成 `/schema` 返回值，不用 Reaction 版本替换它们。通用客户端也可使用 MCP/API 的上传接口及各自的凭证。
5. 查询处理回执、核对草稿，用户确认后再提交审核。不能将格式校验通过显示成已发布。

The receiver supports this structured transport. **The current RxnSeek preparation UI does not yet offer a reviewed structured-export mode**: its default remains source-preserving export. The maintainer should add a mode only after reviewing the converter and the checks below; this document does not claim that route is already implemented inside RxnSeek.

## 3. 如何提供选择 / What to offer RxnSeek

集成 `/schema` 的 `reaction_object_contract.integration_choices` 提供可供维护方读取的模式、说明和状态。建议用户界面默认显示“保留原始记录”，另在已有合格转换器时提供“标准化反应”。两者的作者、许可、引用与上传审核规则一致，无需用户理解底层 JSONB，也不把上传方式与反应数据类型混在一起。

| 内容 / Contract | 入口 / Entry | 用途 / Purpose |
| --- | --- | --- |
| 元信息、列选择、上传清单 | `/api/integrations/v1/schema` | RxnSeek 现有提交流程，外层指纹 |
| 完整反应规范 | `/api/reaction-contract?view=object` | 多阶段结构、科学指纹 |
| 文献提取子集 | `/api/reaction-contract?view=extraction` | 同一规范的精简视图 |
| 模型可直接阅读的字段说明 | `/schemas/reaction-reference.en.md` | 提取提示及字段解释 |
| Python 构建、校验、读写 | `/schemas/isynth-python-toolkit.zip` | 独立工具包，不依赖平台数据库 |
| 完整提交示例 | `/examples/structured-upload.json` | 元信息与 `reaction_record` 行 |
| 参数登记与检索规则 | `/api/reactions/parameter-catalog` | 已登记可检索参数的标识、类型和单位 |

## 4. RxnSeek 当前如何存储 / Current storage

根据本地 RxnSeek 源码，数据库是 PostgreSQL，使用关系表加 JSONB：

- `reactions.details`：原始提取/中间反应内容。
- `normalized_reactions.normalized`：归一化反应组，形如 `{"reactions":[...]}`；同一来源按版本保留。
- `literature_id`、`source_reaction_id`、图号与页码等使用关系字段关联；分子信息另有分子表。
- `isynth_publications`：保存提交流程的来源 ZIP、规范快照、元信息、清单、校验报告和远端状态。

这些 JSONB 结构不等同于 iSynth Reaction。导出为 JSON/JSONL 是交换方式，不能据此判断底层数据库只存文件。建议在导出边界完成适配，不重写原始提取结果。

## 5. 验收内容 / Converter review

- 普通反应和一锅多步都使用同一 `initial_state` / `segments` 结构，阶段顺序与原文一致。
- 分子编号、来源子反应编号和 iSynth 被测对象编号保持明确映射；重复投料只增加 Charge。
- 产物与反应物的测量统一使用 `measurements`，通过 `subject` 关联；阶段结果不复制为整体结果。
- 所有额外结构化字段放到所属对象的 `parameters`；补充文字用 `text`。未知字段保留，登记后才能参加结构化参数筛选。
- 不补造原文缺失的结构、用量、构型、比较对象、作者、许可或阶段。
- 旧版本仍按冻结规范读取；规范变更不重写历史来源，也不悄悄更新已经保存的清单指纹。
- 验证权限、绑定账号归属、完整文件校验和、重复请求幂等、可恢复的处理回执及审核状态。

ORD 将规范与构建/校验/读写工具配套提供。iSynth 采用相同分工，但数据格式是 JSON Schema，而非 ORD Protocol Buffers；互转需要另行明确字段与单位映射。参考：https://github.com/open-reaction-database/ord-schema