create-modsemi 0.1.0

package/template/modern.config.ts

@@ -0,0 +1,38 @@
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/en/configure/app/usage
+export default defineConfig({
+  plugins: [appTools()],
+  tools: {
+    // 啟用 Less 支援（Modern.js 內建，安裝 less 即可）
+    styleLoader: {},
+  },
+  dev: {
+    server: {
+      proxy: {
+        /**
+         * API Proxy — 解決本地開發的 CORS 問題
+         *
+         * 所有 /api/** 請求會在 dev server 端轉發給後端，
+         * 瀏覽器只看到同源的 /api，不會觸發 CORS。
+         *
+         * 使用方式：
+         *   將 target 改為後端實際位址，例如：
+         *   'http://localhost:3001'
+         *   'https://staging-api.example.com'
+         *
+         * 注意：此設定僅在 `pnpm dev` 時生效；
+         *       正式環境請改用 Nginx / CDN 的 proxy 設定。
+         */
+        '/api': {
+          target: 'http://localhost:3001',
+          changeOrigin: true,
+          // 將 /api 前綴從轉發路徑中移除
+          // 例如：前端呼叫 /api/users → 後端收到 /users
+          // 若後端 route 本身已包含 /api，請刪除下面這行
+          pathRewrite: { '^/api': '' },
+        },
+      },
+    },
+  },
+});

package/template/orval.config.ts

@@ -0,0 +1,98 @@
+import { defineConfig } from 'orval';
+
+/**
+ * Orval 設定檔 — API 程式碼自動生成
+ *
+ * 使用方式：
+ *   pnpm api:gen              → 依 swagger/*.json 生成所有 API
+ *   pnpm api:gen --watch      → 監聽 spec 變更並自動重新生成
+ *
+ * 生成結果輸出至 src/api/generated/
+ * ⚠️  請勿手動編輯 src/api/generated/ 內的任何檔案
+ *
+ * 文件：https://orval.dev/docs
+ */
+export default defineConfig({
+  /**
+   * ── 主要 API（範例使用 swagger/sample.json）────────────────────
+   * 開發者只需將 Swagger / OpenAPI JSON 放到 swagger/ 目錄下，
+   * 並在此新增對應設定區塊即可。
+   */
+  sampleApi: {
+    input: {
+      /**
+       * target：Swagger spec 來源
+       * 支援：本地檔案路徑 | 遠端 URL
+       *
+       * 本地範例：'./swagger/sample.json'
+       * 遠端範例：'https://api.example.com/swagger.json'
+       *           'https://api.example.com/v3/api-docs'
+       */
+      target: './swagger/sample.json',
+    },
+    output: {
+      /**
+       * mode：
+       *   'single'    — 所有 API 生成到一個檔案（小型 spec 適用）
+       *   'split'     — models 與 functions 分開（預設推薦）
+       *   'tags'      — 依 OpenAPI tags 拆分成多個檔案（大型 spec 推薦）
+       *   'tags-split'— tags + split 的組合
+       */
+      mode: 'tags',
+
+      /** 生成的 API 請求函式輸出目錄 */
+      target: './src/api/generated',
+
+      /** 生成的 TypeScript 型別定義輸出目錄 */
+      schemas: './src/api/generated/model',
+
+      /**
+       * client：生成的客戶端類型
+       *   'axios-functions' — 純函式（預設，無框架依賴）
+       *   'axios'           — 工廠函式（支援注入自訂 instance）
+       *   'react-query'     — 生成 useQuery / useMutation hooks
+       *   'swr'             — 生成 SWR hooks
+       *   'fetch'           — 使用原生 Fetch API
+       */
+      client: 'axios',
+
+      override: {
+        /**
+         * mutator：使用自訂的 axios instance 取代預設的 axios
+         * 讓所有生成的 API 都走 src/api/instance.ts 中的
+         * 攔截器（自動注入 Token、統一錯誤處理）
+         */
+        mutator: {
+          path: './src/api/instance.ts',
+          name: 'customInstance',
+        },
+      },
+    },
+    // hooks: {
+    //   afterAllFilesWrite: 'prettier --write',
+    // },
+    // 注意：src/api/generated/ 已加入 .gitignore，無需格式化
+  },
+
+  /**
+   * ── 新增其他 API 服務的範例 ────────────────────────────────
+   * 若後端有多個 micro-service，各自有不同的 Swagger spec，
+   * 在此複製上方 sampleApi 區塊並修改 input.target 即可。
+   *
+   * anotherService: {
+   *   input: { target: './swagger/another.json' },
+   *   output: {
+   *     mode: 'tags',
+   *     target: './src/api/generated/another',
+   *     schemas: './src/api/generated/another/model',
+   *     client: 'axios',
+   *     override: {
+   *       mutator: {
+   *         path: './src/api/instance.ts',
+   *         name: 'customInstance',
+   *       },
+   *     },
+   *   },
+   * },
+   */
+});

