# BRIDGE-005 — Figma boolean property 三层 schema 升级（generator + DocsFigmaMembers）

> **触发方式**：用户对 executor 说 `请按 docs/internal/_prompts/bridge-005-boolean-property-schema.prompt.md 执行`
> **角色**：executor
> **依赖**：
> - Tier 1-A 全 ship（commit `8534f01d`）+ Step 1-3.5 ship（`788f1be2`）
> - prop-aliases.json scope=boolean-property 18 entries 已 cover（Sprint 2 已落）
> - figma-mcp-cache/<comp>.tsx 已含 boolean property 类型定义（不需要重跑 extract）
> **完成后 STOP**，列改动 + 未解决项给 plan owner 复审

> ⚠️ **Plan owner baseline 后 scope 简化**（实跑前 backlog 估 6-10h；plan owner read mcp-cache + canonical + generator 后实估 ~3-5h）。如实际跑超 6h **STOP** 报告。

---

## 0. 起手 Pre-flight check

**Pre-flight 判断规则**（同 Sprint 3-4 范式）：

只有当**以下任意一项**为真时才 STOP：

1. 本任务输出路径已 dirty / exists：
   - `figma-sync/generate-docs-figma-members.mjs` already modified by uncommitted change
   - `figma-data/normalized/docs-figma-members/<comp>.ts` modified beyond expected regenerate（每个本任务跑前 expected 是已存在 → 跑完会更新）

2. 已 ship 产物被改动（回归风险）：
   - `src/design-system/translation/axis-implementation-map.json` modified
   - `src/design-system/translation/prop-aliases.json` modified（Sprint 2 已 cover boolean-property）
   - `src/design-system/translation/divergences-decisions.json` modified
   - `figma-sync/audit-translation-completeness.mjs` modified

3. baseline 不绿（见下）

**其它 dirty / untracked**（如 `.claude/`、`docs/STATUS.md`、`_metrics/phase0-ledger.md`、本 prompt 文件 untracked）与本任务无关，正常继续。

```bash
git status --short
git log --oneline -3
# 顶部应是 788f1be2 fix: SoT drift cleanup ... + 8534f01d Sprint 4

pnpm test                       # 105 passed | 1 skipped
pnpm exec vue-tsc --noEmit      # 0 错
pnpm run audit:translation-completeness  # ✅ 0 active findings (10th gate)
```

任一不绿 → **STOP**。

---

## 1. 任务摘要

升级 `figma-sync/generate-docs-figma-members.mjs`：

- **读** `figma-data/normalized/figma-mcp-cache/<comp>.tsx` 中 `type XxxProps = { ... }` 段
- **抽** boolean 类型 props（含 `?: boolean` / `: boolean`）
- **输出** `DocsFigmaMembers<T>` 的新字段 `booleanProperties` 含每个 boolean prop 的 figma name + canonical 映射（通过 prop-aliases.json scope=boolean-property 查 alias）
- **不动** axes 字段（已工作）/ variants / 现有逻辑
- **不动** canonical 组件源码 — 仅 audit 报告 canonical 是否真 expose 对应 prop（plan owner 后续决策补 prop）

**严格范围**：仅 generator + docs-figma-members 输出 + DocsFigmaMembers 类型。**不**改 canonical / prop-aliases / extract pipeline。

**Out of scope**（明示不做）：
- 不抽 instance-swap properties（实际 = `children: React.ReactNode`，已通过 prop-aliases.json scope=slot-property cover；不需要重复登记）
- 不抽 text-type properties（不在 BRIDGE-005 scope）
- 不升级 extract.mjs 跑 figma API（mcp-cache 已有数据）

---

## 2. 实施指导

### 2.1 数据源 baseline

**Input**: `figma-data/normalized/figma-mcp-cache/<comp>.tsx`（已存在 10+ 文件）

Sample TSX 结构（Pagination）：

```tsx
type PaginationProps = {
  className?: string;
  children?: React.ReactNode | null;
  showPageSize?: boolean;
  showTotal?: boolean;
  type?: "Classic" | "Simple" | "Small";
};
```

**抽取规则**:
- 找 `type <Name>Props = { ... }` 段（regex 或简单字符串扫）
- 行内 `<propName>?: boolean` 或 `<propName>: boolean` → 加入 booleanProperties
- **跳过**：
  - `className` / `children` / `style`（React 内置）
  - `type: "..."` 这种 axis variant（已在 axes 字段）
  - `React.ReactNode` / `string` / 其它非 boolean 类型

### 2.2 输出 schema 升级

`DocsFigmaMembers<T>` 类型定义（在 `figma-data/normalized/docs-figma-members/types.ts` 或 generator 内联）加：

