mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-11 05:26:15 -08:00
60 lines
4.6 KiB
Markdown
60 lines
4.6 KiB
Markdown
# 文档站 console.js 的兼容迁移边界
|
||
|
||
SITE-07 先冻结原始 bundle 和浏览器契约，后续实现由 SITE-CONSOLE-01 负责。
|
||
不能将 consoleLog 替换成一个只打印字符串的新面板，就声称旧接口已兼容。
|
||
|
||
## 已核实的现状
|
||
|
||
- 原文件最后修改于提交 5d6b2f22bc75213ac97cff0bcffa4a1ce2bc786c，2021-11-30。
|
||
- 340,306 字节，102 个 Parcel 模块；所有静态依赖表条目都指向该 bundle 内的模块。
|
||
- Focm 是自有安装入口，W5CS 是自有 React 控制台视图，其余模块须继续溯源。
|
||
- 实际全局包括 React、ReactDOM、consoleLog 和 parcelRequire。React/ReactDOM
|
||
均为 17.0.2，styled-components bundle 声明版本 5.3.3。
|
||
- console-feed 的包版本不能只凭年代推定；npm 当时最新版本 3.2.2 是待比对候选，
|
||
本批没有确认它就是当前捆绑版本，也没有确认全部传递依赖的版本与许可。
|
||
- 原末尾指向不存在的 /index.js.map。原始 bundle 和模块指纹见
|
||
[冻结来源](baselines/site-console-inventory.json)。
|
||
|
||
## 必须保留或明确验证的契约
|
||
|
||
| 边界 | 已有行为与迁移要求 |
|
||
| --- | --- |
|
||
| URL / 全局 | 保留 /assets/js/console.js、React、ReactDOM、consoleLog 及现有 Parcel 加载器的调用兼容；不得混入根工程 React 19 导致两份 React 冲突 |
|
||
| 返回值 | consoleLog(element) 返回 React 组件实例；重复挂载同一元素复用实例和 hook，不能改成 void 或全新句柄 |
|
||
| 实例接口 | add、onClear、onMouseEnter、onMouseLeave、render 等已有方法及 logs/hover 状态必须评估和测试 |
|
||
| DOM/CSS | console-header、console-header-number、console-header-right、console-component；保留 Clear、计数、滚动、悬停暂停及对象检查能力 |
|
||
| 数据 | 日志顺序、等级、普通对象/循环引用、错误、console 原方法转发与返回行为；不要把对象提前 stringify |
|
||
| 生命周期 | 多个容器、同容器重复挂载、卸载顺序、待处理日志和滚动、外部 console 包装者、页面切换/恢复 |
|
||
| 依赖 | 自有 TS 模块与第三方运行时代码分开；冻结来源/许可和可复现构建，不把 minified vendor 改名为 TS |
|
||
|
||
冻结文件 [console-original.js](baselines/site-vendor/console-original.js) 仅作为旧行为
|
||
对照，不进入站点分发。测试校验其 SHA-256；后续不得覆盖旧文件来制造差分通过。
|
||
|
||
## 已复现、尚未修复的问题
|
||
|
||
1. **CONSOLE-SCROLL-01**：add 安排 200ms 滚动回调；卸载后未取消，回调仍访问已移除
|
||
视图。使用真实定时器、原 ReactDOM 卸载和 DOM 验证，三个引擎均可复现。
|
||
2. **CONSOLE-OWNERSHIP-01**：两个容器挂载会相互包装同一个全局 console；卸载第一个
|
||
时 Unhook 读取的是第二个写入的 pointers，导致仍存在的视图停止收到日志。
|
||
3. **CONSOLE-ERROR-01**：console-feed 的 error 解析分支取参数的 stack；Firefox 和
|
||
WebKit 的原生 Error.stack 不含 message，界面丢失消息。Chromium 为有消息的对照。
|
||
普通对象保留引用，但 Error 已被旧 parser 转成字符串，不能误称仍保留 Error 身份。
|
||
|
||
## 实施顺序
|
||
|
||
1. 从已冻结自有入口/视图恢复可维护 TS，拆开安装、日志订阅/状态、视图与资源清理。
|
||
结合固定第三方边界建立构建/check，保留旧入口和已观测全局，不引入 React 版本混用。
|
||
2. 单一 owner 管理 console hook 的订阅者与原方法恢复，处理多容器和外部包装者；
|
||
取消滚动及过期更新，避免卸载后继续触碰 DOM。不得用永久吞掉异常绕过释放问题。
|
||
3. 修复原生 Error 消息丢失，同时保留堆栈、普通对象和非错误日志语义；先建立候选
|
||
失败回归，再实现。不要把普通 Error 统一转换成无堆栈的字符串。
|
||
4. 对照旧版执行接口/DOM/滚动/多容器/卸载矩阵，验证实际编辑器、Run/切换/页面恢复。
|
||
检查构建字节和依赖隔离，并完成包内架构、问题、生成说明。
|
||
5. SITE-07 继续完成全部第三方来源/版本与完整许可。来源未确认时不得关闭 VENDOR-08；
|
||
旧 vendor 的冻结不等于许可审查通过，也不等于完成其可复现来源恢复。
|
||
|
||
当前 [site-console.spec.js](../test/browser/site-console.spec.js) 含两种输入的共同
|
||
行为，以及三个仅指向冻结旧版的问题复现。历史问题用例通过意味着问题仍可复现，
|
||
**不意味着候选已修复**。SITE-CONSOLE-01 必须新增候选“无泄漏/不丢日志/错误消息可见”
|
||
断言并通过；不得将历史缺陷断言移用为候选验收标准。
|