# Component Map 模板

> 目标: 明确每个页面由哪些可复用组件组成，防止 Codex 直接生成不可维护的整页代码。

| 页面/模块 | 组件 | 层级 | 责任 | 复用来源 | Props / 数据输入 | 事件输出 | 必备状态 | 测试方式 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| | | page / feature / primitive | | existing / new / generated | | | default, empty, loading, error | story / interaction / e2e / visual |

## 组件状态矩阵

| 组件 | default | empty | loading | error | disabled | permission | long_content | mobile |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| | 是 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 |

## 复用与新增规则

- 优先复用现有组件库，不要为单一页面随意造新组件。
- 新组件必须说明为什么现有组件不满足。
- `必备状态` 至少覆盖 `default / empty / loading / error`。
- `测试方式` 写明 story、interaction test、e2e 或 visual。
- generated client / types 不作为 UI 组件复用来源。
- 如果组件依赖接口字段，必须能追溯到 `contracts/openapi.yaml` 或 PRD 数据字典。
- `primitive` 组件不得依赖业务枚举、权限、API client 或路由。
- `feature` 组件可以依赖业务字段和权限，但默认不进入通用组件库。
- 抽到项目级复用层前，必须有两个真实使用场景或明确的架构决策。

## 组件复用决策

| 候选组件 / Hook | 当前用途 | 未来复用场景 | 决策 | 原因 |
| --- | --- | --- | --- | --- |
| | | | local / feature / project | |

## 公共组件改动影响面

如果本次不是新增组件，而是修改 `existing` 公共组件，至少补这张表：

| 公共组件 | 受影响页面 / 模块 | 兼容性策略 | 风险 | 需要补的验证 |
| --- | --- | --- | --- | --- |
| | | 保持旧 props / 新增可选 props / 包装层兼容 | 样式 / 交互 / 权限 / 数据 | story / interaction / e2e / visual |

规则:

- 不允许为了单个页面直接破坏现有 props 契约。
- 能通过新增可选 props、slot、variant 或 wrapper 解决时，不直接改旧行为。
- 如果必须改旧行为，必须列出所有受影响调用方和回归验证。
