root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ROADMAP 细化（P4 依赖分析 / P2 前置验证 / 执行状态总览）

Browse Source 
趁执行模型未到，把规划里最可能导致走弯路的两个任务细化到函数级。

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 页全通过）
This commit is contained in:
aurora-admin
2026-09-11 22:50:11 +08:00
parent dd1e306c86
commit f0e0d7ad1a
1 changed files with 115 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ROADMAP.md
+115 -20
View File
@@ -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/<slug>/<kind>.txt`（kind ∈ html/css/jsx/vue2/vue3）
- 修改：`data.js` 里 `components[].sources` 改为 `sourcesRef: "sources/<slug>/"`（只留路径，不留内容）
- **保持 `data.json` 完整**（For Agents 页承诺"一次请求拿到全部"，不能破坏 —— 这是硬约束）
2. **改造 `app.js`**：
- 详情页渲染代码区时 `fetch('sources/<slug>/<kind>.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 源码提取 `<h2>` 场景标题 |
这两个函数**在渲染详情页时同步调用**，依赖源码字符串立即可用。改成 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（前六个是「可交付」与「可信」的地基）