@teamix-evo/skills 0.4.0 → 0.5.0

package/src/teamix-evo-design-opentrek/generation-flow.md

@@ -1,6 +1,6 @@
 # 生成 / 翻新 / 验证流程
 
-> AI 在执行页面级任务时，按本文件的门控顺序执行。每一步都有明确的输入输出，跳步会导致结果不可控。
+> ⚠️ **本文件是页面级任务的唯一执行路径。每一步都有 GATE 门禁和 MUST READ 文件清单。** > **跳步 = 产出不合规。AI 不得凭"已有知识"省略任何文件读取。**
 
 ---
 
@@ -11,11 +11,13 @@
 ```
 Step 1 需求确认 → Step 2 类型识别 → Step 3 子类型 + 布局
                                             ↓
-Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
+Step 7 自检    ← Step 6 视觉填充  ← Step 5 可用性校验 ← Step 4 组件挑选
 ```
 
 ### Step 1 · 最小 quorum + 默认值
 
+📖 **MUST READ**: [philosophy.md](./philosophy.md)（理解"为什么这么做" — 四大原则优先级）+ [brand.md](./brand.md)（视觉调性 + 文案语气基调）
+
 **只有两个信息缺一不可**（最小 quorum，缺则反问）：
 
 - [ ] **页面类型**：ListPage / DetailPage / FormPage / Dashboard / Dialog（缺则按 Step 2 决策树推断）
@@ -23,13 +25,13 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 **其他信息全部走默认值，先生成再细化**（避免连环反问让用户失去耐心）：
 
-| 维度       | 默认                                                  | 何时升级                              |
-| ---------- | ----------------------------------------------------- | ------------------------------------- |
-| 业务领域   | 资源管理                                              | 用户明确说"工作流 / 报表"等           |
-| 用户角色   | 业务管理员                                            | 涉及审计 / 审批 / 平台运维等敏感角色  |
-| 核心动作   | CRUD（增 / 删 / 改 / 查 + 列表）                      | 明确出现"批量 / 审批 / 导出"等关键词  |
-| 入口路径   | 从同名菜单进入，无外部跳转                            | 明确说"从 X 跳到 Y"                   |
-| 子类型     | ListPage→standard / FormPage→single-page / 其余各 1   | 用户提到 wizard / drawer / tabbed 等  |
+| 维度     | 默认                                                | 何时升级                             |
+| -------- | --------------------------------------------------- | ------------------------------------ |
+| 业务领域 | 资源管理                                            | 用户明确说"工作流 / 报表"等          |
+| 用户角色 | 业务管理员                                          | 涉及审计 / 审批 / 平台运维等敏感角色 |
+| 核心动作 | CRUD（增 / 删 / 改 / 查 + 列表）                    | 明确出现"批量 / 审批 / 导出"等关键词 |
+| 入口路径 | 从同名菜单进入，无外部跳转                          | 明确说"从 X 跳到 Y"                  |
+| 子类型   | ListPage→standard / FormPage→single-page / 其余各 1 | 用户提到 wizard / drawer / tabbed 等 |
 
 **反问触发条件**（只有以下情况反问，否则直接出方案）：
 
@@ -40,6 +42,10 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 ### Step 2 · 页面类型识别
 
