create-yoya-ui 0.2.1 → 0.2.2

package/README.md

@@ -1,23 +1,24 @@
 # create-yoya-ui
 
-快速搭建 [yoya-ui](https://github.com/yoyaflow/yoya-ui) 项目的脚手架。
+快速体验 [yoya-ui](https://github.com/yoyaflow/yoya-ui) 的脚手架。
+
+## 安装
+
+```bash
+npm install -g create-yoya-ui
+```
 
 ## 用法
 
 ```bash
-npx create-yoya-ui@latest my-app                 # basic 模板（SPA）
-npx create-yoya-ui@latest my-app --template ssr  # SSR 模板
-npx create-yoya-ui@latest my-app --template admin # 后台管理模板
+create-yoya-ui my-app --template admin
 cd my-app
 npm install
+npm run dev
 ```
 
-- **basic**：默认模板，`npm run dev` 启动 Vite 开发服务器
-- **ssr**：服务端渲染模板，`npm run build && npm start`（renderPage 整页渲染 + hydrateOrMount 客户端接入）
-- **admin**：标准后台管理模板（顶部导航 + 可折叠侧栏 + RouterViews 内容区）
+- **admin**：标准后台管理模板（顶部导航 + 左侧菜单 + RouterViews 内容区）
 
 ## 模板内容
 
-- `templates/basic`：页面壳、按钮事件、表单收集校验、主题切换
-- `templates/ssr`：home-page.js（页面组件 + 词典）、server.mjs（node:http + renderPage）、client.js（hydrateOrMount）
-- `templates/admin`：标准后台管理模板（logo/系统名、顶部导航、用户头像、可折叠菜单、带标题内容区），内置数据概览看板与图表，以及成员 / 角色 / 权限 / 字典管理示例
+- `templates/admin`：标准后台管理模板（logo/系统名、顶部导航、用户头像、左侧菜单、带标题内容区），内置数据概览看板与图表，以及成员 / 角色 / 权限 / 字典管理示例

package/bin/create-yoya-ui.js

@@ -41,7 +41,7 @@ if (templateName === 'ssr') {
 } else {
   console.log('  npm run dev');
   console.log(
-    `\n${templateName === 'admin' ? '管理后台模板：顶部导航 + 可折叠侧栏 + RouterViews 内容区。' : ''}更多：npm run build 构建，npm run preview 预览产物。\n`
+    `\n${templateName === 'admin' ? '管理后台模板：顶部导航 + 左侧菜单 + RouterViews 内容区。' : ''}更多：npm run build 构建，npm run preview 预览产物。\n`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yoya-ui",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Scaffold a new yoya-ui project with Vite: basic template (SPA) or SSR template (renderPage + hydrateOrMount).",
   "type": "module",
   "bin": {

package/templates/admin/README.md

@@ -5,7 +5,7 @@
 - 左上角：logo + 系统名
 - 中间：顶级导航
 - 右上角：用户头像
-- 下方：左侧可折叠菜单 + 右侧带标题的 RouterViews 内容区
+- 下方：左侧菜单 + 右侧带标题的 RouterViews 内容区
 - 点击顶级导航切换左侧菜单与内容路由
 
 ## 启动
@@ -23,55 +23,67 @@ npm run dev
 
 ```text
 src/
-  main.js                       入口：初始化主题、创建路由与外壳并挂载
+  main.js                       入口：初始化主题、加载菜单状态、装配外壳并挂载
   api/
     fetch.api.js                原始传输层（fetch 实现，换请求库只改这里）
     domain.api.js               领域请求入口：统一 Result 解析 + mock/真实切换
-  app/
-    modules.js                  模块配置（顶级导航 → 左侧菜单 → 路由）
-    router.js                   路由组装（占位页兜底）
-    admin-shell.js              AdminShell 页面组件（顶栏 + 侧栏 + 内容区组合）
-  ui/
-    placeholder-page.js         PlaceholderPage 通用占位页
-    app-navbar.js               AppNavbar 顶部导航（logo + 顶级导航 + 主题/头像）
-    app-sidebar.js              AppSidebar 左侧导航外壳
-    sidebar-menu.js             SidebarMenu 模块菜单组件
-  features/
-    dashboard/                  工作台（数据概览示例：数字看板 / 趋势卡 / 图表）
-      pages/dashboard-overview-page.js 页面编排：核心指标看板 + 趋势卡 + 图表 + 资源使用
-      components/dashboard-chart.js     vChart 内置 SVG 适配器（柱状图 / 折线图）
-    members/                    成员管理业务域（CRUD 示例）
-      pages/member-list-page.js 页面编排：组合工具栏、表格、弹窗与分页
-      components/
-        member-toolbar.js       MemberToolbar 搜索/新增工具栏
-        member-table.js         MemberTable 成员表格
-        member-form-dialog.js   MemberFormDialog 新增/编辑弹窗
-      api/
-        member.mgr.js           管理请求命令（增删改查等）
-        member.req.js           外部请求命令（其他模块调用本域能力）
-        member.views.js         领域结果结构（列表项 / 详情）
-        member.state.js         状态类 MembersPageState：持有数据与筛选，动作 submit 命令后驱动视图
-        member.mock.js          演示用内存 mock（接入真实后端后删除）
-      utils/options.js          领域常量（角色/状态选项与文案）
-    permissions/                权限管理业务域（vTree 权限树示例）
-      pages/permission-list-page.js 页面编排：权限树 + 工具栏 + 表单弹窗 + 删除确认
-      components/
-        permission-form-dialog.js PermissionFormDialog 新增/编辑权限弹窗
-      api/
-        permission.mgr.js       权限管理请求命令（查询树 / 新增 / 编辑 / 删除）
-        permission.state.js     状态类 PermissionsPageState
-        permission.views.js     权限节点结构
-        permission.mock.js      演示用内存 mock
-    roles/                      角色管理业务域（分页 CRUD 示例）
-      pages/role-list-page.js   页面编排：搜索 + 表格 + 分页 + 表单弹窗
-      components/               RoleToolbar / RoleTable / RoleFormDialog
-      api/                      请求命令 / 状态类 / 结果结构 / mock
-    dicts/                      字典管理业务域（字典类型 + 字典项主从示例）
-      pages/dict-list-page.js   页面编排：字典类型表格 + 编辑弹窗（基本信息 + 字典值表格）
-      components/               DictEditorDialog / DictItemFormDialog
-      api/                      请求命令 / 状态类 / 结果结构 / mock
+  shared/                       跨模块共享（按类别集中管理）
+    ui.buttons.js               按钮类共享 UI（RowActionButton 行内操作按钮）
+    ui.pages.js                 页面类共享 UI（PlaceholderPage 路由占位页）
+  shell/                        应用外壳（按 api / components 组织）
+    api/
+      shell.req.js              外壳请求命令：QueryMenus 获取菜单（可换服务端接口）
+      shell.mock.js             外壳 mock：模拟服务端返回（viewKey 由客户端映射页面）
+      shell.views.js            外壳结果结构（Module / Route）
+      shell.state.js            外壳状态类 ShellState：菜单 + 导航状态（当前模块/路径），加载时创建并持有路由，暴露导航动作（switchModule / navigate）
+    components/
+      admin-shell.js            AdminShell 外壳装配（布局组装 + 顶栏/侧栏从状态派生）
+      app-navbar.js             AppNavbar 顶部导航（logo + 顶级导航 + 主题/头像）
+      app-sidebar.js            AppSidebar 左侧导航外壳
+      sidebar-menu.js           SidebarMenu 模块菜单组件
+    router.js                   路由组装：viewKey → 页面组件映射 + 404 占位页兜底
+  features/                     业务域 = 父模块节点（对应顶级菜单），下按菜单项分子模块
+    dashboard/                  工作台
+      overview/                 数据概览
+        pages/dashboard-overview-page.js 页面编排：核心指标看板 + 趋势卡 + 图表 + 资源使用
+        components/dashboard-chart.js     vChart 内置 SVG 适配器（柱状图 / 折线图）
+      todos/                    待办审批（简单页示例）
+        pages/todo-approval-page.js
+    ops/                        运维
+      services/                 服务清单（简单页示例）
+        pages/service-list-page.js
+      deploys/                  部署任务（简单页示例）
+        pages/deploy-list-page.js
+    system/                     系统
+      members/                  成员管理业务域（CRUD 完整模块示例）
+        pages/member-list-page.js 页面编排：组合工具栏、表格、弹窗与分页
+        components/
+          member-toolbar.js     MemberToolbar 搜索/新增工具栏
+          member-table.js       MemberTable 成员表格
+          member-form-dialog.js MemberFormDialog 新增/编辑弹窗
+        api/
+          member.mgr.js         管理请求命令（增删改查等）
+          member.req.js         外部请求命令（其他模块调用本域能力）
+          member.views.js       领域结果结构（列表项 / 详情）
+          member.state.js       状态类 MembersPageState：持有数据与筛选，动作 submit 命令后驱动视图
+          member.mock.js        演示用内存 mock（接入真实后端后删除）
+        utils/options.js        领域常量（角色/状态选项与文案）
+      roles/                    角色管理业务域（分页 CRUD 示例）
+        pages/role-list-page.js 页面编排：搜索 + 表格 + 分页 + 表单弹窗
+        components/             RoleToolbar / RoleTable / RoleFormDialog
+        api/                    请求命令 / 状态类 / 结果结构 / mock
+      permissions/              权限管理业务域（vTree 权限树示例）
+        pages/permission-list-page.js 页面编排：权限树 + 工具栏 + 表单弹窗 + 删除确认
+        components/             PermissionFormDialog
+        api/                    请求命令 / 状态类 / 结果结构 / mock
+      dicts/                    字典管理业务域（字典类型 + 字典项主从示例）
+        pages/dict-list-page.js 页面编排：字典类型表格 + 编辑弹窗（基本信息 + 字典值表格）
+        components/             DictEditorDialog / DictItemFormDialog
+        api/                    请求命令 / 状态类 / 结果结构 / mock
 ```
 
-目录规则遵循 yoya-ui skill 的业务模块组织（feature 自包含、页面只编排、service 里 api 管数据交互、state 管状态）。
+目录规则遵循 yoya-ui skill 的业务模块组织（feature 自包含、页面只编排、api 管数据交互、state 管状态）。每个菜单项对应 `features/` 下的一个子模块目录；简单页只放 `pages/` 文件，有数据交互的页面展开 api / components / pages / utils。
 
-扩展新模块：在 `app/modules.js` 的 `modules` 数组里加一组 `{ key, label, icon, routes }`；有数据交互的页面参考 `features/members` 的 api / pages 分层。
+扩展新模块：在 `features/` 下建父模块目录（如 `features/orders/`），每个菜单项对应一个子目录；在 `shell/api/shell.mock.js` 模拟返回的菜单数据里加一组 `{ key, label, icon, routes }`（key 与父目录名一致），并把菜单项的 `viewKey` 注册到 `shell/router.js` 的视图注册表。接入真实后端时删除 `shell.mock.js`，由服务端返回同样的菜单结构即可。简单页只放 `pages/` 文件，有数据交互的页面参考 `features/system/members` 的 api / components / pages 分层。
+
+完整开发规则见 [RULES.md](./RULES.md)（目录结构、命名、api 分层、请求命令范式、共享组件、导航状态等）。

package/templates/admin/RULES.md

@@ -0,0 +1,105 @@
+# yoya-ui admin 模板开发规则
+
+本文件是 admin 模板的开发规则全集：目录结构、命名、api 分层、请求命令范式、共享组件、导航状态、页面与 mock 接入。以代码为准，新增/修改功能时先对照本文件。
+
+## 1. 目录结构
+
+```text
+src/
+  main.js                装配根：注册 mock → 加载状态 → 装配外壳 → 启动
+  api/                   全局传输层（fetch.api.js / domain.api.js）
+  shared/                跨模块共享（按类别集中）
+  shell/                 应用外壳（也是模块，按 api / components 组织）
+  features/              业务域 = 父模块节点（对应顶级菜单）
+    <父模块>/<菜单项>/     每个菜单项一个子模块，自包含 api / components / pages / utils
+```
+
+- **配置即目录**：菜单 `key` = features 父目录名 = 路由前缀（`system` ↔ `features/system/` ↔ `/system/members`）
+- **模块自包含**：叶子模块只依赖自己的 api / components / pages / utils，不跨模块 import 内部实现
+- **依赖方向**：跨模块唯一允许的引用是业务域 `req.js`（对外能力入口）；`shared → features/<域>/api/req.js` 是允许的公开单向依赖
+
+## 2. 文件命名
+
+- api 层：`<域>.<层>.js`（`member.mgr.js`、`shell.req.js`、`ui.buttons.js`）
+- 页面：`<名字>-page.js`（`member-list-page.js`、`todo-approval-page.js`）
+- 组件：PascalCase（`AdminShell`、`MemberTable`）
+- 共享 UI 类别文件：`ui.<类别>.js`（`ui.buttons.js`、`ui.pages.js`）
+
+## 3. api 分层
+
+每个业务域（含外壳）的 `api/` 按职责分文件：
+
+- `mgr.js`：本域管理请求命令（增删改查等）
+- `req.js`：对外能力入口（其他模块 / 共享组件调用本域时使用）
+- `views.js`：领域结果结构（纯数据类），由命令的 `toItem / toDetail` 映射
+- `state.js`：状态类，持有数据与筛选，`subscribe(listener)` 通知视图更新
+- `mock.js`：演示用内存 mock（接入真实后端后删除）
+
+判据：有管理动作用 `mgr.js`；只提供查询给外部用 `req.js`；两者可并存（如 `member.mgr.js` + `member.req.js`）。
+
+## 4. 请求命令范式
+
+- 构造器收**单一 `init` 对象**，`id` / `parentId` / `typeId` 等字段也放里面，不单独取参数
+- 导出为工厂：`命令名: (init) => new 命令类(init)`
+- 消费方：`Mgr.命令({ ... }).submit()`，不写 `new`
+- 命令类继承 `RequestBase`，覆写 `address() / method() / params() / body() / toItem() / toDetail()`
+
+```js
+export default {
+  Query: (init) => new Query(init),
+  Create: (init) => new Create(init),
+  Update: (init) => new Update(init),
+  Remove: (init) => new Remove(init)
+};
+```
+
+## 5. 共享组件
+
+- **通用 UI**（无业务语义）：放 `shared/ui.<类别>.js`
+- **业务共享组件**（带业务语义且多模块使用）：放 `shared/<组件>/` 自包含子目录（组件 + 状态 + 文案），对外只暴露工厂
+- **数据获取走 req.js**：共享组件需要业务数据时调用所属域 `api/<域>.req.js` 的公开能力（如 `MemberReq.QueryAvailable().submit()`），不自造数据请求、不注入数据源
+- **不深层 import**：只允许跨模块引用 `req.js`，不 import 业务域的 pages / components / state 内部实现
+- **自包含 UI 与状态**：弹窗、下拉、open/close 状态内聚在组件内，对外暴露工厂与必要方法（`open()/close()/value()`），不暴露内部状态实现
+- **浮层自洽**：弹窗/下拉类共享组件自带 fixed 定位逻辑，不依赖使用方容器样式
+
+## 6. 外壳与导航状态
+
+- `ShellState` 是导航状态（当前模块 / 当前路径）的**唯一事实源**，持有 router，暴露 `switchModule(module)` / `navigate(path)`
+- 路由订阅驱动同步：`router.subscribe → state.syncFromPath(path)`，状态变化时通知订阅者
+- 顶栏 / 侧栏从状态**派生高亮**，组件不持有自己的激活状态
+- `AdminShell` 只做装配：布局组装 + 状态接线，不直接操作 router
+- 组件统一写法：节点在 `render()` 内声明式构建，内部引用（如 sidebar 实例、items Map）只用于动态更新
+- 前进 / 后退、同模块内切换路由的高亮同步由状态管道自动完成，不需要手动调用
+
+## 7. 页面规则
+
+- **简单 / 占位页**：只放 `pages/<页面>-page.js`，可复用 `shared/ui.pages.js` 的 `PlaceholderPage`
+- **有数据交互的页面**：展开完整模块（api / components / pages / utils）
+- 页面只做编排：组合子组件、绑定事件、调用 state 动作，不写请求逻辑
+
+## 8. mock 与数据接入
+
+- 所有 mock 在 `main.js` 导入注册（副作用导入）
+- mock 返回 `{ ok, data }` 结构，统一经 `Result.from` 解析
+- 接入真实后端：删除对应 `mock.js`（或替换为真实接口），调用方零改动
+
+## 9. 类型声明同步
+
+- 改了 mgr / req / views / state 的 js 接口，必须同步对应 `d.ts`
+- `d.ts` 与运行时一致：导出为工厂函数类型（如 `(init?) => Query`），不用 `typeof` 构造器类型
+
+## 10. 新增菜单项 checklist（三处同步）
+
+1. `features/` 建父模块目录与菜单项子目录、页面文件
+2. `shell/api/shell.mock.js` 菜单数据加 `{ key, label, icon, routes: [{ path, title, viewKey }] }`，`key` 与目录名一致
+3. `shell/router.js` 的 `viewRegistry` 注册 `viewKey → 页面组件`
+
+## 11. 启动流程
+
+`main.js` 固定顺序：
+
+1. 导入并注册所有 mock（含 `shell.mock.js`）
+2. `state.load()`：获取菜单 + 创建路由 + 订阅导航
+3. `AdminShell({ state })` 装配外壳
+4. `shell.render().bindTo('#app')`
+5. `state.start()` 启动路由