lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
afb2a5b8a0ab4234034ff1f592e4e881cb2e072c
mnote/design/old/08-legacy-rust-kernel/done/release-readiness-source-audit.md
T

9.8 KiB
Raw Blame History

[recycle] 发布前源代码审计

更新时间：2026-04-16

审计范围：/mnt/Data1T/mnote

1. Bridge 入口与日志回查

1.1 最小查询与写入入口

当前已确认的 bridge 主线入口：

  • 查询：
    • src/app/api/documents/content/route.ts
    • src/app/api/documents/meta/route.ts
    • src/app/api/sidebar/route.ts
  • 写入：
    • src/app/api/documents/title/route.ts
    • src/app/api/documents/stats/route.ts
    • src/app/api/documents/options/route.ts
    • src/app/api/documents/save/route.ts
    • src/app/api/blocks/patch/route.ts
    • src/app/api/onlyoffice/callback/route.ts

1.2 日志与事件落账

当前已确认：

  • src/lib/documents/metadata-command-adapter.ts 成功路径会调用 recordBridgeCommandArtifacts
  • src/lib/documents/save-command-adapter.ts 成功路径会调用 recordBridgeCommandArtifacts
  • src/app/api/blocks/patch/route.ts 成功路径会调用 recordBridgeCommandArtifacts
  • src/lib/documents/media-asset-command-adapter.ts 会在 ONLYOFFICE callback 成功写回后尝试复用同一 bridge log 落账
  • src/lib/documents/bridge-log.ts 会同时写入：
    • bridgeLogs.recordCommandLog
    • bridgeLogs.recordDomainEvent
  • 回查入口：
    • src/app/api/bridge/request/route.ts -> bridgeLogs.listByRequest
    • src/app/api/bridge/trace/route.ts -> bridgeLogs.listByTrace

结论：

  • bridge 的最小查询、最小写入、日志生成、事件生成和错误返回已经形成源码闭环。

2. 保存口径审计

当前正文与页面元信息主写链如下：

  • documents.save -> api.documents.updateContent
  • documents.title.update -> api.documents.updateTitle
  • documents.stats.update -> api.documents.updateStats
  • documents.options.update -> api.documents.updateOptions
  • blocks.patch -> 读取文档内容后回写 api.documents.updateContent

OnlyOffice 写回：

  • src/app/api/onlyoffice/callback/route.ts -> media.assets.replace_storage -> api.mediaAssets.replaceStorageFromUpload

结论：

  • 页面正文、页面元信息、块补丁与 OnlyOffice 附件写回最终都以 Convex mutation 为主事实写入点。
  • 当前未发现把页面/块主真相改写到 mnote-rust、本地缓存目录或其他派生目录的主写链。

3. trace_id / request_id / workspace_id / page_id 一致性

3.1 前端与 route

  • buildDocumentBridgeContext() 统一生成 requestId、traceId、workspaceId
  • buildDocumentBridgeContextWithActor() 可为 ONLYOFFICE callback 这类无用户 cookie 的服务端回调显式注入 actor/source
  • buildDocumentCommandEnvelope() 统一挂载 commandId、target.pageId
  • documents.title/stats/options/save 均将 normalizedDocumentId 作为 target.pageId
  • onlyoffice/callback 会把 asset.document_id 作为 target.pageId，并透传 workspaceId

3.2 日志落账

  • recordBridgeCommandArtifacts() 使用同一 context.requestId、context.traceId
  • workspaceId 统一取 target.workspaceId 或 context.workspaceId
  • targetPageId 统一落到 command log
  • domain event payload 同时记录 request_id、trace_id、command_id、command_name

3.3 当前辅助验证

  • src/lib/documents/bridge.test.ts 已覆盖：
    • target.pageId = doc_1
    • executeSaveBridgeCommand 成功路径会调用 recordBridgeCommandArtifacts
    • 返回结果保留 req_1、trace_1
  • src/app/api/onlyoffice/callback/route.test.ts 已覆盖：
    • callback 成功路径会调用 executeMediaAssetWritebackBridgeCommand
    • storageId、assetId、documentId、workspaceId 会进入 media.assets.replace_storage envelope

结论：

  • trace_id、request_id、workspace_id、page_id 在 route、adapter、bridge log、回查入口之间已有统一口径。

4. 禁止事项复查

4.1 不双仓并行

  • 主仓脚本与文档已统一指向 /mnt/Data1T/mnote
  • wolai-frontend/src、wolai-frontend/convex、rust/ 下未发现直接依赖 /mnt/Data1T/mnote-rust 的运行时代码路径

4.2 不跨仓链接

  • 排除 node_modules、.next、.venv、rust/target 等构建产物后，主仓源码范围内未发现跨仓符号链接

4.3 不复制第二套产品前端壳

  • 主仓保留的是既有 wolai-frontend 主壳
  • 历史仓对象页壳与第二套 sidebar 仅在文档中被标记为禁止误复制范围

4.4 不把对象页壳 / diagnostics / smoke 页带入主线

  • 当前主仓 wolai-frontend/src/app 下未发现新增的 diagnostic / smoke 页面目录
  • 历史仓相关页面已在边界文档中明确列入禁止误复制清单

