create-lumal-admin 0.0.5-beta → 0.0.6-beta

package/templates/base/tests/session.test.ts.template

@@ -1,34 +1,45 @@
-import { describe, expect, it } from 'vitest'
-import { createApplicationSession } from '../src/services/session-runtime'
+import { describe, expect, it } from 'vitest';
+import { createApplicationSession } from '../src/app/services/session-runtime';
 
 describe('应用会话', () => {
   it('统一清理认证、权限、菜单与标签', () => {
-    const values = new Map<string, string>()
+    const values = new Map<string, string>();
     const storage = {
       getItem: (key: string) => values.get(key) ?? null,
-      setItem: (key: string, value: string) => { values.set(key, value) },
-      removeItem: (key: string) => { values.delete(key) },
+      setItem: (key: string, value: string) => {
+        values.set(key, value);
+      },
+      removeItem: (key: string) => {
+        values.delete(key);
+      },
       clear: () => values.clear(),
       key: (index: number) => [...values.keys()][index] ?? null,
-      get length() { return values.size },
-    }
-    const app = createApplicationSession(() => ({
-      login: async () => ({ accessToken: 'test-only' }),
-      getUser: async () => ({ id: '1', username: 'test', name: 'Test' }),
-      getAccess: async () => ({ roles: ['admin'], permissions: ['read'] }),
-      getMenus: async () => [],
-      logout: async () => {},
-      clearCache: () => {},
-      list: async () => ({ items: [], total: 0 }),
-      save: async () => {},
-      remove: async () => {},
-    }), storage, storage)
-    app.session.setSession({ accessToken: 'test-only' })
-    app.permissionStore.setPermissions(['read'])
-    storage.setItem(app.tabStorageKey, 'old-tabs')
-    app.reset()
-    expect(app.isAuthenticated()).toBe(false)
-    expect(app.permissionStore.permissions).toEqual([])
-    expect(storage.getItem(app.tabStorageKey)).toBeNull()
-  })
-})
+      get length() {
+        return values.size;
+      },
+    };
+    const app = createApplicationSession(
+      () => ({
+        login: async () => ({ accessToken: 'test-only' }),
+        getUser: async () => ({ id: '1', username: 'test', name: 'Test' }),
+        getAccess: async () => ({ roles: ['admin'], permissions: ['read'] }),
+        getMenus: async () => [],
+        logout: async () => {},
+        clearCache: () => {},
+        request: async <T>() => undefined as T,
+        list: async () => ({ items: [], total: 0 }),
+        save: async () => {},
+        remove: async () => {},
+      }),
+      storage,
+      storage,
+    );
+    app.session.setSession({ accessToken: 'test-only' });
+    app.permissionStore.setPermissions(['read']);
+    storage.setItem(app.tabStorageKey, 'old-tabs');
+    app.reset();
+    expect(app.isAuthenticated()).toBe(false);
+    expect(app.permissionStore.permissions).toEqual([]);
+    expect(storage.getItem(app.tabStorageKey)).toBeNull();
+  });
+});

package/templates/base/vite.config.ts

@@ -1,6 +1,6 @@
-import { fileURLToPath, URL } from 'node:url'
-import vue from '@vitejs/plugin-vue'
-import { defineConfig } from 'vite'
+import { fileURLToPath, URL } from 'node:url';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
 
 /***********************应用开发配置*********************/
 export default defineConfig({
@@ -51,4 +51,4 @@ export default defineConfig({
       '@': fileURLToPath(new URL('./src', import.meta.url)),
     },
   },
-})
+});

package/templates/blank/README.md

@@ -0,0 +1,6 @@
+# Vue 项目
+
+Vue 3 + TypeScript + Vite。运行时仅依赖 Vue，无登录、路由、Store 或后台框架。
+
+首次运行 `pnpm install`，开发使用 `pnpm dev`，提交前执行 `pnpm check`。
+工程规范见 [开发约定](docs/DEVELOPMENT.md)。

package/templates/blank/src/App.vue

@@ -0,0 +1,11 @@
+<template>
+  <main class="app">
+    <h1>Vue</h1>
+  </main>
+</template>
+
+<style scoped>
+.app {
+  padding: 24px;
+}
+</style>

package/templates/common/AGENTS.md

