@pactor-app/skills 1.34.0 → 1.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/skills",
-  "version": "1.34.0",
+  "version": "1.40.0",
   "description": "Agent skills for rapidly building pactor Server-Driven UI applications",
   "keywords": [
     "pactor",

package/pactor-dsl/SKILL.md

@@ -181,7 +181,33 @@ Facts that are NOT guessable and must be followed:
 
 - Top level is `{ dsl, page, state?, dataSources?, actions?, components?, lifecycle?, body? }` — `page` is a wrapper object, `dsl: '1.0'` is mandatory.
 - `Table` reads data via an **expression** (`dataSource: ${data.customers}`), not a source name; column templates use the `cell` key (not `render`) with `${row.x}` scope; pagination is `pagination: { pageSize: 5 }`.
-- Form fields bind via `props.name`; the submit button uses `submit: true` (not `htmlType`); `Form onSubmit` receives all values as `${event.<field>}`.
+- **Inside `Form`, every form control must be wrapped in a `Field`** (`Input`/`NumberInput`/`Select`/`Textarea`/`RadioGroup`/`Checkbox`/`Switch`/`Slider`/`DatePicker` …): label / required / description / error belong to `Field`, the control keeps only its own props (`name` / `placeholder` / `value` / `options` / `rules`). Search-bar buttons (查询/重置) also go inside a `Field` so they align with the inputs; **multiple buttons in one `Field` are placed side by side directly — adjacent buttons get spacing automatically (`[&>button+button]:ml-2`), no extra wrapper or margin needed** (use a `Flex` with `gap` inside the `Field` only when aligning mixed content, e.g. a right-aligned button row). Fields bind via `props.name`; the submit button uses `submit: true` (not `htmlType`); `Form onSubmit` receives all values as `${event.<field>}`.
+
+```yaml
+- type: Form
+  props: { layout: inline }
+  children:
+    - type: Field
+      props: { label: 关键词 }
+      children:
+        - type: Input
+          props: { name: keyword, placeholder: 输入关键词 }
+    - type: Field
+      props: { label: 状态 }
+      children:
+        - type: Select
+          props:
+            name: status
+            options:
+              - { label: 启用, value: enabled }
+              - { label: 停用, value: disabled }
+    - type: Field            # 查询/重置按钮同样放 Field 内，与输入框对齐
+      children:
+        - type: Button
+          props: { text: 查询, variant: primary, submit: true }
+        - type: Button
+          props: { text: 重置 }
+```
 - `navigate` takes `to`; `message` takes `text` + `messageType` (a `type` key in action `params` disables expression evaluation).
 - Query linkage = `onSubmit: [setState, reload]`; the data source's `params` referencing `${state.x}` pick up new values on reload.
 
@@ -357,6 +383,7 @@ pnpm pactor create my-app
 - **Do not** rely on frontend permission checks for security; enforce authorization on backend APIs.
 - **Do not** forget to import `@pactor-app/ui/styles.css` when using the default shadcn kit (`@pactor-app/chat/styles.css` additionally for chat surfaces).
 - **Do not** put a `type` key in action `params` (see the events workflow pitfall).
+- **Do not** place bare form controls directly under `Form`; wrap every control (including search-bar buttons) in a `Field`.
 - **Do not** expect DslNode slots (sidebar / toolbar / inspector / …) to render outside a page runtime; in pure React hosts pass ReactNode instead.
 
 ## References (bundled — works from npm install)

package/pactor-dsl/references/dsl-authoring.md

@@ -178,7 +178,9 @@ Event payloads (`${event}`):
 | Button `onClick` | none |
 | Input / Select / Switch `onChange` | the new value (`${event}`) |
 | Tabs `onChange` | new active key |
-| Table `onChange` | `{ current, pageSize, total }` |
+| Table `onChange` | `{ current, pageSize, total, field?, order? }` |
+| Table `onSelectChange` | selected row keys array (`rowSelection: true`) |
+| Table `onRowDrop` | `{ dragKey, dropKey, position: 'before' \| 'after' }` (`rowDraggable: true`) |
 | Form `onSubmit` | all values (`${event.name}`) |
 | Form `onValuesChange` | ONLY the changed field `{ <field>: newValue }` |
 
@@ -198,6 +200,7 @@ Action catalog:
 | `call` | `name` | run a top-level named action, inherits caller scope |
 | `delay` | `ms` | wait |
 | `form.setValues` | `values` (req), `form?` (default `default`) | write field values; does NOT trigger validation or onValuesChange |
+| `form.submit` | `form?` (default `default`) | trigger the form's native submit — runs validation and `onSubmit`; for submit buttons outside the `<form>` DOM (e.g. Drawer `footer` slot) |
 | `overlay.open` / `overlay.close` | see below | open overlay and await close; close `payload` becomes open's result |
 
 `overlay.open` params: `{ overlay: { type: modal|drawer, title?, width?, content: <DslNode> | page: { pageId }, params? } }`. Overlay content evaluates in overlay scope: `${params.x}` = injected params, `${parent.x}` = parent page snapshot, `${state}`/`${data}` still live.
@@ -249,17 +252,24 @@ body:
               - action: reload
                 params: { dataSource: customers }
           children:
-            - type: Input
-              props: { name: keyword, label: Keyword, placeholder: Name / owner }
-            - type: Select
-              props:
-                name: status
-                label: Status
-                options:
-                  - { label: Enabled, value: active }
-                  - { label: Disabled, value: inactive }
-            - type: Button
-              props: { text: Search, variant: primary, submit: true }   # submit: true, NOT htmlType
+            - type: Field                      # Form 内控件必须放 Field 内（label 归 Field）
+              props: { label: Keyword }
+              children:
+                - type: Input
+                  props: { name: keyword, placeholder: Name / owner }
+            - type: Field
+              props: { label: Status }
+              children:
+                - type: Select
+                  props:
+                    name: status
+                    options:
+                      - { label: Enabled, value: active }
+                      - { label: Disabled, value: inactive }
+            - type: Field                      # 查询按钮也放 Field 内，与输入框对齐
+              children:
+                - type: Button
+                  props: { text: Search, variant: primary, submit: true }   # submit: true, NOT htmlType
     - type: Card
       props: { title: Customer Data }
       children:
@@ -315,15 +325,19 @@ events:
                       - action: message
                         params: { messageType: error, text: Save failed, please retry }
             children:
-              - type: Input
-                props:
-                  name: name
-                  label: Name
-                  value: ${params.name}    # field-level initial value (row data backfill)
-                  rules:
-                    - { required: true, message: Please enter a name }
-              - type: Button
-                props: { text: Save, variant: primary, submit: true }
+              - type: Field
+                props: { label: Name, required: true }
+                children:
+                  - type: Input
+                    props:
+                      name: name
+                      value: ${params.name}    # field-level initial value (row data backfill)
+                      rules:
+                        - { required: true, message: Please enter a name }
+              - type: Field
+                children:
+                  - type: Button
+                    props: { text: Save, variant: primary, submit: true }
     - action: if                           # runs after the drawer closes; cancel (X / mask / Esc) skips
       params:
         condition: ${actions.editResult.success}
@@ -334,6 +348,60 @@ events:
             params: { messageType: success, text: Customer updated }
 ```
 
+### 8.2.1 Controlled overlay nodes (state + `open` expression)
+
+Alternative to `overlay.open`: declare `Drawer` / `Dialog` / `AlertDialog` as ordinary DSL nodes with `open: ${state.x}` and drive them with `setState`. Use this when the overlay is a fixed part of the page tree (templates, statically known content). Key wiring:
+
+```yaml
+state: { drawerOpen: false }
+body:
+  type: Page
+  children:
+    - type: Button                            # open
+      props: { text: 新建, variant: primary }
+      events:
+        onClick:
+          - action: setState
+            params: { drawerOpen: true }
+    - type: Drawer
+      props:
+        title: 编辑
+        open: "${state.drawerOpen}"
+        style: { width: 480, maxWidth: 'none' }
+        okText: 保存                          # 默认 footer [取消, 保存]
+      events:
+        onClose:                              # 关闭图标 / mask / Esc / 默认「取消」
+          - action: setState
+            params: { drawerOpen: false }
+        onOk:                                 # 默认「保存」→ form.submit 桥接校验 + onSubmit
+          - action: form.submit
+      children:
+        - type: Form
+          events:
+            onSubmit:
+              - action: message
+                params: { messageType: success, text: 保存成功 }
+              - action: setState
+                params: { drawerOpen: false }
+          children:
+            - type: Field
+              props: { label: 名称, required: true }
+              children:
+                - type: Input
+                  props:
+                    name: name
+                    rules:
+                      - { required: true, message: 请输入名称 }
+```
+
+Rules of thumb:
+
+- `Drawer` 默认带右上角关闭图标（`closable: false` 关闭）与默认 footer（[取消 → onClose, 确定 → onOk]，右对齐、固定底部）；关闭链路在未 wiring `onClose` 时也会默认自闭合，wiring `onClose` 回写 state 是推荐做法。
+- 表单抽屉优先用 `okText` + `events.onOk: form.submit`（最简）；需要非按钮组布局时才给 `footer` 传 DslNode 或 `false`。
+- A `submit: true` button only submits the enclosing `<form>`; from the `footer` slot (outside the `<form>` DOM) use the `form.submit` action instead — it runs the same validation + `onSubmit` chain.
+- `AlertDialog` in controlled mode never self-closes: wire BOTH `events.onConfirm` and `events.onCancel` to `setState x=false`.
+- `${form.x}` is written to state only on successful submit; for per-step data in a wizard, submit at each step (or read Form values only after submit).
+
 ### 8.3 Server-side pagination
 
 Table's own `pagination` paginates the data already bound to it (client-side). For a server-paginated API, turn it off and pair the table with a standalone `Pagination` component driving state + reload:
@@ -372,6 +440,28 @@ dataSources:
 
 Table also supports `rowKey` (row key field, default `'id'`); Table `onChange` (`{ current, pageSize, total }`) exists for its built-in client-side pager.
 
+### 8.3.1 Table extras: tree data, row drag, sticky header
+
+```yaml
+- type: Table
+  props:
+    dataSource: ${data.menus}            # rows containing a `children` array render as a tree table automatically
+    childrenColumnName: children         # default; set another field name, or false to disable tree mode
+    indentSize: 16                       # px per tree level (default 16); expand toggles render in the first column
+    defaultExpandAllRows: true           # start fully expanded (default: all collapsed, toggle via the row arrow)
+    rowDraggable: true                   # grip handle column; drag to reorder within the same parent level
+    scrollY: 400                         # px; body scrolls vertically with the header stuck on top
+  events:
+    onRowDrop:                           # reorder already applied internally; use this to persist
+      - action: request
+        params:
+          url: /api/menus/reorder
+          method: POST
+          body: ${event}                 # { dragKey, dropKey, position }
+```
+
+Tree tables sort recursively per level and paginate by top-level rows. Sortable columns (`sorter: true`), `rowSelection`, fixed columns (`fixed: right` on the action column) all compose with the above.
+
 ### 8.4 Confirm then act
 
 ```yaml
@@ -396,23 +486,67 @@ events:
 state:
   cityMap: { Zhejiang: [{ label: Hangzhou, value: Hangzhou }], Jiangsu: [{ label: Nanjing, value: Nanjing }] }
   cityOptions: []
-# fields:
-- type: Select
-  props: { name: region, label: Province, options: [{ label: Zhejiang, value: Zhejiang }, { label: Jiangsu, value: Jiangsu }] }
-  events:
-    onChange:
-      - action: form.setValues             # clear the child field first
-        params: { values: { city: '' } }   # add `form: edit` when targeting a named form
-      - action: setState                   # then update child options (computed member access)
-        params: { cityOptions: ${state.cityMap[event]} }
-- type: Select
-  props:
-    name: city
-    label: City
-    options: ${state.cityOptions}
-    disabled: ${state.cityOptions.length === 0}
+# fields (each control wrapped in Field, as required inside Form):
+- type: Field
+  props: { label: Province }
+  children:
+    - type: Select
+      props: { name: region, options: [{ label: Zhejiang, value: Zhejiang }, { label: Jiangsu, value: Jiangsu }] }
+      events:
+        onChange:
+          - action: form.setValues             # clear the child field first
+            params: { values: { city: '' } }   # add `form: edit` when targeting a named form
+          - action: setState                   # then update child options (computed member access)
+            params: { cityOptions: ${state.cityMap[event]} }
+- type: Field
+  props: { label: City }
+  children:
+    - type: Select
+      props:
+        name: city
+        options: ${state.cityOptions}
+        disabled: ${state.cityOptions.length === 0}
 ```
 
+### 8.6 Card list page (CardList / EntityCard business components)
+
+`CardList` renders a grid of `EntityCard` summary cards in one node — no `For` + nested `Flex`/`Text`/`Tag` scaffolding. Item fields mirror `EntityCard` props; extra business fields ride along and come back in event payloads.
+
+```yaml
+state:
+  plugins:
+    - id: 1
+      icon: users                      # Icon whitelist name (or `logo` image URL)
+      title: 用户管理
+      subtitle: v0.1.0                 # auxiliary line under the title
+      description: 管理插件安装状态与运行生命周期，支持启停与依赖检查。
+      tags: [{ text: 已安装, color: success }]   # Tag colors: default/success/warning/error/info
+      actions: [{ text: 停用 }]        # footer buttons, right-aligned, muted bar
+body:
+  - type: CardList
+    props:
+      items: ${state.plugins}
+      columns: 3                       # grid columns, default 3; 1 = single wide rows
+      gap: 16                          # default 16
+      showCount: true                  # footer "共 N 个" count line
+      # createText: 新建插件           # dashed "create" placeholder card in the first cell
+      # hoverable: true                # whole-card pointer + hover highlight
+    events:
+      onCreateClick: { action: message, params: { messageType: info, text: open create dialog } }
+      onItemClick: { action: message, params: { messageType: info, text: "进入详情：${event.item.title}" } }
+      onItemAction:                    # ${event} = { key, text, item, index }
+        - action: confirm
+          id: opConfirm
+          params: { title: "确认${event.text}「${event.item.title}」？" }
+        - action: if
+          params:
+            condition: ${actions.opConfirm}
+            then: [{ action: message, params: { messageType: success, text: done } }]
+```
+
+- `EntityCard` standalone: `icon`/`logo`, `title`, `subtitle`, `tags[]`, `description` (two-line clamp), `meta` (right side of the middle row), `actions[]` (`{ text, key?, variant?, danger? }`), `footerBackground` (muted footer bar, default `true`), `hoverable`. Events `onClick` (whole card) and `onAction` (`{ key, text, index }`) — footer button clicks never trigger the card click.
+- Empty `items` renders an `Empty` state (`emptyText` overrides the default).
+
 ## 9. Common mistakes (observed — do not do these)
 
 | Wrong | Right |
@@ -423,6 +557,10 @@ state:
 | Column template key `render` | `cell` |
 | `pagination: true` | `pagination: { pageSize: 10 }` |
 | `htmlType: submit` | `submit: true` |
+| Bare `Input`/`Select`/`Button` directly under `Form` | Wrap every form control (incl. search-bar buttons) in `Field`; label / required / description / error belong to `Field` |
+| Relying on `Field required: true` for validation | It is a visual `*` marker only — declare `rules: [{ required: true, message: ... }]` on the CONTROL (`Input`/`Select`/…); Form validates control rules on submit |
+| `style` / `className` as node-level keys (sibling of `props:`) | They are component props — always nest them inside `props: { className: ..., style: ... }`; node-level keys are silently ignored |
+| `children` nested inside `props:` | `children` is a NODE-level key (sibling of `props:`); nested under `props:` it is silently dropped |
 | `navigate` param `path` / `url` | `to` |
 | `message` param `type: success` | `messageType: success` — a `type` (or `action`) key inside action `params` makes the engine treat params as a nested DSL/action config and SKIP expression evaluation |
 | Reading full form values in `onValuesChange` | It only carries the changed field; use `onSubmit` or `${form.x}` |

package/pactor-prd/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pactor-prd
 description: |
-  Use when PRD or markdown wireframes drive Pactor YAML pages (skill id pactor-prd). Greenfield: copy template/ into a new repo. Incremental: in an existing Pactor project, add or update pages from new/changed wireframe files (DSL, sitemap, menus, mock API, styles). Triggers: pactor-prd, prd-to-app, 线框图增量, 已有项目加页面, PRD 更新页面.
-version: 1.3.0
+  Use when PRD or markdown wireframes drive Pactor YAML pages (skill id pactor-prd). Greenfield: copy template/ into a new repo. Incremental: in an existing Pactor project, add or update pages from new/changed wireframe files (DSL, sitemap, menus, data API, styles). Triggers: pactor-prd, prd-to-app, 线框图增量, 已有项目加页面, PRD 更新页面.
+version: 1.5.0
 ---
 
 # PRD → YAML 页面应用生成
 
-把「产品文档 + Markdown 线框图」落到 **YAML 页面 + sitemap/mock/样式**；支持 **两种模式**（先选型再执行）：
+把「产品文档 + Markdown 线框图」落到 **YAML 页面 + sitemap/数据接口/样式**；支持 **两种模式**（先选型再执行）：
 
 | 模式 | 何时用 | 脚手架 |
 | --- | --- | --- |
@@ -17,6 +17,7 @@ version: 1.3.0
 ## 输入要求
 
 - PRD/线框图：总览 README（模块 × 页面 × 优先级）+ 分页线框 markdown（ASCII + 区域 + 交互）
+- **接口文档/说明（可选）**：API 路径、方法、参数、返回结构；存在时页面 dataSources 直接对接文档接口，不再走 `/api/d/...` 约定
 - **增量**：可只提供 **变更的线框图文件** 列表（或 PRD 目录 + 标明 diff 范围）
 - 原产品代码仓（可选）：抽设计令牌、自定义 CSS、交互
 - 目标：空目录（新建工程）或已有工程根目录（增量）
@@ -25,20 +26,21 @@ version: 1.3.0
 
 ## 红线（必须遵守）
 
-1. **dataSources 一律 `type: http`**，指向 `/api/data/...`，不写 `type: service`，便于后续替换真实接口
+1. **dataSources 一律 `type: http`，不写 `type: service`**；**PRD 含接口文档/说明时，url 取文档中的接口地址**（方法、路径、返回形状对齐，见「1. 输入解析」）；无接口文档时指向 `/api/d/...`（转发层空数据回退，后续按 `references/data-api.md` 接真实接口）
 2. **布局与间距以样板页为准**：新建工程时以 `template/` 同类页为准；**增量时以目标工程内同模块/同类型页**为准。线框图只提取结构与功能，不逐像素还原 ASCII
-3. **样式与原产品一致**：主题令牌（含深浅色）、自定义 CSS（如登录页）、换肤入口全部移植对齐，见 `references/theme-and-style.md`
+3. **样式与原产品一致**：主题令牌（含深浅色）、自定义 CSS、换肤入口全部移植对齐，见 `references/theme-and-style.md`
 4. **功能与原产品一致**：线框图描述的筛选/搜索/跳转/弹窗/提交等交互必须经 events/actions 闭环可用，禁止只画静态骨架；错误分支（校验失败提示等）也要实现
 5. **表单一律用 `Form` 组件**：凡是一组「字段 + 校验 + 提交」的表单——独立表单页、页面内嵌的配置面板（如树/列表右侧的编辑表单）、弹窗/抽屉表单、**搜索栏（关键词 + 查询/重置 的筛选区，用 `Form layout: inline`）**——都必须用 `Form` 包裹，字段经 `props.name` 绑定，校验用字段级 `rules`（required + message），提交用 `submit: true` 的 Button 触发 `onSubmit`；**禁止**散放 `Input`/`Select` + `setState` 攒草稿 + `if` 动作手写校验。上下结构的字段一律用 `Field` 包裹：label、必填星号（`required: true`）、行右提示（`labelHint`）由 `Field` 渲染，控件上只留 `name`/`rules` 等（`Form layout: inline` 的搜索栏除外，label 直接挂控件）；禁止手写 `Text("*") + Label` 拼标签。回填联动（如点击列表/树节点填充表单）用 `form.setValues` 动作，不要绑 `${state.x}` 到字段 value；即点即生效的 ChipFilter 快筛行没有提交语义，不属于表单
 6. **列表页操作列规范**：操作列按钮样式统一 `Button variant: link`；「编辑」与「新建」指向同一个表单（同一路由页或同一弹窗），唯一区别是编辑以行数据预填（路由页 `initialValues: ${data.detail}`，弹窗/内嵌面板 `form.setValues`）；**数据列表页（搜索 + 表格 + 新建/编辑）以 `template/src/server/yaml/models/data-list.yaml` 为标准骨架生成**（结构与要点见 `references/page-templates.md`「数据列表标准模型」）
 7. **文案以线框图为准**：标题、按钮、空态文案逐字取自线框图/PRD
-8. DSL 语法细节（组件 props、表达式、动作）以 `pactor-dsl` skill 与 packages/ui 当前导出为准，本 skill 只约定流程与产出物
+8. **登录页用 `Login` 业务组件**：PRD 含登录页时，以模板 `yaml/common/login.yaml`（`type: Login`）为样板生成，禁止手写 Card+Form+自定义 CSS；**原型未明确布局方式时必须向用户提问**选择 `layout`（`split` 左右分栏 / `centered` 居中 / `brand-card` 品牌卡片 / `overlap` 卡片叠加 / `backdrop` 整页渐变背景，附效果简述，必要时含 `brandSide`/`brandRatio`/`authVariant` 修饰项），原型可判定布局则直接用、不提问；用户不答默认 `split` + `authVariant: card`；品牌区文案/logo/插画取自 PRD，提交闭环沿用 `onSubmit` → `request` + `message` + `app.reload` 模式
+9. DSL 语法细节（组件 props、表达式、动作）以 `pactor-dsl` skill 与 packages/ui 当前导出为准，本 skill 只约定流程与产出物
 
 ## 流程总览
 
 ```text
-选型 → 1 解析 → 2 脚手架（仅新建工程）→ 3 页面 → 4 mock → 5 样式 → 6 验收
-增量：2 改为「摸底」；1/3 只处理 delta；6 变更页全验 + 少量回归
+选型 → 1 解析 → 2 脚手架（仅新建工程）→ 3 页面 → 4 样式 → 5 验收
+增量：2 改为「摸底」；1/3 只处理 delta；5 变更页全验 + 少量回归
 ```
 
 详细增量步骤：**`references/incremental-wireframe-delta.md`**。
@@ -47,6 +49,7 @@ version: 1.3.0
 
 - 读 README / 变更线框图：模块树、页面 id（kebab-case）、path、菜单、P0/P1/P2
 - 逐页读线框：页面类型、区域、字段、交互
+- **接口文档解析**：PRD 含接口文档/说明时，提取「资源 → 路径 / 方法 / 返回形状」接口清单，页面 dataSources 以该清单为准；无接口文档则按 `references/data-api.md` 命名约定写 `/api/d/...`
 - **新建工程**：输出全量 **页面清单表**（`references/page-inventory-and-files.md`）
 - **增量**：扫描工程现状清单 + 输出 **delta 表**（add / update / deprecate，`references/incremental-wireframe-delta.md`）；P2 不建文件
 
@@ -57,7 +60,7 @@ version: 1.3.0
 - **整体复制 `template/`** 为新项目起点；不要用 `pnpm create pactor-app` 替代
 - 工程名：README 产品名 → kebab-case 英文名，创建前确认一次
 - `pnpm install` + dev 验证；核对 `references/project-structure.md`
-- 参考模块 provider/route 作样板；`yaml/models/` 是页面骨架目录（按模块目录结构存放，已注册 sitemap、菜单「页面骨架」分组可直接预览），生成时复制到目标模块目录改字段与文案；**全站生成完成后删除**参考模块、models/ 及对应 mock
+- 参考模块 provider/route 作样板；`yaml/models/` 是页面骨架目录（按模块目录结构存放，已注册 sitemap、菜单「页面骨架」分组可直接预览），生成时复制到目标模块目录改字段与文案；**全站生成完成后删除**参考模块与 models/
 
 **增量**
 
@@ -71,17 +74,13 @@ version: 1.3.0
 - 校验见 `page-inventory-and-files.md`（全量）或 `incremental-wireframe-delta.md`（增量）
 - 按 `references/component-mapping.md` 映射组件；按 `references/page-templates.md` 选列表/详情/表单模板（**数据列表页直接复制 `yaml/models/data-list.yaml` 替换占位符**）；表单一律 `Form` 包裹
 - 同步更新 `sitemap.yaml` 的 `pages` + `menus`（hidden 详情/编辑带 `activeMenu`）
-- 每页 dataSources 全部 `type: http`；交互 events + actions 闭环
+- 每页 dataSources 全部 `type: http`：**有接口文档 → url 取文档接口地址**；无 → 按 `references/data-api.md` 命名约定写 `/api/d/...`（转发层空数据回退，无需 mock）；交互 events + actions 闭环
 
-### 4. mock 服务
-
-- 按 `references/mock-data-routes.md` 注册/更新路由表与 `src/pactor/mocks/`；**增量只动变更页涉及的接口**
-
-### 5. 样式移植
+### 4. 样式移植
 
 - 按 `references/theme-and-style.md`；**增量**仅受影响页面/令牌（新建工程做全站对齐）
 
-### 6. 功能与视觉验收（必经，不可跳过）
+### 5. 功能与视觉验收（必经，不可跳过）
 
 - `references/acceptance-checklist.md`：**新建工程**逐页全站验收；**增量**对 **所有变更页** 全项验收 + **至少 1～2 个未改页回归**（菜单可达、控制台无新增 error）
 
@@ -90,16 +89,16 @@ version: 1.3.0
 | 文件 | 何时加载 |
 | --- | --- |
 | `template/` | 阶段 2 **仅新建工程**：复制为新工程起点；增量勿用 |
-| `references/incremental-wireframe-delta.md` | **已有工程**：线框图 add/update/deprecate、改 sitemap/mock/样式 |
+| `references/incremental-wireframe-delta.md` | **已有工程**：线框图 add/update/deprecate、改 sitemap/数据接口/样式 |
 | `references/project-structure.md` | 阶段 2：目录结构约定与 sitemap.yaml 骨架 |
 | `references/component-mapping.md` | 阶段 3：线框图区域 → pactor 组件映射 |
 | `references/page-templates.md` | 阶段 3：列表/详情/表单页 yaml 模板；数据列表页默认用「数据列表标准模型」（搜索 Form + 表格 + 抽屉新建/编辑） |
-| `references/mock-data-routes.md` | 阶段 4：mock 路由表模板与命名约定 |
-| `references/theme-and-style.md` | 阶段 5：主题令牌提取、皮肤、自定义 CSS、换肤 |
-| `references/acceptance-checklist.md` | 阶段 6：验收清单与结果输出格式 |
+| `references/data-api.md` | 阶段 3：数据接口层约定（纯转发、路径即契约、空数据回退、路径命名） |
+| `references/theme-and-style.md` | 阶段 4：主题令牌提取、皮肤、自定义 CSS、换肤 |
+| `references/acceptance-checklist.md` | 阶段 5：验收清单与结果输出格式 |
 | `references/page-inventory-and-files.md` | 阶段 1–3：清单列 → 目录与文件批量创建、与 sitemap 对齐 |
 
 ## Sibling skills
 
-- **`pactor-dsl`** — 无线框图的单页/清单加页；**有线框图 + mock/sitemap 联动**仍用本 skill 增量模式
+- **`pactor-dsl`** — 无线框图的单页/清单加页；**有线框图 + 数据接口/sitemap 联动**仍用本 skill 增量模式
 - **`pactor-project`** — `pnpm create pactor-app` 空壳（**不要**用其替代本 skill 的 template 复制）

package/pactor-prd/references/acceptance-checklist.md

@@ -45,5 +45,5 @@
 
 - **dev server 不会因 yaml 改动热重载**（yaml 在服务端模块加载时读取）：改 `src/server/yaml/**` 后重启 dev server 再验
 - **端口冲突**：启动前 `lsof -nP -iTCP:<port> -sTCP:LISTEN`，已有 dev server 直接复用
-- **两段数据路径被当详情解析**：选项类接口用单段路径（`/api/data/project-members` 而非 `project/members`）
+- **两段数据路径被当详情解析**：选项类接口用单段路径（`/api/d/project-members` 而非 `project/members`）
 - **toast 消失快误判未触发**：验证错误提示时在操作后立即截图/读 DOM

package/pactor-prd/references/component-mapping.md

@@ -13,7 +13,7 @@
 | 下拉筛选（操作人等枚举） | `Select` | `options` 可绑 `${data.xxx}`（接口下发选项，单段路径） |
 | 日期范围筛选 | `DatePicker` | range 模式绑 state，onChange reload |
 | 数据表格 | `Table` | `columns` + `dataSource: ${data.x.items}`；操作列按钮统一 `Button variant: link`；「编辑」与「新建」共用同一表单，仅以预填数据区分（initialValues / form.setValues） |
-| 卡片网格（约 3-4 列） | `Grid` + `Card` | `columns: 3, gap: 16`；「添加卡」用 `Card` 虚线边框自定义样式 |
+| 卡片网格（约 3-4 列） | `CardList`（业务组件） | 数据项直接携带 `icon`/`title`/`subtitle`/`tags`/`description`/`meta`/`actions` 字段；`columns`、`createText`（首格虚线新建卡）、`showCount`、事件 `onItemClick`/`onItemAction`/`onCreateClick`（`${event}` 含 item/index/key）；单卡即 `EntityCard`，无需 `For`+`Card` 手写三层结构 |
 | 状态徽标（启用/停用/告警） | `Badge` / `StatusBadge` | 颜色语义化，状态文案取自线框图 |
 | 启停开关图标（⏻） | `StatusToggleIcon` | 卡片/行内启停，onChange 闭环动作 + reload |
 | 权限控制显隐（无权限隐藏新建卡等） | 表达式 `hidden` / `if` 动作 | 绑 `${data.session.permissions}` 等，按会话裁剪 |

package/pactor-prd/references/data-api.md

@@ -0,0 +1,37 @@
+# 数据接口层（接口文档优先 + 纯转发空数据约定）
+
+**接口文档驱动（优先）**：PRD/产品文档含接口文档或接口说明时，页面 dataSources 的 url 直接取文档中的接口地址——方法、参数、返回形状均以文档为准，不再使用下述 `/api/d/...` 命名约定。同源相对路径直接写；跨域绝对地址写完整 URL（`type: http` 原生支持）。转发层与命名约定仅在**无接口文档**时兜底。
+
+页面 DSL 的 http 数据源统一入口：`app/api/d/[...parts]/route.ts`（**纯转发层，不含任何路径映射**）。**路径即契约**：DSL 中的 url（如 `/api/d/providers`）就是服务端接口路径；转发层按相同路径、方法、查询与请求体原样转发到 `$NEXT_PUBLIC_API_BASE_URL/api/d/<parts>`（携带会话 cookie，匿名 401）。
+
+**没有服务层接口时返回空数据（不报错）**：上游不可达（连接失败）、接口不存在（404）或返回非 JSON（如命中前端兜底 HTML）时，GET 返回 `{}`、POST 返回 `{ ok: true }`，页面按空态渲染。接真实后端只需把 `NEXT_PUBLIC_API_BASE_URL`（next.config.js 的 `API_BASE_URLS`）换成真实地址，页面 yaml 与转发层零改动。
+
+## 命名约定
+
+- **单段路径**：`/api/d/projects`、`/api/d/project-members`——列表/选项类一律单段 kebab-case
+- **禁止** `/api/d/project/members` 这种两段写法：`[...parts]` 会把第二段当详情 id 解析（`project/detail?id=members`），踩过的坑
+- 详情：`/api/d/<resource>/<code|id>`；子资源：`/api/d/<resource>/<code>/<sub>`；写操作：`/api/d/ops/<action>`（POST）
+- 数据源 url 与页面 id 语义对应：`project-list` 页 → `/api/d/projects`
+
+## 转发层结构
+
+```text
+浏览器（同源 /api/d/*）
+  → app/api/d/[...parts]/route.ts   纯转发：会话鉴权（匿名 401）→
+                                     fetch $NEXT_PUBLIC_API_BASE_URL/api/d/<parts>
+                                     不可达 / 404 / 非 JSON → 空数据（GET {} / POST { ok: true }）
+  → 服务端接口                        真实后端（与 DSL 同路径契约）
+```
+
+完整实现见模板工程 `app/api/d/[...parts]/route.ts`。
+
+## 对页面 yaml 的要求
+
+- dataSources 一律 `type: http`；有接口文档时 url 取文档接口地址（方法/返回形状对齐），否则按命名约定写 `/api/d/...` 最终路径
+- 列表接口返回形状约定 `{ items, total, filters? }`；详情接口对空 id 返回空对象而非 404（新建预填链路依赖）
+- 选项类接口（如下拉的操作人列表）用单段路径，页面 `options: ${data.xxx}` 绑定
+- 写操作走 `ops/` 前缀 POST，页面提交闭环（request → message → reload）不依赖返回体内容
+
+## 替换为真实接口
+
+把 `NEXT_PUBLIC_API_BASE_URL` 换成真实后端基准地址即可——页面 yaml 与转发层代码零改动。页面 dataSources 声明在无后端/真实后端两种状态下都无需改动，这就是必须 `type: http` 且路径即契约的原因。

package/pactor-prd/references/incremental-wireframe-delta.md

@@ -8,7 +8,7 @@
 
 - `src/server/yaml/sitemap.yaml`（或等价 sitemap 源）
 - 页面 yaml 目录（**模式 B** `yaml/<模块>/<id>.yaml` 或 **模式 A** `yaml/pages/*.page.yaml` — 见 `pactor-dsl/references/page-catalog-and-layout.md`）
-- PRD 风格 mock：`app/api/data/[...parts]/route.ts` + `src/pactor/mocks/`（若工程仍用 `type: service`，增量页 **仍须 http**，并迁移或仅对新页遵守红线）
+- 数据接口层：`app/api/d/[...parts]/route.ts` 纯转发（路径即契约、无服务层接口时返回空数据，见 `data-api.md`）；**无 mock 层**（若工程仍用 `type: service`，增量页 **仍须 http**，并迁移或仅对新页遵守红线）
 
 不满足时：先 **`pactor-project`** 或 **新建工程 `pactor-prd` 模式** 搭壳，再回来做增量。
 
@@ -41,12 +41,12 @@
 
 | 变更 | 动作 |
 | --- | --- |
-| **add 页面** | `mkdir` 模块目录；新建 yaml；`sitemap.yaml` 增加 `pages` + `menus`；mock 路由表 + mocks 文件 |
+| **add 页面** | `mkdir` 模块目录；新建 yaml；`sitemap.yaml` 增加 `pages` + `menus`；dataSources 直接声明最终接口路径（无需注册） |
 | **update 页面** | 改对应 yaml（结构/字段/交互/文案）；若 path 或 id 变则同步 `sitemap.yaml`、检查 `router.push` / 菜单 `pageId` |
-| **update 仅文案/字段** | 只改 yaml；mock 字段变更时改 `mocks/*` 与路由返回形状 |
-| **add 数据源** | yaml 内 `dataSources` + `app/api/data/...` 注册 + mock handler |
-| **样式** | 仅当线框图要求新页面级样式时改 `globals.css` / `login.css` / 皮肤；见 `theme-and-style.md` |
-| **deprecate** | 删 yaml；从 `pages`/`menus` 移除；删 mock 路由项；全局搜 `pageId` / 路径引用 |
+| **update 仅文案/字段** | 只改 yaml |
+| **add 数据源** | yaml 内 `dataSources` 声明即可（路径即契约，转发层无需注册） |
+| **样式** | 仅当线框图要求新页面级样式时改 `globals.css` / 皮肤；见 `theme-and-style.md` |
+| **deprecate** | 删 yaml；从 `pages`/`menus` 移除；全局搜 `pageId` / 路径引用 |
 
 **禁止**：为增量在仓库根再复制一份 `template/` 覆盖工程。
 
@@ -56,7 +56,6 @@
 | --- | --- | --- |
 | 脚手架 | 复制 `template/` | **跳过**；仅摸底 |
 | 页面 | 全量清单 N 文件 | 仅 **delta** 行对应文件 |
-| mock | 全表扩展 | 只加/改涉及接口 |
 | 样式 | 全站移植 | 仅受影响页面/令牌 |
 | 验收 | 全站清单 | **变更页全量验** + **抽 1～2 条旧页回归**（见 acceptance-checklist） |
 
@@ -65,7 +64,7 @@
 ```text
 对每个 add：存在 yaml 且 sitemap.pages 含 id 且 menus 正确
 对每个 update：page.id 未变（除非走 rename 流程）且 validate 通过
-mock：变更页涉及的所有 http 路径在 Network 200
+数据接口：变更页涉及的所有 http 路径在 Network 200（无后端时为空数据 {}，页面按空态渲染）
 ```
 
 `npx pactor validate` 仅覆盖改动的 yaml 路径。
@@ -73,4 +72,4 @@ mock：变更页涉及的所有 http 路径在 Network 200
 ## 5. 与 `pactor-dsl` 的分工
 
 - **单页小改**、无线框图、只改 DSL 语法：可用 **`pactor-dsl`**。
-- **线框图驱动**、含 mock/sitemap/多页联动：用 **本增量流程**（仍属 `pactor-prd`）。
+- **线框图驱动**、含 数据接口/sitemap/多页联动：用 **本增量流程**（仍属 `pactor-prd`）。

package/pactor-prd/references/page-inventory-and-files.md

@@ -30,7 +30,7 @@ src/server/yaml/
 3. **一次更新 sitemap**：
    - `pages`：清单中每一页一条（含 hidden 的详情/编辑）
    - `menus`：仅「进导航」的页进 group；hidden 页带 `activeMenu`
-4. **mock 批量注册**：按 `references/mock-data-routes.md`，每个 http 数据源在 `app/api/data/[...parts]/route.ts` 路由表增加一项；`src/pactor/mocks/` 按域拆分文件。
+4. **数据源声明**：按 `references/data-api.md` 命名约定，每个 http 数据源在 yaml 内直接声明最终接口路径（转发层纯转发，**无需注册**）；无后端时页面按空态渲染。
 5. **交叉检查**（生成后必做）：
 
 ```text
@@ -53,7 +53,7 @@ src/server/yaml/
 
 ## 参考模块（模板内）
 
-复制 `pactor-prd/template/` 后，保留 `yaml/provider/`、`yaml/route/` 作写法样本；新模块 **照同样目录深度** 新增；全站生成完成后删除参考模块及其 mock 路由项。
+复制 `pactor-prd/template/` 后，保留 `yaml/provider/`、`yaml/route/` 作写法样本；新模块 **照同样目录深度** 新增；全站生成完成后删除参考模块。
 
 ## 已有工程（增量）