采用 Collator → SOP → dry-run writer 的真实 HTTP 链路，保证治理规则和合同校验是真实执行的，只有最终写入是 dry-run。
INTEGRATION PORTAL · GOVERNANCE MVP
飞书智能业务数据中台 Portal
截图录入 → 候选结构化 → 治理校验 → 人工确认 → dry-run 写入
以 Collator + SOP 双入口治理架构为基础，构建可视化 Portal MVP，把截图智能录入、Candidate 合同校验、业务规则复核和人工确认组合成可演示的端到端闭环。
6/6集成 Gate 场景通过
7个截图 API 端点
2个治理入口 (PRE/POST)
0生产写入副作用
口径说明：当前为 Prototype 阶段，所有写入均为 dry-run，不接触生产飞书业务表。集成 Gate 6 场景在本地通过。
01
PROBLEM & SCOPE
先定义问题和责任边界。
业务问题
- Collator 和 SOP 各自具备完整的 HTTP 合同和治理逻辑，但缺少一个把上传、候选预览、治理结果和人工确认串成可视化流程的入口。
- 直接连接生产飞书业务表进行演示风险过高，需要在真实 HTTP 链路和 dry-run writer 之间建立可信切换边界。
我的职责
产品架构 / 合同设计 / Portal 开发
- 团队
- 个人主导
- 周期
- 2026.07 - 至今
- 交付状态
- Prototype · dry-run
02
PRODUCT DECISIONS
关键决策，不只是功能列表。
Portal 显著标注当前模式（Demo / Real API / Live Mode），通过顶部 Disclosure 横幅和颜色编码避免模式混淆。
集成 Gate 脚本设计 6 个场景：正常客片、正常样片、缺关联、类型未知、幂等确认、SOP 拒绝后无副作用，全部输出机器可读 JSON 证据。
03
SYSTEM ARCHITECTURE
从输入到反馈的产品链路。
Portal 层
Next.js App Router + Zustand + mock/real API 双模式
Collator 层
Fastify :8787 + 7 个截图 API + MockOcrEngine
SOP 治理层
Node http :3001 + PRE_WRITE + BR-01~06 业务规则
写入层
dry-run writer（不接触生产飞书表）
证据层
integration-gate-evidence.json + 日志 + 截图
实现栈
Next.js 16React 19TypeScriptTailwindZustandFastifyNode.jsVitestZod
04
EVIDENCE & OUTCOMES
展示证据，也说明证据边界。
完成 Portal 上传、候选预览、证据查看、人工修正、确认写入和转复核 6 段可视化流程。
集成 Gate 6/6 场景 PASS，包含 fail-closed（SOP BLOCKED → 无写入副作用）和幂等（重复 confirm 返回相同 completed_at）验证。
collator 504 单元测试 + typecheck 通过；SOP 91 单元测试通过；Portal build 成功。
指标边界
当前为 Prototype 阶段，所有写入均为 dry-run，不接触生产飞书业务表。集成 Gate 6 场景在本地通过。
05
PRODUCT EVIDENCE
界面、流程与实现证据。
06
TRADE-OFFS & NEXT
取舍、风险和下一步。
关键取舍
- Prototype 阶段使用 MockOcrEngine 返回固定预设文本，不接入真实 OCR，换取可重复演示和零凭据风险。
- Portal 未初始化为独立 git 仓库，当前以目录形式存在；后续如需独立部署可拆分。
下一步验证
- 接入真实 OCR 引擎和飞书生产凭据，在受控环境验证 live write 路径。
- 建立固定评测集，统计 OCR 字段准确率、治理拦截率和人工修改率。
- 将 Portal 拆分为独立仓库并部署 Preview，形成可分享的演示链接。
07
CROSS-PROJECT RELATIONSHIPS