# 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/证书、游标语义、限流与失败恢复预期。应在同一版本和批准样本上重跑兼容、增量、幂等、
取消/恢复、凭据轮换、审计和容量验证，之后由企业数据源验收责任人签字。