@qlover/create-app 1.1.0 → 2.0.0

package/dist/templates/next-app/docs/zh/page.md

@@ -1,457 +0,0 @@
-# Next.js 页面开发指南
-
-## 目录
-
-1. [页面开发概述](#页面开发概述)
-2. [服务端组件详解](#服务端组件详解)
-3. [客户端组件详解](#客户端组件详解)
-4. [数据获取和状态管理](#数据获取和状态管理)
-5. [页面路由和元数据](#页面路由和元数据)
-6. [最佳实践和性能优化](#最佳实践和性能优化)
-
-## 页面开发概述
-
-### 1. 服务端组件 vs 客户端组件
-
-在 Next.js 13+ 中，所有组件默认都是服务端组件（Server Components），除非显式声明为客户端组件。
-
-```typescript
-// 服务端组件（默认）
-// page.tsx
-export default function Page() {
-  return <div>服务端渲染的内容</div>;
-}
-
-// 客户端组件
-// 需要在文件顶部添加 'use client' 指令
-'use client';
-
-export function ClientComponent() {
-  return <div>客户端渲染的内容</div>;
-}
-```
-
-### 2. 选择指南
-
-**使用服务端组件的场景**：
-
-- 需要直接访问后端资源
-- 包含敏感信息（API 密钥、tokens 等）
-- 依赖后端的重量级操作
-- 需要减少客户端 JavaScript 体积
-- 需要 SEO 优化
-- 页面级组件
-- 不需要客户端交互
-- 不需要浏览器 API
-
-**使用客户端组件的场景**：
-
-- 需要添加交互和事件处理
-- 使用浏览器 API
-- 使用 React hooks
-- 需要维护组件状态
-- 需要使用客户端特有的生命周期
-- 使用依赖浏览器 API 的第三方库
-
-## 服务端组件详解
-
-### 1. 基本结构
-
-```typescript
-// app/[locale]/login/page.tsx
-export default async function LoginPage(props: PageParamsProps) {
-  // 1. 参数验证
-  if (!props.params) {
-    return notFound();
-  }
-
-  // 2. 服务端初始化
-  const params = await props.params;
-  const pageParams = new PageParams(params);
-  const server = new BootstrapServer();
-
-  // 3. 服务端数据获取和验证
-  if (await server.getIOC(ServerAuth).hasAuth()) {
-    return redirect({ href: '/', locale: params.locale! });
-  }
-
-  // 4. 获取国际化文本
-  const tt = await pageParams.getI18nInterface(loginI18n);
-
-  // 5. 渲染页面
-  return (
-    <BaseLayout>
-      <div>{/* 页面内容 */}</div>
-      <ClientComponent /> {/* 嵌入客户端组件 */}
-    </BaseLayout>
-  );
-}
-```
-
-### 2. 服务端数据获取
-
-```typescript
-// 直接在服务端组件中获取数据
-export default async function UsersPage() {
-  const server = new BootstrapServer();
-
-  const result = await server
-    .use(new AdminAuthPlugin())  // 使用服务端中间件
-    .execNoError(async ({ parameters: { IOC } }) => {
-      const userService = IOC(UserService);
-      return userService.getUsers();
-    });
-
-  // 数据直接传递给客户端组件
-  return <UserList initialData={result.data} />;
-}
-```
-
-### 3. 静态生成和动态渲染
-
-```typescript
-// 静态页面生成
-export const dynamic = 'force-static'; // 强制静态生成
-export const revalidate = 3600; // 每小时重新生成
-
-// 动态页面生成
-export const dynamic = 'force-dynamic'; // 强制动态生成
-
-// 生成静态路由参数
-export async function generateStaticParams() {
-  return [{ locale: 'en' }, { locale: 'zh' }];
-}
-```
-
-## 客户端组件详解
-
-### 1. 基本结构
-
-```typescript
-'use client';  // 声明为客户端组件
-
-export function LoginForm(props: { tt: LoginI18nInterface }) {
-  // 1. Hooks 使用
-  const [loading, setLoading] = useState(false);
-  const userService = useIOC(I.UserServiceInterface);
-
-  // 2. 事件处理
-  const handleLogin = async (values: LoginFormData) => {
-    try {
-      setLoading(true);
-      await userService.login(values);
-      routerService.gotoHome();
-    } catch (error) {
-      logger.error(error);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  // 3. 渲染 UI
-  return (
-    <Form onFinish={handleLogin}>
-      {/* 表单内容 */}
-    </Form>
-  );
-}
-```
-
-### 2. 客户端状态管理
-
-```typescript
-'use client';
-
-export function UserProfile() {
-  // 1. 本地状态
-  const [isEditing, setIsEditing] = useState(false);
-
-  // 2. 服务状态
-  const userStore = useIOC(UserStore);
-  const user = useStore(userStore, userStore.selector.currentUser);
-
-  // 3. 表单状态
-  const [form] = Form.useForm();
-
-  // 4. 副作用
-  useEffect(() => {
-    if (user) {
-      form.setFieldsValue(user);
-    }
-  }, [user, form]);
-
-  return (
-    <div>{/* 组件内容 */}</div>
-  );
-}
-```
-
-### 3. 与服务端组件交互
-
-```typescript
-// 1. 通过属性接收服务端数据
-interface Props {
-  initialData: UserData;    // 从服务端获取的初始数据
-  tt: I18nInterface;        // 从服务端获取的翻译文本
-}
-
-'use client';
-export function UserList({ initialData, tt }: Props) {
-  const [data, setData] = useState(initialData);
-
-  // 使用服务端数据初始化客户端状态
-  useEffect(() => {
-    setData(initialData);
-  }, [initialData]);
-
-  return (
-    <div>{/* 组件内容 */}</div>
-  );
-}
-```
-
-## 数据获取和状态管理
-
-### 1. 服务端数据获取
-
-```typescript
-// 1. 在服务端组件中获取数据
-export default async function DashboardPage() {
-  const server = new BootstrapServer();
-
-  // 并行数据获取
-  const [userData, statsData] = await Promise.all([
-    server.execNoError(async ({ IOC }) => IOC(UserService).getCurrentUser()),
-    server.execNoError(async ({ IOC }) => IOC(StatsService).getStats())
-  ]);
-
-  return (
-    <Dashboard
-      userData={userData}
-      statsData={statsData}
-    />
-  );
-}
-
-// 2. 使用服务端 action
-export async function fetchUserData(userId: string) {
-  'use server';  // 声明为服务端 action
-
-  const server = new BootstrapServer();
-  return server.execNoError(async ({ IOC }) => {
-    return IOC(UserService).getUserById(userId);
-  });
-}
-```
-
-### 2. 客户端状态管理
-
-```typescript
-'use client';
-
-// 1. 使用 Store 管理状态
-@injectable()
-export class UserProfileStore extends StoreInterface<UserProfileState> {
-  constructor() {
-    super(() => ({
-      user: null,
-      loading: false,
-      error: null
-    }));
-  }
-
-  async fetchUser(id: string) {
-    this.emit({ ...this.state, loading: true });
-    try {
-      const user = await this.userService.getUser(id);
-      this.emit({ ...this.state, user, loading: false });
-    } catch (error) {
-      this.emit({ ...this.state, error, loading: false });
-    }
-  }
-}
-
-// 2. 在组件中使用 Store
-export function UserProfile() {
-  const store = useIOC(UserProfileStore);
-  const user = useStore(store, store.selector.user);
-  const loading = useStore(store, store.selector.loading);
-
-  return (
-    <div>
-      {loading ? <Loading /> : <UserInfo user={user} />}
-    </div>
-  );
-}
-```
-
-## 页面路由和元数据
-
-### 1. 动态路由
-
-```typescript
-// app/[locale]/users/[id]/page.tsx
-export default async function UserPage({
-  params: { locale, id }
-}: {
-  params: { locale: string; id: string };
-}) {
-  // 处理路由参数
-}
-
-// 生成静态路由
-export async function generateStaticParams() {
-  const users = await fetchUsers();
-
-  return users.map((user) => ({
-    locale: ['en', 'zh'],
-    id: user.id
-  }));
-}
-```
-
-### 2. 元数据生成
-
-```typescript
-// 1. 静态元数据
-export const metadata: Metadata = {
-  title: 'User Profile',
-  description: 'User profile page'
-};
-
-// 2. 动态元数据
-export async function generateMetadata({
-  params
-}: {
-  params: PageParamsType;
-}): Promise<Metadata> {
-  const pageParams = new PageParams(await params);
-  const tt = await pageParams.getI18nInterface(userI18n);
-
-  return {
-    title: tt.pageTitle,
-    description: tt.pageDescription
-  };
-}
-```
-
-## 最佳实践和性能优化
-
-### 1. 组件分割原则
-
-```typescript
-// ❌ 错误：在一个组件中混合服务端和客户端逻辑
-export default function Page() {
-  const [state, setState] = useState();  // 错误：服务端组件不能使用 hooks
-  const data = await fetchData();        // 正确：服务端数据获取
-
-  return <div>{/* ... */}</div>;
-}
-
-// ✅ 正确：分离服务端和客户端逻辑
-// page.tsx (服务端组件)
-export default async function Page() {
-  const data = await fetchData();  // 服务端数据获取
-  return <ClientComponent data={data} />;
-}
-
-// ClientComponent.tsx (客户端组件)
-'use client';
-export function ClientComponent({ data }) {
-  const [state, setState] = useState();  // 客户端状态管理
-  return <div>{/* ... */}</div>;
-}
-```
-
-### 2. 性能优化策略
-
-```typescript
-// 1. 组件级缓存
-export default async function UserList() {
-  const users = await fetchUsers();
-
-  return (
-    <div>
-      {users.map(user => (
-        <Suspense key={user.id} fallback={<Loading />}>
-          <UserCard user={user} />
-        </Suspense>
-      ))}
-    </div>
-  );
-}
-
-// 2. 路由级缓存
-export const revalidate = 3600;  // 缓存一小时
-
-// 3. 选择性水合
-export default function Page() {
-  return (
-    <>
-      <StaticContent />
-      <Suspense fallback={<Loading />}>
-        <DynamicContent />
-      </Suspense>
-    </>
-  );
-}
-```
-
-### 3. 错误处理
-
-```typescript
-// 1. 错误边界
-'use client';
-export function ErrorBoundary({
-  error,
-  reset
-}: {
-  error: Error;
-  reset: () => void;
-}) {
-  return (
-    <div>
-      <h2>出错了！</h2>
-      <button onClick={reset}>重试</button>
-    </div>
-  );
-}
-
-// 2. 加载状态
-export default async function Page() {
-  return (
-    <Suspense fallback={<Loading />}>
-      <SlowComponent />
-    </Suspense>
-  );
-}
-```
-
-## 总结
-
-Next.js 13+ 的页面开发需要注意以下几点：
-
-1. **组件类型选择**：
-   - 默认使用服务端组件
-   - 只在必要时使用客户端组件
-   - 合理分割组件职责
-
-2. **数据流处理**：
-   - 服务端优先获取数据
-   - 通过属性传递给客户端
-   - 使用 Store 管理客户端状态
-
-3. **性能优化**：
-   - 合理使用缓存策略
-   - 实现选择性水合
-   - 优化加载性能
-
-4. **开发体验**：
-   - 清晰的代码组织
-   - 类型安全
-   - 完善的错误处理
-
-5. **最佳实践**：
-   - 遵循单一职责原则
-   - 实现优雅降级
-   - 保持代码可维护性

package/dist/templates/next-app/docs/zh/project-structure.md

@@ -1,176 +0,0 @@
-# 项目结构详细说明
-
-## 目录结构概览
-
-```
-next-app/
-├── config/           # 全局配置文件
-├── src/             # 源代码目录
-│   ├── app/         # Next.js 应用路由
-│   ├── base/        # 客户端核心代码
-│   ├── core/        # 核心启动和IOC配置
-│   ├── server/      # 服务端代码
-│   ├── styles/      # 样式文件
-│   └── uikit/       # UI组件库
-└── public/          # 静态资源
-```
-
-## 详细结构说明
-
-### 1. 客户端架构 (src/base)
-
-#### 1.1 接口层 (src/base/port)
-
-- `AdminLayoutInterface.ts` - 管理布局接口
-- `AppApiInterface.ts` - 应用API接口
-- `AppUserApiInterface.ts` - 用户API接口
-- `AsyncStateInterface.ts` - 异步状态接口
-- `I18nServiceInterface.ts` - 国际化服务接口
-- `IOCInterface.ts` - 依赖注入接口
-- `RouterInterface.ts` - 路由接口
-- `UserServiceInterface.ts` - 用户服务接口
-
-#### 1.2 业务逻辑层 (src/base/cases)
-
-- 状态管理控制器
-- 对话框处理
-- 路由服务
-- 用户服务
-- 加密服务
-
-#### 1.3 服务实现层 (src/base/services)
-
-- `AdminUserService.ts` - 管理用户服务
-- `I18nService.ts` - 国际化服务
-- `UserService.ts` - 用户服务
-- `adminApi/` - 管理API实现
-- `appApi/` - 应用API实现
-
-### 2. 服务端架构 (src/server)
-
-#### 2.1 接口层 (src/server/port)
-
-- `CrentialTokenInterface.ts` - 凭证令牌接口
-- `DBBridgeInterface.ts` - 数据库桥接接口
-- `DBTableInterface.ts` - 数据表接口
-- `PaginationInterface.ts` - 分页接口
-- `ParamsHandlerInterface.ts` - 参数处理接口
-- `ServerAuthInterface.ts` - 服务认证接口
-- `ServerInterface.ts` - 服务器接口
-- `UserRepositoryInterface.ts` - 用户仓库接口
-- `ValidatorInterface.ts` - 验证器接口
-
-#### 2.2 核心实现
-
-- `AppErrorApi.ts` - API错误处理
-- `AppSuccessApi.ts` - API成功响应
-- `ServerAuth.ts` - 服务认证实现
-- `UserCredentialToken.ts` - 用户凭证令牌
-
-#### 2.3 服务层 (src/server/services)
-
-- `AdminAuthPlugin.ts` - 管理认证插件
-- `AIService.ts` - AI服务
-- `ApiUserService.ts` - API用户服务
-- `UserService.ts` - 用户服务
-
-#### 2.4 数据访问层
-
-- `repositorys/UserRepository.ts` - 用户数据仓库
-- `sqlBridges/SupabaseBridge.ts` - Supabase数据库桥接
-
-#### 2.5 验证器 (src/server/validators)
-
-- `LoginValidator.ts` - 登录验证
-- `PaginationValidator.ts` - 分页验证
-
-### 3. API路由结构 (src/app/api)
-
-```
-api/
-├── admin/           # 管理接口
-│   └── users/       # 用户管理
-├── ai/             # AI相关接口
-│   └── completions/ # AI补全
-└── user/           # 用户接口
-    ├── login/      # 登录
-    ├── logout/     # 登出
-    └── register/   # 注册
-```
-
-### 4. 页面路由结构 (src/app/[locale])
-
-```
-[locale]/
-├── admin/          # 管理页面
-│   └── users/      # 用户管理
-├── login/          # 登录页面
-├── register/       # 注册页面
-└── page.tsx        # 首页
-```
-
-### 5. UI组件库 (src/uikit)
-
-#### 5.1 组件 (components)
-
-- `AdminLayout.tsx` - 管理布局
-- `BaseHeader.tsx` - 基础头部
-- `BaseLayout.tsx` - 基础布局
-- `ChatRoot.tsx` - 聊天根组件
-- `LanguageSwitcher.tsx` - 语言切换
-- `ThemeSwitcher.tsx` - 主题切换
-- 其他通用组件
-
-#### 5.2 Hooks和Context
-
-- `useI18nInterface.ts` - 国际化Hook
-- `useIOC.ts` - IOC容器Hook
-- `useStore.ts` - 状态管理Hook
-- `IOCContext.ts` - IOC上下文
-
-## 技术特点
-
-1. **依赖注入模式**
-   - 使用 IOC 容器管理依赖
-   - 客户端和服务端分别维护独立的 IOC 容器
-   - 通过接口进行解耦
-
-2. **分层架构**
-   - 清晰的接口定义
-   - 职责分明的实现层
-   - 松耦合的模块设计
-
-3. **状态管理**
-   - 基于控制器的状态管理
-   - 响应式数据流
-   - 可预测的状态变更
-
-4. **国际化支持**
-   - 基于 next-intl 的多语言支持
-   - 动态语言切换
-   - 路由级别的语言隔离
-
-5. **主题系统**
-   - 基于 Tailwind CSS
-   - 暗黑模式支持
-   - 可配置的主题变量
-
-## 开发流程
-
-1. **API开发**
-   - 定义接口 (port)
-   - 实现验证器 (validators)
-   - 实现服务 (services)
-   - 创建API路由 (api)
-
-2. **页面开发**
-   - 创建页面组件
-   - 实现控制器
-   - 注册依赖
-   - 添加路由
-
-3. **组件开发**
-   - 创建UI组件
-   - 实现业务逻辑
-   - 注入依赖
-   - 添加样式