+🚧 **GATE**: Step 1 必须已产出"页面类型 + 资源实体 + 场景假设"
+
+📖 **MUST READ**: [patterns/page-types.md](./patterns/page-types.md) §决策树 + §Zone Map
+
 根据 [patterns/page-types.md](./patterns/page-types.md) §决策树匹配类型：
 
 ```
@@ -55,6 +61,10 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 ### Step 3 · 子类型识别 + 布局选择
 
+🚧 **GATE**: Step 2 必须已产出"页面类型 ID"
+
+📖 **MUST READ**: 对应的 `patterns/{type}-page.md` + [flows.md](./flows.md)（涉及用户旅程时）
+
 根据页面类型读取对应 `patterns/{type}-page.md`：
 
 - 列表页 6 种子类型：`standard / pure-card / standard-card / drawer / expandable / l2-sidebar / advanced-filter`
@@ -65,6 +75,10 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 ### Step 4 · 组件挑选
 
+🚧 **GATE**: Step 3 必须已产出"子类型 ID + 区域骨架"
+
+📖 **MUST READ**: [components.md](./components.md) §0 兗底铁律 + §1 双层架构 + §3 决策树 + §5 拼装配方
+
 读 [components.md](./components.md) §选型决策树确定组件集：
 
 1. 优先使用 `@teamix-evo/ui` 注册表中的稳定组件
@@ -74,7 +88,35 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 **输出**：组件清单 + 每个组件的关键 Props。
 
-### Step 5 · 视觉填充（Token 绑定）
+### Step 5 · 组件可用性校验（新增 gate）
+
+🚧 **GATE**: Step 4 必须已产出"组件清单 + 每个组件的关键 Props"
+
+> ❗ **此步是 Step 4 → Step 6 的强制闸门**。跳过会导致生成代码引用未安装组件而报错。
+
+对 Step 4 选定的每个组件，执行以下校验：
+
+```text
+① MCP find_components(id) 查询注册表
+   ├─ 命中 entries(活跃) → ②
+   ├─ 命中 deprecatedEntries 且有 replacedBy → 自动替换为 replacedBy 组件，回到 ①
+   ├─ 命中 deprecatedEntries 且无 replacedBy → 走 components.md §0 兔底铁律
+   └─ 未命中 → 走 components.md §0 兔底铁律（原子件拼装）
+
+② 检查目标项目是否已装机
+   ├─ 已装（grep src/components/ui/<id> 或查 manifest.lock.json）→ ✅ 继续
+   └─ 未装 → 输出安装指令：
+       「teamix-evo ui add <id>」
+       等待装机完成后再进入 Step 6
+```
+
+**输出**：校验后的最终组件清单（含替换记录）+ 待安装组件列表（若有）。
+
+### Step 6 · 视觉填充（Token 绑定）
+
+🚧 **GATE**: Step 5 必须已产出"校验后的最终组件清单"
+
+📖 **MUST READ**: [foundations.md](./foundations.md) 全文 + [brand.md](./brand.md) §1 视觉五维（圆角/配色/密度/阴影/焦点风格对齐）+ [patterns/color-mapping.md](./patterns/color-mapping.md)（语义色映射表）
 
 读 [foundations.md](./foundations.md)，所有色彩、间距、字号、圆角、阴影、动效**必须**使用 Token：
 
@@ -91,7 +133,11 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 **输出**：含 Token 引用的可执行代码 / HTML。
 
-### Step 6 · 自检
+### Step 7 · 自检
+
+🚧 **GATE**: Step 6 必须已产出"含 Token 引用的可执行代码"
+
+📖 **MUST READ**: [boundaries.md](./boundaries.md) 全文（38 条硬规则）+ [checklist.md](./checklist.md) 全文
 
 对照 [checklist.md](./checklist.md) 10 项逐项验证：
 
@@ -106,6 +152,12 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 适用关键词：**"改造 / 升级 / 翻新 / 对齐规范 / 重新生成"**。
 
+📖 **MUST READ** (全部必读，不得省略)：
+
+1. [boundaries.md](./boundaries.md) — 硬规则真值
+2. [foundations.md](./foundations.md) — Token 真值
+3. [components.md](./components.md) — 组件选型
+
 ```
 1. 读取目标页面源码
 2. 扫描违规项（按 boundaries.md F1-F10 + S1-S8）
@@ -126,6 +178,12 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 适用关键词：**"检查 / 验证 / 评估 / 是否符合规范"**。
 
