diff --git a/docs/USER_FLOWS_ACCEPTANCE.md b/docs/USER_FLOWS_ACCEPTANCE.md index 8cb84eb..336bef9 100644 --- a/docs/USER_FLOWS_ACCEPTANCE.md +++ b/docs/USER_FLOWS_ACCEPTANCE.md @@ -16,6 +16,17 @@ - 期望:解析监控出现"处理中";失败进**死信**,可重排 - 证据:`解析监控 → 死信` 队列;重排轮次键 `artifact-fetch::r` - 状态:✅(死信重排修复 `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 控制台那条本期不做)。