# Next Session Pickup — v0.4.0 API 形态统一
> **用途**：新 session 起手直接读本文件接手 v0.4.0 主线。
> **前任**：[`next-session-pickup-2026-05-14-v0-2-0-publish.md`](next-session-pickup-2026-05-14-v0-2-0-publish.md) → 已过期（v0.2.0 / v0.3.0 都 ship 完了）
> **当前版本**：v0.3.0 ✅ shipped 2026-05-14（[retrospect](../retrospection/2026-05-14-v030-release.md)）
> **目标版本**：v0.3.0 → **v0.4.0**（minor，**含破坏性**）
---
## TL;DR
1. v0.3.0 主线 4 大块 + release wrap-up 全部 ship 完（commits `40e8c777` → `50d024e5`，8 commits）
2. **next 2 周可推进的 = v0.4.0**：Phase 6.6 双形态 API + Phase 6.7 Badge prop 拆分（**都是破坏性 API 改造**）+ 顺路 Tier 2-D
3. **总估时 ~12-18h**（按 tracker；按 v0.3.0 实跑 4-8x under-estimate 经验，实际可能更短）
---
## 1. 当前状态确认（起手必做）
按 SessionStart hook + STATUS.md §起手必读链路，**机械跑 5-step onboarding**：
```bash
# Step 0 — git baseline
git status --short # 应只有别 session 持续动的 .claude/settings.json
git log --oneline -5 # 顶部应是 50d024e5 docs(wrap-up): v0.3.0 ...
# 全 baseline green
pnpm test # 108 passed | 1 skipped
pnpm exec vue-tsc --noEmit # 0 错
pnpm run audit:translation-completeness # 9 findings / 0 active / 9 allowlisted
pnpm run prepublishOnly # 10 strict gates 全通过
```
任一不绿 → STOP 排查。
5-step onboarding 文档：
1. [`docs/STATUS.md`](../../STATUS.md) — v0.3.0 ✅ shipped，v0.4.0 active (2)
2. [`docs/PROJECT_GOAL.md`](../../PROJECT_GOAL.md) — 5 能力 + Quick Reference
3a. [`docs/internal/retrospection/design-spec-canonical-alignment-tracker.md`](../retrospection/design-spec-canonical-alignment-tracker.md) §排期原则 + v0.4.0 段
3b. **本文件**
4. [`AGENTS.md`](../../../AGENTS.md) 必读链路 §1-10
5. v0.4.0 各项的 spec — 见 §3 下面
---
## 2. v0.4.0 内容（tracker SoT）
| 项 | 估时 | 破坏性？ | 备注 |
|---|---|---|---|
| **Phase 6.6** FormItem.label + Tooltip.content 双形态 API | ~8-12h | 是 | string prop OR default slot 双形态 |
| **Phase 6.7** Badge prop 拆分 | ~4-6h | 是 | type → color + shape（同名异义 fix） |
| 顺路 **Tier 2-D** `scripts/new-backlog.mjs` ID generator | ~2h | 否 | 防 backlog ID collision |
**总估时**：~12-18h（按 tracker）。v0.3.0 实跑经验提示真实可能更短（4-8x under）。
**对齐能力**（PROJECT_GOAL）：
- Phase 6.6 → 能力 1（dev API 一致）+ 能力 2（AI 从 Figma URL 不撞双 API）
- Phase 6.7 → 能力 1（API 清晰）+ 能力 2（避免 type 同名异义）
- Tier 2-D → 工程基础设施
---
## 3. 各项 spec 真源
### 3.1 Phase 6.6 — 双形态 API
**真源**：[`src/design-system/translation/divergences.md`](../../../src/design-system/translation/divergences.md) §`## API 双形态映射`
**Decisions JSON**：[`divergences-decisions.json`](../../../src/design-system/translation/divergences-decisions.json) entries `formitem-label-dual-form` + `tooltip-content-dual-form`
**Scope**：
- `FormItem.label`：现 string prop → 加 default slot 支持（slot 优先 fallback prop）
- `Tooltip.content`：同上 → 加 default slot 支持
**实施位置**：
- `src/canonical/FormItem.vue` + `src/components/FormItem/FormItem.vue`
- `src/canonical/Tooltip.vue` + `src/components/Tooltip/Tooltip.vue`
**破坏性**：
- 旧 `label="..."` API 仍工作
- 新 default slot 可替代（如 `...` 或 ``）
- 旧 prop 仍兼容，**不删**（破坏性指 schema 扩张可能影响下游 type infer）
### 3.2 Phase 6.7 — Badge prop 拆分
**真源**：[`divergences-decisions.json`](../../../src/design-system/translation/divergences-decisions.json) `badge-api-split` entry
**背景**：Badge 当前 `type` prop 在 canonical (Black/Blue/Green/Orange/Red) 和 legacy (brand/red/orange/blue) 同名异义（颜色 vs 形状），Figma Type 才是形状（Circle/Rectangle）。
**Scope**：
- canonical `Badge.color` 保留（颜色枚举）
- canonical 新增 `Badge.shape: 'Circle' | 'Rectangle'`（对齐 Figma Type）
- 旧 `Badge.type` 标 `@deprecated`，保留一个版本（向后兼容）
- 下版本（v0.5.0 / v0.6.0）才真正删除
**实施位置**：
- `src/canonical/Badge.vue`（canonical 是 SoT）
- prop-aliases.json 加 entry 登记 type → color + shape 拆分
- 不动 `src/components/Badge/Badge.vue` legacy（用户已说 deferred）
### 3.3 Tier 2-D — `scripts/new-backlog.mjs` ID generator
**触发**：用户加 backlog entry 前 grep 所有已用 ID（Active + Resolved）→ 挑最大数字 +1
**真源**：memory [`feedback_backlog-id-collision.md`](memory)
**Scope**：CLI 工具 `pnpm run new-backlog [prefix]`（如 `CANONICAL` / `BRIDGE` / `INFRA`）输出下个可用 ID + 模板 stub。
---
## 4. v0.4.0 推荐路径
按 tracker §排期原则自检 + 文件冲突分析：
| 项 | 文件 | 冲突？ |
|---|---|---|
| Phase 6.6 FormItem + Tooltip | `canonical/FormItem.vue` + `canonical/Tooltip.vue` | 0 冲突 with Phase 6.7 |
| Phase 6.7 Badge | `canonical/Badge.vue` | 0 冲突 with 6.6 |
| Tier 2-D | `scripts/new-backlog.mjs`（新建） | 0 冲突 |
**3 个项 0 文件冲突，可并行**。但 plan owner 推**串行**：
1. Phase 6.6 先（unblock 面广 — FormItem 和 Tooltip 用得多，dev 直接受益）
2. Phase 6.7 后（Badge 单组件 + 已 deprecated 旧 type 兼容方案设计完成）
3. Tier 2-D 顺路（工程基础设施，~2h 顺手）
或全做完一起 release 也 OK。
---
## 5. Sprint 拆解建议
按 v0.3.0 Tier 1-A 4 sprint 范式（每 sprint 1 prompt fire executor，plan owner 复审 + commit）：
**Sprint A — Phase 6.6 FormItem.label 双形态**（~3-4h）
- Prompt：`docs/internal/_prompts/phase-6.6a-formitem-label-dual-form.prompt.md`
- Deliverable：FormItem.vue (canonical + base) + tests + prop-aliases entry 升级 status
**Sprint B — Phase 6.6 Tooltip.content 双形态**（~3-4h）
- Prompt：`docs/internal/_prompts/phase-6.6b-tooltip-content-dual-form.prompt.md`
- 同 A 但 Tooltip
**Sprint C — Phase 6.7 Badge prop 拆分**（~4-6h）
- Prompt：`docs/internal/_prompts/phase-6.7-badge-prop-split.prompt.md`
- Deliverable：Badge.vue + prop-aliases entry + @deprecated 标 type prop + tests
**Sprint D — Tier 2-D ID generator**（~2h）
- Prompt：`docs/internal/_prompts/tier-2d-backlog-id-generator.prompt.md`
- Deliverable：`scripts/new-backlog.mjs` + npm script + doc 加 usage
**Sprint E — v0.4.0 release wrap-up**（~30min）
- changeset + version bump + tag push + Packages 页 verify + STATUS / tracker / retrospect sync
---
## 6. Active 余量（v0.4.0 ship 后）
```
v0.4.0 minor (0 active): shipped
v0.5.0 minor (2): Phase 6.8 Button (DS 最大组件) Tier 1-B mockup audit
v0.6.0 minor (3): Tier 1-C ESLint plugin EXTRACT-006 CANONICAL-007
v1.0.0 stable (3): Tier 3-H axe-core Phase 8 (if Org plan) API lock
Infrastructure (5): F21-v2/v3/v4 F24 F25 (release-agnostic)
设计师 owner (5): BRIDGE-MOCKUP-001/002/003/005 BRIDGE-DESIGN-REVIEW
Deferred (3): T1c T4 Phase 8 (needs Org plan)
```
---
## 7. v0.3.0 累计 commits（context）
```
50d024e5 docs(wrap-up): v0.3.0 ✅ shipped + Tier 1-A 4 sprints + SoT drift retrospect
516d14ab release: v0.3.0
8ce29ac8 feat(phase-6.4): Input.showCount + Select.multiple/editable runtime additions
201895c4 feat(bridge-005): generator 加 booleanProperties 字段 + Radio.status axis skip fix
788f1be2 fix: SoT drift cleanup + audit dim 6 (active vs resolved cross-check) + 2 collateral
8534f01d feat(tier1a-sprint4): audit:translation-completeness + 10th strict gate + Tier 1-A 收尾
859c2ba5 feat(tier1a-sprint3): divergences md split → decisions JSON + 保留 narrative
76e99070 feat(tier1a-sprint2): prop-aliases md split → JSON + 瘦身 md
40e8c777 feat(tier1a-sprint1): axis-implementation-map md → JSON + schema
```
v0.3.0 完整复盘：[`2026-05-14-v030-release.md`](../retrospection/2026-05-14-v030-release.md)
---
## 8. 起手第一句话（用户对 Claude Code 说）
```
开始 v0.4.0 — 按 docs/internal/_plans/next-session-pickup-2026-05-15-v0-4-0.md 接手
```
或更短：
```
继续 v0.4.0 主线
```
新 session 起手会自动跑 SessionStart hook → 5-step onboarding → read 本文件 → 推荐 Sprint A (Phase 6.6 FormItem) 起步。