+📖 **MUST READ** (全部必读，不得省略)：
+
+1. [boundaries.md](./boundaries.md) — 38 条硬规则
+2. [checklist.md](./checklist.md) — 10 项自检
+3. [foundations.md](./foundations.md) — Token 真值（用于校验是否符合）
+
 ```
 1. 读取目标页面源码
 2. 逐条对照 boundaries.md
@@ -162,7 +220,7 @@ Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
 
 | 任务类型 | 何时停止生成                      |
 | -------- | --------------------------------- |
-| 生成     | Step 6 自检全部通过               |
+| 生成     | Step 7 自检全部通过               |
 | 翻新     | 替换清单为空 + 重新对照无违规     |
 | 验证     | 报告完整列出所有违规项 + 修复建议 |
 

package/src/teamix-evo-design-opentrek/patterns/color-mapping.md

@@ -0,0 +1,96 @@
+# Color Mapping — OpenTrek v4.1 语义色映射表
+
+> ⚠️ **Prerequisites**: 你必须由 [generation-flow.md](../generation-flow.md) Step 6（视觉填充）引导到这里，或在翻新路径中处理色彩替换时使用。
+
+> AI 在写组件代码时**只**消费下表中的 CSS 变量名，**不**直接写色值。Token 真值见 `tokens/tokens.theme.css`，本文件仅做语义到 token 名的映射。
+
+---
+
+## 1. 主色系（OpenTrek 品牌蓝）
+
+| 用途              | 变量                         | 备注                              |
+| ----------------- | ---------------------------- | --------------------------------- |
+| 主行动 / CTA 按钮 | `--color-primary`            | `#0055EE` (hsl(218.6 100% 46.7%)) |
+| primary hover     | `--color-primary-hover`      | 加深 5%                           |
+| primary pressed   | `--color-primary-pressed`    | 加深 10%                          |
+| primary 高亮辉光  | `--color-primary-glow`       | 焦点环 / 强调动效                 |
+| primary 文字色    | `--color-primary-foreground` | 主色背景上的文字（白）            |
+
+**消费规则**：
+
+- 仅用于 CTA、当前选中项、品牌标识、Switch/Checkbox 选中态
+- **禁止**用于错误态（错误用 `--color-destructive`）
+
+---
+
+## 2. 状态色（5 档体系）
+
+每种状态色提供 5 档：`--color-{X}` / `-foreground` / `-hover` / `-bg` / `-border`。
+
+| 状态          | 含义                    | 主变量                |
+| ------------- | ----------------------- | --------------------- |
+| `success`     | 成功 / 正常             | `--color-success`     |
+| `warning`     | 警告 / 待办（色相 40°） | `--color-warning`     |
+| `destructive` | 错误 / 删除 / 危险      | `--color-destructive` |
+| `info`        | 中性提示 / 引导         | `--color-info`        |
+
+**消费场景对照**：
+
+- Alert / Banner → 用 `bg-{X}-bg border-{X}-border text-{X}` 三件套
+- Status Tag / Badge → 用 `bg-{X}/10 text-{X}` 浅底深字
+- 错误输入框 → `aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive`
+
+---
+
+## 3. 灰阶语义层（gray-\* 8 级）
+
+| 用途                   | 变量                                |
+| ---------------------- | ----------------------------------- |
+| 主要灰底（卡片背景等） | `--color-gray-primary`              |
+| 主要灰底文字           | `--color-gray-primary-foreground`   |
+| 次要文字               | `--color-gray-secondary-foreground` |
+| 禁用态                 | `--color-gray-disabled`             |
+| 分隔线 / 边框          | `--color-gray-line`                 |
+| sidebar 选中底色       | `--color-gray-sidebar-accent`       |
+| 弱提示底色             | `--color-gray-muted`                |
+| 反白纯白               | `--color-gray-white`                |
+
+> 与 shadcn 标准槽（`--color-foreground` / `--color-muted` / `--color-border`）并存，提供更细粒度的引用入口。
+
+---
+
+## 4. 扩展色（accent-10）
+
+10 色调色板，用于 Tag 分类、用户头像底色、状态点等区分性场景：
+
+`--color-accent-{blue,violet,apricot,indigo,green,magenta,turquoise,orange,berry,olive}`
+
+> 选色顺序：blue → violet → apricot → indigo → green → magenta → turquoise → orange → berry → olive
+
+---
+
+## 5. 数据可视化色（chart-1..10）
+
+| 场景                    | 推荐范围               |
+| ----------------------- | ---------------------- |
+| 单系列                  | `--color-chart-1`      |
+| 2-5 系列对比            | `chart-1` … `chart-5`  |
+| 6-10 系列（异色高对比） | `chart-1` … `chart-10` |
+
+> chart-1 与 primary 同色相，确保单图表场景下视觉延续。
+
+---
+
+## 6. Sidebar / Topbar 命名空间
+
+详见 [sidebar.md §3](./sidebar.md#3-颜色映射v41-品牌化)。**不**使用主色槽（`--color-primary` 等），全部走 `--color-sidebar-*` / `--color-topbar-*`。
+
+---
+
+## 7. AI 生成自检
+
+- [ ] 没有出现 `bg-blue-{n}` / `text-red-{n}` / `text-gray-{n}` 等原始 Tailwind 色
+- [ ] 没有出现 `#xxxxxx` 十六进制硬编码
+- [ ] 没有出现 `hsl(...)` 内联值
+- [ ] sidebar 内未消费 `--color-primary`（用 `--color-sidebar-primary`）
+- [ ] 状态语义与变量对应（删除按钮用 `destructive` 而非 `warning`）

package/src/teamix-evo-design-opentrek/patterns/dashboard.md

@@ -1,5 +1,7 @@
 # Dashboard — 数据概览与监控页
 
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **Dashboard**，并由 Step 3 引导到这里。
+
 > AI 实操路径:Step 2(页面类型识别)判定为 Dashboard 后,本文档接管。生成频次低于 ListPage / FormPage / DetailPage,当前为最小规范,后续按 list-page.md / form-page.md 体例扩充。
 
 ---

package/src/teamix-evo-design-opentrek/patterns/detail-page.md

@@ -1,5 +1,7 @@
 # Detail Page — 详情页模式
 
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **DetailPage**，并由 Step 3 引导到这里。
+
 > **触发**：用户描述含"详情/查看/信息/概览"。
 > **核心特征**：单条记录的只读展示 + DescriptionList + 操作按钮。
 > **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。
@@ -140,15 +142,14 @@
 
 ## 8. 嵌套约束
 
-| 父子关系                                                                                     | 状态                             |
-| -------------------------------------------------------------------------------------------- | -------------------------------- |
-| PageContainer → ContentWrapper → Card(白卡) → PageHeader / InfoCard / Tabs / DescriptionList | ALLOW                            |
-| ContentWrapper → 业务组件（无 Card）                                                         | **FORBID**                       |
-| Card → Card                                                                                  | **FORBID**（白卡单例）           |
-| InfoCard → DescriptionList / MonitorPanel                                                    | ALLOW                            |
-| Tabs → TabPane → DescriptionList / DataTable                                                 | ALLOW（关联资源用 DataTable）    |
-| Sidebar → DescriptionList                                                                    | **FORBID**                       |
-| PageHeader → Tabs                                                                            | WARN（Tab 应在 PageHeader 下方） |
+| 父子关系                                                                                                                  | 状态                                                   |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → InfoCard / Tabs / DescriptionList | ALLOW                                                  |
+| OpPageContainer 内大白卡 → 再嵌一层 `<Card>` 包业务组件                                                                   | **FORBID**(已内置大白卡,嵌套违反白卡单例)              |
+| InfoCard → DescriptionList / MonitorPanel                                                                                 | ALLOW(InfoCard 是局部信息卡 — 业务子区域级,非主区白卡) |
+| Tabs → TabPane → DescriptionList / DataTable                                                                              | ALLOW(关联资源用 DataTable)                            |
+| Sidebar → DescriptionList                                                                                                 | **FORBID**                                             |
+| PageHeader → Tabs                                                                                                         | WARN(Tab 应在 PageHeader 下方)                         |
 
 ---
 

package/src/teamix-evo-design-opentrek/patterns/form-page.md

@@ -1,5 +1,7 @@
 # Form Page — 表单页模式
 
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **FormPage**，并由 Step 3 引导到这里。
+
 > **触发**：用户描述含"新建/创建/编辑/修改/复制/填写"。
 > **核心特征**：用户输入数据 + 字段校验 + 提交。
 > **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。弹窗表单 = L0。
@@ -16,10 +18,10 @@
 
 ### FormPage vs Wizard 区分
 
-| 场景                       | 类型       | 判断依据                 |
-| -------------------------- | ---------- | ------------------------ |
-| 字段无顺序依赖，一次填写   | FormPage   | 单页表单                 |
-| 步骤间有顺序依赖，逐步完成 | WizardPage | 多步流程,Steps           |
+| 场景                       | 类型       | 判断依据       |
+| -------------------------- | ---------- | -------------- |
+| 字段无顺序依赖，一次填写   | FormPage   | 单页表单       |
+| 步骤间有顺序依赖，逐步完成 | WizardPage | 多步流程,Steps |
 
 > Wizard 是独立页面类型，不是 FormPage 子类型。
 
@@ -78,11 +80,11 @@ SubmitBar  [取消] [创建]
 
 ## 3. 必需组件
 
-| 组件                  | 位置   | 说明                                  |
-| --------------------- | ------ | ------------------------------------- |
-| **PageHeader**        | top    | 面包屑模式(L2 页面)                   |
-| **Form / FieldGroup** | center | 表单容器,**禁止**用 div + space-y-\*  |
-| **SubmitBar**         | bottom | 提交操作栏,居右排列                   |
+| 组件                  | 位置   | 说明                                 |
+| --------------------- | ------ | ------------------------------------ |
+| **PageHeader**        | top    | 面包屑模式(L2 页面)                  |
+| **Form / FieldGroup** | center | 表单容器,**禁止**用 div + space-y-\* |
+| **SubmitBar**         | bottom | 提交操作栏,居右排列                  |
 
 **框架级**(自动继承):Sidebar、Breadcrumb。
 
@@ -116,16 +118,18 @@ SubmitBar  [取消] [创建]
 
 > **枚举数量阈值规则(≤7 RadioGroup / 8-30 Select / >30 Combobox)见 [components.md §3.5 输入控件](../components.md#35-输入控件--input-vs-select-vs-combobox)**。本节只列表单页专属补充字段。
 
-| 字段类型      | 组件                         | 说明                     |
-| ------------- | ---------------------------- | ------------------------ |
-| 布尔(设置)    | Switch                       | "启用 X" 类开关          |
-| 布尔(表单)    | Checkbox                     | 协议确认                 |
-| 单选(2~5 项)  | ToggleGroup                  | 类型选择(可视化优于下拉) |
-| 验证码        | InputOTP                     | 短信 / 邮箱 OTP          |
-| 范围数值      | Slider                       | 资源配比 / 阈值          |
-| 输入 + 按钮   | InputGroup                   | 复制、单位切换           |
-| 文件上传      | FileUpload                   | 单 / 多文件              |
-| 日期 / 时间   | DatePicker / DateRangePicker | —                        |
+| 字段类型       | 组件                         | 说明                              |
+| -------------- | ---------------------------- | --------------------------------- |
+| 布尔(设置)     | Switch                       | "启用 X" 类开关                   |
+| 布尔(表单)     | Checkbox                     | 协议确认                          |
+| 单选(2~5 项)   | RadioGroup variant="button"  | 类型选择(按钮组可视化优于下拉)    |
+| 整数/数值      | InputNumber                  | 年龄/数量/价格等有范围约束的数    |
+| 小数/金额      | InputNumber precision={n}    | 保留 n 位小数(自动四舍五入)       |
+| 范围数值(可视) | Slider                       | 资源配比/阈值(需要拖拽式视觉反馈) |
+| 验证码         | InputOTP                     | 短信 / 邮箱 OTP                   |
+| 输入 + 按钮    | InputGroup                   | 复制、单位切换                    |
+| 文件上传       | FileUpload                   | 单 / 多文件                       |
+| 日期 / 时间    | DatePicker / DateRangePicker | —                                 |
 
 ---
 
@@ -190,7 +194,7 @@ SubmitBar  [取消] [创建]
 - **FC1 表单布局**：`FieldGroup` + `Field`,**禁止** `<div>` + `space-y-*`(并见 S2)
 - **FC2 InputGroup 内子件**：`InputGroupInput` / `InputGroupTextarea`,不用原始 `Input`
 - **FC3 输入 + 按钮**：`InputGroup` + `InputGroupAddon`
-- **FC4 2~5 选项**：`ToggleGroup`,**禁止**循环 `Button` 手动 active
+- **FC4 2~5 选项**：`RadioGroup variant="button"`,**禁止**循环 `Button` 手动 active
 - **FC5 相关选项组**：`FieldSet` + `FieldLegend`
 - **FC6 校验态**：`data-invalid` 在 `Field`、`aria-invalid` 在控件 (与 FF1 配合)
 - **反馈**：`import { toast } from "sonner"` (并见 [boundaries.md C9](../boundaries.md#warn-c9--toast-用-sonner))
@@ -199,17 +203,16 @@ SubmitBar  [取消] [创建]
 
 ## 9. 嵌套约束
 
-| 父子关系                                                                          | 状态                        |
-| --------------------------------------------------------------------------------- | --------------------------- |
-| PageContainer → ContentWrapper → Card(白卡) → PageHeader / FieldGroup / SubmitBar | ALLOW                       |
-| ContentWrapper → 业务组件（无 Card）                                              | **FORBID**                  |
-| Card → Card                                                                       | **FORBID**（白卡单例）      |
-| Card(白卡) → Card(分区)                                                           | ALLOW（分区表单内嵌）       |
-| Card(分区) → FieldGroup                                                           | ALLOW                       |
-| FieldGroup → Field                                                                | ALLOW                       |
-| Field → Input / Select / Switch / ToggleGroup / Textarea                          | ALLOW                       |
-| Field → InputGroup                                                                | ALLOW                       |
-| Card → Form                                                                       | **FORBID**（用 FieldGroup） |
+| 父子关系                                                                                                       | 状态                                                  |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → FieldGroup / SubmitBar | ALLOW                                                 |
+| OpPageContainer → Card(分区)                                                                                   | ALLOW(分区表单可在内置大白卡里再用 Card 划分若干小节) |
+| Card(分区) → FieldGroup                                                                                        | ALLOW                                                 |
+| Card(分区) → Card                                                                                              | **FORBID**(分区 Card 不可再嵌套)                      |
+| FieldGroup → Field                                                                                             | ALLOW                                                 |
+| Field → Input / Select / Switch / RadioGroup / InputNumber / Textarea                                          | ALLOW                                                 |
+| Field → InputGroup                                                                                             | ALLOW                                                 |
+| Card → Form                                                                                                    | **FORBID**(用 FieldGroup)                             |
 
 ---
 
@@ -230,7 +233,7 @@ SubmitBar  [取消] [创建]
 - [ ] PageHeader 用面包屑模式（L2 页面）
 - [ ] 所有 Input 在 Field → FieldGroup 内(FC1)
 - [ ] data-invalid + aria-invalid 双重声明(FC6)
-- [ ] 控件按字段类型选型正确（2~5 选用 ToggleGroup，不循环 Button）
+- [ ] 控件按字段类型选型正确（2~5 选用 RadioGroup variant="button"，不循环 Button；数值用 InputNumber，不用 Input[type=number]）
 - [ ] SubmitBar 居右 + 按钮顺序：取消 → 上一步 → 主操作
 - [ ] 长表单（> 10）分组或分区
 - [ ] 异步提交：按钮 loading + Spinner

package/src/teamix-evo-design-opentrek/patterns/list-page.md

@@ -1,5 +1,7 @@
 # List Page — 列表页模式
 
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **ListPage**，并由 Step 3 引导到这里。
+
 > **触发**：用户描述含"列表/表格/查询/检索/卡片管理"。
 > **核心特征**：多条结构化数据 + 搜索/筛选 + 分页。
 > **页面级别**：L1（标题模式 PageHeader，自动继承 Sidebar）。
@@ -32,7 +34,36 @@
 
 ---
 
-## 2. 标准结构
+## 2. Template 组件拼装
+
+> 源自 `packages/create/variants/opentrek/src/templates/list-page.tsx`
+
+```tsx
+<PageShell background="muted" sidebar={<OpSidebar />}>
+  <OpPageContainer header={<PageHeader title="..." actions={...} />}>
+    {/* children: 以下组件由消费方自由组合 */}
+    <ActionToolbar ... />
+    <DataTable ... />   {/* 或 CardGrid */}
+    <Pagination ... />
+  </OpPageContainer>
+</PageShell>
+```
+
+| Slot         | 注入内容                                          | 来源                               |
+| ------------ | ------------------------------------------------- | ---------------------------------- |
+| `sidebar`    | OpSidebar（左导）                                 | `@/components/business/op-sidebar` |
+| `pageHeader` | PageHeader 整块（title + Tabs + Toolbar 组合）    | `@/components/ui/page-header`      |
+| `children`   | ActionToolbar + DataTable / CardGrid + Pagination | 消费方自组合                       |
+
+**壳层特征**：
+
+- PageShell `background="muted"` → 灰底主区
+- OpPageContainer → 内嵌**无边框大白卡**（`bg-card rounded-2xl p-6`）
+- 业务组件直接作为 children，**不要再包 `<Card>`**（白卡单例）
+
+---
+
+## 3. 标准结构（设计线框）
 
 ```
 ┌────────────────────────────────────────────┐
@@ -52,20 +83,20 @@
 
 ---
 
-## 3. 必需组件
+## 4. 必需组件
 
-| 组件                          | 位置    | 说明                                                        |
-| ----------------------------- | ------- | ----------------------------------------------------------- |
-| **PageHeader**                | top     | 标题模式(L1 页面);右侧主操作(如「新建」)                    |
-| **ActionToolbar**             | toolbar | 单行 flex(nowrap);左 actions + 中 SearchCombo + 右 tools    |
-| **DataTable** 或 **CardGrid** | main    | 二选一,按子类型                                             |
-| **Pagination**                | footer  | 默认 10 条/页(标准列表) / 12 条/页(卡片)                    |
+| 组件                          | 位置    | 说明                                                     |
+| ----------------------------- | ------- | -------------------------------------------------------- |
+| **PageHeader**                | top     | 标题模式(L1 页面);右侧主操作(如「新建」)                 |
+| **ActionToolbar**             | toolbar | 单行 flex(nowrap);左 actions + 中 SearchCombo + 右 tools |
+| **DataTable** 或 **CardGrid** | main    | 二选一,按子类型                                          |
+| **Pagination**                | footer  | 默认 10 条/页(标准列表) / 12 条/页(卡片)                 |
 
 **框架级**(自动继承,不在 skill 内声明):Sidebar。
 
 ---
 
-## 4. SearchCombo 规范
+## 5. SearchCombo 规范
 
 > ListPage 顶部搜索 + 筛选的标准复合组件。**禁止**用 Input + Select 散件拼装。
 
@@ -121,7 +152,7 @@
 
 ---
 
-## 5. DataTable 规则（核心）
+## 6. DataTable 规则（核心）
 
 ### 5.1 列元规则（每列必备）
 
@@ -190,7 +221,7 @@
 
 ---
 
-## 6. 操作列规范（硬约束）
+## 7. 操作列规范（硬约束）
 
 ### 6.1 结构
 
@@ -213,49 +244,52 @@
 
 ### 6.3 操作列行为映射
 
-| 操作      | 触发     | 前置          | 二次确认        | 目标              | 返回行为                             |
-| --------- | -------- | ------------- | --------------- | ----------------- | ------------------------------------ |
-| 查看/管理 | 点链接   | —             | 否              | DetailPage        | 返回列表保持筛选+分页                |
-| 编辑      | 点按钮   | —             | 否              | FormPage / Drawer | 保存成功返回列表 + Toast「保存成功」 |
-| 删除      | 点按钮   | 资源已停止    | 是(三级 Dialog) | Dialog 确认       | 确认后刷新 + Toast「删除成功」       |
-| 更多      | Dropdown | —             | 按操作分级      | Dropdown 菜单     | 选择子操作                           |
+| 操作      | 触发     | 前置       | 二次确认        | 目标              | 返回行为                             |
+| --------- | -------- | ---------- | --------------- | ----------------- | ------------------------------------ |
+| 查看/管理 | 点链接   | —          | 否              | DetailPage        | 返回列表保持筛选+分页                |
+| 编辑      | 点按钮   | —          | 否              | FormPage / Drawer | 保存成功返回列表 + Toast「保存成功」 |
+| 删除      | 点按钮   | 资源已停止 | 是(三级 Dialog) | Dialog 确认       | 确认后刷新 + Toast「删除成功」       |
+| 更多      | Dropdown | —          | 按操作分级      | Dropdown 菜单     | 选择子操作                           |
 
 ---
 
-## 7. Card 内对齐规则（硬约束 — 最容易不稳定的点）
+## 8. 主区对齐规则(硬约束 — 最容易不稳定的点)
 
-水平 padding 分层模型：
+opentrek 主区由 `OpPageContainer` 提供 — 外层 `py-5 pr-5`(无左 padding,sidebar 自带 20px 间隙) + 内嵌**无边框白底大 Card**(`bg-card rounded-2xl p-6`)承载 PageHeader / ActionToolbar / DataTable / Pagination。水平 padding 分层模型:
 
-- **Card.paddingX = 24px**：提供 Card 外缘 ↔ 非 Table 子组件的呼吸
-- **Table 中间列 padding = 12px**（左右 12+12=24，列间 24px）
-- **Table 首列 padding-left = 20px**（额外缩进）
+- **OpPageContainer 外层**:`py-5 pr-5`(灰底主区 ↔ 白卡的间隙;左侧贴 sidebar 不留 padding)
+- **OpPageContainer 内白卡 padding = 24px**(`p-6`):提供白卡内缘 ↔ 非 Table 子组件的呼吸 — **由容器统一管,不要在 PageHeader / Toolbar 上再加 paddingX**
+- **Table 中间列 padding = 12px**(左右 12+12=24,列间 24px)
+- **Table 首列 padding-left = 20px**(额外缩进让 checkbox 与白卡内缘有呼吸)
 - **Table 末列 padding-right = 20px**
 
-| 组件                                                    | 水平 padding        | 起始 X         |
-| ------------------------------------------------------- | ------------------- | -------------- |
-| Card 白卡容器                                           | **24px**            | Card 外缘      |
-| PageHeader / ActionToolbar / BulkActionBar / Pagination | **0**               | Card 外缘 + 24 |
-| Table 中间列 td                                         | 12px                | —              |
-| Table 首列 td                                           | padding-left: 20px  | Card 外缘 + 44 |
-| Table 末列 td                                           | padding-right: 20px | Card 右缘 - 44 |
+| 组件                                                    | 水平 padding        | 起始 X              |
+| ------------------------------------------------------- | ------------------- | ------------------- |
+| OpPageContainer 外层                                    | `pr-5`(右 20,左 0)  | PageShell main 外缘 |
+| OpPageContainer 内白卡                                  | **24px**(`p-6`)     | 白卡内缘            |
+| PageHeader / ActionToolbar / BulkActionBar / Pagination | **0**               | 白卡内缘 + 24       |
+| Table 中间列 td                                         | 12px                | —                   |
+| Table 首列 td                                           | padding-left: 20px  | 白卡内缘 + 44       |
+| Table 末列 td                                           | padding-right: 20px | 白卡右内缘 - 44     |
 
 ### 禁止项
 
-- ❌ 在 PageHeader / ActionToolbar / Pagination 上重复设 paddingX（会与 Card.paddingX 叠加为 48px）
+- ❌ 在 OpPageContainer 主区再叠一层 `<Card>` — 容器已经内置大白卡,嵌套违反白卡单例
+- ❌ 在 PageHeader / ActionToolbar / Pagination 上重复设 paddingX(会与 OpPageContainer 内白卡的 `p-6` 叠加为 48px)
 - ❌ Table 中间列 padding 不为 12px
 - ❌ Table 首/末列 padding 不为 20px
-- ❌ 用 `px-4` `px-6` 字面量 — 用 `px-3 first:pl-5 last:pr-5`
-- ❌ 在 Card 与子组件间插入额外 paddingX 包裹层
+- ❌ 用 `px-4` `px-6` 字面量直接套子组件 — 用 `px-3 first:pl-5 last:pr-5` 让 Table 自己分配
+- ❌ 在 OpPageContainer 内白卡与子组件间插入额外 paddingX 包裹层
 
 ### 验证
 
-1. PageHeader / ActionToolbar / Pagination 起始 X = Card 左缘 + 24
-2. Table 首列 (checkbox) 内容 X = Card 左缘 + 44
+1. PageHeader / ActionToolbar / Pagination 起始 X = OpPageContainer 内白卡左内缘 + 24
+2. Table 首列(checkbox)内容 X = OpPageContainer 内白卡左内缘 + 44
 3. Table 相邻中间列内容间距 = 24
 
 ---
 
-## 8. 状态-操作模式
+## 9. 状态-操作模式
 
 ### 8.1 元规则
 
@@ -290,21 +324,20 @@
 
 ---
 
-## 9. 嵌套约束
+## 10. 嵌套约束
 
-| 父子关系                                                                                        | 状态                         |
-| ----------------------------------------------------------------------------------------------- | ---------------------------- |
-| PageContainer → ContentWrapper → Card(白卡容器) → PageHeader/ActionToolbar/DataTable/Pagination | ALLOW                        |
-| ContentWrapper → 业务组件（无 Card 包裹）                                                       | **FORBID**                   |
-| Card → Card                                                                                     | **FORBID**（白卡单例）       |
-| ActionToolbar → SearchCombo                                                                     | ALLOW                        |
-| CardGrid → ItemCard → CardActionBar                                                             | ALLOW                        |
-| DataTable → Pagination                                                                          | ALLOW                        |
-| DataTable → Form                                                                                | **FORBID**（用 Drawer 触发） |
+| 父子关系                                                                                                                       | 状态                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → ActionToolbar / DataTable / Pagination | ALLOW                                                                   |
+| OpPageContainer 内大白卡 → 再嵌一层 `<Card>` 包业务组件                                                                        | **FORBID**(OpPageContainer 已内置大白卡,嵌套违反白卡单例)               |
+| ActionToolbar → SearchCombo                                                                                                    | ALLOW                                                                   |
+| CardGrid → ItemCard → CardActionBar                                                                                            | ALLOW(卡片网格内每个 ItemCard 是局部小卡 — 业务子区域级,非主区白卡嵌套) |
+| DataTable → Pagination                                                                                                         | ALLOW                                                                   |
+| DataTable → Form                                                                                                               | **FORBID**(用 Drawer 触发)                                              |
 
 ---
 
-## 10. 禁止项
+## 11. 禁止项
 
 | 禁项                   | 原因                                |
 | ---------------------- | ----------------------------------- |
@@ -319,7 +352,7 @@
 
 ---
 
-## 11. 列表页特有自检
+## 12. 列表页特有自检
 
 - [ ] PageHeader / ActionToolbar / DataTable / Pagination 嵌套结构正确
 - [ ] Card 内统一左右 padding 24px（除 Table 列）