@qlover/create-app 0.7.14 → 0.8.0

package/dist/templates/next-app/config/i18n/i18nKeyScheam.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { COMMON_I18N_KEY_INVALID } from '@config/Identifier';
+
+/**
+ * 用于校验 i18n 键的格式
+ *
+ * 冒号分隔命名空间和键
+ *
+ * @example
+ * ```
+ * "namespace:key1"
+ * "namespace:key_2"
+ * "namespace:key_2__3"
+ * "namespace_1:key_2__3__4"
+ * ```
+ */
+export const i18nKeySchema = z
+  .string()
+  .regex(
+    /^[a-zA-Z][a-zA-Z0-9_-]*:[a-zA-Z][a-zA-Z0-9_-]*$/,
+    COMMON_I18N_KEY_INVALID
+  );
+
+export type I18nKeySchema = z.infer<typeof i18nKeySchema>;
+
+export function splitI18nKey(source: string): {
+  namespace: string;
+  key: string;
+} {
+  const [namespace, key] = source.split(':');
+  return { namespace, key };
+}
+
+export function joinI18nKey(namespace: string, ...key: string[]): string {
+  return `${namespace}:${key.join('__')}`;
+}

package/dist/templates/next-app/config/i18n/loginI18n.ts

@@ -1,4 +1,4 @@
-import * as i18nKeys from '../Identifier/page.login';
+import * as i18nKeys from '../Identifier/pages/page.login';
 
 /**
  * Login page i18n interface
@@ -16,27 +16,27 @@ export const loginI18n = Object.freeze({
   keywords: i18nKeys.PAGE_LOGIN_KEYWORDS,
 
   // login page
-  welcome: i18nKeys.LOGIN_WELCOME,
-  subtitle: i18nKeys.LOGIN_SUBTITLE,
-  feature_ai_paths: i18nKeys.LOGIN_FEATURE_AI_PATHS,
-  feature_smart_recommendations: i18nKeys.LOGIN_FEATURE_SMART_RECOMMENDATIONS,
-  feature_progress_tracking: i18nKeys.LOGIN_FEATURE_PROGRESS_TRACKING,
+  welcome: i18nKeys.PAGE_LOGIN_WELCOME,
+  subtitle: i18nKeys.PAGE_LOGIN_SUBTITLE,
+  feature_ai_paths: i18nKeys.PAGE_LOGIN_FEATURE_AI_PATHS,
+  feature_smart_recommendations: i18nKeys.PAGE_LOGIN_FEATURE_SMART,
+  feature_progress_tracking: i18nKeys.PAGE_LOGIN_TRACKING,
 
   // login form
-  emailRequired: i18nKeys.LOGIN_EMAIL_REQUIRED,
-  email: i18nKeys.LOGIN_EMAIL,
-  emailTitle: i18nKeys.LOGIN_EMAIL_TITLE,
-  passwordRequired: i18nKeys.LOGIN_PASSWORD_REQUIRED,
-  password: i18nKeys.LOGIN_PASSWORD,
-  passwordTitle: i18nKeys.LOGIN_PASSWORD_TITLE,
-  forgotPasswordTitle: i18nKeys.LOGIN_FORGOT_PASSWORD_TITLE,
-  forgotPassword: i18nKeys.LOGIN_FORGOT_PASSWORD,
-  buttonTitle: i18nKeys.LOGIN_BUTTON_TITLE,
-  button: i18nKeys.LOGIN_BUTTON,
-  continueWith: i18nKeys.LOGIN_CONTINUE_WITH,
-  withGoogleTitle: i18nKeys.LOGIN_WITH_GOOGLE_TITLE,
-  withGoogle: i18nKeys.LOGIN_WITH_GOOGLE,
-  noAccount: i18nKeys.LOGIN_NO_ACCOUNT,
-  createAccountTitle: i18nKeys.LOGIN_CREATE_ACCOUNT_TITLE,
-  createAccount: i18nKeys.LOGIN_CREATE_ACCOUNT
+  emailRequired: i18nKeys.PAGE_LOGIN_EMAIL_REQUIRED,
+  email: i18nKeys.PAGE_LOGIN_EMAIL,
+  emailTitle: i18nKeys.PAGE_LOGIN_EMAIL2,
+  passwordRequired: i18nKeys.PAGE_LOGIN_PASSWORD_REQUIRED,
+  password: i18nKeys.PAGE_LOGIN_PASSWORD,
+  passwordTitle: i18nKeys.PAGE_LOGIN_PASSWORD2,
+  forgotPasswordTitle: i18nKeys.PAGE_LOGIN_FORGOT_PASSWORD2,
+  forgotPassword: i18nKeys.PAGE_LOGIN_FORGOT_PASSWORD,
+  buttonTitle: i18nKeys.PAGE_LOGIN_BUTTON,
+  button: i18nKeys.PAGE_LOGIN_BUTTON,
+  continueWith: i18nKeys.PAGE_LOGIN_CONTINUE_WITH,
+  withGoogleTitle: i18nKeys.PAGE_LOGIN_WITH_GOOGLE2,
+  withGoogle: i18nKeys.PAGE_LOGIN_WITH_GOOGLE,
+  noAccount: i18nKeys.PAGE_LOGIN_NO_ACCOUNT,
+  createAccountTitle: i18nKeys.PAGE_LOGIN_CREATE_ACCOUNT2,
+  createAccount: i18nKeys.PAGE_LOGIN_CREATE_ACCOUNT
 });

package/dist/templates/next-app/config/i18n/register18n.ts

@@ -1,4 +1,4 @@
-import * as i18nKeys from '../Identifier/page.register';
+import * as i18nKeys from '../Identifier/pages/page.register';
 
 /**
  * Register page i18n interface
@@ -16,29 +16,28 @@ export const register18n = Object.freeze({
   keywords: i18nKeys.PAGE_REGISTER_KEYWORDS,
 
   // register page
-  welcome: i18nKeys.REGISTER_WELCOME,
-  subtitle: i18nKeys.REGISTER_SUBTITLE,
-  feature_ai_paths: i18nKeys.REGISTER_FEATURE_AI_PATHS,
-  feature_smart_recommendations:
-    i18nKeys.REGISTER_FEATURE_SMART_RECOMMENDATIONS,
-  feature_progress_tracking: i18nKeys.REGISTER_FEATURE_PROGRESS_TRACKING,
+  welcome: i18nKeys.PAGE_REGISTER_WELCOME,
+  subtitle: i18nKeys.PAGE_REGISTER_SUBTITLE,
+  feature_ai_paths: i18nKeys.PAGE_REGISTER_AI_PATHS,
+  feature_smart_recommendations: i18nKeys.PAGE_REGISTER_RECOMMENDATIONS,
+  feature_progress_tracking: i18nKeys.PAGE_REGISTER_TRACKING,
 
   // register form
-  username: i18nKeys.REGISTER_USERNAME,
-  username_required: i18nKeys.REGISTER_USERNAME_REQUIRED,
-  email: i18nKeys.REGISTER_EMAIL,
-  email_required: i18nKeys.REGISTER_EMAIL_REQUIRED,
-  password: i18nKeys.REGISTER_PASSWORD,
-  password_required: i18nKeys.REGISTER_PASSWORD_REQUIRED,
-  confirm_password_required: i18nKeys.REGISTER_CONFIRM_PASSWORD_REQUIRED,
-  password_mismatch: i18nKeys.REGISTER_PASSWORD_MISMATCH,
-  button: i18nKeys.REGISTER_BUTTON,
-  terms_prefix: i18nKeys.REGISTER_TERMS_PREFIX,
-  terms_link: i18nKeys.REGISTER_TERMS_LINK,
-  terms_and: i18nKeys.REGISTER_TERMS_AND,
-  privacy_link: i18nKeys.REGISTER_PRIVACY_LINK,
-  have_account: i18nKeys.REGISTER_HAVE_ACCOUNT,
-  confirm_password: i18nKeys.REGISTER_CONFIRM_PASSWORD,
-  terms_required: i18nKeys.REGISTER_TERMS_REQUIRED,
-  login_link: i18nKeys.REGISTER_LOGIN_LINK
+  username: i18nKeys.PAGE_REGISTER_USERNAME,
+  username_required: i18nKeys.PAGE_REGISTER_USERNAME_REQUIRED,
+  email: i18nKeys.PAGE_REGISTER_EMAIL,
+  email_required: i18nKeys.PAGE_REGISTER_EMAIL_REQUIRED,
+  password: i18nKeys.PAGE_REGISTER_PASSWORD,
+  password_required: i18nKeys.PAGE_REGISTER_PASSWORD_REQUIRED,
+  confirm_password_required: i18nKeys.PAGE_REGISTER_CONFIRM_PASSWORD_REQUIRED,
+  password_mismatch: i18nKeys.PAGE_REGISTER_PASSWORD_MISMATCH,
+  button: i18nKeys.PAGE_REGISTER_BUTTON,
+  terms_prefix: i18nKeys.PAGE_REGISTER_TERMS_PREFIX,
+  terms_link: i18nKeys.PAGE_REGISTER_TERMS_LINK,
+  terms_and: i18nKeys.PAGE_REGISTER_TERMS_AND,
+  privacy_link: i18nKeys.PAGE_REGISTER_PRIVACY_LINK,
+  have_account: i18nKeys.PAGE_REGISTER_HAVE_ACCOUNT,
+  confirm_password: i18nKeys.PAGE_REGISTER_CONFIRM_PASSWORD,
+  terms_required: i18nKeys.PAGE_REGISTER_TERMS_REQUIRED,
+  login_link: i18nKeys.PAGE_REGISTER_LOGIN_LINK
 });

package/dist/templates/next-app/docs/en/api.md

@@ -0,0 +1,387 @@
+# API Development Guide
+
+## Table of Contents
+
+1. [API Architecture Overview](#api-architecture-overview)
+2. [Client-Side API Implementation](#client-side-api-implementation)
+3. [Server-Side API Implementation](#server-side-api-implementation)
+4. [Error Handling and Validation](#error-handling-and-validation)
+5. [Best Practices and Examples](#best-practices-and-examples)
+
+## API Architecture Overview
+
+### 1. Overall Architecture
+
+The project adopts a layered API architecture design:
+
+```
+Client Layer                Server Layer
+┌──────────────┐           ┌──────────────┐
+│  API Interface│           │  API Routes  │
+├──────────────┤           ├──────────────┤
+│ API Services │   HTTP    │  Service     │
+├──────────────┤ Requests  ├──────────────┤
+│API Requester │ ◄──────► │ Validation   │
+├──────────────┤           ├──────────────┤
+│Plugin System │           │  Data Layer  │
+└──────────────┘           └──────────────┘
+```
+
+### 2. Core Components
+
+- **Interface Definitions**: `AppApiInterface`, `AppUserApiInterface`, etc.
+- **Request Clients**: `AppApiRequester`, `AdminApiRequester`
+- **Service Implementations**: `AppUserApi`, `AdminUserApi`, etc.
+- **Plugin System**: `AppApiPlugin`, `RequestEncryptPlugin`, etc.
+
+### 3. Unified Response Format
+
+```typescript
+// Success response
+interface AppApiSuccessInterface<T = unknown> {
+  success: true;
+  data?: T;
+}
+
+// Error response
+interface AppApiErrorInterface {
+  success: false;
+  id: string;
+  message?: string;
+}
+
+// Unified response type
+type AppApiResult<T = unknown> =
+  | AppApiSuccessInterface<T>
+  | AppApiErrorInterface;
+```
+
+## Client-Side API Implementation
+
+### 1. API Requester
+
+```typescript
+@injectable()
+export class AppApiRequester extends RequestTransaction<AppApiConfig> {
+  constructor(
+    @inject(FetchAbortPlugin) protected abortPlugin: FetchAbortPlugin
+  ) {
+    super(
+      new RequestAdapterFetch({
+        baseURL: '/api',
+        responseType: 'json'
+      })
+    );
+  }
+}
+```
+
+### 2. API Service Implementation
+
+```typescript
+@injectable()
+export class AppUserApi implements AppUserApiInterface {
+  constructor(
+    @inject(AppApiRequester)
+    protected client: RequestTransaction<AppApiConfig>
+  ) {}
+
+  async login(params: UserApiLoginTransaction['data']): Promise<AppApiResult> {
+    const response = await this.client.request<UserApiLoginTransaction>({
+      url: '/user/login',
+      method: 'POST',
+      data: params,
+      encryptProps: 'password' // Automatically encrypt password field
+    });
+
+    return response.data;
+  }
+}
+```
+
+### 3. API Plugin System
+
+```typescript
+export class AppUserApiBootstrap implements BootstrapExecutorPlugin {
+  onBefore({ parameters: { ioc } }: BootstrapContext): void {
+    const appUserApi = ioc.get<AppApiRequester>(AppApiRequester);
+
+    // Register plugins
+    appUserApi.usePlugin(new FetchURLPlugin());
+    appUserApi.usePlugin(new RequestEncryptPlugin(ioc.get(StringEncryptor)));
+    appUserApi.usePlugin(
+      new RequestCommonPlugin({
+        requestDataSerializer: this.requestDataSerializer.bind(this)
+      })
+    );
+    appUserApi.usePlugin(new AppApiPlugin(ioc.get(I.Logger)));
+    appUserApi.usePlugin(ioc.get(DialogErrorPlugin));
+  }
+}
+```
+
+## Server-Side API Implementation
+
+### 1. API Route Handling
+
+```typescript
+// app/api/admin/users/route.ts
+export async function GET(req: NextRequest) {
+  const server = new BootstrapServer();
+
+  const result = await server
+    .use(new AdminAuthPlugin()) // Use authentication plugin
+    .execNoError(async ({ parameters: { IOC } }) => {
+      // 1. Parameter validation
+      const searchParams = Object.fromEntries(
+        req.nextUrl.searchParams.entries()
+      );
+      const paginationParams = IOC(PaginationValidator).getThrow(searchParams);
+
+      // 2. Call service
+      const apiUserService = IOC(ApiUserService);
+      const result = await apiUserService.getUsers({
+        page: paginationParams.page,
+        pageSize: paginationParams.pageSize
+      });
+
+      return result;
+    });
+
+  // 3. Error handling
+  if (result instanceof ExecutorError) {
+    return NextResponse.json(new AppErrorApi(result.id, result.message), {
+      status: 400
+    });
+  }
+
+  // 4. Success response
+  return NextResponse.json(new AppSuccessApi(result));
+}
+```
+
+### 2. Service Layer Implementation
+
+```typescript
+@injectable()
+export class ApiUserService {
+  constructor(
+    @inject(IOCIdentifier.UserRepository)
+    private userRepository: UserRepositoryInterface
+  ) {}
+
+  async getUsers(params: PaginationInterface): Promise<PaginationResult<User>> {
+    return this.userRepository.findUsers(params);
+  }
+}
+```
+
+### 3. Authentication and Middleware
+
+```typescript
+export class AdminAuthPlugin implements BootstrapExecutorPlugin {
+  async onBefore(context: BootstrapContext): Promise<void> {
+    const { IOC } = context.parameters;
+    const serverAuth = IOC(ServerAuth);
+
+    // Verify admin permissions
+    await serverAuth.verifyAdmin();
+  }
+}
+```
+
+## Error Handling and Validation
+
+### 1. Error Response
+
+```typescript
+export class AppErrorApi implements AppApiErrorInterface {
+  success = false as const;
+
+  constructor(
+    public id: string,
+    public message?: string
+  ) {}
+}
+
+export class AppSuccessApi<T = unknown> implements AppApiSuccessInterface<T> {
+  success = true as const;
+
+  constructor(public data?: T) {}
+}
+```
+
+### 2. Parameter Validation
+
+```typescript
+@injectable()
+export class PaginationValidator implements ValidatorInterface {
+  validate(data: unknown): ValidationResult {
+    // Implement validation logic
+    const errors: ValidationError[] = [];
+
+    if (!this.isValidPageNumber(data.page)) {
+      errors.push({ field: 'page', message: 'Invalid page number' });
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  getThrow(data: unknown): PaginationInterface {
+    const result = this.validate(data);
+    if (!result.valid) {
+      throw new ValidationError(result.errors);
+    }
+    return data as PaginationInterface;
+  }
+}
+```
+
+## Best Practices and Examples
+
+### 1. API Interface Definition
+
+```typescript
+// 1. Define interface
+interface UserApiInterface {
+  login(params: LoginParams): Promise<AppApiResult<LoginResult>>;
+  logout(): Promise<AppApiResult<void>>;
+}
+
+// 2. Implement interface
+@injectable()
+class UserApi implements UserApiInterface {
+  constructor(
+    @inject(AppApiRequester)
+    private client: AppApiRequester
+  ) {}
+
+  async login(params: LoginParams): Promise<AppApiResult<LoginResult>> {
+    // Implement login logic
+  }
+
+  async logout(): Promise<AppApiResult<void>> {
+    // Implement logout logic
+  }
+}
+```
+
+### 2. Error Handling Best Practices
+
+```typescript
+// 1. Use unified error handling
+try {
+  const result = await userApi.login(params);
+  if (!result.success) {
+    // Handle business error
+    handleBusinessError(result);
+    return;
+  }
+  // Handle success response
+  handleSuccess(result.data);
+} catch (error) {
+  // Handle network errors etc.
+  handleNetworkError(error);
+}
+
+// 2. Use error plugin
+class DialogErrorPlugin implements ExecutorPlugin {
+  onError(error: Error, context: ExecutorContext): void {
+    // Show error dialog
+    this.dialogHandler.showError({
+      title: 'Error',
+      content: error.message
+    });
+  }
+}
+```
+
+### 3. API Testing Example
+
+```typescript
+describe('UserApi', () => {
+  let userApi: UserApi;
+  let mockClient: jest.Mocked<AppApiRequester>;
+
+  beforeEach(() => {
+    mockClient = {
+      request: jest.fn()
+    } as any;
+    userApi = new UserApi(mockClient);
+  });
+
+  it('should handle login success', async () => {
+    const mockResponse = {
+      success: true,
+      data: { token: 'test-token' }
+    };
+    mockClient.request.mockResolvedValue({ data: mockResponse });
+
+    const result = await userApi.login({
+      email: 'test@example.com',
+      password: 'password'
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockClient.request).toHaveBeenCalledWith({
+      url: '/user/login',
+      method: 'POST',
+      data: {
+        email: 'test@example.com',
+        password: 'password'
+      },
+      encryptProps: 'password'
+    });
+  });
+});
+```
+
+### 4. API Documentation Generation
+
+Use TypeScript types and comments to generate API documentation:
+
+```typescript
+/**
+ * User login API
+ * @param params - Login parameters
+ * @param params.email - User email
+ * @param params.password - User password (will be automatically encrypted)
+ * @returns Login result containing user token
+ * @throws {ValidationError} When parameter validation fails
+ * @throws {AuthError} When authentication fails
+ */
+async login(params: LoginParams): Promise<AppApiResult<LoginResult>>;
+```
+
+## Summary
+
+The project's API design follows these principles:
+
+1. **Layered Architecture**:
+   - Clear interface definitions
+   - Service layer implements business logic
+   - Unified request handling
+   - Plugin-based feature extension
+
+2. **Type Safety**:
+   - Complete TypeScript type definitions
+   - Runtime parameter validation
+   - Compile-time type checking
+
+3. **Error Handling**:
+   - Unified error response format
+   - Plugin-based error handling
+   - Complete error tracking
+
+4. **Extensibility**:
+   - Plugin system supports feature extension
+   - Dependency injection achieves loose coupling
+   - Middleware supports cross-cutting concerns
+
+5. **Security**:
+   - Automatic parameter encryption
+   - Unified authentication mechanism
+   - Parameter validation and sanitization