From f0e0d7ad1affc1fcda54adccc874c8b67ba60cb8 Mon Sep 17 00:00:00 2001 From: aurora-admin Date: Fri, 11 Sep 2026 22:50:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20ROADMAP=20=E7=BB=86=E5=8C=96=EF=BC=88P4?= =?UTF-8?q?=20=E4=BE=9D=E8=B5=96=E5=88=86=E6=9E=90=20/=20P2=20=E5=89=8D?= =?UTF-8?q?=E7=BD=AE=E9=AA=8C=E8=AF=81=20/=20=E6=89=A7=E8=A1=8C=E7=8A=B6?= =?UTF-8?q?=E6=80=81=E6=80=BB=E8=A7=88=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 趁执行模型未到，把规划里最可能导致走弯路的两个任务细化到函数级。 P4 依赖分析（关键） - 实测 app.js 有 10 处消费 c.sources，分三类： · 类别 A（难点 2 处）：extractComponentAPI / extractScenarios 是 渲染期同步解析源码，改 fetch 会波及详情页渲染流程 · 类别 B（易改 3 处）：Playground / 代码展示 · 类别 C（易改 2 处）：可用性判断，可用轻量字段替代 - 给出解法：把解析产物预计算进 data.js，这两个函数不再需要源码 - 体积成本实测：1.0 KB（原估 < 30KB，乐观 30 倍），净减 887 KB - 附三阶段执行建议（先预计算+跑回归，再分离源码，最后验收） P2 前置验证 - npm 可用：v11.17.0 - 包名 aurora-admin-design：registry 查询未被占用 - colors_and_type.css 含 :root 与 75 令牌，可直接作 dist 令牌源 新增「执行状态总览」 - 12 个任务的状态矩阵（已完成/可开工/待依赖） - 当前 4 个可开工：P2、P3、P4、P7（后两个优先级低） - 推荐顺序与理由：P3 第一（唯一让后续改动自动受保护的任务）、 P4 第二（收益成本比最高） - 指出并行机会：P2 与 P4 互不阻塞 新增「规划修正记录」 - 5 条已发生的规划修正，全部以实测为准 - 建立机制：执行中发现规划与实际不符时在此登记，不悄悄改 规划文档完整度：9 个章节齐全 / 1030 行 / 13 个任务包 回归：100%（961 断言 / 0 失败 / 79 页全通过） --- ROADMAP.md | 135 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 115 insertions(+), 20 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 506bb1f..f396945 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -222,6 +222,15 @@ README OK **依据**：G2。当前用户只能 clone 整个仓库（5.1MB git + 2.6MB site），对"只想用几个组件"的人成本过高。 +**前置验证已完成**（规划阶段实测）： + +| 假设 | 结果 | +|---|---| +| npm 可用 | ✅ v11.17.0 | +| 包名 `aurora-admin-design` 是否被占用 | ✅ **未被占用**（registry 返回 `{"error":"Not found"}`） | +| `colors_and_type.css` 可否直接作 dist 令牌源 | ✅ 含 `:root`、75 个令牌，可直接用 | +| 零依赖约束下能否构建 dist | ✅ Node 内置能力足够（读写文件 + JSON） | + **依赖**：S1-P1（package.json 需声明 `license` 字段）。 **路径**： @@ -407,12 +416,67 @@ components[] 内部（单组件） - 新增：把每个组件的 5 端源码写到 `site/sources//.txt`（kind ∈ html/css/jsx/vue2/vue3） - 修改：`data.js` 里 `components[].sources` 改为 `sourcesRef: "sources//"`（只留路径，不留内容） - **保持 `data.json` 完整**（For Agents 页承诺"一次请求拿到全部"，不能破坏 —— 这是硬约束） -2. **改造 `app.js`**： - - 详情页渲染代码区时 `fetch('sources//.txt')` - - 加 loading 态（复用现有 `.demo-code` 样式） - - 加失败兜底（fetch 失败显示"源码加载失败"+ 重试按钮，不留空白） +2. **改造 `app.js`（见下方「已完成的依赖分析」）** 3. **验证 For Agents 承诺未破**：`data.json` 仍然包含完整 `sources`。 +##### 已完成的依赖分析（执行前必读） + +`app.js` 里有 **10 处**消费 `c.sources`，分三类，改造难度不同： + +**类别 A · 渲染期同步解析（难点，2 处）** + +| 位置 | 函数 | 用途 | +|---|---|---| +| `app.js:969-971` | `extractComponentAPI(c)` | 从 vue3/vue2/jsx 源码正则提取 Props/Events/Slots | +| `app.js:1544` | `extractScenarios(c)` | 从 html 源码提取 `