package/template/src/api/instance.ts

@@ -0,0 +1,87 @@
+/**
+ * Axios Instance — ModSemi API 統一請求入口
+ *
+ * 所有 orval 生成的 API 函式都使用此 instance 發出請求。
+ * 在此集中管理：baseURL、逾時、請求攔截器（注入 Token）、回應攔截器（錯誤處理）。
+ */
+
+import axios, {
+  type AxiosError,
+  type AxiosRequestConfig,
+  type AxiosResponse,
+} from 'axios';
+
+// ── 環境設定 ────────────────────────────────────────────────
+// Modern.js 透過 .env 檔案注入環境變數，於 modern.config.ts 中設定 source.define
+const BASE_URL = (typeof process !== 'undefined' && process.env.MODERN_APP_API_BASE_URL) || '/api';
+
+// ── 建立 instance ──────────────────────────────────────────
+export const apiInstance = axios.create({
+  baseURL: BASE_URL,
+  timeout: 15000,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+// ── 請求攔截器：自動注入 Bearer Token ─────────────────────
+apiInstance.interceptors.request.use(
+  config => {
+    // 從 localStorage 讀取 authStore 持久化的 token
+    // 若日後 authStore 新增 token 欄位，在此取用
+    const raw = localStorage.getItem('modsemi-auth');
+    if (raw) {
+      try {
+        const state = JSON.parse(raw) as { state?: { token?: string } };
+        const token = state?.state?.token;
+        if (token) {
+          config.headers.Authorization = `Bearer ${token}`;
+        }
+      } catch {
+        // JSON 解析失敗時忽略，不影響請求
+      }
+    }
+    return config;
+  },
+  error => Promise.reject(error),
+);
+
+// ── 回應攔截器：統一錯誤處理 ──────────────────────────────
+apiInstance.interceptors.response.use(
+  (response: AxiosResponse) => response,
+  (error: AxiosError) => {
+    if (error.response) {
+      const { status } = error.response;
+
+      if (status === 401) {
+        // Token 過期或無效 → 清除本地登入狀態並導向登入頁
+        localStorage.removeItem('modsemi-auth');
+        window.location.href = '/login';
+      }
+
+      if (status === 403) {
+        console.warn('[API] 403 Forbidden — 無此操作權限');
+      }
+
+      if (status >= 500) {
+        console.error('[API] 伺服器錯誤', error.response.data);
+      }
+    } else if (error.request) {
+      console.error('[API] 網路錯誤，請檢查連線', error.message);
+    }
+
+    return Promise.reject(error);
+  },
+);
+
+/**
+ * orval mutator — 供 orval.config.ts 的 `mutator` 欄位引用。
+ * orval 生成的每個 API 函式會呼叫此函式發送請求。
+ */
+export const customInstance = <T>(
+  config: AxiosRequestConfig,
+): Promise<T> => {
+  return apiInstance(config).then(response => response.data as T);
+};
+
+export default apiInstance;

package/template/src/components/Access/index.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+
+interface AccessProps {
+  /** 是否有存取權限（通常來自 useAccess() 的某個 key） */
+  accessible: boolean;
+  /** 無權限時顯示的替代內容，預設為 null（不渲染任何東西） */
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+/**
+ * 條件渲染包裝組件。根據 `accessible` 決定是否渲染 `children`。
+ *
+ * @example 基本用法
+ * ```tsx
+ * const access = useAccess();
+ *
+ * <Access accessible={access.isAdmin}>
+ *   <DeleteButton />
+ * </Access>
+ * ```
+ *
+ * @example 搭配 fallback
+ * ```tsx
+ * <Access accessible={access.canViewSettings} fallback={<NoPermissionTip />}>
+ *   <SettingsPanel />
+ * </Access>
+ * ```
+ */
+export function Access({ accessible, fallback = null, children }: AccessProps) {
+  return accessible ? <>{children}</> : <>{fallback}</>;
+}

package/template/src/components/AppBreadcrumb/index.tsx

@@ -0,0 +1,34 @@
+import { Breadcrumb } from '@douyinfe/semi-ui-19';
+import { useNavigate } from '@modern-js/runtime/router';
+import type { BreadcrumbItem } from '../../hooks/useMenuData';
+
+export interface BreadcrumbComponentProps {
+  breadcrumbs: BreadcrumbItem[];
+}
+
+/**
+ * 預設 Breadcrumb 元件，使用 Semi Design 的 Breadcrumb.Item 子元素方式渲染。
+ * 非最後一項可點擊並導航至對應路徑。
+ * 可在 src/config/global.tsx 的 breadcrumbComponent 欄位替換為自訂元件。
+ */
+export function AppBreadcrumb({ breadcrumbs }: BreadcrumbComponentProps) {
+  const navigate = useNavigate();
+  const lastIndex = breadcrumbs.length - 1;
+
+  return (
+    <Breadcrumb>
+      {breadcrumbs.map((b, i) => {
+        const isLast = i === lastIndex;
+        return (
+          <Breadcrumb.Item
+            key={b.path}
+            onClick={isLast ? undefined : () => navigate(b.path)}
+            style={isLast ? undefined : { cursor: 'pointer' }}
+          >
+            {b.text}
+          </Breadcrumb.Item>
+        );
+      })}
+    </Breadcrumb>
+  );
+}

package/template/src/components/UserAvatar/index.less

@@ -0,0 +1,66 @@
+// ── UserAvatar 觸發器 ─────────────────────────────────────
+
+.ua-trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  cursor: pointer;
+  outline: none;
+  transition: box-shadow 0.2s ease, opacity 0.15s ease;
+
+  &:hover {
+    opacity: 0.85;
+    box-shadow: 0 0 0 3px var(--semi-color-primary-light-hover);
+  }
+
+  &:focus-visible {
+    box-shadow: 0 0 0 3px var(--semi-color-primary-light-active);
+  }
+}
+
+.ua-avatar {
+  cursor: pointer;
+}
+
+// ── Dropdown 選單樣式 ─────────────────────────────────────
+
+.ua-menu {
+  min-width: 200px !important;
+}
+
+// 使用者資訊區塊
+.ua-user-info {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 14px 16px 12px;
+}
+
+.ua-user-avatar {
+  flex-shrink: 0;
+}
+
+.ua-user-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  overflow: hidden;
+}
+
+.ua-user-name {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--semi-color-text-0);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.ua-user-email {
+  font-size: 12px;
+  color: var(--semi-color-text-2);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/template/src/components/UserAvatar/index.tsx

@@ -0,0 +1,96 @@
+import {
+  IconExit,
+  IconMoon,
+  IconSettingStroked,
+  IconSun,
+} from '@douyinfe/semi-icons';
+import { Avatar, Dropdown } from '@douyinfe/semi-ui-19';
+import { useNavigate } from '@modern-js/runtime/router';
+import { useAuthStore } from '../../store/authStore';
+import { useLayoutStore } from '../../store/layoutStore';
+import './index.less';
+
+function getInitials(name: string) {
+  return name.trim().slice(0, 1).toUpperCase();
+}
+
+/** Header 右側使用者頭像 + Dropdown 選單 */
+export function UserAvatar() {
+  const navigate = useNavigate();
+  const { currentUser, logout } = useAuthStore();
+  const { themeMode, toggleTheme } = useLayoutStore();
+
+  const name = currentUser?.name ?? '使用者';
+  const email = currentUser?.email;
+
+  const handleLogout = () => {
+    logout();
+    navigate('/login', { replace: true });
+  };
+
+  const menu = (
+    <Dropdown.Menu className="ua-menu">
+      {/* 使用者資訊區塊（非可點選） */}
+      <div className="ua-user-info">
+        <Avatar
+          size="default"
+          color="blue"
+          src={currentUser?.avatar}
+          className="ua-user-avatar"
+        >
+          {getInitials(name)}
+        </Avatar>
+        <div className="ua-user-text">
+          <div className="ua-user-name">{name}</div>
+          {email && <div className="ua-user-email">{email}</div>}
+        </div>
+      </div>
+
+      <Dropdown.Divider />
+
+      <Dropdown.Item
+        icon={<IconSettingStroked />}
+        onClick={() => navigate('/settings/account')}
+      >
+        個人設定
+      </Dropdown.Item>
+
+      <Dropdown.Item
+        icon={themeMode === 'dark' ? <IconSun /> : <IconMoon />}
+        onClick={toggleTheme}
+      >
+        {themeMode === 'dark' ? '切換亮色模式' : '切換暗色模式'}
+      </Dropdown.Item>
+
+      <Dropdown.Divider />
+
+      <Dropdown.Item
+        type="danger"
+        icon={<IconExit />}
+        onClick={handleLogout}
+      >
+        登出
+      </Dropdown.Item>
+    </Dropdown.Menu>
+  );
+
+  return (
+    <Dropdown
+      trigger="click"
+      position="bottomRight"
+      render={menu}
+      clickToHide
+    >
+      <div className="ua-trigger" role="button" tabIndex={0} aria-label="使用者選單">
+        <Avatar
+          size="small"
+          color="blue"
+          src={currentUser?.avatar}
+          className="ua-avatar"
+        >
+          {getInitials(name)}
+        </Avatar>
+      </div>
+    </Dropdown>
+  );
+}

package/template/src/config/global.tsx

@@ -0,0 +1,59 @@
+/**
+ * ModSemi 全域設定
+ *
+ * 這是框架開放給使用者自訂的主要介面。
+ * 修改此檔案的欄位以替換預設的框架行為，無需深入框架內部。
+ *
+ * 目前支援的自訂項目：
+ *   - errorPages.notFound      — 404 頁面元件
+ *   - breadcrumbComponent      — 麵包屑元件
+ */
+
+import type { ComponentType } from 'react';
+import {
+  AppBreadcrumb,
+  type BreadcrumbComponentProps,
+} from '../components/AppBreadcrumb';
+import { NotFoundPage } from '../pages/Error/NotFound';
+
+// ── 型別定義 ─────────────────────────────────────────────
+
+export type { BreadcrumbComponentProps };
+
+/** 錯誤頁面元件映射表 */
+export interface GlobalErrorConfig {
+  /** 訪問不存在的路徑時顯示的頁面（HTTP 404）*/
+  notFound: ComponentType;
+}
+
+/** ModSemi 全域設定型別 */
+export interface GlobalConfig {
+  errorPages: GlobalErrorConfig;
+  /**
+   * 麵包屑元件。接收 `breadcrumbs: BreadcrumbItem[]`，自行決定渲染方式。
+   *
+   * @example 使用自訂 Breadcrumb
+   * ```tsx
+   * import type { BreadcrumbComponentProps } from './global';
+   *
+   * function MyBreadcrumb({ breadcrumbs }: BreadcrumbComponentProps) {
+   *   return <div>{breadcrumbs.map(b => b.text).join(' › ')}</div>;
+   * }
+   *
+   * export const globalConfig: GlobalConfig = {
+   *   ...
+   *   breadcrumbComponent: MyBreadcrumb,
+   * };
+   * ```
+   */
+  breadcrumbComponent: ComponentType<BreadcrumbComponentProps>;
+}
+
+// ── 設定本體 ─────────────────────────────────────────────
+
+export const globalConfig: GlobalConfig = {
+  errorPages: {
+    notFound: NotFoundPage,
+  },
+  breadcrumbComponent: AppBreadcrumb,
+};

package/template/src/config/navigation.tsx

@@ -0,0 +1,91 @@
+import {
+  IconBarChartVStroked,
+  IconChecklistStroked,
+  IconFlowChartStroked,
+  IconHome,
+  IconLayers,
+  IconSettingStroked,
+} from '@douyinfe/semi-icons';
+import type { ReactNode } from 'react';
+
+export interface RouteItem {
+  text: string;
+  itemKey: string;
+  icon?: ReactNode;
+  children?: RouteItem[];
+  /** 是否隱藏於導航（如詳情頁） */
+  hideInMenu?: boolean;
+  /** 跳轉路徑，預設同 itemKey */
+  path?: string;
+  /**
+   * 存取權限 key，對應 `AccessConfig` 中的欄位名稱。
+   * 設定後，使用者須擁有對應權限才能在選單中看到此項目。
+   * 未設定則所有登入使用者均可見。
+   *
+   * @example
+   * // 只有管理員（isAdmin）才能看到此項目
+   * access: 'isAdmin'
+   *
+   * // 只有可查看設定的使用者才能看到此項目
+   * access: 'canViewSettings'
+   */
+  access?: string;
+}
+
+export const routesConfig: RouteItem[] = [
+  {
+    text: '歡迎',
+    itemKey: '/',
+    icon: <IconHome />,
+    hideInMenu: true,
+  },
+  {
+    text: '儀表板',
+    itemKey: '/dashboard',
+    icon: <IconBarChartVStroked />,
+    children: [
+      { text: '工作台', itemKey: '/dashboard/workplace' },
+      { text: '分析頁', itemKey: '/dashboard/analysis' },
+      { text: '監控頁', itemKey: '/dashboard/monitor' },
+    ],
+  },
+  {
+    text: '表單頁面',
+    itemKey: '/form',
+    icon: <IconChecklistStroked />,
+    children: [
+      { text: '基礎表單', itemKey: '/form/basic' },
+      { text: '步驟表單', itemKey: '/form/step' },
+      { text: '進階表單', itemKey: '/form/advanced' },
+    ],
+  },
+  {
+    text: '列表頁面',
+    itemKey: '/list',
+    icon: <IconLayers />,
+    children: [
+      { text: '查詢列表', itemKey: '/list/query' },
+      { text: '標準列表', itemKey: '/list/standard' },
+      { text: '卡片列表', itemKey: '/list/card' },
+    ],
+  },
+  {
+    text: '詳情頁面',
+    itemKey: '/detail',
+    icon: <IconFlowChartStroked />,
+    children: [
+      { text: '基礎詳情', itemKey: '/detail/basic' },
+      { text: '進階詳情', itemKey: '/detail/advanced' },
+    ],
+  },
+  {
+    text: '系統設定',
+    itemKey: '/settings',
+    icon: <IconSettingStroked />,
+    access: 'canViewSettings',
+    children: [
+      { text: '帳號設定', itemKey: '/settings/account' },
+      { text: '權限管理', itemKey: '/settings/permission' },
+    ],
+  },
+];

package/template/src/hooks/useAccess.ts

@@ -0,0 +1,53 @@
+import { useAuthStore } from '../store/authStore';
+
+/**
+ * 系統權限定義。
+ * 每個 key 代表一項存取能力，值為 boolean。
+ * 在 navigation.tsx 的 `access` 欄位填入對應 key，
+ * 可自動控制選單的顯示 / 隱藏。
+ */
+export interface AccessConfig {
+  /** 是否為系統管理員 */
+  isAdmin: boolean;
+  /** 是否可查看儀表板 */
+  canViewDashboard: boolean;
+  /** 是否可查看表單頁面 */
+  canViewForm: boolean;
+  /** 是否可查看列表頁面 */
+  canViewList: boolean;
+  /** 是否可查看詳情頁面 */
+  canViewDetail: boolean;
+  /** 是否可查看系統設定 */
+  canViewSettings: boolean;
+}
+
+/**
+ * 根據當前登入使用者的角色（roles），計算各功能的存取權限。
+ *
+ * **設計原則：**
+ * - 「角色 → 權限」的對映邏輯集中於此 hook，業務程式碼只消費語意化 key。
+ * - 新增角色或調整權限範圍，只需修改此檔案。
+ *
+ * @example
+ * ```tsx
+ * function AdminButton() {
+ *   const access = useAccess();
+ *   if (!access.isAdmin) return null;
+ *   return <Button>管理員功能</Button>;
+ * }
+ * ```
+ */
+export function useAccess(): AccessConfig {
+  const { currentUser } = useAuthStore();
+  const roles = currentUser?.roles ?? [];
+  const isAdmin = roles.includes('admin');
+
+  return {
+    isAdmin,
+    canViewDashboard: true,    // 所有登入使用者皆可存取
+    canViewForm: true,
+    canViewList: true,
+    canViewDetail: true,
+    canViewSettings: isAdmin,  // 僅管理員可見
+  };
+}