create-lumal-admin 0.0.4-beta → 0.0.6-beta

package/templates/base/src/shared/components/BaseEntityDialog.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import type { SchemaFormItem, SchemaFormModel } from '@lumal/core/components';
+import { LumalSchemaForm } from '@lumal/core/components';
+import { ElAlert, ElDialog } from 'element-plus';
+
+/***********************编辑弹窗契约*********************/
+defineProps<{ title: string; schemas: SchemaFormItem[]; editing?: boolean; saving?: boolean; error?: string }>();
+defineEmits<{ submit: [model: SchemaFormModel] }>();
+const visible = defineModel<boolean>('visible', { required: true });
+const model = defineModel<SchemaFormModel>('model', { required: true });
+</script>
+
+<template>
+  <ElDialog
+    v-model="visible"
+    :title="title"
+    width="min(760px, 94vw)"
+    append-to-body
+    destroy-on-close
+    :close-on-click-modal="!saving"
+    :close-on-press-escape="!saving"
+  >
+    <ElAlert v-if="error" :title="error" type="error" :closable="false" role="alert" />
+    <LumalSchemaForm
+      v-model="model"
+      :mode="editing ? 'edit' : 'create'"
+      :schemas="schemas"
+      :columns="2"
+      :submit-loading="saving"
+      show-actions
+      submit-text="保存"
+      @submit="$emit('submit', $event)"
+    >
+      <template v-for="(_, name) in $slots" #[name]="scope">
+        <slot :name="name" v-bind="scope || {}" />
+      </template>
+    </LumalSchemaForm>
+  </ElDialog>
+</template>

package/templates/base/src/shared/composables/use-async-data.ts

@@ -0,0 +1,35 @@
+import { onActivated, onDeactivated, onMounted, onScopeDispose, shallowRef } from 'vue';
+
+export function useAsyncData<T>(fetcher: () => Promise<T>, initial: T) {
+  const data = shallowRef(initial);
+  const loading = shallowRef(false);
+  const error = shallowRef('');
+  let generation = 0;
+  let reactivating = false;
+  async function load(): Promise<void> {
+    const version = ++generation;
+    loading.value = true;
+    error.value = '';
+    try {
+      const next = await fetcher();
+      if (version === generation) data.value = next;
+    } catch (reason) {
+      if (version === generation) error.value = reason instanceof Error ? reason.message : '加载失败';
+      throw reason;
+    } finally {
+      if (version === generation) loading.value = false;
+    }
+  }
+  const reload = () => load().catch(() => {}); // 错误已保留供页面显示和重试。
+  onMounted(reload);
+  onDeactivated(() => {
+    reactivating = true;
+  });
+  onActivated(() => {
+    if (reactivating) void reload();
+  });
+  onScopeDispose(() => {
+    generation += 1;
+  });
+  return { data, loading, error, load, reload };
+}

package/templates/base/src/shared/composables/use-entity-editor.ts

@@ -0,0 +1,77 @@
+import type { SchemaFormModel } from '@lumal/core/components';
+import { ElMessage, ElMessageBox } from 'element-plus';
+import { shallowRef } from 'vue';
+
+interface EditorOptions<T extends { id: string }, Input> {
+  create: (input: Input) => Promise<unknown>;
+  update: (id: string, input: Input) => Promise<unknown>;
+  remove: (id: string) => Promise<unknown>;
+  toInput: (model: SchemaFormModel) => Input;
+  reload: () => Promise<void>;
+  removeMessage?: (record: T) => string;
+}
+export function useEntityEditor<T extends { id: string }, Input>(options: EditorOptions<T, Input>) {
+  const visible = shallowRef(false);
+  const model = shallowRef<SchemaFormModel>({});
+  const editing = shallowRef<T>();
+  const saving = shallowRef(false);
+  const error = shallowRef('');
+  function openCreate(initial: SchemaFormModel = {}): void {
+    editing.value = undefined;
+    model.value = structuredClone(initial);
+    error.value = '';
+    visible.value = true;
+  }
+  function openEdit(record: T): void {
+    editing.value = record;
+    model.value = structuredClone(record) as SchemaFormModel;
+    error.value = '';
+    visible.value = true;
+  }
+  async function submit(values: SchemaFormModel): Promise<void> {
+    if (saving.value) return;
+    saving.value = true;
+    error.value = '';
+    let persisted = false;
+    try {
+      const input = options.toInput(values);
+      if (editing.value) await options.update(editing.value.id, input);
+      else await options.create(input);
+      persisted = true;
+      visible.value = false;
+      await options.reload();
+      ElMessage.success('保存成功');
+    } catch (reason) {
+      const message = reason instanceof Error ? reason.message : '操作失败';
+      error.value = persisted ? `保存已完成，但刷新失败：${message}。请重新加载，不要重复提交。` : message;
+    } finally {
+      saving.value = false;
+    }
+  }
+  async function remove(record: T): Promise<void> {
+    if (saving.value) return;
+    try {
+      await ElMessageBox.confirm(options.removeMessage?.(record) ?? '确定删除该记录？', '删除确认', {
+        confirmButtonText: '删除',
+        cancelButtonText: '取消',
+        type: 'warning',
+      });
+    } catch {
+      return;
+    }
+    saving.value = true;
+    error.value = '';
+    let persisted = false;
+    try {
+      await options.remove(record.id);
+      persisted = true;
+      await options.reload();
+      ElMessage.success('删除成功');
+    } catch (reason) {
+      error.value = `${persisted ? '删除已完成，但刷新失败：' : ''}${reason instanceof Error ? reason.message : '删除失败'}`;
+    } finally {
+      saving.value = false;
+    }
+  }
+  return { visible, model, editing, saving, error, openCreate, openEdit, submit, remove };
+}

