docs(acceptance): 补 2026-10-10 界面端到端验收结果(含三处修复与顺序约束)

- A1:记录白名单环境漏传 dws 变量这一缺陷与修复后的真实产物证据(d29e04e)
- A3/C1:写明生成即固化的顺序约束——处理完成 → 批准 → 生成新版本 → 确认冻结(冻结不重算)
- B1/C1/C2/C3/C4:补本期实测(tp-c3412382… / rb-d6eb1c91… / rx-63b81560… / rx-71d13453…)
- C2:记录首个真实跨环境 wiki 发布与「写入保留外来源页 vs 校验要求集合相等」的口径冲突(eabe55b)
- F:wiki 跨环境发布不再列为未跑;新增健康探测误报、测试端 404、snapshot_verification_id 空 三项待办
This commit is contained in:
姚章浩
2026-10-10 10:23:51 +08:00
parent eabe55b432
commit 134da985fa
+52 -6
View File
@@ -16,6 +16,17 @@
- 期望:解析监控出现"处理中";失败进**死信**,可重排
- 证据:`解析监控 → 死信` 队列;重排轮次键 `artifact-fetch:<version>:r<n>`
- 状态:✅(死信重排修复 `cddc4c9`)
- **2026-10-10 端到端实测(界面操作)**:勾选 `App账号注册.adoc` → 标记"对内" → 取件
- 首次取件**终态失败** `artifact_fetch_rejected: credentials`(1/8 次即终态)——**已定位并修复**:
`artifactfetch` 的 runner 给子进程的是**白名单环境**(防凭据外泄),但没透传
`ARTIFACT_DINGTALK_FETCHER/DWS_BIN/DWS_CONFIG_DIR/DWS_HOME/DWS_DISABLE_KEYCHAIN`,
dws 找不到配置目录与文件型 keychain → 报"未登录" → 被映射成 `credentials` 终态
(且按设计不回落老路径)→ **钉钉取件在真实链路上整体失败**。脚本单跑正常,因为绕过了白名单
(提交 `d29e04e`;同时失败时把 stderr 尾部脱敏后带进错误,否则只能看到裸 code)
- **重排(重新入队)后**:`artifact.fetch` 1 次完成 → 产物 `sn-753f….docx` **4799 B**、
`file` 认作 Microsoft Word 2007+、zip 12 项;`content_objects` 记 `validated_format=docx`、
`content_state=verified`、`sha256=5d8f38d0…` ✓
- 教训:**dws 取件的端到端证据必须在"平台真实调用路径"里取**(脚本直接跑会漏掉环境白名单这类差异)
#### A1 补充:钉钉取件改走 dws(`f4e1ecc` / `6496ee3` / `9155bd3`,2026-10-09)
- 开关:`ARTIFACT_DINGTALK_FETCHER=dws|auto|legacy`,线上为 **auto**(先 dws;**仅可重试错误**回落老路径)。
@@ -37,13 +48,19 @@
- 步骤:标注 → 生成修订
- 期望:标记按 **系统设置 → 测试知识库绑定** 分发到对应测试库;`不需要` 不入库
- 证据:`GET /api/v1/source-catalog/routing-capabilities`;绑定未配时标记被拒
- 状态:✅(本期实测绑定与路由能力)
- 状态:✅ 本期实测(界面勾选 → "对内" → 目录刷新完成;`internal_enabled/external_enabled` 均 true)
### A3 生成修订 / 新版本(发布准备)
- 入口:**发布管理 → 生成新版本** → `批准` / `驳回`
- 期望:只有批准后的变更集才能进入密封与批次
- 证据:变更集版本号与审核动作记录
- 状态:✅(见 `P5_REVIEW_AND_SEAL_ACCEPTANCE.md`)
- **⚠️ 顺序约束(2026-10-10 实测踩到)**:`生成新版本` 是**生成即固化**的——它把当时的
"测试是否就绪 / 是否批准"快照写进条目。若在**处理完成/审核批准之前**生成,则该条目会被
记为 `not_ready`,且此后 `确认冻结` **不会重算**(冻结沿用生成时的条目),
重生成才是唯一的刷新方式。正确顺序:**处理完成 → 批准 → 生成新版本 → 确认冻结 → 建批次**。
实测:批准前生成 v2(新增1/阻断195,本条 not_ready)→ 批准后重生成 v3(**新增2/阻断194**,
本条 `ready/can_release=t`)→ 冻结 → 定批次 ✓
## B. 入库与监控
@@ -51,7 +68,10 @@
- 入口:**文档工作台**(待入库列表)→ 选中 → **开始处理**
- 期望:上传 → 解析 → 索引 → `completed`;目标库里能看到知识条目与 wiki 页
- 证据:单文档 E2E `tp-3056261d46396a0695497f38421346b3` → `processing_state=completed`;知识 `cf0af40f-7c0c-4526-ad6a-4515b3b2ca00`(4 chunks,wiki 9 页)
- 状态:✅ 2026-10-08 实测
- 证据(2026-10-10 界面实测):`解析监控 → 待入库(1)` → **开始处理** → `tp-c3412382b66f55404d2b51672ffd0549`
→ `parse_status=completed`、`ingest_state=uploaded`、`poll_sequence=4`、`last_remote_status=completed`;
知识 `98be235b-68cf-43e1-94ca-419f5b97fddb`;任务链 `test.upload` → `test.poll`×4 → `test.validate` 全 completed ✓
- 状态:✅ 2026-10-08 / 2026-10-10 实测
### B2 解析监控与补救
- 入口:**解析监控** → 处理中 / 需要你出手 / 需下架 / 死信 / 已完成 / 知识库差异 / 知识库解析进度
@@ -66,25 +86,48 @@
- 入口:**发布管理 → 创建草稿批次 → 密封 → 锁定**
- 期望:密封后批次不可改;锁定后才能授权生产发布
- 证据:批次 `rb-9678722c…`(1 项);变更集 `rcs-832f0cf9…` v1(196 项:1 可发布 / 195 阻塞)
- 状态:✅ 本期实测
- 证据(2026-10-10 界面实测):`批准` → `生成新版本`(v3 `rcs-69c1810b…`,新增2/阻断194)→ `确认冻结`
(`state=confirmed`、`confirmed_by=admin`)→ 勾选本条 + 批次名 `验收-App账号注册-20261010` →
`创建草稿批次` → `锁定清单` → 批次 `rb-d6eb1c91ee49ab3aedaa16d3c3c91f85`(**sealed**、1 项、
绑定 v3、`review_id=rv-e4b38040…`、`action=upsert`、`decided_visibility=internal`)✓
- 状态:✅ 2026-10-08 / 2026-10-10 实测
### C2 授权发布(双闸 + 页面确认语句)
- 入口:**发布管理 → 授权发布** → 逐字输入确认语句 `publish-to-production` → 确认执行
- 期望:执行 `completed` + `verified`;目标库出现该文档;不出现"一键发布"
- 证据:执行 `rx-dd47920a5b5f5019af4f197fd0c2f92c`;目标库 `0b217e8a…` 文档数 2069→2070;两个闸门 `PRODUCTION_RELEASE_REQUESTS_ENABLED` / `PRODUCTION_BACKUP_RESTORE_VERIFIED` 均为 true
- 状态:✅ 本期实测(页面通道由管理员会话记录操作人;另支持 0600 Bearer 通道)
- **2026-10-10 界面实测(含首个真实跨环境 wiki 发布)**:授权前留档 2m52s → `guardcheck` 两库 PASS
→ 输入 `publish-to-production` → 确认执行
- 首次执行**失败**:项级 `release_verification_failed`,worker 日志
`release wiki replace scope in_scope=0 foreign=8 foreign_ref_stripped=0 untouched=1 skipped_library=1 degraded=true`
→ **已定位并修复**:写入侧(`replaceWiki`)按设计保留目标库**外来源** wiki 页,
而校验侧 `VerifyWiki` 仍要求"生产页集合与包内快照完全相等" → 跨来源共库必然误判。
修复:校验改为与写入侧同一套归属口径(共用 `packageWikiOwners`)——
"快照内页必须都存在 + 多出来的页只有在**不属于本包**时才放行",本包拥有却残留/缺失仍判失败,
撤权仍禁止任何页引用被撤权文档(提交 `eabe55b`)
- **重排后完成**:执行 `rx-63b815604766c750f95c6bba8682a4fe` → `completed`(1/1、failed 0、
项级 `verified`、`production_revision=rv-e4b38040…`、`bundle_sha256=19a85aea…`),
worker 日志 `in_scope=1 foreign=8 … degraded=true` 无失败行
- 页面原文:该执行 `发布 已完成 1/1`;每项结果 `App账号注册.adoc → 发布并验证通过 · 目标库 0b217e8a… · 生产可用` ✓
### C3 查看结果 → 回滚
- 入口:**发布管理 → 查看结果** → 需要时 **回滚** → 确认语句 `rollback-production-release`
- 期望:回滚后目标库该知识停用(**不删知识行**),wiki 页保持
- 证据:`rx-f1d1d669…` → `rolled_back`,`authorized_by=admin`,`prior_execution_id=rx-dd47920a…`;目标库该知识 `enable_status=disabled`、chunks 4/0 enabled、wiki 9 页完整
- 状态:✅ 本期实测
- 证据(2026-10-10 界面实测):输入 `rollback-production-release` → 执行 `rx-71d13453f5c684a7fa6f9c8337610d78`
→ `rolled_back`(1/1、failed 0、项级 `rolled_back`);页面 `回滚 已回滚`、每项结果
`App账号注册.adoc → 已恢复上一版本 · 目标库 0b217e8a… · 已恢复`;
**独立核对目标库**:`knowledges` 行仍在、`parse_status=completed`、`enable_status=disabled` ✓(首发布回滚=停用,不删行)
- 状态:✅ 2026-10-08 / 2026-10-10 实测
### C4 重排失败执行
- 入口:**发布管理 → 失败执行 → 重排** → 确认语句 `retry-production-release`
- 期望:只重置失败项;`verified` / `rolled_back` 项保持完成;重排不改写 `AuthorizedBy`(历史不可篡改)
- 证据:`internal/httpapi/production_action_test.go` 双通道用例
- 状态:✅ 单测覆盖|⚠️ 当时无失败执行可点
- 状态:✅ 单测覆盖 + **2026-10-10 真实失败项实测**(上面 C2 的失败执行即用 `重排` +
固定语句 `retry-production-release` 重跑成功;同一条执行号 `rx-63b81560…` 由 `failed` 转为 `completed`,
`authorized_by=admin` 未被改写)
## D. 系统设置
@@ -156,7 +199,10 @@
## F. 本期已知限制与边界(验收时不必当缺陷)
1. **ES 留档字节默认留目标主机**(`PULL_ES=0`);异地副本不做(你的决定)。
2. **ES 快照仓与留档同机同盘**:整机故障需靠 RDS 托管备份 + OSS 还原。
3. **wiki 通道的真实跨环境发布**本期未跑(归属门禁已单测 + 真库集成测试;建议首次在映射库上与 D3 一起验收)。
3. **wiki 通道的真实跨环境发布已跑通**(2026-10-10,见 C2):发现并修复"写入保留外来源页、校验却要求集合相等"的口径冲突(`eabe55b`);降级保留(`degraded=true`)现在是发布常态路径。
3b. **指标条的健康探测有误报**:`解析监控` 顶部把 Embedding 模型 / LLM 模型 / OSS / Redis-MQ / WeKnora API 显示为"阻断",但本期入库与发布全链路(上传/解析/索引/发布/回滚)都实际成功 → 探测口径待校正(不作阻塞项)。
3c. **`系统设置 → 服务配置` 的"测试端"探测报 404**:`test_weknora_base_url` 为空时 api 用 `TEST_WEKNORA_BASE_URL=http://app:8080` 探测,而 `app` 在治理栈网络内不可解析 → 显示"可达·不可接单";worker 走的是可用路径(本清单 B1/C2 均成功),仅探测口径问题。
3d. **`release_executions.snapshot_verification_id` 为空**:发布前快照门禁确实生效(缺少/过期会 `release_target_snapshot_missing`),但执行行没有记下"用的是哪份快照",追踪性待补。
4. **"重排"在页面上无真实失败项可点**(单测覆盖);指标条"失败 1"是旧 `artifact.fetch` 死信遗留。
5. 自管逻辑备份**不能替代 PITR**(RDS 控制台那条本期不做)。