D1 3.0 使用说明

三步完成整理

新建任务，填写连接，测试后确定。在数据选取页选表、勾字段。普通字段默认原名、原值和数据库备注，允许修改；每表选好后确认采用，需要修正时重新编辑。

JSON 使用独立解析窗口，查看样本、选择内部字段、填写英文输出名及中文备注。数组成员归属于字段，默认保留类型、层级、顺序和 null 对应关系，无须逐项设置类型。备注保存在字段说明中。

第二步设置主表、唯一标识及关联列；第三步可直接预览本页编辑，再点击“保存配置”校验并生效。只有一份当前配置，不自动保存草稿，也无需二次发布。单商品失败单独列出，其他商品继续。

导入导出配置

任务顶部“导出配置模板”只导出当前已保存配置；未保存修改不会混入模板。新建整理任务时导入模板，填写密码、测试并确定连接后复用设置，新任务默认未启动。模板不含密码、商品数据、运行进度或运行开关。

按需读取

运行与输出页按需下载 JSONL。服务端不保存商品正文、JSON 样本、历史输出或投递快照；来源离线无法提供上次商品内容。页面下载仅在本次页面内存，刷新释放；大于 256 MiB 使用流式接口。

GET /v1/sources/{id}/export
GET /v1/sources/{id}/products?ids=1,2
GET /v1/sources/{id}/output-fields

export 返回 d1-stream-v1 NDJSON 帧：begin → record / record_error → end。record.document 为商品对象。只有计数一致的 end 表示扫描结束，complete=true 表示全部成功。aborted、缺少 end、部分失败或 HTTP 200 均不能作为完整集合删除依据。页面验证结束帧后生成商品 JSONL，部分文件标记 partial，错误另行下载。

products 按输出 id 获取来源当前结果，返回 items、errors、missing_ids、deleted_ids、mapping_id；错误不等于删除。output-fields 提供来源、路径、名称及备注。Typesense 等消费方自行设置业务字段、索引和投递。

可选变更监测

按表选择新增/更新时间，无时间列则全量差异核对。整数时间戳与日期时间可混用；周期完整核对补查修改、空时间、未推进时间和物理删除。分类与关联变化会重新整理受影响商品。

点击“启动持续查询”后，直到主动停止都继续查询，关闭页面不停止。保存配置不会改变查询开关；字段或关联变化后自动完整核对。保存按钮旁显示结果；运行占用时等待重试，继续编辑取消旧请求；只改间隔不重置进度。失败商品保存标识、原因、旧摘要与依赖以便重试，正常商品继续提交。

为完成监测，D1 仍保存配置、加密密码、主键、摘要、依赖、进度与限量通知，并非完全无状态。通知不含正文，每来源默认保留 10000 条，可在高级设置调整上限。

GET /v1/sources/{id}/sync/status
GET /v1/sources/{id}/changes?after=123&feed_id=...&limit=100
GET /v1/sources/{id}/sync/failures

先启用监测并等待 sync/status.baseline_ready=true，再读取 export（确认 begin.baseline_ready=true），记录 begin 的 feed_id、change_cursor 和 mapping_id；全量完成后从该游标读取通知。无匹配监测时二者为 null，需配置后重建基线。收到 upsert 或 delete 均按 ID 读取当前状态，避免删除后重建的竞态；整批处理成功才保存 next_cursor，错误重试。

游标过期、超出范围或 feed_id 不符返回 410 CURSOR_EXPIRED，必须重新全量核对。不能用 after=0 或空通知替代基线。映射或软删除规则改变会更换 feed_id。轮询不是 binlog CDC，不能恢复两次读取之间的中间状态。

部署边界

3.0 使用空运行目录，不迁移旧任务、文件及商品库。只监听本机；管理操作需令牌登录，数据客户端需 Bearer 读取令牌，写请求还需 X-D1-Client: console；只读来源，不修改源表或索引。最多 13 张表、200 个顶层字段，需要非空单列唯一键。JSON 派生字段不能作为关联键。

不再提供历史文件、产物分页、定时文件归档、Typesense 配置和自动投递。完整说明见项目 README.md，侧边“数据接口”提供当前调用地址。

接口定义

查询周期与安全边界

旧配置保留查询频率；无时间字段表可选择按完整核对周期扫描。单语句最多 30 秒，无索引预览 3 秒，单次快照最多 15 分钟。低空间停止新批，错误详情在运行页查看。更改连接身份需重新填写密码。界面会话 8 小时有效，令牌仅从本实例运维终端获取，不写模板。