```ts
export type DocsFigmaMembers<T> = {
  // ... existing fields (schemaVersion, component, source, axes, variants) ...

  /** BRIDGE-005 (2026-05-14): figma BOOLEAN component properties not encoded
   * in variant axes. Sourced from figma-data/normalized/figma-mcp-cache/<comp>.tsx
   * `type XxxProps` segment. */
  booleanProperties?: BooleanProperty[];
}

export type BooleanProperty = {
  /** figma property name (e.g. "showTotal", "showCloseIcon", "enable") */
  figmaName: string;
  /** canonical prop name from prop-aliases.json (e.g. "showTotal", "closable",
   * "disabled" for inverted). null if no alias entry. */
  codeName: string | null;
  /** "exact-match" | "approved-alias" | "inverted-alias" | "runtime-addition"
   * | "axis-alias" (skipped from canonical prop) | "n-a" (not exposed).
   * Null if no prop-aliases entry (alias gap → BRIDGE-005 audit-report). */
  status: string | null;
}
```

### 2.3 Alias lookup 算法

对每个抽出的 figma boolean prop：

```js
// 读 prop-aliases.json 一次
const aliases = readJson('src/design-system/translation/prop-aliases.json')

function findAlias(component, figmaName) {
  return aliases.entries.find(e =>
    e.scope === 'boolean-property'
    && e.component === component
    && (e.figmaName === figmaName || e.figmaName?.startsWith(`${figmaName} (`))  // handle "enable (inverted)"
  ) ?? null
}
```

注意：
- `figmaName` 实际值可能是 `"enable (inverted)"` (CheckBox.disabled entry) — 用 `startsWith` 匹配
- `codeName` 可能是 `"(via theme axis)"` (axis-alias) 或 `"(no canonical bool)"` (n-a) — 输出时保留这些值（表达 figma 有 boolean property 但 canonical 不暴露此 prop）

### 2.4 Audit 兼容

生成完 docs-figma-members/<comp>.ts 后跑 `pnpm run audit:translation-completeness`，应该：
- 不引入新 finding
- 现有 9 allowlisted finding 不变（component-coverage 7 + divergence-verify-hint 2）

如果跑出新 finding → STOP 报告（说明 generator 引入了 backward 一致性问题）。

### 2.5 Canonical 验证（report only — 不动 code）

对 generator 输出 `booleanProperties` 中 status 是 `exact-match` / `approved-alias` / `inverted-alias` / `runtime-addition` 的 entry，verify canonical 组件 `defineProps` 真 expose 对应 codeName（同 audit dim 2 的 backward 检查）。

预期已 expose（plan owner baseline）：
- BreadcrumbItem.showSeparator ✅
- Pagination.showTotal / showPageSizeSelector / showJumper ✅
- PromptMessage.closable ✅
- Switch.loading + disabled ✅
- Table.showLeftIcon / showRightIcon ✅
- TopBar.showMenu / showSearchBox ✅
- CheckBox.disabled + Radio.disabled ✅

任一 verify fail → 列报告（不补 canonical prop — 留 plan owner sprint化后续）。

---

## 3. 任务输出（4 个 deliverable）

### D1 — generator 升级 `figma-sync/generate-docs-figma-members.mjs`

- 新增 `parseBooleanPropsFromTsx(componentName)` 函数读 mcp-cache TSX
- 新增 `lookupBooleanPropertyAlias(component, figmaName)` 函数读 prop-aliases.json
- 主流程加 booleanProperties 输出到 DocsFigmaMembers
- 保持现有 axes / variants 逻辑不变

### D2 — DocsFigmaMembers 类型定义升级

如 `figma-data/normalized/docs-figma-members/types.ts` 存在，加 `BooleanProperty` 类型 + `booleanProperties?: BooleanProperty[]` 字段。

如类型只在生成的 `<comp>.ts` 内联，generator 输出时一起加。

### D3 — 重生成所有 docs-figma-members/<comp>.ts

跑 generator 重生成所有已有 figma-mcp-cache 对应的 component members（10+ files）。

如 figma-mcp-cache 文件没对应 canonical：仍生成 boolean props 字段（status: null）。

### D4 — Audit 验证 + 报告

```bash
pnpm run audit:translation-completeness  # 不引入新 finding
pnpm run prepublishOnly                  # 10 strict gates 全通过
pnpm test                                 # 105 passed | 1 skipped
pnpm exec vue-tsc --noEmit                # 0 错
```

报告 generator 输出的 booleanProperties 总数 + 各 status 分布。

---

## 4. 执行步骤

1. 起手 §0 pre-flight 全绿
2. Read figma-sync/generate-docs-figma-members.mjs（全文，包括 import / output 段）
3. Read 1-2 个 figma-mcp-cache TSX（Pagination + PromptMessage）了解 TSX 结构差异
4. Read 1-2 个 docs-figma-members ts（pagination.ts + promptmessage.ts）了解输出范式
5. Read prop-aliases.json scope=boolean-property 18 entries（已 baseline 给）
6. 实施 D1 + D2
7. 跑 generator 一次 verify D3 输出格式正确
8. 跑全套验收 §5
9. STOP + 报告

---

## 5. 验收命令

```bash
# D1 + D2 — 检查 generator 含 booleanProperties 输出
grep -n "booleanProperties\|BooleanProperty" figma-sync/generate-docs-figma-members.mjs | head -5
# 预期：>=3 命中

# D3 — 重生成所有 components
for tsx in figma-data/normalized/figma-mcp-cache/*.tsx; do
  comp=$(basename "$tsx" .tsx)
  # 找对应 canonical 组件名（大小写还原 — 大概率 PascalCase）
done
# 或简单：跑 generator 不传参 generate 全部
node figma-sync/generate-docs-figma-members.mjs

# 验证输出含 booleanProperties
node -e "
const ts = require('fs').readFileSync('./figma-data/normalized/docs-figma-members/pagination.ts', 'utf8');
if (!ts.includes('booleanProperties')) { console.error('Pagination missing booleanProperties'); process.exit(1); }
console.log('Pagination has booleanProperties ✓');
"

# D4 — Audit 0 回归
pnpm run audit:translation-completeness   # ✅ 0 active
pnpm run prepublishOnly                    # 10 strict gates 全通过
pnpm test                                  # 105 passed | 1 skipped
pnpm exec vue-tsc --noEmit                 # 0 错

# Idempotent: 再跑 generator 看是否产生 git churn
node figma-sync/generate-docs-figma-members.mjs
git status figma-data/normalized/docs-figma-members/
# 预期：clean 或仅 first-run diff（同一份内容跑两次应一致）
```

任一 fail → STOP 报告。

---

## 6. 报告格式（STOP 后必交）

```markdown
## BRIDGE-005 完成报告

### 改动文件清单
- [ ] figma-sync/generate-docs-figma-members.mjs（X 行新增）
- [ ] figma-data/normalized/docs-figma-members/types.ts（如适用）
- [ ] figma-data/normalized/docs-figma-members/<comp>.ts × N 文件重生成

### Boolean properties 输出统计
- 共 Y 个 component 含 booleanProperties
- 总 boolean props: Z
- Status 分布：
  - exact-match: A
  - approved-alias: B
  - inverted-alias: C
  - runtime-addition: D
  - axis-alias (skip prop): E
  - n-a: F
  - null (no alias entry): G  ← BRIDGE-005 audit-gap

### 验收结果
- audit:translation-completeness：[OK / FAIL 详情]
- prepublishOnly：[10 gate 全通过 / 哪个 fail]
- vitest / vue-tsc：[OK]

### 实际耗时
[Xh，对比 plan owner 重估 3-5h]

### Canonical verify 结果
- 已 expose（按预期）：列哪些 ✅
- Missing canonical prop（gap）：列哪些 ← 留 plan owner 后续 sprint 决策

### 未解决 / 待 plan owner 决策项
- [若有 TSX 文件 schema 异常 / regex 不能 parse 的 case]
- [若有 figma boolean property 在 prop-aliases.json 没 entry — alias gap]
- [若 canonical 缺 prop 应该补 / 标 deferred]
```

---

## 7. 严格不做的事（executor 边界）

- ❌ 改 canonical 组件源码加 missing prop（留 plan owner 决策）
- ❌ 改 prop-aliases.json / divergences-decisions.json / axis-implementation-map.json
- ❌ 改 figma extract pipeline / 跑 figma API
- ❌ 改 audit:translation-completeness 逻辑
- ❌ 加 instance-swap properties（out of scope，slot 已处理）
- ❌ 改 STATUS.md / tracker.md / CHANGELOG.md（plan owner wrap-up 时做）
- ❌ commit — plan owner 审完后用户决定
- ❌ 修 mcp-cache TSX 文件（read-only baseline）

如遇 figma boolean property 在 prop-aliases.json 找不到 entry → **不要**自创 entry；报 `alias-gap` 给 plan owner。

---

## 8. 完成后 STOP

把报告交给 plan owner，由 plan owner 复审 + 用户决定：

- 是否 commit BRIDGE-005
- 是否进 Phase 6.4（v0.3.0 剩余主线）
- 是否补 canonical missing prop（如 audit 报 gap）
- 是否 release v0.3.0