feat: migrate CN HTML API references

[Foesa-yyx]

Summary

This PR migrates the Chinese HTML API reference content into content/docs/zh-CN/api-reference on top of CN-NEWDOC.

It also brings in the shared HTML migration framework from the migration stack so CN-NEWDOC can rerun the conversion locally:

• shared migration framework and TypeDoc lane
• Doxygen/Javadoc lane, including helper/static page filtering and semantic rendering
• iOS doc-generator / appledoc / Jazzy lane
• Flutter Dartdoc lane
• validation matrix and rerunnable validation script

The Whiteboard Web reference was regenerated from shengwang-doc-source/html-docs/whiteboard/Web after the #715/#716 TypeDoc fixes. Detailed global property documentation, nested tables/lists, and valid heading depths are now preserved.

Migrated content

Migrated from the latest shengwang-doc-source release/prod legacy HTML sources into Chinese API Reference:

• IM: Flutter API reference
• Flexible Classroom: Android, Electron, Web, iOS API references
• IoT aPaaS: Android API reference
• Local Server Recording: Java and C++ API references
• RTC Server SDK: C++ and Java API references
• RTC: Android, C++, C# Windows, Electron, Flutter, HarmonyOS, React Native, React SDK, Unity, Unreal Blueprint, Unreal C++, Web, iOS, macOS, Mini Program
• RTSA: C and Java API references
• Whiteboard: Fastboard Android/iOS/Web plus Android SDK, iOS SDK, Web SDK reference pages

Out of scope and intentionally not migrated in this PR:

• REST/OpenAPI sources
• dummy-product

Migration script fixes

• Doxygen/Javadoc detection wins when a Doxygen tree also contains modules.html.
• TypeDoc declaration/property details preserve prose, ordered/unordered lists, and tables.
• TypeDoc presentation-only Optional badges are removed from headings.
• Dynamic generated headings are clamped to levels 1-6.
• Unrelated Dartdoc summary-list behavior was removed from this incremental fix.

Verification

• bun test scripts/html-to-md-migration.test.ts scripts/validate-html-api-migration.test.ts passed: 14 tests
• both migration scripts pass node --check
• Biome and git diff --check pass
• six-lane real-source validation passed with --no-compile
• test: validate generated HTML API migration lanes #704 full validation ran types:check against the same regenerated Whiteboard Web output
• no level-7+ headings exist in content/docs/zh-CN/api-reference/whiteboard/web
• Standards review: no findings
• Spec review: no findings
• bun run build was not run

Known blocker

#709 remains separate: three legacy first-party /api-ref/whiteboard/javascript/enums/cursornames.html#rectangle links are intentionally unchanged and must be handled by the legacy-link compatibility work rather than hardcoded into #715/#716.

2026-07-12 rerun

Re-ran the full CN HTML API reference migration on this PR branch against local legacy source shengwang-doc-source release/prod commit e6002e161 (Release 0.0.492).

Regenerated the committed Chinese API reference targets for IM Flutter, Flexible Classroom Android/Electron/Web/iOS, IoT aPaaS Android, Local Server Recording Java/C++, RTC Server SDK C++/Java, RTC Android/C++/C#/Electron/Flutter/HarmonyOS/React Native/React SDK/Unity/Unreal/Web/iOS/macOS/Mini Program, RTSA C/Java, and Whiteboard Android/Web/iOS.

Verification after rerun:

• bun test scripts/html-to-md-migration.test.ts scripts/validate-html-api-migration.test.ts passed: 14 tests
• bun run types:check passed
• helper/static page pollution scan passed
• invalid level-7+ generated heading scan passed

Note: refreshing shengwang-doc-source from GitHub failed locally with an SSL connection error, so this rerun used the existing local release/prod checkout at e6002e161.

[shczhen]

已完成 #723 最终修正（commit 1f713996）：

• 解析 DITA 根 index.html 的 <nav><ul class="map"> 与 topichead 包装层
• 按旧站功能 TOC 生成嵌套侧栏与目录
• 未列入主 TOC 的符号页面继续生成并保持原路由可访问，只从主侧栏隐藏
• 保留正文到符号页面的链接映射
• 重新生成 RTC Android/iOS current 产物