@@ -0,0 +1,13 @@
+# 项目开发指令
+
+先阅读 [开发约定](docs/DEVELOPMENT.md)，再修改代码。
+
+- 使用 Vue 3、Composition API、`<script setup lang="ts">` 和明确的 TypeScript 类型。
+- 组合式逻辑按 `/***********************说明*********************/` 分块，模板引用使用 `useTemplateRef`。
+- 只使用依赖包的公开 API，不导入 Lumal Monorepo 私有源码。
+- 组件负责呈现，Composable 负责复用状态与生命周期，API Adapter 负责后端字段转换。
+- 路由负责页面装配，Store 只保存跨页面状态；业务规则留在业务模块。
+- 前端认证、菜单和按钮权限不能替代服务端鉴权。
+- 新增页面、修改接口或公共行为时补充对应测试，禁止将接口失败伪装成演示成功。
+- 不添加未使用的重依赖，不批量改写无关文件，不提交凭据、私有数据或构建产物。
+- 完成前执行 `pnpm check`，分别报告通过、失败和未执行的检查。

package/templates/common/_editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2

package/templates/common/_gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.woff2 binary

package/templates/{base → common}/_gitignore

@@ -4,3 +4,4 @@ coverage/
 .env.local
 .env.*.local
 *.log
+.pnpm-store/

