@qlover/create-app 0.10.1 → 0.10.3

package/dist/templates/next-app/src/core/serverIoc/ServerIOCRegister.ts

@@ -5,7 +5,7 @@ import {
 } from '@qlover/corekit-bridge';
 import { Logger, ConsoleHandler, TimestampFormatter } from '@qlover/logger';
 import type { IocRegisterOptions } from '@/base/port/IOCInterface';
-import { SupabaseBridge } from '@/server/sqlBridges/SupabaseBridge';
+import { SupabaseBridge } from '@/server/SupabaseBridge';
 import { IOCIdentifier as I } from '@config/IOCIdentifier';
 
 export class ServerIOCRegister implements IOCRegisterInterface<
@@ -19,6 +19,7 @@ export class ServerIOCRegister implements IOCRegisterInterface<
    *
    * 一般用于注册全局
    *
+   * @override
    * @param ioc - IOC container
    */
   protected registerGlobals(ioc: IOCContainerInterface): void {
@@ -45,16 +46,22 @@ export class ServerIOCRegister implements IOCRegisterInterface<
     );
   }
 
+  /**
+   * @override
+   */
   protected registerImplement(ioc: IOCContainerInterface): void {
     ioc.bind(I.DBBridgeInterface, ioc.get(SupabaseBridge));
   }
 
+  /**
+   * @override
+   */
   protected registerCommon(_ioc: IOCContainerInterface): void {}
 
   /**
    * @override
    */
