generator-mico-cli 0.2.13 → 0.2.14

package/generators/micro-react/templates/apps/layout/docs/utils-timezone.md

@@ -0,0 +1,322 @@
+# 时区工具函数
+
+> 创建时间：2025-01-27
+
+## 概述
+
+本模块提供时区管理工具函数，支持 UTC-12 到 UTC+14 的全时区范围。基于 `dayjs` 及其 `utc`、`timezone` 插件实现，时区偏移量存储在 `localStorage` 中，支持用户切换时区。
+
+**文件位置**：`apps/layout/src/common/helpers.ts`
+
+## 核心概念
+
+### 时区表示法
+
+本模块使用两种时区表示法：
+
+| 表示法 | 格式 | 示例 | 说明 |
+|--------|------|------|------|
+| **UTC Offset** | `UTC+N` / `UTC-N` | `UTC+8`、`UTC-5` | 用于用户界面显示 |
+| **IANA 时区** | `地区/城市` | `Asia/Shanghai`、`America/New_York` | 用于 dayjs 时区计算 |
+
+### 存储机制
+
+时区信息通过 `localStorage` 持久化：
+
+| 存储键 | 常量 | 说明 |
+|--------|------|------|
+| `mico-cs-timezone` | `STORAGE_KEYS.TIMEZONE` | 存储数字（如 `8`）或字符串（如 `UTC+8`） |
+| `mico-cs-timezone-region` | `STORAGE_KEYS.TIMEZONE_REGION` | 存储 IANA 时区标识（如 `Asia/Shanghai`） |
+
+## 常量定义
+
+### TIMEZONE
+
+UTC 偏移量键的枚举映射，覆盖 UTC-12 到 UTC+14：
+
+```typescript
+export const TIMEZONE = {
+  'UTC-12': 'UTC-12',
+  'UTC-11': 'UTC-11',
+  // ... 省略中间值
+  'UTC+12': 'UTC+12',
+  'UTC+13': 'UTC+13',
+  'UTC+14': 'UTC+14',
+} as const;
+
+export type TTimezone = keyof typeof TIMEZONE;
+```
+
+### TIMEZONE_HASH
+
+UTC 偏移量到 IANA 时区标识的映射表：
+
+```typescript
+export const TIMEZONE_HASH: Record<TTimezone, string> = {
+  [TIMEZONE['UTC-12']]: 'Etc/GMT+12',      // 无居住区
+  [TIMEZONE['UTC-11']]: 'Pacific/Pago_Pago', // 帕果帕果，美属萨摩亚
+  [TIMEZONE['UTC-10']]: 'Pacific/Honolulu',  // 檀香山，夏威夷
+  [TIMEZONE['UTC-9']]:  'America/Anchorage', // 安克雷奇，阿拉斯加
+  [TIMEZONE['UTC-8']]:  'America/Los_Angeles', // 洛杉矶
+  [TIMEZONE['UTC-7']]:  'America/Denver',    // 丹佛
+  [TIMEZONE['UTC-6']]:  'America/Chicago',   // 芝加哥
+  [TIMEZONE['UTC-5']]:  'America/New_York',  // 纽约
+  [TIMEZONE['UTC-4']]:  'America/Puerto_Rico', // 波多黎各
+  [TIMEZONE['UTC-3']]:  'America/Sao_Paulo', // 圣保罗
+  [TIMEZONE['UTC-2']]:  'America/Noronha',   // 费尔南多岛
+  [TIMEZONE['UTC-1']]:  'Atlantic/Azores',   // 亚速尔群岛
+  [TIMEZONE['UTC+0']]:  'Europe/London',     // 伦敦
+  [TIMEZONE['UTC+1']]:  'Europe/Paris',      // 巴黎
+  [TIMEZONE['UTC+2']]:  'Europe/Kyiv',       // 基辅
+  [TIMEZONE['UTC+3']]:  'Europe/Moscow',     // 莫斯科
+  [TIMEZONE['UTC+4']]:  'Asia/Dubai',        // 迪拜
+  [TIMEZONE['UTC+5']]:  'Asia/Tashkent',     // 塔什干
+  [TIMEZONE['UTC+6']]:  'Asia/Dhaka',        // 达卡
+  [TIMEZONE['UTC+7']]:  'Asia/Bangkok',      // 曼谷
+  [TIMEZONE['UTC+8']]:  'Asia/Shanghai',     // 上海（默认）
+  [TIMEZONE['UTC+9']]:  'Asia/Tokyo',        // 东京
+  [TIMEZONE['UTC+10']]: 'Australia/Sydney',  // 悉尼
+  [TIMEZONE['UTC+11']]: 'Pacific/Noumea',    // 努美阿
+  [TIMEZONE['UTC+12']]: 'Pacific/Auckland',  // 奥克兰
+  [TIMEZONE['UTC+13']]: 'Pacific/Tongatapu', // 汤加
+  [TIMEZONE['UTC+14']]: 'Pacific/Kiritimati', // 基里巴斯圣诞岛
+};
+```
+
+> **说明**：地理上有 24 个时区，但实际应用中存在 UTC+13 和 UTC+14（太平洋岛国），因此本模块覆盖 27 个时区。
+
+## API 参考
+
+### 时区转换函数
+
+#### utcOffsetToTimezone
+
+将 UTC 偏移量数字转换为 `UTC+N` 格式字符串。
+
+```typescript
+function utcOffsetToTimezone(utcOffset: number): string;
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `utcOffset` | `number` | UTC 偏移量，如 `8` 表示 UTC+8 |
+
+**示例**：
+
+```typescript
+utcOffsetToTimezone(8);   // => 'UTC+8'
+utcOffsetToTimezone(-5);  // => 'UTC-5'
+utcOffsetToTimezone(0);   // => 'UTC+0'
+```
+
+#### utcOffsetToTimeZoneStr
+
+将 UTC 偏移量转换为 IANA 时区标识。
+
+```typescript
+function utcOffsetToTimeZoneStr(utcOffset: number): string;
+```
+
+**回退逻辑**：
+
+1. 查找 `TIMEZONE_HASH` 映射
+2. 若无匹配，使用 `dayjs.tz.guess()` 推断浏览器时区
+3. 最终回退到 `Asia/Shanghai`
+
+**示例**：
+
+```typescript
+utcOffsetToTimeZoneStr(8);   // => 'Asia/Shanghai'
+utcOffsetToTimeZoneStr(-5);  // => 'America/New_York'
+```
+
+### 时区读写函数
+
+#### getTimezoneOffset
+
+从 `localStorage` 获取时区偏移量数字。
+
+```typescript
+function getTimezoneOffset(): number;
+```
+
+**返回值**：偏移量数字，默认 `8`（UTC+8）
+
+#### getTimezone
+
+获取当前时区的 IANA 标识。
+
+```typescript
+function getTimezone(): string;
+```
+
+**返回值**：IANA 时区标识（如 `Asia/Shanghai`）
+
+**回退逻辑**：
+
+1. 从 `localStorage` 读取存储值
+2. 若为数字字符串，转换为 `UTC+N` 格式后查找 IANA 映射
+3. 若已是 `UTC+N` 格式，直接查找 IANA 映射
+4. 若无匹配，使用 `dayjs.tz.guess()` 推断
+5. 最终回退到 `Asia/Shanghai`
+
+#### getCurrentTimezone
+
+获取当前时区的 `UTC+N` 格式字符串。
+
+```typescript
+function getCurrentTimezone(): string;
+```
+
+**返回值**：UTC 偏移量字符串（如 `UTC+8`），默认 `UTC+8`
+
+#### setTimezone
+
+设置时区到 `localStorage`。
+
+```typescript
+function setTimezone(timezone: string): void;
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `timezone` | `string` | 时区字符串，如 `UTC+8` 或偏移量数字字符串如 `8` |
+
+#### getTimezoneRegion
+
+获取时区地区（IANA 标识）。
+
+```typescript
+function getTimezoneRegion(): string;
+```
+
+**返回值**：时区地区字符串（如 `Asia/Shanghai`），未设置则返回空字符串
+
+#### setTimezoneRegion
+
+设置时区地区到 `localStorage`。
+
+```typescript
+function setTimezoneRegion(region: string): void;
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `region` | `string` | IANA 时区标识，如 `Asia/Shanghai` |
+
+## 使用示例
+
+### 初始化时区
+
+```typescript
+import { setTimezone, setTimezoneRegion } from '@/common/helpers';
+
+// 用户选择 UTC+9 (东京)
+setTimezone('9');
+setTimezoneRegion('Asia/Tokyo');
+```
+
+### 获取当前时区
+
+```typescript
+import { getCurrentTimezone, getTimezoneRegion } from '@/common/helpers';
+
+const timezone = getCurrentTimezone();  // => 'UTC+8'
+const region = getTimezoneRegion();     // => 'Asia/Shanghai'
+```
+
+### 用户时区切换（AvatarDropdown）
+
+**文件**：`apps/layout/src/components/RightContent/AvatarDropdown.tsx`
+
+用户头像下拉菜单中的时区选择器，允许用户切换时区并刷新页面：
+
+```typescript
+import {
+  getCurrentTimezone,
+  getTimezoneRegion,
+  setTimezoneRegion as setTimezoneRegionToStorage,
+  setTimezone as setTimezoneToStorage,
+  utcOffsetToTimezone,
+} from '@/common/helpers';
+
+// 获取当前时区用于显示
+const [currentTimezone, setCurrentTimezone] = useState(getCurrentTimezone());
+
+// 用户切换时区时
+const handleTimezoneChange = (key: string) => {
+  const lastSlashIndex = key.lastIndexOf('/');
+  const region = key.substring(0, lastSlashIndex); // 如 "Asia/Shanghai"
+  const utcOffsetStr = key.substring(lastSlashIndex + 1); // 如 "8"
+  
+  // 保存到 localStorage
+  setTimezoneToStorage(utcOffsetStr);
+  setTimezoneRegionToStorage(region);
+  
+  // 刷新页面使时区生效
+  window.location.reload();
+};
+```
+
+## 数据流
+
+```
+用户选择时区
+     ↓
+setTimezone('9') / setTimezoneRegion('Asia/Tokyo')
+     ↓
+localStorage 存储
+     ↓
+getCurrentTimezone() / getTimezone()
+     ↓
+返回 'UTC+9' / 'Asia/Tokyo'
+```
+
+## 注意事项
+
+1. **默认时区为 UTC+8**：如果 `localStorage` 中没有存储时区信息，所有函数默认使用 `Asia/Shanghai`（UTC+8）。
+
+2. **存储兼容性**：时区存储支持两种格式：
+   - 数字字符串（如 `"8"`）：推荐格式
+   - UTC 格式（如 `"UTC+8"`）：兼容格式
+   
+   读取时会自动兼容两种格式。
+
+3. **时区列表来源**：时区列表支持两种模式：
+   
+   **模式一：静态列表（默认）**
+   
+   未配置 `timezoneListUrl` 时，使用内置的静态时区列表（覆盖 UTC-12 到 UTC+14 共 27 个时区）。
+   
+   **模式二：API 获取**
+   
+   通过 `window.__MICO_CONFIG__.timezoneListUrl` 配置 API 地址：
+   
+   ```javascript
+   // 在 index.html 或应用初始化时配置
+   window.__MICO_CONFIG__ = {
+     timezoneListUrl: '/custom/api/getTimezoneList',
+   };
+   ```
+   
+   API 返回格式：
+   ```typescript
+   interface ITimezone {
+     utc_offset: number;  // UTC 偏移量
+     region: string;      // IANA 时区标识
+   }
+   ```
+
+## 文件清单
+
+| 文件路径 | 说明 |
+|----------|------|
+| `apps/layout/src/common/helpers.ts` | 时区工具函数实现 |
+| `apps/layout/src/common/auth/type.ts` | 存储键常量定义（`STORAGE_KEYS.TIMEZONE` 等） |
+| `apps/layout/src/services/config/index.ts` | 时区列表 API 服务 |
+| `apps/layout/src/services/config/type.ts` | 时区类型定义 |
+| `apps/layout/src/components/RightContent/AvatarDropdown.tsx` | 时区切换 UI 组件 |
+
+## 相关文档
+
+- [AvatarDropdown 组件](../apps/layout/docs/feature-avatar-dropdown.md)

package/generators/micro-react/templates/apps/layout/mock/menus.ts

@@ -23,16 +23,22 @@ import type { MenuItem, PageConfig } from '@/common/menu/types';
 /** Mock 页面配置 - 只需要核心字段 */
 type MockPageConfig = Pick<PageConfig, 'id' | 'name' | 'route' | 'enabled' | 'htmlUrl' | 'jsUrls' | 'cssUrls'>;
 
-/** Mock 菜单项 - page 字段使用简化类型 */
+/** Mock 菜单项 - page 字段使用简化类型，包含多语言字段 */
 type MockMenuItem = Omit<MenuItem, 'page' | 'children'> & {
   page: MockPageConfig | null;
   children: MockMenuItem[];
+  /** 英文名称（用于英文环境权限匹配） */
+  nameEn?: string;
+  /** 菜单唯一标识符（用于权限匹配的兜底） */
+  nameKey?: string;
 };
 
 const mockMenus: MockMenuItem[] = [
   {
     "id": 1,
     "name": "首页",
+    "nameEn": "Home",
+    "nameKey": "cs_web_menu_home",
     "type": "page",
     "path": null,
     "icon": "Home",
@@ -53,6 +59,8 @@ const mockMenus: MockMenuItem[] = [
   {
     "id": 2,
     "name": "示例模块",
+    "nameEn": "Example Module",
+    "nameKey": "cs_web_menu_example_module",
     "type": "group",
     "path": null,
     "icon": "List",
@@ -64,6 +72,8 @@ const mockMenus: MockMenuItem[] = [
       {
         "id": 3,
         "name": "示例页面",
+        "nameEn": "Example Page",
+        "nameKey": "cs_web_menu_example_page",
         "type": "page",
         "path": "/example/page",
         "icon": "File",
@@ -86,6 +96,8 @@ const mockMenus: MockMenuItem[] = [
   {
     "id": 5,
     "name": "微应用示例",
+    "nameEn": "Microapp Example",
+    "nameKey": "cs_web_menu_microapp_example",
     "type": "group",
     "path": null,
     "icon": "Apps",
@@ -97,6 +109,8 @@ const mockMenus: MockMenuItem[] = [
       {
         "id": 6,
         "name": "子应用页面",
+        "nameEn": "Subapp Page",
+        "nameKey": "cs_web_menu_subapp_page",
         "type": "page",
         "path": null,
         "icon": "Desktop",
@@ -119,6 +133,8 @@ const mockMenus: MockMenuItem[] = [
   {
     "id": 7,
     "name": "外部链接",
+    "nameEn": "External Link",
+    "nameKey": "cs_web_menu_external_link",
     "type": "link",
     "path": "https://github.com",
     "icon": "Link",

package/generators/micro-react/templates/apps/layout/package.json

@@ -3,6 +3,7 @@
   "private": true,
   "author": "Easton <easton@micous.com>",
   "scripts": {
+    "check-types": "tsc --noEmit",
     "build": "npm run build:production",
     "build:development": "cross-env UMI_ENV=development max build",
     "build:production": "cross-env UMI_ENV=production max build",
@@ -21,8 +22,9 @@
     "test": "cross-env UMI_ENV=test max dev"
   },
   "dependencies": {
-    "@arco-design/web-react": "^2.66.6",
-    "<%= packageScope %>/shared-styles": "workspace:*",
+    "<%= packageScope %>/common-intl": "workspace:*",
+    "@mico-platform/ui": "<%= micoUiVersion %>",
+    "@mico-platform/theme": "<%= themeVersion %>",
     "@umijs/max": "^4.6.15",
     "babel-plugin-dynamic-import-node": "^2.3.3",
     "cross-env": "^10.1.0",
@@ -35,6 +37,7 @@
   "devDependencies": {
     "@types/react": "^18.0.33",
     "@types/react-dom": "^18.0.11",
+    "@types/spark-md5": "^3.0.5",
     "lint-staged": "^13.2.0",
     "prettier": "^2.8.7",
     "prettier-plugin-organize-imports": "^3.2.2",

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -1,8 +1,8 @@
 import { history, type RequestConfig } from '@umijs/max';
 import { addGlobalUncaughtErrorHandler } from 'qiankun';
 import { errorConfig } from './requestErrorConfig';
-// 解决「React19 中无法使用 Message/Notification」的问题。 @see https://github.com/arco-design/arco-design/issues/2900#issuecomment-2796571653
-import * as arco from '@arco-design/web-react';
+// 将 @mico-platform/ui 暴露到 window，供子应用 externals 使用
+import * as micoUi from '@mico-platform/ui';
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 
@@ -22,6 +22,7 @@ import {
 import { initTheme } from './common/theme';
 import MicroAppLoader from './components/MicroAppLoader';
 import { isNoAuthRoute } from '@/constants';
+import { getUmiLocale } from '@/common/locale';
 import './global.less';
 
 // ==================== qiankun 全局错误处理 ====================
@@ -41,15 +42,15 @@ if (typeof window !== 'undefined') {
       event instanceof ErrorEvent
         ? event.error
         : event instanceof PromiseRejectionEvent
-        ? event.reason
-        : event;
+          ? event.reason
+          : event;
 
     const errorMessage =
       error instanceof Error
         ? error.message
         : typeof error === 'string'
-        ? error
-        : 'Unknown micro-app error';
+          ? error
+          : 'Unknown micro-app error';
 
     console.error('[qiankun] Global uncaught error:', {
       error,
@@ -85,12 +86,26 @@ if (typeof window !== 'undefined') {
   const win = window as unknown as Record<string, unknown>;
   win.React = React;
   win.ReactDOM = ReactDOM;
-  win.arco = arco;
+  win.micoUi = micoUi;
 }
 
 // 初始化主题（在页面加载时立即执行，避免闪烁）
 initTheme();
 
+// ==================== 国际化运行时配置 ====================
+// 使用 umi 本地文案，通过映射转换保持 localStorage 与 common-intl 统一
+
+/**
+ * 运行时国际化配置
+ * 自定义 getLocale 函数，将 common-intl 格式 (zh_CN, en) 转换为 umi 格式 (zh-CN, en-US)
+ * @see https://umijs.org/docs/max/i18n#%E8%BF%90%E8%A1%8C%E6%97%B6%E9%85%8D%E7%BD%AE
+ */
+export const locale = {
+  getLocale() {
+    return getUmiLocale();
+  },
+};
+
 /**
  * @see https://umijs.org/docs/api/runtime-config#getinitialstate
  */
@@ -144,8 +159,6 @@ export async function getInitialState(): Promise<{
     fetchUserInfo: fetchUserInfoFn,
   };
 }
-
-
 /**
  * @name request 配置，可以配置错误处理
  * 它基于 axios 和 ahooks 的 useRequest 提供了一套统一的网络请求和错误处理方案。
@@ -225,7 +238,6 @@ export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
   });
 }
 
-
 /**
  * @name 路由变化处理
  * @description 处理 defaultPath 重定向：访问 "/" 时自动跳转到配置的默认路径

package/generators/micro-react/templates/apps/layout/src/common/auth/index.ts

@@ -3,6 +3,9 @@ import { checkStaffAuth } from '@/services/auth';
 import { handleAuthFailureRedirect } from '../request';
 import { clearStoredTokens, getAuthInfo } from './auth-manager';
 
+// 导出 STORAGE_KEYS 常量
+export { STORAGE_KEYS } from '../../constants';
+
 export function logout(): void {
   clearStoredTokens();
 }