create-dwy 0.26.0 → 0.27.0

package/templates/ai-tools/skills/Vue/dwy-admin-kit/references/v0/0.3.0.md

@@ -0,0 +1,176 @@
+<!-- 来源：@dwydev/admin-kit@0.3.0 的 frontend/admin-shell/README.md；相对链接以原仓库为准。 -->
+
+# @dwydev/admin-kit
+
+Vue 3 **管理框架与通用组合组件**：模块装配菜单与路由，统一壳布局、页头、面包屑、列表状态和管理页面展示。不读取产品 API、store 或领域模型。
+
+视觉底座用 [`@dwydev/eui`](https://www.npmjs.com/package/@dwydev/eui) 的 `EAdminLayout`，**不并入 eui**（eui 只提供 UI 原语）。
+
+## 安装
+
+```bash
+pnpm add @dwydev/admin-kit
+# peers
+pnpm add vue vue-router @dwydev/eui @dwydev/ekit lucide-vue-next
+```
+
+宿主需接入 eui theme（`@dwydev/eui/theme`）与 Tailwind。若 shell 类名未生效，把 content 扫到：
+
+```txt
+./node_modules/@dwydev/admin-kit/dist/**/*.{js,mjs}
+```
+
+### Vite 跨仓联调注意（file: / 源码 alias）
+
+若用 `file:` 或 alias 指 monorepo **源码**（而非已发布 dist），宿主 `vite.config` 必须 **dedupe 并钉死 `vue` / `vue-router`** 到应用自身 `node_modules`，否则会出现两份 vue-router，`useRoute()` inject 为 `undefined`，控制台页读 `.meta` 白屏：
+
+```ts
+resolve: {
+  dedupe: ['vue', 'vue-router'],
+  alias: {
+    vue: fileURLToPath(new URL('./node_modules/vue', import.meta.url)),
+    'vue-router': fileURLToPath(new URL('./node_modules/vue-router', import.meta.url)),
+  },
+}
+```
+
+发 npm 后消费 dist、peer 由宿主安装时通常无此问题。
+## 快速接入（壳组件模式，适合营销 + 控制台共存）
+
+```ts
+import { createAdminShell, defineAdminModule, asMenuIcon, AdminShell } from '@dwydev/admin-kit'
+import { LayoutDashboard } from 'lucide-vue-next'
+
+export const appShell = createAdminShell({
+  title: 'My App',
+  logo: '/logo.png',
+  collapsedStorageKey: 'myapp:admin:sidebar:collapsed',
+  routeMetaDefaults: { requiresAuth: true, layout: 'admin' },
+  modules: [
+    defineAdminModule({
+      id: 'dashboard',
+      order: 10,
+      menu: { key: '/dashboard', label: '概览', icon: asMenuIcon(LayoutDashboard) },
+      routes: [{
+        path: '/dashboard',
+        name: 'dashboard',
+        component: () => import('./pages/Dashboard.vue'),
+        meta: { title: '概览' },
+      }],
+    }),
+    // 隐藏菜单、仅保留直访路由
+    defineAdminModule({
+      id: 'hidden-page',
+      showInMenu: false,
+      routes: [{ path: '/internal', name: 'internal', component: () => import('./pages/Internal.vue'), meta: { title: '内部' } }],
+    }),
+  ],
+})
+
+// router: [...publicRoutes, ...appShell.routes]
+// layout:
+// <AdminShell v-bind="appShell.shellProps">
+//   <template #header-extra>…用户菜单…</template>
+// </AdminShell>
+```
+
+## 纯后台父子路由
+
+首版以**扁平绝对 path + 宿主渲染 AdminShell** 为主（与 quant-cloud 一致）。
+`path: '/'` + `children` 形态可在后续版本用 `createAdminShellRoute` 增强。
+
+## 导出
+
+| API | 说明 |
+|-----|------|
+| `createAdminShell` / `defineAdminModule` | 菜单 + 路由装配 |
+| `AdminShell` | 布局组件 |
+| `AdminPageHero` / `AdminBreadcrumb` / `AdminPageHeader` | 页头与面包屑 |
+| `asMenuIcon` / `useAdminActiveKey` / `useAdminBreadcrumb` | 工具 |
+
+## meta 约定
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 页头标题 |
+| `description` | 页头副标题 |
+| `menuKey` | 侧栏高亮（嵌套子页） |
+| `pageHero` | 默认 true；false 时页面自管页头 |
+| `breadcrumb` | 覆盖自动面包屑 |
+
+## 不负责
+
+鉴权守卫、角色模型、业务 header 内容、HTTP / Pinia。
+
+## 0.3 通用管理组件
+
+0.3 保留原根入口，新增以下显式子路径。EUI peer 下限为已修复标签关联与键盘输入操作的 2.7.2。
+
+```ts
+import { PagedTable, RecordSearch, RequestFeedback, ConfigFieldControl } from '@dwydev/admin-kit/components'
+import { usePagedList } from '@dwydev/admin-kit/composables'
+import { STATUS_TONE } from '@dwydev/admin-kit/status/tone'
+```
+
+`components` 还提供总览/统计卡、记录详情/代码/省略/日期展示、状态徽章、筛选器、图表容器及确认执行。`OverviewCard` 与 `WindowToggle` 旧名保持兼容；图表容器不引入 Plotly。密码字段和产品领域页面不在本包内。
+
+加载样式并让 Tailwind 扫描实际安装的构建产物：
+
+```css
+@import '@dwydev/eui/theme';
+@import '@dwydev/admin-kit/style.css';
+@source '../node_modules/@dwydev/eui/dist/**/*.js';
+@source '../node_modules/@dwydev/admin-kit/dist/**/*.js';
+```
+
+扫描路径以宿主 CSS 文件为基准。产品已有相应配置时只调整路径，不重复加载主题。
+
+### 分页状态
+
+`RecordSearch` 的 `label` 提供持久、视觉隐藏的输入标签；省略时沿用 `placeholder`。输入法合成回车不提交。用户手动删空或点击清空按钮时会先更新 `modelValue`，再各发一次 `clear` 与 `search`；`clear` 只用于通知，宿主统一在 `search` 中请求，避免重复加载。外部直接清空 `modelValue` 不触发搜索。
+
+`PagedTable` 在实际横向溢出时显示滑动提示，并使滚动区可键盘聚焦。需要常驻的行操作列直接使用既有列属性 `{ key: 'actions', title: '操作', width: 80, fixed: 'right' }`；仅固定较窄的操作列，避免占满窄屏。列定义及 `#cell-*` 插槽仍原样转交 EUI。
+
+`RecordEllipsis` 仅在文本实际截断时开启全文提示与键盘停靠，完整文本与占位符不增加 Tab 次数。
+
+```ts
+const list = usePagedList({
+  fetcher: async ({ page, pageSize, keyword }, request) => {
+    const result = await hostApi.list({ page, pageSize, keyword })
+    if (request.isCurrent()) hostSummary.value = result.summary
+    return { items: result.items, total: result.total }
+  },
+})
+```
+
+`hostApi` 与 `hostSummary` 由产品提供。单参数 fetcher 继续兼容；`paged-list` 子路径与 `composables` 导出同一实现。
+
+- `error` 保留原始失败对象；当前失败清空数据但不向调用方抛出，便于页面区分失败和零条记录。
+- 每次 `load` 开始清旧错误，旧请求成功/失败/finally 不得覆盖新请求。
+- `invalidate()` 停止 loading 并淘汰在途请求，保留数据、错误与筛选，允许之后再次加载。
+- `reset()` 另清空数据/错误/关键词，恢复初始每页条数和排序。
+- Vue 作用域销毁时自动 invalidate；底层 HTTP 不会被取消。
+
+### 构建与实际制品验收
+
+在仓库根执行：
+
+```sh
+pnpm --dir frontend/eui build
+pnpm --dir frontend/ekit build
+pnpm --dir frontend/admin-shell test
+pnpm --dir frontend/admin-shell build
+pnpm --dir frontend/admin-shell smoke:pack
+```
+
+smoke 将本轮实际 admin-kit/EUI/ekit tgz 安装到干净目录，检查根/子入口、类型、分页生命周期和 Vite 打包后的真实 EUI SSR；不依赖源码 alias 或共享仓库外的私有产物。它验证 Vue/Vite 消费模式，不承诺现有 ekit 可由原生 Node 无打包直接加载。其他固定依赖从官方 npm registry 安装，冷缓存需要网络。
+
+两产品可暂保留 `@dwy/components` 转出口；本地准备脚本将本包 tgz 复制到各自 `.shared-packages`，不把临时绝对路径写进 package/lock。正式 registry 接入在另行发行后切换，制品验收通过不表示已经发布。
+
+## 开发
+
+```bash
+cd frontend/admin-shell
+pnpm test
+pnpm build
+```

package/templates/ai-tools/skills/Vue/dwy-auth-web/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: dwy-auth-web
+description: 使用或排查 @dwydev/auth-web 的接入和现有功能时使用，核实消费项目实际版本。
+---
+
+# @dwydev/auth-web
+
+管理员 Cookie 登录表单与会话；宿主提供 EConfigProvider、样式和成功导航。
+
+先查项目实际依赖、锁文件与已安装包的声明文件和现有调用；版本范围不是安装版本。核实组件 props、初始化和生命周期后再使用。当前仓库清单是 0.1.0，但尚未核实对应发布标签；不能仅凭清单推断已发布包的内容。源码与接入文档在仓库 `frontend/auth-web`；先确认实际来源与版本一致。缺少证据时说明，不猜接口。项目未安装时不自行添加依赖。

package/templates/ai-tools/skills/Vue/dwy-ekit/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: dwy-ekit
-description: "@dwydev/ekit 工具库使用指南。涉及以下任何主题，**必须**使用此 skill（即使用户没有说 'ekit'）：HTTP 请求 / axios 封装 / token 刷新 / dwyeapi 响应契约对接 / localStorage / Cookie / useStorage / useCookie / 日期格式化 / 时区处理 / dayjs / 表单校验 / zod schema / vee-validate / PII 脱敏 / 剪贴板 / useClipboard / 文件下载 / Blob / 查询字符串 / qs / Vue composables（debounce / throttle / click-outside / event-listener / window-size / media-query / intersection-observer / resize-observer / useFormPersist）。本 skill 是 @dwydev/ekit 的唯一权威导航来源，禁止绕过 ekit 直接手写底层 API。"
-ekit_baseline_version: "0.8.0"
+description: 使用或排查 @dwydev/ekit 的请求、存储、日期、校验、文件和 Vue 工具时使用；按项目实际版本查证能力。
 ---
 
 # @dwydev/ekit 工具库使用指南
@@ -20,7 +19,7 @@ ekit 共 82 个对外导出。**本文档不再镜像函数签名** —— 因
 
 ### 第一步：定位 ekit 真实版本
 
-读消费方项目 `package.json`，找 `dependencies["@dwydev/ekit"]` 或 `peerDependencies["@dwydev/ekit"]`。这才是写代码的依据。
+先读消费方项目的实际安装包和锁文件确定版本，再核对 `package.json` 的依赖范围；范围不等于实际安装版本。未安装时不要假设该库已可用或自行增加依赖。
 
 ### 第二步：读 module-manifest.json（一次拿导出索引）
 

package/templates/ai-tools/skills/Vue/dwy-eui/SKILL.md

@@ -16,7 +16,7 @@ Vue 3 组件库（Reka-ui + shadcn 视觉 + Element Plus 式 API + Tailwind 4）
    node -p "require('@dwydev/eui/package.json').version"
    ```
    失败则读 `pnpm-workspace.yaml` catalog `'@dwydev/eui'`，再读 `package.json` 的 `dependencies` / `peerDependencies`。
-   仍失败：按 `v2` 给脚手架，并声明「未探测到安装版本」。
+   声明的依赖范围不代表实际安装版本。仍无法确定时说明缺口，不按任一版本猜测 API。
 
 2. **选线**：读同目录 `versions.yml`。`2.y.z` → `v2/`，`1.y.z` → `v1/`。目录不存在（例如装了 3.x 但还没有 `v3/`）→ 不要用 `v2` 冒充；按下面「读源码」拿该版本代码，并说明文档线未建。
 

package/templates/ai-tools/skills/Vue/dwy-eui/versions.yml

@@ -6,7 +6,7 @@ sparse:
   - frontend/eui/src
   - frontend/eui/package.json
 lines:
-  - match: ">=2.0.0"
+  - match: ">=2.0.0 <3.0.0"
     dir: v2
-  - match: ">=1.0.0"
+  - match: ">=1.0.0 <2.0.0"
     dir: v1

package/templates/ai-tools/skills/Vue/dwy-vue-architecture/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: dwy-vue-architecture
+description: 设计、开发或评审 Vue 项目的模块边界、依赖方向和共享代码时使用。
+---
+
+# Vue 架构
+
+先检查项目实际结构与调用链；旧项目不因启用 Skill 重建。需要设计模块与依赖边界时阅读 [分层与依赖](references/dwy-vue-layering.md)，按实际规模和项目约束使用。

package/templates/ai-tools/skills/Vue/dwy-vue-development/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dwy-vue-development
+description: 开发、修改、测试或排查 Vue 应用、组件及组合式函数时使用；覆盖团队写法、常见踩坑和自有基础库发现。
+---
+
+# Vue 开发
+
+先确认 Vue、TypeScript、构建工具及项目已有依赖。优先复用项目现有组件和工具，不自动新增自有依赖。涉及模块边界时使用可用的 dwy-vue-architecture。
+
+- [Vue 规范](references/dwy-vue-core.md)：组件、路由、样式及配置。
+- [Pinia](references/dwy-vue-pinia.md)：项目使用 Pinia 时参考。
+- [测试](references/dwy-vue-testing.md)：组件和业务测试。
+- [踩坑](references/dwy-vue-pitfalls.md)：响应式、路由和构建排查。
+- [自有基础库](references/dwy-vue-base-lib.md)：项目已使用时查 dwy-eui、dwy-ekit；管理后台和认证分别查 dwy-admin-kit、dwy-auth-web。
+
+资料中的强制选型仅适用于已采用该栈或用户明确选择的新项目，现有项目遵循现有依赖和用户要求。

package/templates/ai-tools/{rules/Vue → skills/Vue/dwy-vue-development/references}/dwy-vue-base-lib.md

@@ -1,13 +1,13 @@
 ---
-description: 团队内部基础库强制复用规范（eui UI 组件 + ekit 工具：禁重复造轮子、HTTP/存储/日期/校验/脱敏走 ekit、UI 走 eui）
+description: 已使用 eui 和 ekit 的项目如何查找和复用基础能力
 paths:
   - "**/*.vue"
   - "**/*.ts"
 ---
 
-# Vue 团队基础库强制复用规范
+# Vue 团队基础能力
 
-`dwy-vue-core` rule 的团队内补充。通用 Vue 工程规范见 `dwy-vue-core`；本文件只管「凡 eui / ekit 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子」。
+本资料适用于已采用 eui 或 ekit 的项目；版本及公开接口以实际安装包和对应 Skill 为准。项目未采用时此处仅用于了解能力，不要求引入或替换现有实现。
 
 `@dwydev/eui` 与 `@dwydev/ekit` 是团队内部 npm 基础库，分别覆盖 UI 组件层与通用工具层。
 

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-architecture/SKILL.md

@@ -39,19 +39,19 @@ description: "【dwy·技术架构】产品 0 到 1 设计与架构阶段。触
 
 ### 四层架构
 
-层名、依赖边、分包树以对应栈的 layering rule 为准，本 skill **不另定义目录**：
+层名、依赖边、分包树以对应技术栈的架构指引为准，本 skill **不另定义目录**：
 
-- Python → `dwy-python-layering`
-- Vue → `dwy-vue-layering`
+- Python → `dwy-python-architecture`
+- Vue → `dwy-vue-architecture`
 - Android → `dwy-android-layering`
-- iOS / macOS → `dwy-apple-layering`
+- iOS / macOS → `dwy-apple-architecture`
 
-铁律（细节与正反例见上列 rule）：依赖只许向下；`features/*` 互不依赖；具体实现只在 Assembly 注入；第三方版本只写在仓库根 catalog。
+团队新项目参考对应架构指引；既有项目先核实当前依赖边和模块组织，避免擅自重构。
 
 ## 实现
 [自写型]
 1. 读项目 `.claude/rules/`，结合上方架构约束产出架构（项目 rules 优先，本约束兜底）
-2. 技术架构：**先读对应栈 `dwy-*-layering` 按四层归位模块、按业务域聚目录**，再写分层/模块边界/选型理由；选型不确定处走 `AskUserQuestion`
+2. 技术架构：先读可用的对应栈架构 Skill 或 Android layering 规则，再写分层、模块边界和选型理由；选型不确定处走 `AskUserQuestion`
 3. **判有无后端**（读选型/PRD：有 API / 持久化 / 账户体系 → 有后端）：
    - **有后端** → 必出数据库设计，且**建模到位**：库表清单 / 字段(类型·约束·默认·可空) / 主外键关系 / 索引 / 必要的范式或反范式说明，与接口契约 schema 对齐
    - **纯前端**（无后端）→ 跳过数据库设计，在 `技术架构.md` 注明「无后端，不涉及库表」