` 场景标题 | + +这两个函数**在渲染详情页时同步调用**，依赖源码字符串立即可用。改成 fetch 后必须处理异步。 + +**推荐解法**：把「源码解析」的产物**预计算进 data.js**，而不是运行时 fetch 后再解析。 + +- `build-site.ps1` 已经能读源码 → 顺手把 `extractComponentAPI` / `extractScenarios` 的**结果**写进 `data.js` +- `app.js` 改为直接读预计算结果，**这两个函数不再需要源码** +- 源码 fetch 只服务「代码展示」这一处需求 + +**体积成本已实测**（规划阶段验证过）： + +``` +API 表（79 组件） : 0.2 KB +场景标题（79 组件） : 0.9 KB +合计新增 : 1.0 KB +sources 移除后节省 : 888 KB +净减少 : 887 KB +``` + +预计算产物只占 **1 KB**（原估 < 30KB，实测乐观 30 倍），代价可忽略。 + +这样做的好处：① 消除两处异步改造；② 解析逻辑从浏览器移到构建期（更快）；③ 详情页首屏不再等源码下载。 + +**类别 B · 代码展示（3 处，易改）** + +| 位置 | 用途 | +|---|---| +| `app.js:1635` | Playground textarea 初值 | +| `app.js:1667` | Playground 复位 | +| `app.js:1714/1722` | 代码区高亮渲染 | + +改法：进详情页时 `Promise.all` 拉当前组件 5 个源码文件（或按需拉 tab 切换的那一个），拿到后填充。加 loading 占位。 + +**类别 C · 判断可用性（2 处，用元数据替代）** + +| 位置 | 用途 | +|---|---| +| `app.js:1703-1704` | 判断哪些端有源码（决定 tab 显示） | +| `app.js:1720` | 复制按钮取当前 tab 源码 | + +改法：`data.js` 保留一个轻量字段 `sourcesAvailable: ["html","css","jsx","vue2","vue3"]`（79 × 5 个字符串，< 5KB），替代 `sources[k] != null` 的判断。复制按钮改为从已缓存的 fetch 结果取。 + +##### 分阶段执行建议 + +1. **阶段 1**：`build-site.ps1` 预计算 API/场景 → 写入 `data.js`；`app.js` 改读预计算结果。此时 `sources` 仍完整（先不瘦身），跑回归确认无回退。 +2. **阶段 2**：`build-site.ps1` 分离源码到文件 + `data.js` 只留 `sourcesRef` 与 `sourcesAvailable`；`app.js` 改 fetch。 +3. **阶段 3**：跑验收 + 浏览器实测（含断网兜底）。 + **验收**： ```bash # 1) 体积达标（实测应约 110KB） @@ -915,21 +979,52 @@ figma export OK --- -## 附 · 优先级总表 +## 附 · 执行状态总览 -| ID | 任务 | 阶段 | 优先级 | 预算 | 依赖 | -|---|---|---|---|---|---| -| P1 | LICENSE | S1 | **P0** | 10 min | 用户确认类型 | -| P2 | npm 分发 | S1 | **P0** | 2 h | P1 | -| P3 | CI 回归 | S1 | **P0** | 1.5 h | — | -| P4 | `data.js` 瘦身 | S1 | **P0** | 3 h | — | -| P5 | 暗色模式 | S2 | **P0** | 1 d | P4 | -| P6 | 跨端一致性验证 | S2 | **P0** | 1 d | P3 | -| P7 | 行为断言 | S2 | P1 | 1.5 d | — | -| P8 | RTL | S3 | P1 | 2 d | P5 | -| P9 | FAQ 页 | S3 | P2 | 1 d | — | -| P10 | Figma 资源 | S4 | P2 | 2 d | P2 | -| P11 | 模板页库 | S4 | P2 | 2 d | — | -| P12 | 版本发布流程 | S4 | P3 | 1 d | P2 | +> **执行模型看这里**：找下一个可开工的任务。状态为「待开始」且依赖已满足的最优先任务就是你的目标。 + +| ID | 任务 | 阶段 | 优先级 | 预算 | 依赖 | 状态 | +|---|---|---|---|---|---|---| +| P1 | LICENSE | S1 | **P0** | 10 min | — | ✅ **已完成**（MIT） | +| P2 | npm 分发 | S1 | **P0** | 2 h | P1 ✅ | 🟢 **可开工**（前置验证已过：包名可用、npm 可用） | +| P3 | CI 回归 | S1 | **P0** | 1.5 h | — | 🟢 **可开工**（无依赖，与 P2 并行） | +| P4 | `data.js` 瘦身 | S1 | **P0** | 3 h | — | 🟢 **可开工**（依赖分析已完成，见任务包内） | +| P5 | 暗色模式 | S2 | **P0** | 1 d | P4 | ⚪ 待 P4 | +| P6 | 跨端一致性验证 | S2 | **P0** | 1 d | P3 | ⚪ 待 P3 | +| P7 | 行为断言 | S2 | P1 | 1.5 d | — | 🟢 可开工（优先级低于 P2-P4） | +| P8 | RTL | S3 | P1 | 2 d | P5 | ⚪ 待 P5 | +| P9 | FAQ 页 | S3 | P2 | 1 d | — | 🟢 可开工（优先级低） | +| P10 | Figma 资源 | S4 | P2 | 2 d | P2 | ⚪ 待 P2 | +| P11 | 模板页库 | S4 | P2 | 2 d | — | 🟢 可开工（优先级低） | +| P12 | 版本发布流程 | S4 | P3 | 1 d | P2 | ⚪ 待 P2 | + +### 推荐执行顺序 + +``` +P3（CI，无依赖最快见效） + → P4（瘦身，收益最大） + → P2（分发，解除交付阻塞） + → P5 + P6（可信度双支柱） + → P7 → P8 → P9 → P10 → P11 → P12 +``` + +**为什么 P3 排第一**：它是唯一能让后续所有改动**自动受保护**的任务 —— 有了 CI，其他任务的质量不再依赖人工记得跑回归。 + +**为什么 P4 第二**：实测净减 887 KB（991KB → ~110KB），收益/成本比最高，且依赖分析已完成。 + +**并行机会**：P2 与 P4 互不阻塞，可由两个模型同时做。P3 完成后应立即合并，让后续任务都在 CI 保护下。 + +--- + +## 附 · 规划修正记录 + +> 执行中发现规划与实际不符时，**以实测为准**，在此登记。 + +| 日期 | 任务 | 规划原写 | 实测 | 处理 | +|---|---|---|---|---| +| 2026-09-11 | P4 | `data.js` 目标 < 400 KB（推测 `sources` 是最大头） | `sources` 实测占 **89.6%**（888KB/991KB）；拆出后可达 **~110KB** | 目标改为 < 150 KB，策略与体积数据全部替换为实测 | +| 2026-09-11 | P4 | 预计算 API 表估算 < 30 KB | 实测 **1.0 KB**（比估算乐观 30 倍） | 更新为实测值 | +| 2026-09-11 | P2 | 包名可用性未知 | registry 查询：`aurora-admin-design` **未被占用** | 补入「前置验证已完成」 | +| 2026-09-11 | P4 | 只说「改成 fetch」，未识别难点 | `app.js` 有 **10 处**消费 `sources`，其中 2 处是**渲染期同步解析** | 补入「依赖分析」与三阶段执行建议 | +| 2026-09-11 | P2/P4 | 验收命令有 3 处会误判（npm 不可用时误报 OK 等） | 实测触发 | 已改写为显式判断 exit code | -**建议执行顺序**：P1 → P3 → P4 → P2 → P5 → P6（前六个是「可交付」与「可信」的地基）