4.5 不散落多个 Rust 源码根

  • 主仓顶层 Cargo.toml 仅存在 rust/Cargo.toml
  • 其余 crate Cargo.toml 均位于 rust/crates/*

5. 运行态复核结果与最终结论

本审计只能关闭源码可验证项，但截至 2026-04-16，发布前运行态复核已经补齐五条直接证据：

  • 已复跑 scripts/task019-document-ui-regression.js，文档页标题、正文、保存、刷新、回查链通过。
  • 已复跑 scripts/task021-mindmap-ui-regression.js，Mindmap 全屏页的新增子节点、删除子节点、保存链、刷新回查与 requestId/traceId 元信息同步通过。
  • 已复跑 scripts/task022-onlyoffice-ui-regression.js，ONLYOFFICE 9.3.1 基线下的打开、插件桥、callback 写回、forcesave 与 storage_id 变化通过。
  • 已通过 pnpm exec vitest run src/lib/ai-agent/runtime/runAgent.test.ts，补齐 docs_search -> docs_read 的 AI runtime 调用证据。
  • 已通过 bash /mnt/Data1T/mnote/rust/scripts/task049-cli-smoke.sh，补齐 CLI 主链的最小真实执行验收。

当前已不再存在阻塞发布的 CLI / AI 运行态尾项。

补充核验结果：

  • cargo test --manifest-path /mnt/Data1T/mnote/rust/Cargo.toml -p mnote-cli -p bridge-runtime 已通过。
  • wolai-frontend 相关定向 eslint 当前无 error，仅剩仓库既有 warnings，不构成本轮发布阻塞。

仍然要求环境满足的前置条件：

  • 浏览器回归环境可访问 http://127.0.0.1:3000
  • MNOTE_ONLYOFFICE_PROBE_DOCX=/tmp/mnote-onlyoffice-probe/probe.docx 可用
  • 已登录态可通过 /auth 或测试账号快速登录建立

6. 旧 TS 执行面割接清单

当前源码审计之外，还需要看“哪些 TS route 还能留，哪些只是历史兼容”。

本轮已新增：

  • /mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md

该文档已把主仓当前执行面明确分成四类：

  • RUST_OWNER
  • TS_TRANSPORT_KEEP
  • TS_COMPAT_PENDING
  • TS_LEGACY_DELETE

其中当前仍需要长期观察但不再构成主链阻塞的旧面主要包括：

  • src/app/api/documents/embed/route.ts
  • src/app/api/mindmap-ai/**

其中页面旧面在 2026-04-16 的最终口径如下：

  • src/app/api/documents/create-child/route.ts 已改走 documents.create
  • src/app/api/documents/empty-trash/route.ts 已改走 documents.emptyTrashByWorkspace
  • src/app/api/documents/purge/route.ts 已改走 documents.purge
  • src/app/api/documents/template/route.ts 已改走 documents.template
  • src/app/api/documents/embed/route.ts 已改走 documents.save，但目标页面插入位与 pageReference block 组装仍在 TS，因此继续按 TS_COMPAT_PENDING / 产品编排壳维护
  • src/app/api/mindmap/[docId]/route.ts 与 src/app/api/mindmap/[docId]/[mindmapId]/route.ts 的 DELETE/PATCH 已改走 mindmaps.delete/restore/purge
  • src/app/api/mindmap-trash/empty/route.ts 已改走 mindmaps.emptyTrashByWorkspace
  • src/app/api/blocks/* 现网主链实际统一走 src/lib/blocks/block-command-adapter.ts；src/lib/documents/block-command-adapter.ts 应视为遗留兼容 helper，而非现网主执行面
  • src/app/api/ai-agent/run/route.ts 的核心工具主链现在已经统一走 Rust tool runtime：docs_search、docs_read、search_web、image_read、slash_run 不再保留 TS 真执行兜底

结论：

  • 当前可以说“Rust 已成为 mnote 的主业务执行平面”。
  • 仍保留的 TS 路径只剩 TS_TRANSPORT_KEEP、少量 TS_COMPAT_PENDING 产品编排壳与冻结的 TS_LEGACY_DELETE 清单。
  • 第一批 TS_LEGACY_DELETE 已不再阻塞这轮 release readiness；它们现在的要求是“保持纯壳 / 冻结 helper，不允许反向长出新的业务规则”。

最终 release readiness 口径：

  • 若按源码审计口径：可以说明“Rust 已成为 mnote 的唯一业务执行平面”，同时明确仍保留 TS_TRANSPORT_KEEP 与少量产品编排壳。
  • 若按完整发布口径：文档页、Mindmap、OnlyOffice、AI runtime、CLI smoke 的 Phase 8 scoped gate 已闭合，可以给出最终完成结论。
  • 后续维护口径：剩余 TS_TRANSPORT_KEEP / TS_LEGACY_DELETE 只属于长期清理与边界维护，不再构成第二套业务执行平面。

补记：

  • 2026-04-15 已复跑 scripts/task019-document-ui-regression.js，确认文档页标题、正文、保存与刷新回查通过。
  • 2026-04-15 已复跑 scripts/task021-mindmap-ui-regression.js，确认新增/删除节点、保存链、刷新回查与 requestId / traceId 元信息同步通过。
  • 2026-04-15 已复跑 scripts/task022-onlyoffice-ui-regression.js，在升级后的 ONLYOFFICE 9.3.1 基线上确认 oo_insert_text 插件桥、同步保存、callback 写回与 storage_id 变化仍然通过；本次 callback 最终写回已不再由 route 直接调用 api.mediaAssets.replaceStorageFromUpload，而是先经 media.assets.replace_storage bridge 命令再落到 Convex。
  • 2026-04-16 已通过 src/lib/ai-agent/runtime/runAgent.test.ts，确认 docs_search -> docs_read 的运行态工具链顺序、事件流与结果归一化闭合。
  • 2026-04-16 已通过 rust/scripts/task049-cli-smoke.sh，确认 sidebar/page/block/search/tool/mindmap 主链 CLI 真实执行闭合。
Reference in New Issue View Git Blame Copy Permalink