Files
knowledge-governance/docs/USER_FLOWS_ACCEPTANCE.md
T
姚章浩 134da985fa 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 空 三项待办
2026-10-10 10:23:51 +08:00

18 KiB
Raw Blame History

用户操作流程与验收清单

按流程逐项验收用。每条给出:入口 → 用户步骤 → 期望 → 验收证据 → 状态。 状态标记:✅ 已实测(附证据)|⏳ 待验收|⚠️ 已知限制。 深度细节见各自专题文档(P3…/P5…/P6…/P8…/PRODUCTION_BACKUP_RECOVERY.md/WIKI_CO_TRANSPORT…)。

统一入口:http://127.0.0.1:8088/(测试栈;右侧面板可直接操作)。角色:管理员 / 文档工程师 / 只读。


A. 内容进入

A1 取件(钉钉知识库 / PP 清单)

  • 入口:来源与目录 → 内容来源(勾选条目;钉钉扫码会话失效时先刷新会话——注意:走 dws 取件后钉钉这条不再依赖浏览器会话)
  • 步骤:选来源 → 展开目录 → 勾选 → 取件(后台入队)
  • 期望:解析监控出现"处理中";失败进死信,可重排
  • 证据:解析监控 → 死信 队列;重排轮次键 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;仅可重试错误回落老路径)。
  • 路由:adoc→doc export docx;axls→sheet 读取转 xlsx;其余→drive 直下;dlink/hlink→missing;amind/appt→unsupported(详见 docs/DINGTALK_DWS_FETCHER.md)。
  • 平台侧判定全部保留:后缀路由、PPT 必须 PDF 双胞胎、magic、大小上限、sha256、spool 原子写、空壳检查 → dws 只负责"取字节"。
  • 本人复核(2026-10-09,在已部署 worker 内):
    • 接线:dws v1.0.63(Edition: open)在 /usr/local/bin/dws;DWS_HOME=/data/home、DWS_CONFIG_DIR=/data/dws、DWS_DISABLE_KEYCHAIN=1;宿主两份 state 已按文档挂载 ✓
    • 鉴权(必须带 HOME=DWS_HOME,直接 docker exec dws 会误报"未登录"):authenticated:true、refresh_token_valid:true、refresh_expires_at 2026-11-08、账号 姚章浩 / 深圳市越疆科技股份有限公司 ✓
    • 真实调用:dws wiki +space-list --limit 1 → ok:true,返回"公司级技术支持知识库" ✓
    • 回归测试:artifact_fetch_test.py 18 项、test_dws_error_map.py 19 断言全绿 ✓
  • 运维依赖(验收时作为背景知识):
    • refresh token 30 天轮换:到期前 7 天按 runbook dws auth login --device 续期(本人浏览器授权);出现 code=credentials 立即停批,不要重试风暴,授权后 --retry-failed 续跑。
    • 在线文档并发建议 ≤4(当前 ingestion_concurrency=2 ✓ 满足);8 路混合时巨型文档曾现 export_failed(已判可重试)。
    • 回退开关:ARTIFACT_DINGTALK_FETCHER=legacy 可完全绕过 dws。
    • CI:Gitea Run #6/#7/#8 全 success(#8 = 含本清单的 b1b4ca5)✓

A2 标注与目录范围(路由到哪个库)

  • 入口:来源与目录 → 勾选 → 标记:对内 / 对外 / 不需要(目录级标记决定整目录)
  • 步骤:标注 → 生成修订
  • 期望:标记按 系统设置 → 测试知识库绑定 分发到对应测试库;不需要 不入库
  • 证据: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. 入库与监控

