P3_WP03_ENTERPRISE_CONNECTORS.md 6.4 KB
P3-WP03 企业连接器与扩展契约交付说明
状态
ENGINEERING_COMPLETE_ENTERPRISE_SOURCE_UAT_BLOCKED
enterprise_confirmation_status 仍为 TBD_EXTERNAL。Oracle 与 SQL Server 是工程实现，
不是企业真实来源验收结果。当前缺少 enterprise_source_1、enterprise_source_2、企业
网络、真实产品版本、只读账号与批准样本，因此不得声明企业 UAT 或生产就绪。
工程交付
- 稳定公开入口
app.core.connectors，SDK v1.0 包含版本化 manifest、能力白名单、严格 配置 Schema、秘密引用、健康与兼容接口，以及 discover/snapshot/incremental/lineage/ profile/cancel/resume/evidence 统一协议。 - registry 以
(connector_id, version)精确注册，未知连接器、版本和未声明能力默认拒绝； 受控 REST Catalog 只调用公开注册入口，采集运行核心没有连接器名称分支。 - runtime 以 connector/version/source/principal/domain/environment/process/binding/config/scope/ cursor/checkpoint/operation/dry-run 和 client hint 生成服务端规范请求哈希；调用方提供的 hint 不再直接 充当运行主键。相同 hint 跨身份或请求边界复用返回 409，且不返回另一运行记录。
- execute/resume 合计最多五次 attempt。每次 attempt 具有随机 lease token，终态写入必须同时命中 running、attempt number、lease token 和未取消标志；迟到 worker 不能覆盖新 attempt。失败态重试和 取消态恢复只有 CAS 获胜者可调用 connector operation，竞争失败者不追加重复 attempt。
- 取消在单条数据库 UPDATE 中原子写入
status=cancelled,cancel_requested=true，并通过 runtime probe、SQL 查询前后/逐行、REST 地址与流式 分块/逐页协作检查。它受驱动查询超时和网络读取超时约束，不承诺立即中断已进入驱动的阻塞调用。 - Oracle 与 SQL Server 使用只读系统目录 SQL，支持 schema/table include/exclude scope；
python-oracledb与pyodbc是可选驱动，缺失时返回稳定配置/驱动不可用错误，不影响启动。 - REST Catalog 配置只能来自服务端批准的版本化 source binding；机器请求携带 config（即便猜中
环境 secret reference）也会在 transport 前拒绝。REST 强制 HTTPS、精确 host allowlist、一次 DNS 公共地址校验后直接连接固定 IP，
同时用原域名完成 TLS SNI 与证书 hostname 校验；禁重定向、连接/读取超时、64 KiB 流式读取、
2 MiB 响应上界和 Draft 2020-12 响应校验。默认缺少 secret resolver 时在 DNS/socket 前失败关闭；
resolver 的秘密只进入
Authorization请求头。默认 resolver 只允许env:DATAOPS_CONNECTOR_*命名空间；未配置后端的vault:/secret:稳定失败关闭。 - Oracle、SQL Server、REST 的每个 connector principal 都严格绑定 connector/version/source/business-domain/environment 以及批准的 source binding 版本；操作和资源 scope 最小授权；binding 升版在同一事务内撤销旧版、创建新版并 rebind principal，binding 撤销同步停用 principal 和存量 active credential。凭证最长 15 分钟、仅返回一次、仅存 SHA-256；绑定、环境和 scope 在消费一次性凭证前校验，拒绝不会消耗凭证。
- PostgreSQL 迁移
20260802_472持久化 manifest、principal、credential metadata、run、attempt、 checkpoint、evidence、graph edge 与 audit；追加迁移20260802_473增加版本绑定、运行绑定、 安全配置/scope 与持久限流；后续20260802_474在多 active manifest 或 legacy binding 多版本 principal 时要求显式映射/合并并持续拒绝歧义 active 版本。20260802_475增加批准 source binding、规范请求哈希/client hint、attempt lease 和持久取消标志；存在绑定或绑定运行时 降级会失败关闭。20260802_476在升级时拒绝 active 未绑定 principal，并将所有企业连接器的 新建/更新 trigger 统一为 approved binding 强约束。473 在任何 ALTER/backfill 前执行歧义预检。 - run claim 时立即建立 domain→source、source→run、process→run 控制关系；running、failed、 cancelled、resumable、succeeded 状态同步到关系边，成功结果再补 source/run→asset。
/api/datasource/graph已由 501 替换为关系查询，管理 API 分为connectors:read、connectors:operate、connectors:manage；人工运行入口只允许显式dry_run=true，非 dry-run 只能通过一次性机器凭证入口。人工 cancel/resume 只能处理人工 dry-run；机器 cancel/resume 必须 提交新的短期凭证并按已持久化运行重新认证，不能用人工 bearer 或另一 binding/principal 越权。 cancel/resume 路由不读取请求体，OpenAPI 也不声明 requestBody。 人工 dry-run 的首次执行和 resume 都只做本地 validation，不调用 connector operation、秘密解析器 或网络/数据库；第三方 operation 只能返回succeeded，最终dry_run状态由 runtime 设置。 Vue2 页面按精确 permission 控制动作且不展示秘密或短期 credential。- runtime 在持久化前分别清洗 records、cursor、checkpoint 和 evidence；限制分别为 10,000 条/ 1 MiB、32 KiB、256 KiB、32 KiB，并递归移除 secret key、Bearer、URL userinfo 与敏感查询参数。 列表 API 只返回 cursor/checkpoint 的哈希、项数与字节数摘要。
- Oracle/SQL Server 当前只声明并实现已验证的 discover/snapshot/incremental/cancel/resume/evidence
能力，不虚报 lineage/profile。REST 逐页消费 next cursor，完成后持久化 completion marker，下一轮
从完整扫描起点开始；checkpoint 只保存 snapshot hash/count 摘要，不保存全量记录，也不伪造
removed 明细。分页仍受 100 页与 10,000 条总量上界约束。SQL Server 默认
Encrypt=yes、TrustServerCertificate=no；环境来自 authenticated binding 而非 tls_options，伪造 development 被拒绝。 开发弱化仅允许 binding 中明确批准的策略，证书路径限制在批准目录内。
外部门禁
真实 UAT 需企业提供两个来源的厂商/版本、规模、批准 schema/table scope、只读账号、网络路径、 TLS/证书、游标语义、限流与失败恢复预期。应在同一版本和批准样本上重跑兼容、增量、幂等、 取消/恢复、凭据轮换、审计和容量验证，之后由企业数据源验收责任人签字。