验证：迁移测试 13/13、bun run types:check、Biome、git diff --check 均通过；Standards 与 Spec 双轴复审均无阻塞项。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #724（commit bdf8ee4d）：Doxygen/Javadoc 生成的 helper/index 页面继续保留路由与交叉链接，但通过 lane 的导航分类从 meta.json 侧栏中隐藏。Whiteboard Android 的 annotated、classes、deprecated、examples、hierarchy、pages、dir-* 已不再进入 pages 数组；实际 class/interface/enum/API 页面不受影响。

验证：迁移测试 13/13、types:check、Biome、git diff --check 通过，Standards/Spec 双轴复审通过。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #725（commit f5f95253）：Doxygen 字母索引现在输出不可见 fragment target（如 <a id="letter_A"></a>）和可读的 ### A 分组标题，不再把 raw anchor 显示为代码标题；字母跳转与类链接均保留。

验证：迁移测试 13/13、types:check、Biome、git diff --check 通过，Standards/Spec 双轴复审通过。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #726（commit 866d77ff）：--version-dir 现在进入迁移目标路由，4.6.0 内链保留版本段，(current)/无版本继续使用 clean URL；同时归一化已提交的 RTC Android 4.6.0 产物。原始扫描 121 文件/3659 条错误链接已降为 0。

验证：迁移测试 14/14、types:check、Biome、git diff --check、Standards/Spec 双轴复审均通过。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #727（commit a1166dc8）：顶层 DITA related-links 现在会生成真实正文；源 HTML 本身无语义正文的 DITA/TypeDoc 叶子在规划阶段被移除并退出导航，空父节点有子页时降为合成目录页。已清理 4 个 TypeDoc 空 namespace 和 5 个 HarmonyOS 空 observer 页面；四个目标根目录的 frontmatter-only 扫描为 0。

验证：迁移测试 15/15、types:check、Biome、git diff --check、Standards/Spec 双轴复审均通过；未混入 #723 导航重排。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #728（commit 66ce46de）：确认旧源 rtc/React 实际为 Agora Web SDK API Reference v4.22.0，因此完整撤下错误发布的 rtc/react-sdk 内容及两处导航入口，没有通过改标题伪装 React 文档。迁移器新增写入前身份校验：--platform react-sdk 遇到 Web SDK 源会明确失败且不创建输出。

验证：迁移测试 16/16、types:check、Biome、git diff --check、Standards/Spec 双轴复审均通过。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #729（commit 8789bcd8）：安全解析 Doxygen onclick 中分段拼接的 mailto: 字符串，经邮箱格式校验后生成标准 mailto 链接；不执行 JavaScript、不猜测无效地址。16 个受影响页面的 24 行 nosp@m/空 # 邮箱链接已全部清零。

验证：迁移测试 16/16、types:check、Biome、git diff --check、Standards/Spec 双轴复审均通过；未改动 #724/#725 行为。PR 保持未合并，等待 doc team 测试。

[shczhen]

已修复 #730（commit cdc9bb88）：迁移器会折叠相邻重复 anchor，并用页面级唯一 ID 分配器为分离重复项稳定生成 -2/-3 后缀；即使源 ID 本身带后缀也不会碰撞，后续页内链接同步指向当前有效 ID。新增重复 anchor 验证门禁。现有 27 个页面的 123 个重复 ID 已清零。\n\n验证：专项测试 19/19、types:check、Biome、git diff --check、Standards/Spec 双轴复审均通过。PR 保持未合并，等待 doc team 测试。

[shczhen]

Issue #810/#815 的真实内容闭环测试已推送：86f298197。在本 PR 已发布的 Agora Chat Flutter 内容上，测试现在同时验证 send-message canonical route、source.getPage、server payload activePath、navScope 和仅限 Flutter 的局部侧栏；集成 10/10、nav-scope 10/10、types/Biome/diff check 通过。

[shczhen]

Issue #818 真实页面树回归已推送：241caf5ad。在既有通用根修复 d36689b95 上，新增 Android/iOS/Flutter/C++ 四个平台 class-rtcconnection 的局部 navScope 断言；14/14、Biome/diff check、Standards/Spec 复核均通过。旧关闭 PR #704 未改，待文档团队在本 PR 复测。

[shczhen]

Issue #819 已同步并真实发布：4f8b4dcee。用 817 个 legacy Dartdoc HTML 重跑后更新 85 个 summary index，canonical Flutter linked headings 1219 → 0；迁移测试 37/37、重复重跑 hash 一致、types/Biome/diff check、双复核通过。