B1 待入库 → 开始处理 → 完成

  • 入口:文档工作台(待入库列表)→ 选中 → 开始处理
  • 期望:上传 → 解析 → 索引 → completed;目标库里能看到知识条目与 wiki 页
  • 证据:单文档 E2E tp-3056261d46396a0695497f38421346b3 → processing_state=completed;知识 cf0af40f-7c0c-4526-ad6a-4515b3b2ca00(4 chunks,wiki 9 页)
  • 证据(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 解析监控与补救

  • 入口:解析监控 → 处理中 / 需要你出手 / 需下架 / 死信 / 已完成 / 知识库差异 / 知识库解析进度
  • 步骤:看"需要你出手" → 重排失败项 / 处理需下架项
  • 期望:失败可重排;"需下架"列出仍留在库里的禁止项
  • 证据:死信与重排链路(cddc4c9)
  • 状态:✅ 链路|⚠️ "重排"按钮行为目前只有单测覆盖(页面当时无失败项可点)

C. 发布与回滚

C1 审核 → 密封 → 建批次 → 锁定

  • 入口:发布管理 → 创建草稿批次 → 密封 → 锁定
  • 期望:密封后批次不可改;锁定后才能授权生产发布
  • 证据:批次 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. 系统设置

D1 服务配置(测试 / 生产端点与 ID)

  • 入口:系统设置 → 服务配置(管理员)
  • 规则:只配四项(测试地址、生产地址、生产 ID、知识库 ID);保存时真探测,无效才拒;凭据只写不读
  • 状态:✅(见 P41/P42 与 ui_settings_* 测试)

D2 测试知识库绑定(对内 / 对外)

  • 入口:系统设置 → 测试知识库绑定 → 选库 → 保存绑定
  • 期望:保存立即生效并重排"还没上传"的待入库项;对内 ≠ 对外
  • 状态:✅ 本期实测

D3 生产知识库绑定(源库 → 目标库)

  • 入口:系统设置 → 生产知识库绑定 → 对内/对外各选一个生产库
  • 期望:发布写入被冻结到该项的 target_knowledge_base_id;未绑定时按同 ID 语义并在契约检查处失败关闭
  • 状态:✅(P8_PRODUCTION_KB_MAPPING_ACCEPTANCE.md;迁移 000044)

D4 存储与备份(整库逻辑备份的定时)★本期新增

  • 入口:系统设置 → 存储与备份(管理员)
  • 步骤:设置 定时时间 + 储存天数(+ 每月归档保留、启用开关)→ 保存并下发到主机;另可 重新下发当前设置 / 立即备份一次
  • 期望:保存即写库并下发到目标主机 cron;页面显示主机上实际生效的计划、cron 条目、最近一次备份与"已一致/待下发"
  • 证据(面板原文):目标主机 weknora-test · 已连接、主机 cron 服务 active、主机 cron 条目:30 03 * * * root /bin/bash /opt/weknora-test/logical-backup.sh >> …、主机上生效的计划 每天 03:30 · 保留 7 天 · 每月 3 份、与设置是否一致 已一致、最近一次备份 20261009T060736Z / 34 秒 · 742.7 MiB / 覆盖 8 库 / 失败 无
  • 实测改动往返:面板改 04:05 / 14 天 → 主机 /etc/cron.d/kb-logical-backup 变 05 04 * * *、参数文件 TIME=04:05 / KEEP_DAYS=14 ✓ → 再改回 03:30 / 7 天 → 主机 30 03 * * * ✓
  • 立即备份:按钮变"备份进行中…"→ 约 50 秒后自动刷出新结果(异步 202 + 在途单飞,重复点击不会跑两次)
  • 状态:✅ 2026-10-09 面板实测(写操作仅管理员:PUT/POST /api/v1/backup-schedule*)

D5 刷新策略

  • 入口:系统设置 → 刷新策略(文档工程师可改)
  • 期望:文档/资源刷新间隔、停滞判定、finalizing 时长;保存先验证再原子启用、旧版本留审计
  • 状态:✅(ui_settings 版本化激活测试)

D6 成员与角色

  • 入口:系统设置 → 成员与角色(管理员)
  • 期望:成员增删、角色(viewer/engineer/admin);管理员初始密码首登强改
  • 状态:✅(users 接口与角色网关)

E. 备份与恢复(运维流程)

E1 发布/导入前留档(PG 行 + ES 文档)

  • 入口:命令行 bash scripts/target_kb_snapshot.sh(默认云内执行)
  • 期望:$KB_BACKUP_ROOT/target-kb-snapshots/<UTC>-<kb8>/ 出现 8 张表 JSONL + es_documents.jsonl.gz + MANIFEST.json(sha256/每库 ES 计数) + export.sql + README.md
  • 证据:实测 2 分 52 秒(PG 8 表 44 秒;两库 ES 131,122 条 / 692 MB);PULL_ES=1 拉回本机 19 分 40 秒
  • 状态:✅ 2026-10-09 实测

E2 发布前硬门禁

  • 期望:写目标库之前必须存在覆盖该库、24h 内、PG 与 ES 两层齐备且哈希可校验的留档;否则 release_target_snapshot_missing(不可重试),目标库一行不碰
  • 证据:go run ./cmd/guardcheck backups/target-kb-snapshots <kb_id> → 两个绑定库 PASS、未绑定库 BLOCK;门禁单测 10 条
  • 状态:✅ 已上线(release-worker 已带此门禁)

E3 回填演练(证明"存了能回去")

  • 入口:python3 scripts/restore_drill.py --snapshot-dir <留档> --target-url <本地测试库>
  • 期望:行数与清单逐一致、抽样页面正文/标题逐字段相同、清理后残留 0
  • 证据:13,539 行全部回填成功;8 张表与清单逐一致、冲突 0、抽样页 388 字符一致、残留 0(实测值)
  • 状态:✅ 2026-10-09 实测

E4 整库逻辑备份(自管,落自己盘上)

  • 入口:主机 bash /opt/weknora-test/logical-backup.sh(手动)或按 D4 的定时
  • 期望:$KB_BACKUP_ROOT/rds-logical/<UTC>/<库>.dir(pg_dump -Fd -j4 -Z6)+ MANIFEST.json(含 failed_databases);按天轮转
  • 证据:33 秒 / 742.6 MiB / 214 文件 / 失败 0,覆盖 8 个库;RDS 管理库 rdsadmin 自动跳过;中断的运行改名 *.incomplete
  • 状态:✅ 2026-10-09 实测

E5 其余三层(现状)

  • ES 快照:仓库 kb_backup(宿主 $KB_BACKUP_ROOT/es-snapshots)+ SLM kb-hourly(3 天)/kb-daily(7 天);首个快照 36 秒 / 4.7 GB / 0 分片失败 ✅
  • OSS 版本控制:桶 dobot-weknora-test 已开启(覆盖/删除可按 VersionId 回滚)✅
  • RDS 托管备份:由控制在控制台自管(按你的决定:本期不做,不阻塞)⏳
  • 备份目录契约:scripts/backup_layout.sh 定义 /srv/kb-backups/{target-kb-snapshots,rds-logical,es-snapshots,logs},换主机(未来的生产云主机)跑同一份 ✅

F. 本期已知限制与边界(验收时不必当缺陷)

  1. ES 留档字节默认留目标主机(PULL_ES=0);异地副本不做(你的决定)。
  2. ES 快照仓与留档同机同盘:整机故障需靠 RDS 托管备份 + OSS 还原。
  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 控制台那条本期不做)。

验收建议顺序

  1. D4 存储与备份(本期新增,步骤最短、证据最全)→ 2. E1/E2/E3/E4(留档→门禁→回填→整库)→ 3. C2/C3(授权发布 → 回滚,需闸门开启)→ 4. B1/B2(入库与补救)→ 5. A1–A3、D1–D3、D5、D6(既有流程,按各自专题文档逐条核)。