package/templates/base/src/shared/status.ts

@@ -0,0 +1,4 @@
+export const statusOptions = [
+  { label: '启用', value: 'enabled' },
+  { label: '停用', value: 'disabled' },
+];

package/templates/base/src/shared/tree.ts

@@ -0,0 +1,41 @@
+export interface TreeItem {
+  id: string;
+  parentId: string;
+}
+
+export function assertHierarchy<T extends TreeItem>(items: T[]): void {
+  const byId = new Map(items.map((item) => [item.id, item]));
+  if (byId.size !== items.length) throw new Error('树节点 ID 重复');
+  for (const item of items) {
+    const visited = new Set([item.id]);
+    let parent = item.parentId;
+    while (parent) {
+      if (visited.has(parent)) throw new Error('父子关系形成循环');
+      const found = byId.get(parent);
+      if (!found) throw new Error('父节点不存在');
+      visited.add(parent);
+      parent = found.parentId;
+    }
+  }
+}
+export function buildTree<T extends TreeItem>(
+  items: T[],
+  parentId = '',
+): (T & { children: (T & { children?: T[] })[] })[] {
+  return items
+    .filter((item) => item.parentId === parentId)
+    .map((item) => ({ ...item, children: buildTree(items, item.id) }));
+}
+export function flattenTree<T extends { children?: T[] }>(items: T[]): T[] {
+  return items.flatMap((item) => [item, ...flattenTree(item.children ?? [])]);
+}
+export function excludedDescendants<T extends TreeItem>(items: T[], id?: string): Set<string> {
+  const excluded = new Set<string>();
+  function visit(current?: string): void {
+    if (!current || excluded.has(current)) return;
+    excluded.add(current);
+    items.filter((item) => item.parentId === current).forEach((item) => visit(item.id));
+  }
+  visit(id);
+  return excluded;
+}

package/templates/base/src/styles.scss