package/templates/common/_prettierignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+coverage/
+.pnpm-store/
+pnpm-lock.yaml
+**/*.d.ts

package/templates/common/docs/DEVELOPMENT.md

@@ -0,0 +1,26 @@
+# 开发约定
+
+## 通用
+
+组件使用 PascalCase 文件名，目录、普通 TypeScript 文件使用 kebab-case。
+页面负责组合功能组件；组件通过 props/emits 通信，真正跨页面的状态才放入 Store。
+异步副作用必须处理加载、失败、取消和卸载，不用假成功替代后端错误。
+公共逻辑优先使用稳定生态或已安装包的公开 API，禁止导入 `packages/*/src`。
+业务响应在 API Adapter 中转成稳定类型，校验与业务规则不散落到模板。
+
+ESLint 负责质量与依赖约束，Prettier 负责格式。不要同时开启其他格式化插件。
+`src/shared` 不反向依赖业务模块；存在 admin/screen 双域时两者互不依赖。
+只有当前项目存在相应目录时才应用这些边界，不要求 Blank 建立业务架构。
+
+## 测试与检查
+
+- 新增页面：覆盖关键交互、加载失败和权限边界。
+- 修改接口：验证响应转换、错误、取消和会话切换，不只验证成功路径。
+- 修改公共能力：增加契约回归测试，同时检查已有消费者。
+- 布局、图表、Canvas、地图或点击坐标变化：必要时运行真实浏览器检查，DOM 模拟不能证明布局正确。
+
+统一命令：`pnpm lint`、`pnpm format:check`、`pnpm typecheck`、`pnpm test`、`pnpm build`。
+提交前运行 `pnpm check`。初次安装生成 lockfile，之后使用 `pnpm install --frozen-lockfile`。
+`pnpm format` 应可重复运行且不产生新变化；依赖、产物与声明文件不参与格式化。
+
+<!-- PROJECT_CONVENTIONS -->

package/templates/common/eslint.config.mjs

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import antfu from '@antfu/eslint-config';
+import prettier from 'eslint-config-prettier/flat';
+import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';
+import importX from 'eslint-plugin-import-x';
+
+const root = fileURLToPath(new URL('.', import.meta.url));
+const hybrid =
+  existsSync(new URL('./src/admin', import.meta.url)) && existsSync(new URL('./src/screen', import.meta.url));
+
+export default antfu(
+  {
+    vue: true,
+    typescript: true,
+    // Prettier 独占格式化；不启用 Antfu 的格式插件。
+    stylistic: false,
+    formatters: false,
+    ignores: ['**/dist/**', '**/coverage/**', '**/*.d.ts', 'pnpm-lock.yaml', '**/*.md'],
+    rules: {
+      'antfu/if-newline': 'off',
+      'antfu/curly': 'off',
+      'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
+      'vue/component-name-in-template-casing': ['error', 'PascalCase', { registeredComponentsOnly: true }],
+      'vue/component-api-style': ['error', ['script-setup']],
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'node/prefer-global/process': 'off',
+    },
+  },
+  {
+    files: ['src/**/*.{ts,vue}'],
+    plugins: { 'import-x': importX },
+    settings: {
+      'import-x/resolver-next': [
+        createTypeScriptImportResolver({ project: fileURLToPath(new URL('./tsconfig.json', import.meta.url)) }),
+      ],
+    },
+    rules: {
+      'import-x/no-cycle': ['error', { ignoreExternal: true }],
+      'import-x/no-restricted-paths': [
+        'error',
+        {
+          basePath: root,
+          zones: [
+            { target: './src/shared', from: './src/modules', message: '共享层不得反向依赖业务模块。' },
+            ...(hybrid
+              ? [
+                  { target: './src/screen', from: './src/admin' },
+                  { target: './src/admin', from: './src/screen' },
+                  { target: './src/shared', from: ['./src/admin', './src/screen'] },
+                ]
+              : []),
+          ],
+        },
+      ],
+    },
+  },
+  prettier,
+);

package/templates/common/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "template-base",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^8.2.0",
+    "@types/node": "^24.6.1",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "eslint": "^9.37.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.5",
+    "vue-tsc": "^3.1.1"
+  }
+}

package/templates/common/prettier.config.mjs

@@ -0,0 +1,8 @@
+export default {
+  semi: true,
+  singleQuote: true,
+  tabWidth: 2,
+  printWidth: 120,
+  trailingComma: 'all',
+  endOfLine: 'lf',
+};

package/templates/{base → common}/tsconfig.json

@@ -11,12 +11,9 @@
     "ignoreDeprecations": "6.0",
     "types": ["vite/client", "node"],
     "strict": true,
+    "noEmit": true,
     "isolatedModules": true,
     "skipLibCheck": true
   },
-  "include": [
-    "src/**/*.ts",
-    "src/**/*.vue",
-    "vite.config.ts"
-  ]
+  "include": ["src/**/*.ts", "src/**/*.vue", "tests/**/*.ts", "vite.config.ts", "vitest.config.ts"]
 }

package/templates/common/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({ test: { environment: 'node' } });

package/templates/features/examples/src/modules/examples/CrudExampleView.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import type { CrudDataSource, SchemaTableRow } from '@lumal/core/components';
+import { LumalCrudTable } from '@lumal/core/components';
+
+/***********************隔离的 CRUD 示例数据*********************/
+let rows: SchemaTableRow[] = [{ id: 'example', name: '示例记录', status: 'enabled' }];
+const columns = [
+  { field: 'name', label: '名称' },
+  { field: 'status', label: '状态' },
+];
+const dataSource: CrudDataSource = {
+  fetch: async ({ page, pageSize, query }) => {
+    const filtered = rows.filter((row) => String(row.name).includes(String(query.keyword ?? '')));
+    return { items: filtered.slice((page - 1) * pageSize, page * pageSize), total: filtered.length };
+  },
+  create: async (model) => {
+    rows = [...rows, { ...model, id: crypto.randomUUID() }];
+  },
+  update: async (row, model) => {
+    rows = rows.map((item) => (item.id === row.id ? { ...model, id: row.id } : item));
+  },
+  remove: async (row) => {
+    rows = rows.filter((item) => item.id !== row.id);
+  },
+};
+</script>
+
+<template>
+  <main class="lumal-admin-page">
+    <LumalCrudTable
+      title="CRUD 示例"
+      :data-source="dataSource"
+      :table="{ columns, rowKey: 'id', showColumnSettings: true, selection: true }"
+      :query="{ schemas: [{ field: 'keyword', label: '关键词', component: 'input' }] }"
+      :form-schemas="[
+        { field: 'name', label: '名称', component: 'input', required: true },
+        {
+          field: 'status',
+          label: '状态',
+          component: 'select',
+          options: [
+            { label: '启用', value: 'enabled' },
+            { label: '停用', value: 'disabled' },
+          ],
+          defaultValue: 'enabled',
+        },
+      ]"
+      :toolbar="{ export: true, refresh: true }"
+    />
+  </main>
+</template>

package/templates/features/examples/src/{views → modules}/examples/FormExampleView.vue

@@ -1,19 +1,26 @@
 <script setup lang="ts">
-import type { SchemaFormItem, SchemaFormModel } from '@lumal/core/components'
-import { LumalSchemaForm } from '@lumal/core/components'
-import { ElMessage } from 'element-plus'
-import { shallowRef } from 'vue'
+import type { SchemaFormItem, SchemaFormModel } from '@lumal/core/components';
+import { LumalSchemaForm } from '@lumal/core/components';
+import { ElMessage } from 'element-plus';
+import { shallowRef } from 'vue';
 
 /***********************Schema 与联动*********************/
-const model = shallowRef<SchemaFormModel>({})
+const model = shallowRef<SchemaFormModel>({});
 const schemas: SchemaFormItem[] = [
   { field: 'name', label: '名称', required: true, component: 'input' },
   { field: 'date', label: '日期', component: 'date', componentProps: { valueFormat: 'YYYY-MM-DD' } },
   { field: 'notify', label: '邮件通知', component: 'switch' },
-  { field: 'email', label: '邮箱', component: 'input', hidden: ({ model }) => !model.notify, required: ({ model }) => Boolean(model.notify), rules: [{ type: 'email', message: '请输入有效邮箱' }] },
-]
+  {
+    field: 'email',
+    label: '邮箱',
+    component: 'input',
+    hidden: ({ model }) => !model.notify,
+    required: ({ model }) => Boolean(model.notify),
+    rules: [{ type: 'email', message: '请输入有效邮箱' }],
+  },
+];
 function submit(): void {
-  ElMessage.success('保存成功')
+  ElMessage.success('保存成功');
 }
 </script>
 

package/templates/features/examples/src/modules/examples/module.ts

@@ -0,0 +1,27 @@
+import type { AppModule } from '../../app/module';
+
+export const menus: AppModule['menus'] = [
+  {
+    path: '/examples',
+    name: 'Examples',
+    meta: { title: '开发示例', icon: 'lumal:code', order: 80 },
+    children: [
+      {
+        path: '/examples/form',
+        name: 'SchemaFormExample',
+        component: 'examples/form',
+        meta: { title: 'Schema 表单', keepAlive: true },
+      },
+      {
+        path: '/examples/crud',
+        name: 'CrudExample',
+        component: 'examples/crud',
+        meta: { title: 'CRUD 示例', keepAlive: true },
+      },
+    ],
+  },
+];
+export const views: AppModule['views'] = {
+  'examples/form': () => import('./FormExampleView.vue'),
+  'examples/crud': () => import('./CrudExampleView.vue'),
+};

package/templates/features/system/src/modules/system/config/ConfigView.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import type { SchemaFormItem, SchemaFormModel } from '@lumal/core/components';
+import { LumalPage, LumalSchemaForm } from '@lumal/core/components';
+import { ElAlert, ElButton, ElColorPicker, ElMessage, ElMessageBox } from 'element-plus';
+import { shallowRef, watch } from 'vue';
+import { permissionStore, service } from '../../../app/services/session';
+import { useAsyncData } from '../../../shared/composables/use-async-data';
+import { configInput, createConfigService } from './api';
+
+/***********************配置加载与独立表单*********************/
+const api = createConfigService(service);
+const state = useAsyncData(api.get, null);
+const model = shallowRef<SchemaFormModel>({});
+const saving = shallowRef(false);
+const failure = shallowRef('');
+const canSave = () => permissionStore.hasPermission('system:config:update');
+watch(state.data, (value) => {
+  if (value) model.value = { ...value };
+});
+const schemas: SchemaFormItem[] = [
+  { field: 'appName', label: '应用名称', required: true, rules: [{ max: 64, message: '应用名称最多 64 个字符' }] },
+  { field: 'colorPrimary', label: '主题色', required: true },
+  {
+    field: 'layout',
+    label: '导航布局',
+    component: 'select',
+    required: true,
+    options: [
+      { label: '侧边导航', value: 'sidebar-nav' },
+      { label: '顶部导航', value: 'top-nav' },
+      { label: '混合导航', value: 'mixed-nav' },
+    ],
+  },
+  { field: 'tabbarEnable', label: '标签栏', component: 'switch' },
+  { field: 'transitionEnable', label: '页面动画', component: 'switch' },
+];
+
+/***********************保存、重置与失败恢复*********************/
+async function persist(values: SchemaFormModel, restore = false): Promise<void> {
+  if (saving.value || state.loading.value || !canSave()) return;
+  saving.value = true;
+  failure.value = '';
+  try {
+    const next = restore ? await api.restore() : await api.save(configInput(values));
+    model.value = { ...next };
+    ElMessage.success(restore ? '已恢复默认配置' : '配置已保存');
+  } catch (reason) {
+    failure.value = reason instanceof Error ? reason.message : '配置保存失败';
+  } finally {
+    saving.value = false;
+  }
+}
+async function restore(): Promise<void> {
+  try {
+    await ElMessageBox.confirm('恢复系统默认配置？', '恢复默认', { type: 'warning' });
+  } catch {
+    return;
+  }
+  await persist({}, true);
+}
+async function reload(): Promise<void> {
+  if (saving.value || state.loading.value) return;
+  failure.value = '';
+  await state.reload();
+}
+</script>
+
+<template>
+  <LumalPage class="lumal-admin-page" title="系统配置">
+    <ElAlert v-if="state.error.value || failure" :title="state.error.value || failure" type="error" :closable="false">
+      <ElButton link :loading="state.loading.value" :disabled="saving" @click="reload"> 重新加载 </ElButton>
+    </ElAlert>
+    <div v-if="state.data.value" class="config-form">
+      <LumalSchemaForm
+        v-model="model"
+        :schemas="schemas"
+        :columns="2"
+        :mode="canSave() ? 'edit' : 'view'"
+        :show-actions="canSave()"
+        :disabled="saving || state.loading.value"
+        :submit-disabled="state.loading.value"
+        :submit-loading="saving"
+        submit-text="保存配置"
+        @submit="persist"
+      >
+        <template #field-colorPrimary="{ value }">
+          <ElColorPicker
+            :model-value="String(value || '')"
+            :disabled="!canSave() || saving || state.loading.value"
+            @update:model-value="model = { ...model, colorPrimary: $event }"
+          />
+        </template>
+      </LumalSchemaForm>
+      <ElButton :disabled="saving" :loading="state.loading.value" @click="reload"> 重读配置 </ElButton>
+      <ElButton v-if="canSave()" :disabled="saving" @click="restore"> 恢复默认配置 </ElButton>
+    </div>
+  </LumalPage>
+</template>
+
+<style scoped>
+.config-form {
+  max-width: 900px;
+}
+</style>

package/templates/features/system/src/modules/system/config/api.ts

@@ -0,0 +1,38 @@
+import type { SchemaFormModel } from '@lumal/core/components';
+import type { BusinessTransport } from '../../../app/services/contracts';
+import { object, text } from '../../../shared/api';
+
+export interface SystemConfig {
+  appName: string;
+  colorPrimary: string;
+  layout: 'sidebar-nav' | 'top-nav' | 'mixed-nav';
+  tabbarEnable: boolean;
+  transitionEnable: boolean;
+}
+export function configInput(model: SchemaFormModel): SystemConfig {
+  const appName = text(model.appName, '应用名称', true);
+  const colorPrimary = text(model.colorPrimary, '主题色', true);
+  if (
+    appName.length > 64 ||
+    !/^#[\da-f]{6}$/i.test(colorPrimary) ||
+    !['sidebar-nav', 'top-nav', 'mixed-nav'].includes(String(model.layout))
+  )
+    throw new Error('应用名称、主题色或导航布局无效');
+  if (typeof model.tabbarEnable !== 'boolean' || typeof model.transitionEnable !== 'boolean')
+    throw new Error('标签栏和动画设置必须是布尔值');
+  return {
+    appName,
+    colorPrimary,
+    layout: model.layout as SystemConfig['layout'],
+    tabbarEnable: model.tabbarEnable,
+    transitionEnable: model.transitionEnable,
+  };
+}
+export function createConfigService(transport: BusinessTransport) {
+  return {
+    get: async () => configInput(object(await transport.request('GET', '/system/config'))),
+    save: async (input: SystemConfig) =>
+      configInput(object(await transport.request('PUT', '/system/config', { body: input }))),
+    restore: async () => configInput(object(await transport.request('POST', '/system/config/restore'))),
+  };
+}

package/templates/features/system/src/modules/system/config/routes.ts

@@ -0,0 +1,21 @@
+import type { AppModule } from '../../../app/module';
+
+export const menus: AppModule['menus'] = [
+  {
+    path: '/system/config',
+    name: 'SystemConfig',
+    component: 'system/config',
+    meta: { title: '系统配置', authority: ['system:config:view'], keepAlive: true, order: 7 },
+  },
+];
+export const views: AppModule['views'] = { 'system/config': () => import('./ConfigView.vue') };
+export const permissions: AppModule['permissions'] = [
+  {
+    id: 'system-config',
+    label: '系统配置',
+    children: [
+      { id: 'system:config:view', label: '查看配置', permission: 'system:config:view' },
+      { id: 'system:config:update', label: '保存配置', permission: 'system:config:update' },
+    ],
+  },
+];