yuqei
1d85329a6a
12 KiB
P1-04.7 企业日历、通道握手与轮换、反馈学习、死信批量运营及 WebGL 社区交付报告
日期：2026-08-23
状态：已实现、已迁移、已完成 Chrome 登录态 UAT，自动化测试与生产构建验证通过
1. 阶段目标与结论
本阶段完成 P1-04.7 的五项能力：
- 将租户手工节假日扩展为企业日历源，支持日期清单与安全 HTTPS ICS 同步，并把同步结果合并进 SLA 工作日历；
- 为外部通知通道增加测试握手、启用门槛、密钥版本和轮换流程；
- 将负责人对根因建议的“有帮助/无帮助/修正分类”反馈沉淀为可解释学习证据；
- 为影响分析死信增加批量选择、强制原因、批次审计和可重放状态流；
- 为规则关系图增加离线物化社区、陈旧检测和 WebGL 渲染，并保留 SVG 降级路径。
结论：P1-04.7 把 P1-04.6 的单点治理工具进一步升级为可接入企业日历、可安全验证外部通道、可从人工反馈持续改进、可批量运营失败任务、可承载更大规则网络的治理平台。所有写操作按 tenant_id 隔离；同步、轮换、重放和学习均保留独立证据，不静默改写合同正文、规则正文或历史任务尝试。
2. 产品与业务流程
2.1 企业日历同步
治理管理员可以创建两类租户日历源：
- 日期清单：直接维护企业假期、集中休假日等 YYYY-MM-DD 日期；
- ICS：从公开 HTTPS iCalendar 地址显式同步全天日期及摘要。
日历源创建后由管理员点击同步，系统保存同步批次、状态、开始/完成时间、物化日期数、错误和触发人。成功同步的启用源与 SLA 策略中的手工节假日去重合并，形成“有效节假日快照”；管理员可选择立即重排当前开放治理事项。
本阶段没有伪造后台定时能力。产品界面明确表示当前为显式同步，为后续接入企业调度器、Microsoft Graph、Google Calendar 或 HR 系统保留边界。
2.2 通知通道测试握手与密钥轮换
新建通知通道强制保持停用。管理员必须先执行测试握手，测试通过后才能启用，避免“配置即外发”。通道展示 pending、passed、failed 三态、最近测试时间和错误。
Webhook 密钥不以明文持久化，而是由服务端主密钥、通道 ID 和 secret_version 派生。轮换时：
- secret_version 递增；
- 通道自动停用；
- 握手状态重置为 pending；
- 新密钥只在轮换响应和前端一次性面板中展示；
- 接收方更新密钥后，管理员重新测试并启用。
Webhook 请求同时携带密钥版本头，便于接收方实现灰度切换。邮件通道复用 SMTP 配置；开发模式只模拟接受，不发送真实邮件。
2.3 根因反馈学习
冲突根因卡片增加“建议有帮助”“建议无帮助”和修正分类入口。每名操作者对同一事件只有一份当前反馈，重复提交执行更新，避免刷票。
同一租户、同一 issue_code 的反馈被聚合为学习证据：至少 2 条修正分类且多数占比达到 60% 后，系统才调整同类事件的建议分类。返回结果始终公开 feedback_count、helpful_rate、learned_from_feedback 和 learned_category，避免不可解释的黑箱覆盖。原始冲突事实与负责人反馈均保留。
2.4 死信批量运营
治理管理员可以选择 1～100 个死信任务，填写统一重排原因后批量重放。接口逐条返回已重排 ID 和跳过项，不因部分任务不可重放而回滚整个批次；每个成功动作写入 bulk_requeued 审计并共享 batch_id。
同时修正任务证据语义：attempt_count 永不归零，retry_cycle 标识第几轮人工重放，cycle_attempt_count 只控制当前轮自动重试。这样任务重排后仍能看到连续的第 1、2、3、4 次尝试，而不是把历史失败伪装成首次执行。
2.5 物化关系社区与 WebGL
管理员可对租户完整规则关系生成物化社区快照。服务端计算连通社区，保存成员、节点数、边数、启用数、删除保护数及 graph_digest；查询 materialized 模式时直接读取最新快照。若当前关系与快照摘要不一致，页面显示“快照已陈旧”，提示重新物化。
前端提供自动、SVG、WebGL 三种渲染选择。自动模式在返回节点达到阈值后使用 WebGL；WebGL 不可用时降级为 SVG。画布使用真实 WebGL 上下文绘制节点和边，点击最近节点后继续复用现有焦点、详情与关系筛选逻辑。
3. 技术实现
3.1 数据与迁移
Alembic 版本：20260823_0058。
新增表：
- playbook_calendar_sources：租户日历源、类型、配置、启停和最后同步状态；
- playbook_calendar_dates：按来源物化的日期和摘要；
- playbook_calendar_sync_runs：每次同步的结果证据；
- playbook_notification_channel_tests：通道握手历史；
- playbook_conflict_root_cause_feedback：操作者根因反馈；
- playbook_relationship_community_snapshots：物化社区快照；
- playbook_relationship_community_members：社区成员。
扩展字段：
- playbook_notification_channels：secret_version、secret_rotated_at、handshake_status、last_tested_at、last_test_error；
- playbook_impact_analysis_jobs：retry_cycle、cycle_attempt_count。
运行时 schema-check 已覆盖新增表和关键字段。downgrade 按成员表、证据表、父表和扩展列的依赖顺序回退；回退会删除 P1-04.7 证据，执行前必须备份。
3.2 后端接口
新增或扩展接口：
- GET/POST
/api/v1/enterprise-playbook/governance/calendar-sources； - PUT
/api/v1/enterprise-playbook/governance/calendar-sources/{source_id}； - POST
/api/v1/enterprise-playbook/governance/calendar-sources/{source_id}/sync； - GET
/api/v1/enterprise-playbook/governance/calendar-sync-runs； - POST
/api/v1/enterprise-playbook/governance/notification-channels/{channel_id}/test； - POST
/api/v1/enterprise-playbook/governance/notification-channels/{channel_id}/rotate-secret； - POST
/api/v1/enterprise-playbook/conflict-events/{event_id}/root-cause/feedback； - POST
/api/v1/enterprise-playbook/rules/impact-analysis/jobs/bulk-requeue； - POST
/api/v1/enterprise-playbook/relationship-graph/materialize； - GET
/api/v1/enterprise-playbook/relationship-graph增加 materialized 聚类模式及快照状态。
OpenAPI 契约同步更新为 95 个路径、146 个 schema，并通过 YAML 解析。
3.3 安全与可靠性边界
- ICS 只接受 HTTPS，不允许 URL 内嵌认证信息；解析前和最终重定向后均校验目标地址，阻止 localhost、私网和非全局 IP；响应上限 1 MiB；
- 通道测试不会自动启用通道，密钥轮换会强制停用并要求重新握手；
- Webhook 派生密钥与租户通道和版本绑定，数据库不保存可直接使用的明文；
- 根因学习设置最小样本和多数阈值，学习来源在接口和页面中可见；
- 死信批量重放必须填写原因，尝试历史只追加不覆盖；
- 物化社区使用图摘要识别陈旧快照，前端不把旧快照误报为当前事实。
4. Chrome 登录态 UAT 证据
工作空间：Playbook 隔离 UAT
账号：uat.legal.20260823@example.test
角色：超级管理员/法务治理账号
4.1 企业日历
创建并启用日期清单源“UAT P1047 企业 HR 日历”，同步 2026-10-02、2026-10-05 两个日期。页面显示：
- 1 个启用源；
- 2 个同步日期；
- 与手工维护的 2026-10-01 合并后共 3 个有效节假日；
- 3 个开放治理事项已按新日历重排；
- 同步证据 ID：playbook-calendar-sync-750c7cf305e7。
4.2 通道测试
对停用邮件通道“UAT P1046 治理邮件适配器”执行握手，页面显示 passed 和最近测试时间。通道有意保持停用，开发环境仅返回模拟接受，没有向 governance-uat@example.test 发送真实邮件。
Webhook 轮换状态机由专项自动化覆盖，UAT 未请求真实外部 Webhook。
4.3 根因反馈
展开冲突事件 playbook-conflict-73bfa8408f3a 的根因建议并提交“建议有帮助”。页面刷新后显示反馈 1 条、帮助率 100%，原根因事实和处理状态均未改变。
4.4 物化社区与 WebGL
生成快照 playbook-community-cc4774beb595：6 个节点、3 条边、3 个社区，主社区包含 4 个节点、3 条边和 2 个删除保护节点。页面显示快照与当前关系一致。
强制切换 WebGL 后，Chrome 实际创建 WebGL 画布并绘制 6 个节点及关系边；可见无 WebGL 时的 SVG 回退路径仍保留。
4.5 死信批量运营
UAT 租户当时没有真实死信，本次没有为了演示而制造故障数据。批量选择、必填原因、部分跳过、批次审计、retry_cycle 和连续 attempt 序号由后端专项自动化覆盖。
5. 验证结果
- 当前后端测试集：342 项通过、4 项仅在特定环境执行的测试跳过，共收集 346 项；
- P1-04.7 Playbook operations 专项测试：9/9 通过；
- 前端测试：41/41 通过；
- TypeScript 检查与 Next.js 生产构建：通过，130 个路由/静态生成单元完成；
- OpenAPI YAML：95 个路径、146 个 schema，解析通过；
- Alembic 当前版本：20260823_0058 (head)；
- Contract API
/health：200；运行时 config-check 仅因本地开发安全开关为 warning； - Contract Web 3000、Contract API 8100、AI API 8101 与治理 Worker 保持运行。
6. 市场与架构评估
企业客户通常要求业务日历能进入 SLA、外部通知可在启用前验证、密钥可轮换、运营结论可纠正、失败任务可批量恢复、大规则库可视化不失控。本阶段对应补齐这些采购与落地门槛，尤其减少了误外发、历史证据丢失和图快照失真的风险。
当前继续采用 PostgreSQL 事务表保存同步、握手、反馈、任务和图快照是合理的：治理吞吐尚未需要单独消息或图数据库，事务一致性和租户审计价值更高。接口已把同步器、通知适配器、学习聚合器和图物化器分开，后续可以逐步替换为队列调度、专用通知服务或图计算服务，而不改变管理端业务流程。
根因“学习”当前是阈值明确的反馈聚合，而非不可审计的模型训练，适合合同治理场景。未来若引入排序模型，应继续把确定性事实、人工反馈和模型建议分层展示。
7. 已知边界与后续建议
- 当前日历同步为显式操作，尚未实现定时调度、ETag/Last-Modified 增量拉取和失败告警；
- 当前支持日期清单与 ICS，尚未实现 Microsoft Graph、Google Calendar、钉钉/飞书/企业微信日历 OAuth 适配器；
- Webhook 轮换密钥需要管理员安全分发给接收方；生产可进一步接入 KMS/Vault、租户级包裹密钥和短期双密钥宽限窗口；
- 根因学习是可解释的统计聚合，不等同于机器学习模型训练；样本规模扩大后可增加时间衰减、角色权重和离线评估；
- 批量重放会跳过已不在死信状态的任务，不提供批量取消，避免扩大误操作；
- 当前 WebGL 是点边视图，社区计算仍由服务端完成；达到万级节点后建议增加 Web Worker 布局、GPU picking、LOD、标签瓦片和后台增量物化；
- UAT 没有制造真实死信，也没有连接真实外部 Webhook；对应状态机和证据链已由专项测试覆盖，生产接入前仍应在隔离预发布环境执行一次真实接收端联调。
下一阶段可进入 P1-04.8：企业日历 OAuth/定时增量同步、通知双密钥灰度与专用企业通道、反馈质量评估、死信告警策略和万级图增量社区物化。