@@ -0,0 +1,173 @@
+:root {
+  color: var(--el-text-color-primary);
+  background: var(--el-bg-color-page);
+  font-family: Inter, 'Segoe UI', 'Microsoft YaHei', Arial, sans-serif;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  overflow-x: hidden;
+}
+
+.lumal-admin-home {
+  display: grid;
+  gap: var(--lumal-page-gutter, 20px);
+  box-sizing: border-box;
+  padding: var(--lumal-page-gutter, 20px);
+}
+
+.lumal-admin-home__metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.lumal-admin-home__metric {
+  display: grid;
+  min-width: 0;
+  gap: 8px;
+  padding: 18px;
+  border: 1px solid var(--el-border-color-lighter);
+  border-radius: var(--lumal-radius-base, 8px);
+  background: var(--el-bg-color);
+}
+
+.lumal-admin-home__metric strong {
+  color: var(--el-color-primary);
+  font-size: 28px;
+}
+
+.lumal-admin-home__metric small {
+  color: var(--el-text-color-secondary);
+}
+
+.lumal-admin-page {
+  box-sizing: border-box;
+  padding: var(--lumal-page-gutter, 20px);
+}
+
+.lumal-admin-page__list {
+  display: grid;
+  gap: 10px;
+  margin: 0;
+  padding-left: 18px;
+}
+
+.lumal-admin-page__item {
+  color: var(--el-text-color-regular);
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.lumal-admin-header-actions {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 4px;
+}
+
+.lumal-admin-header-actions .el-button {
+  min-width: 44px;
+  min-height: 44px;
+  margin: 0;
+}
+
+.lumal-admin-header-actions__user {
+  max-width: 120px;
+  overflow: hidden;
+  color: var(--el-text-color-regular);
+  font-size: 13px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.lumal-admin-login {
+  display: grid;
+  min-height: 100dvh;
+  place-items: center;
+  padding: 24px;
+  background: var(--el-bg-color-page);
+}
+
+.lumal-admin-login__panel {
+  box-sizing: border-box;
+  width: min(400px, 100%);
+  padding: 32px;
+  border: 1px solid var(--el-border-color-lighter);
+  border-radius: var(--lumal-radius-large, 12px);
+  background: var(--el-bg-color);
+  box-shadow: var(--lumal-shadow-dialog);
+}
+
+.lumal-admin-login__brand {
+  display: grid;
+  width: 48px;
+  height: 48px;
+  place-items: center;
+  border-radius: var(--lumal-radius-base, 8px);
+  color: var(--el-color-white);
+  background: var(--el-color-primary);
+  font-size: 24px;
+  font-weight: 800;
+}
+
+.lumal-admin-login h1 {
+  margin: 20px 0 6px;
+}
+
+.lumal-admin-login p,
+.lumal-admin-login small {
+  color: var(--el-text-color-secondary);
+}
+
+.lumal-admin-login .el-form {
+  margin: 24px 0 16px;
+}
+
+.lumal-admin-login .el-button {
+  width: 100%;
+  min-height: 44px;
+}
+
+.lumal-admin-login__error {
+  color: var(--el-color-danger) !important;
+  font-size: 13px;
+}
+
+@media (max-width: 900px) {
+  .lumal-admin-home__metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 640px) {
+  .lumal-admin-home,
+  .lumal-admin-page {
+    padding: 12px;
+  }
+
+  .lumal-admin-home__metrics {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .lumal-admin-header-actions__user {
+    display: none;
+  }
+
+  .lumal-admin-login {
+    padding: 16px;
+  }
+
+  .lumal-admin-login__panel {
+    padding: 24px 20px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+  }
+}

package/templates/base/tests/menu-policy.test.ts.template

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isInternalLocation,
+  resolveView,
+  safeExternalUrl,
+  validateMenus,
+  withAccessibleRedirects,
+} from '../src/app/menu-policy';
+import { assembleModules, collectPermissions } from '../src/app/module';
+
+const views = { page: async () => ({}), 'app/iframe': async () => ({}) };
+const page = (path = '/page') => ({ path, name: path, component: 'page', meta: {} });
+describe('远程菜单信任边界', () => {
+  it.each(['constructor', '__proto__', 'prototype', 'missing', 'https://evil.invalid/a.js'])(
+    '拒绝非白名单组件 %s',
+    (component) => {
+      expect(() => validateMenus([{ ...page(), component }], views)).toThrow('白名单');
+      expect(() =>
+        validateMenus([{ path: '/group', name: 'group', children: [{ ...page('/group/page'), component }] }], views),
+      ).toThrow('白名单');
+    },
+  );
+  it('仅接受自有函数加载器', () => {
+    const inherited = Object.create({ page: async () => ({}) });
+    expect(resolveView(inherited, 'page')).toBeUndefined();
+    expect(resolveView({ page: false } as unknown as typeof views, 'page')).toBeUndefined();
+    expect(resolveView(views, 'page')).toBe(views.page);
+  });
+  it.each([
+    'javascript:alert(1)',
+    'data:text/html,bad',
+    'vbscript:x',
+    '//evil.invalid',
+    'ftp://evil.invalid',
+    'https://user:pass@evil.invalid',
+    'https://evil.invalid\\test',
+    ' https://evil.invalid',
+    'https://evil.invalid/\nfoo',
+  ])('拒绝危险外链 %s', (url) => {
+    expect(() => safeExternalUrl(url)).toThrow();
+    expect(() => validateMenus([{ ...page(), meta: { externalLink: url } }], views)).toThrow();
+  });
+  it('站内地址、iframe 来源和重定向有独立约束', () => {
+    expect(safeExternalUrl('https://example.com/path')).toBe('https://example.com/path');
+    expect(isInternalLocation('/page?q=1')).toBe(true);
+    for (const path of ['//host', '/a/../b', '/%2fhost', '/a\\b', 'https://example.com'])
+      expect(isInternalLocation(path)).toBe(false);
+    expect(() => validateMenus([{ ...page(), redirect: '//evil.invalid' }], views)).toThrow();
+    expect(() => validateMenus([{ ...page(), meta: { iframeSrc: 'https://evil.invalid' } }], views)).toThrow('iframe');
+  });
+  it('拒绝异常权限、重复路由和循环结构，远程 ignoreAccess 不能取消权限', () => {
+    expect(() => validateMenus([{ ...page(), meta: { authority: [7] } }], views)).toThrow();
+    expect(() => validateMenus([page(), page()], views)).toThrow('重复');
+    const node = { path: '/loop', name: 'Loop', children: [] as unknown[] };
+    node.children.push(node);
+    expect(() => validateMenus([node], views)).toThrow('循环');
+    const result = validateMenus(
+      [{ ...page(), meta: { authority: ['read'], ignoreAccess: true, requireLogin: false } }],
+      views,
+    );
+    expect(result[0]?.meta?.authority).toEqual(['read']);
+    expect(result[0]?.meta).not.toHaveProperty('requireLogin');
+  });
+});
+describe('模块权限与目录重定向', () => {
+  it('递归提取真实操作，不机械生成权限', () => {
+    const permissions = [{ id: 'group', label: '分组', children: [{ id: 'read', label: '读取', permission: 'read' }] }];
+    expect(collectPermissions(permissions)).toEqual(['read']);
+    expect(assembleModules([{ menus: [], views, permissions }]).permissionCodes).toEqual(['read']);
+  });
+  it('父目录跳到首个有权限的子页，无可访问子页时隐藏', () => {
+    const menus = [
+      {
+        path: '/group',
+        name: 'Group',
+        children: [
+          { ...page('/group/a'), meta: { authority: ['a'] } },
+          { ...page('/group/b'), meta: { authority: ['b'] } },
+        ],
+      },
+    ];
+    expect(withAccessibleRedirects(menus, { roles: [], permissions: ['b'] })[0]?.redirect).toBe('/group/b');
+    expect(withAccessibleRedirects(menus, { roles: [], permissions: [] })[0]?.meta?.hideInMenu).toBe(true);
+    expect(
+      withAccessibleRedirects([{ ...menus[0]!, meta: { authority: ['parent'] } }], { roles: [], permissions: ['b'] })[0]
+        ?.redirect,
+    ).toBe('/403');
+  });
+});

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { createApplicationSession } from '../src/app/services/session-runtime';
+
+describe('应用会话', () => {
+  it('统一清理认证、权限、菜单与标签', () => {
+    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);
+      },
+      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: () => {},
+        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

@@ -0,0 +1,54 @@
+import { fileURLToPath, URL } from 'node:url';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+/***********************应用开发配置*********************/
+export default defineConfig({
+  plugins: [vue()],
+  // manifest 用于核对路由懒加载和初始资源体积。
+  build: {
+    manifest: true,
+    chunkSizeWarningLimit: 500,
+    rolldownOptions: {
+      output: {
+        codeSplitting: {
+          groups: [
+            {
+              entriesAware: true,
+              maxSize: 420 * 1024,
+              name: 'vendor-element-plus',
+              priority: 40,
+              test: /node_modules[\\/]element-plus[\\/]/,
+            },
+            {
+              entriesAware: true,
+              maxSize: 420 * 1024,
+              name: 'vendor-vue',
+              priority: 30,
+              test: /node_modules[\\/](?:@vue|vue|vue-router)[\\/]/,
+            },
+            {
+              entriesAware: true,
+              maxSize: 420 * 1024,
+              name: 'vendor-lumal',
+              priority: 20,
+              test: /node_modules[\\/]@lumal[\\/]/,
+            },
+            {
+              entriesAware: true,
+              maxSize: 420 * 1024,
+              name: 'vendor',
+              priority: 10,
+              test: /node_modules[\\/]/,
+            },
+          ],
+        },
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': 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/common/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+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 -->