-  register(
+  public register(
     ioc: IOCContainerInterface,
     _manager: IOCManagerInterface<IOCContainerInterface>
   ): void {

package/dist/templates/next-app/src/i18n/loadMessages.ts

@@ -0,0 +1,103 @@
+import { useApiLocales } from '@config/common';
+
+/**
+ * 加载 i18n 消息的公共方法
+ * 支持从 API 加载或从 JSON 文件加载
+ *
+ * @param locale - 要加载的语言代码
+ * @param namespace - 可选的命名空间（单个字符串或字符串数组），如果提供则只返回该命名空间下的消息，保留命名空间前缀
+ * @returns Promise<Record<string, string>> 返回翻译消息对象
+ *
+ * @example
+ * ```ts
+ * // 加载所有消息
+ * const allMessages = await loadMessages('en');
+ *
+ * // 加载单个命名空间
+ * const commonMessages = await loadMessages('en', 'common');
+ *
+ * // 加载多个命名空间
+ * const messages = await loadMessages('en', ['common', 'page_home']);
+ * ```
+ */
+export async function loadMessages(
+  locale: string,
+  namespace?: string | string[]
+): Promise<Record<string, string>> {
+  let allMessages: Record<string, string>;
+
+  // 如果配置了使用 API 加载本地化数据
+  if (useApiLocales) {
+    try {
+      const app_host = process.env.APP_HOST;
+      const localeUrl = `${app_host}/api/locales/json?locale=${locale}`;
+      const response = await fetch(localeUrl);
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch locale from API: ${response.statusText}`
+        );
+      }
+
+      allMessages = await response.json();
+    } catch (error) {
+      console.warn(`Failed to load locale from API for ${locale}`, error);
+      // 如果 API 加载失败，继续尝试从文件加载
+      allMessages = (await import(`../../public/locales/${locale}.json`))
+        .default;
+    }
+  } else {
+    allMessages = (await import(`../../public/locales/${locale}.json`)).default;
+  }
+
+  // 如果指定了命名空间，进行过滤
+  return filterMessagesByNamespace(allMessages, namespace);
+}
+
+/**
+ * 根据命名空间过滤消息，保留命名空间前缀
+ *
+ * @param messages - 所有消息对象
+ * @param namespace - 可选的命名空间（单个字符串或字符串数组），如果提供则只返回该命名空间下的消息，保留命名空间前缀
+ * @returns 过滤后的消息对象
+ *
+ * @example
+ * ```ts
+ * const allMessages = { "common:save": "Save", "common:cancel": "Cancel", "page_home:title": "Home" };
+ *
+ * // 单个命名空间
+ * const commonMessages = filterMessagesByNamespace(allMessages, "common");
+ * // 返回: { "common:save": "Save", "common:cancel": "Cancel" }
+ *
+ * // 多个命名空间
+ * const messages = filterMessagesByNamespace(allMessages, ["common", "page_home"]);
+ * // 返回: { "common:save": "Save", "common:cancel": "Cancel", "page_home:title": "Home" }
+ * ```
+ */
+export function filterMessagesByNamespace(
+  messages: Record<string, string>,
+  namespace?: string | string[]
+): Record<string, string> {
+  // 如果没有指定命名空间，返回所有消息
+  if (!namespace) {
+    return messages;
+  }
+
+  // 将单个字符串转换为数组，统一处理
+  const namespaces = Array.isArray(namespace) ? namespace : [namespace];
+  const filteredMessages: Record<string, string> = {};
+
+  // 遍历所有命名空间
+  for (const ns of namespaces) {
+    const namespacePrefix = `${ns}:`;
+
+    for (const [key, value] of Object.entries(messages)) {
+      if (key.startsWith(namespacePrefix)) {
+        // 保留完整的键名（包括命名空间前缀）
+        filteredMessages[key] = value;
+      }
+    }
+  }
+
+  return filteredMessages;
+}

package/dist/templates/next-app/src/i18n/request.ts

@@ -1,7 +1,7 @@
 // src/i18n/request.ts
 
 import { getRequestConfig } from 'next-intl/server';
-import { useApiLocales } from '@config/common';
+import { loadMessages } from './loadMessages';
 import { routing, type Locale } from './routing';
 
 // Export a function to configure next-intl on each request (server-side)
@@ -14,30 +14,11 @@ export default getRequestConfig(async ({ requestLocale }) => {
     locale = routing.defaultLocale;
   }
 
-  // use api locales
-  if (useApiLocales) {
-    const app_host = process.env.APP_HOST;
-    const localeUrl = `${app_host}/api/locales/json?locale=${locale}`;
-    const response = await fetch(localeUrl);
-    const data = await response.json();
-    return {
-      locale,
-      messages: data,
-      // 将 MISSING_MESSAGE 错误转换为警告
-      onError: (error) => {
-        if (error.message.includes('MISSING_MESSAGE')) {
-          console.warn(`[i18n] Missing translation: ${error.message}`);
-          return error.message; // 返回 key 作为 fallback 文本
-        }
-        throw error; // 其他错误仍然抛出
-      }
-    };
-  }
+  const messages = await loadMessages(locale);
 
-  // Dynamically import the translation messages for the selected locale
   return {
     locale,
-    messages: (await import(`../../public/locales/${locale}.json`)).default,
+    messages,
     // 将 MISSING_MESSAGE 错误转换为警告
     onError: (error) => {
       if (error.message.includes('MISSING_MESSAGE')) {

package/dist/templates/next-app/src/pages/[locale]/about.tsx

@@ -0,0 +1,61 @@
+import { useMemo } from 'react';
+import { PagesRouteParams } from '@/server/PagesRouteParams';
+import type { PagesRouteParamsType } from '@/server/PagesRouteParams';
+import { ClientSeo } from '@/uikit/components/ClientSeo';
+import { PagesRoutePage } from '@/uikit/components-pages/PagesRoutePage';
+import { useI18nInterface } from '@/uikit/hook/useI18nInterface';
+import { aboutI18n, i18nConfig } from '@config/i18n';
+import { COMMON_ADMIN_TITLE } from '@config/Identifier';
+import type { GetStaticPropsContext } from 'next';
+
+interface AboutProps {
+  messages: Record<string, string>;
+}
+
+const namespace = 'page_about';
+
+export default function About({}: AboutProps) {
+  const i18nInterface = useMemo(() => {
+    return {
+      ...aboutI18n,
+      adminTitle: COMMON_ADMIN_TITLE
+    };
+  }, []);
+  const seoMetadata = useI18nInterface(i18nInterface);
+
+  return (
+    <PagesRoutePage
+      data-testid="AboutPage"
+      tt={{ title: seoMetadata.title, adminTitle: seoMetadata.adminTitle }}
+      showAdminButton={false}
+    >
+      <ClientSeo i18nInterface={seoMetadata} />
+      <div data-testid="About" className="bg-primary h-screen">
+        {seoMetadata.title}
+      </div>
+    </PagesRoutePage>
+  );
+}
+
+export async function getStaticProps({
+  params
+}: GetStaticPropsContext<PagesRouteParamsType>) {
+  const pageParams = new PagesRouteParams(params);
+
+  const messages = await pageParams.getI18nMessages(namespace);
+
+  return {
+    props: {
+      messages
+    }
+  };
+}
+
+export async function getStaticPaths() {
+  return {
+    paths: i18nConfig.supportedLngs.map((locale) => ({
+      params: { locale }
+    })),
+    fallback: false
+  };
+}

package/dist/templates/next-app/src/pages/_app.tsx

@@ -0,0 +1,50 @@
+import dynamic from 'next/dynamic';
+import { withRouter } from 'next/router';
+import { NextIntlClientProvider } from 'next-intl';
+import '@/styles/css/index.css';
+import type { PagesRouterProps } from '@/base/types/PagesRouter';
+import { BootstrapsProvider } from '@/uikit/components/BootstrapsProvider';
+import { IOCProvider } from '@/uikit/components/IOCProvider';
+import { i18nConfig } from '@config/i18n';
+import { themeConfig } from '@config/theme';
+
+/**
+ * 动态导入 ClientRootProvider，禁用 SSR，确保只在客户端渲染
+ *
+ * 为什么需要禁用 SSR？
+ * 1. ClientRootProvider 内部使用了 AntdRegistry（来自 @ant-design/nextjs-registry），
+ *    该组件主要针对 App Router 设计，在 Pages Router 的 SSR 环境中可能存在兼容性问题
+ * 2. ClientRootProvider 使用了 useIOC() hook，该 hook 在服务端渲染时可能无法正常工作
+ * 3. ThemeProvider 和 AntdThemeProvider 可能依赖浏览器 API（如 localStorage、window 等），
+ *    在服务端渲染时会导致错误或页面一直处于加载状态
+ *
+ * 通过在 Pages Router 中使用 dynamic import 并设置 ssr: false，
+ * 可以确保 ClientRootProvider 只在客户端渲染，避免 SSR 相关的问题
+ */
+const ClientRootProvider = dynamic(
+  () =>
+    import('@/uikit/components/ClientRootProvider').then(
+      (mod) => mod.ClientRootProvider
+    ),
+  {
+    ssr: false
+  }
+);
+
+function App({ Component, pageProps, router }: PagesRouterProps) {
+  const locale = (router.query.locale as string) || i18nConfig.fallbackLng;
+
+  return (
+    <IOCProvider>
+      <NextIntlClientProvider locale={locale} messages={pageProps.messages}>
+        <BootstrapsProvider>
+          <ClientRootProvider themeConfig={themeConfig}>
+            <Component {...pageProps} />
+          </ClientRootProvider>
+        </BootstrapsProvider>
+      </NextIntlClientProvider>
+    </IOCProvider>
+  );
+}
+
+export default withRouter(App);

package/dist/templates/next-app/src/pages/_document.tsx

@@ -0,0 +1,13 @@
+import { Html, Head, Main, NextScript } from 'next/document';
+
+export default function Document() {
+  return (
+    <Html data-testid="PagesRootLayout">
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}

package/dist/templates/next-app/src/{middleware.ts → proxy.ts}

@@ -20,6 +20,7 @@ export const config = {
     // - Next.js internals (_next/*)
     // - Static files (*.svg, *.png, *.jpg, *.jpeg, *.gif, *.ico)
     // - Other static assets and special files
-    '/((?!api|_next|.*\\.(?:svg|png|jpg|jpeg|gif|ico)|favicon.ico|sitemap.xml|sitemap-0.xml).*)'
+    // - Manifest file (manifest.webmanifest)
+    '/((?!api|_next|.*\\.(?:svg|png|jpg|jpeg|gif|ico)|favicon.ico|sitemap.xml|sitemap-0.xml|manifest.webmanifest).*)'
   ]
 };

package/dist/templates/next-app/src/server/AppErrorApi.ts

@@ -1,7 +1,7 @@
 import type { AppApiErrorInterface } from '@/base/port/AppApiInterface';
 
 export class AppErrorApi implements AppApiErrorInterface {
-  readonly success = false;
+  public readonly success = false;
 
   constructor(
     public readonly id: string,

package/dist/templates/next-app/src/server/AppPageRouteParams.ts

@@ -0,0 +1,107 @@
+import { cookies } from 'next/headers';
+import { notFound } from 'next/navigation';
+import { getMessages, getTranslations } from 'next-intl/server';
+import { TranslateI18nInterface } from '@/base/cases/TranslateI18nInterface';
+import { filterMessagesByNamespace } from '@/i18n/loadMessages';
+import { i18nConfig } from '@config/i18n';
+import type { LocaleType, PageI18nInterface } from '@config/i18n';
+import { themeConfig } from '@config/theme';
+import type { RouteParamsnHandlerInterface } from './port/RouteParamsnHandlerInterface';
+
+export interface PageWithParams {
+  params?: Promise<PageParamsType>;
+}
+
+export interface PageParamsType {
+  locale?: string;
+}
+
+/**
+ * 用于 src/app/page 路由的参数管理工具
+ */
+export class AppPageRouteParams<
+  T extends PageParamsType
+> implements RouteParamsnHandlerInterface {
+  private locale: string | null;
+
+  constructor(protected readonly params: T) {
+    this.locale = this.params.locale || i18nConfig.fallbackLng;
+  }
+
+  /**
+   * @override
+   */
+  public getLocale(defaultLocale?: string): string {
+    if (this.locale) {
+      return this.locale;
+    }
+
+    this.locale = this.params.locale || defaultLocale || i18nConfig.fallbackLng;
+
+    return this.locale;
+  }
+
+  /**
+   * @override
+   */
+  public getI18nWithNotFound(): string {
+    const locale = this.getLocale();
+
+    if (!i18nConfig.supportedLngs.includes(locale as LocaleType)) {
+      notFound();
+    }
+
+    return locale;
+  }
+
+  /**
+   * 获取 i18n 消息
+   * 使用 next-intl 的 getMessages 加载消息
+   *
+   * @override
+   * @param namespace - 可选的命名空间（单个字符串或字符串数组），会与默认命名空间 ['common', 'api'] 合并
+   * @returns Promise<Record<string, string>> 返回翻译消息对象
+   */
+  public async getI18nMessages(
+    namespace?: string | string[]
+  ): Promise<Record<string, string>> {
+    const locale = this.getLocale();
+    const messages = await getMessages({ locale });
+    // 将默认命名空间和用户提供的命名空间合并
+    const defaultNamespaces = [...i18nConfig.defaultNamespaces];
+    const userNamespaces = namespace
+      ? Array.isArray(namespace)
+        ? namespace
+        : [namespace]
+      : [];
+    // 合并并去重
+    const namespaces = [...new Set([...defaultNamespaces, ...userNamespaces])];
+    return filterMessagesByNamespace(messages, namespaces);
+  }
+
+  /**
+   * @override
+   */
+  public async getI18nInterface<T extends PageI18nInterface>(
+    i18nInterface: T,
+    _namespace?: string
+  ): Promise<T> {
+    const t = await getTranslations({
+      locale: this.getLocale()
+      // namespace: namespace
+    });
+
+    return TranslateI18nInterface.translate<T>(i18nInterface, t);
+  }
+
+  /**
+   * @override
+   */
+  public async getTheme(): Promise<string> {
+    const cookieStore = await cookies();
+    return (
+      cookieStore.get(themeConfig.storageKey)?.value ||
+      themeConfig.supportedThemes[0]
+    );
+  }
+}

package/dist/templates/next-app/src/server/AppSuccessApi.ts

@@ -1,7 +1,7 @@
 import type { AppApiSuccessInterface } from '@/base/port/AppApiInterface';
 
 export class AppSuccessApi<T = unknown> implements AppApiSuccessInterface<T> {
-  readonly success = true;
+  public readonly success = true;
 
   constructor(public readonly data?: T) {}
 }

package/dist/templates/next-app/src/server/NextApiServer.ts

@@ -0,0 +1,62 @@
+import { ExecutorError } from '@qlover/fe-corekit';
+import { NextResponse } from 'next/server';
+import {
+  isAppApiErrorInterface,
+  isAppApiSuccessInterface,
+  type AppApiResult
+} from '@/base/port/AppApiInterface';
+import type { BootstrapServerContextValue } from '@/core/bootstraps/BootstrapServer';
+import { BootstrapServer } from '@/core/bootstraps/BootstrapServer';
+import { AppErrorApi } from './AppErrorApi';
+import { AppSuccessApi } from './AppSuccessApi';
+import type { PromiseTask } from '@qlover/fe-corekit';
+
+export class NextApiServer extends BootstrapServer {
+  /**
+   * @override
+   */
+  protected isAppApiResult(result: unknown): result is AppApiResult {
+    return isAppApiSuccessInterface(result) || isAppApiErrorInterface(result);
+  }
+
+  /**
+   * @override
+   */
+  public async run<Result>(
+    task?: PromiseTask<Result | AppApiResult, BootstrapServerContextValue>
+  ): Promise<AppApiResult> {
+    const result = await this.execNoError(task);
+
+    // Is result is AppApiResult, return it directly
+    if (this.isAppApiResult(result)) {
+      return result;
+    }
+
+    // If result is ExecutorError, return AppErrorApi
+    if (result instanceof ExecutorError) {
+      return new AppErrorApi(result.id, result.message);
+    }
+
+    // If result is Error, return AppErrorApi
+    if (result instanceof Error) {
+      return new AppErrorApi('SERVER_ERROR', result.message);
+    }
+
+    return new AppSuccessApi(result);
+  }
+
+  /**
+   * @override
+   */
+  public async runWithJson<Result>(
+    task?: PromiseTask<Result | AppApiResult, BootstrapServerContextValue>
+  ): Promise<NextResponse> {
+    const result = await this.run(task);
+
+    if (!result.success) {
+      return NextResponse.json(result, { status: 400 });
+    }
+
+    return NextResponse.json(result);
+  }
+}

package/dist/templates/next-app/src/server/PagesRouteParams.ts

@@ -0,0 +1,146 @@
+import { TranslateI18nInterface } from '@/base/cases/TranslateI18nInterface';
+import { loadMessages } from '@/i18n/loadMessages';
+import { i18nConfig } from '@config/i18n';
+import type { LocaleType, PageI18nInterface } from '@config/i18n';
+import { themeConfig } from '@config/theme';
+import type { RouteParamsnHandlerInterface } from './port/RouteParamsnHandlerInterface';
+import type { useTranslations } from 'next-intl';
+import type { ParsedUrlQuery } from 'querystring';
+
+export interface PagesRouteParamsType extends ParsedUrlQuery {
+  locale?: string | string[];
+}
+
+/**
+ * 用于 src/pages/** 路由的参数管理工具
+ *
+ * ⚠️ 注意：此类仅在服务器端使用（getStaticProps、getServerSideProps 中）
+ * 此类直接从 JSON 文件加载翻译消息，不依赖 next-intl/server，因此可以在 pages 目录中安全使用
+ *
+ * @example
+ * ```ts
+ * export async function getStaticProps({ params }: GetStaticPropsContext<PagesRouteParamsType>) {
+ *   const pageParams = new PagesRouteParams(params);
+ *   const messages = await pageParams.getI18nMessages();
+ *   return { props: { messages } };
+ * }
+ * ```
+ */
+export class PagesRouteParams implements RouteParamsnHandlerInterface {
+  private locale: string | null;
+
+  constructor(protected readonly params: PagesRouteParamsType = {}) {
+    const localeParam = Array.isArray(this.params.locale)
+      ? this.params.locale[0]
+      : this.params.locale;
+    this.locale = localeParam || i18nConfig.fallbackLng;
+  }
+
+  /**
+   * @override
+   */
+  public getLocale(defaultLocale?: string): string {
+    if (this.locale) {
+      return this.locale;
+    }
+
+    const localeParam = Array.isArray(this.params.locale)
+      ? this.params.locale[0]
+      : this.params.locale;
+    this.locale = localeParam || defaultLocale || i18nConfig.fallbackLng;
+
+    return this.locale;
+  }
+
+  /**
+   * 获取 locale，如果 locale 不支持则抛出错误
+   * 注意：在 pages 目录中，应该在 getStaticProps/getServerSideProps 中返回 { notFound: true } 来处理不支持的 locale
+   *
+   * @override
+   * @returns 支持的 locale 字符串
+   * @throws 如果 locale 不支持
+   */
+  public getI18nWithNotFound(): string {
+    const locale = this.getLocale();
+
+    if (!i18nConfig.supportedLngs.includes(locale as LocaleType)) {
+      // 在 pages 目录中，应该返回 { notFound: true } 而不是调用 notFound()
+      // 这里抛出错误，由调用方在 getStaticProps/getServerSideProps 中处理
+      throw new Error(`Unsupported locale: ${locale}`);
+    }
+
+    return locale;
+  }
+
+  /**
+   * 获取 i18n 消息
+   * 使用公共方法加载消息，支持从 API 加载或动态导入 JSON 文件
+   * 不依赖 next-intl/server，适用于 getStaticProps/getServerSideProps
+   *
+   * @override
+   * @param namespace - 可选的命名空间（单个字符串或字符串数组），会与默认命名空间 ['common', 'api'] 合并
+   * @returns Promise<Record<string, string>> 返回翻译消息对象
+   */
+  public async getI18nMessages(
+    namespace?: string | string[]
+  ): Promise<Record<string, string>> {
+    const locale = this.getLocale();
+    // 将默认命名空间和用户提供的命名空间合并
+    const defaultNamespaces = [...i18nConfig.defaultNamespaces];
+    const userNamespaces = namespace
+      ? Array.isArray(namespace)
+        ? namespace
+        : [namespace]
+      : [];
+    // 合并并去重
+    const namespaces = [...new Set([...defaultNamespaces, ...userNamespaces])];
+    return loadMessages(locale, namespaces);
+  }
+
+  /**
+   * 获取翻译后的 i18n 接口
+   * 创建一个简单的翻译函数，基于加载的 messages
+
+   * @override
+      */
+  public async getI18nInterface<T extends PageI18nInterface>(
+    i18nInterface: T,
+    namespace?: string
+  ): Promise<T> {
+    const messages = await this.getI18nMessages(namespace);
+
+    // 创建一个简单的翻译函数
+    const t = (
+      key: string,
+      params?: Record<string, string | number | Date>
+    ) => {
+      const fullKey = namespace ? `${namespace}:${key}` : key;
+
+      let message = messages[fullKey] || messages[key] || key;
+
+      // 简单的参数替换
+      if (params) {
+        Object.entries(params).forEach(([paramKey, paramValue]) => {
+          message = message.replace(
+            new RegExp(`\\{${paramKey}\\}`, 'g'),
+            String(paramValue)
+          );
+        });
+      }
+
+      return message;
+    };
+
+    return TranslateI18nInterface.translate<T>(
+      i18nInterface,
+      t as ReturnType<typeof useTranslations>
+    );
+  }
+
+  /**
+   * @override
+   */
+  public getTheme(): string {
+    return themeConfig.defaultTheme;
+  }
+}

package/dist/templates/next-app/src/server/PasswordEncrypt.ts

@@ -2,11 +2,17 @@ import crypto from 'crypto';
 import type { Encryptor } from '@qlover/fe-corekit';
 
 export class PasswordEncrypt implements Encryptor<string, string> {
-  encrypt(password: string): string {
+  /**
+   * @override
+   */
+  public encrypt(password: string): string {
     return crypto.createHash('md5').update(password).digest('hex');
   }
 
-  decrypt(): string {
+  /**
+   * @override
+   */
+  public decrypt(): string {
     throw new Error('Md5Encrypt is not decryptable');
   }
 }