generator-mico-cli 0.2.1 → 0.2.2-8.beta.1

package/generators/micro-react/templates/apps/layout/docs/fix-SSO/346/227/240/351/231/220/351/207/215/345/256/232/345/220/221.md

@@ -0,0 +1,88 @@
+# 修复 SSO 无限重定向循环
+
+> 创建时间：2026-03-12
+
+## 功能概述
+
+修复 SSO 登录流程中 `redirect_count` 防护机制被过早清除，导致 `fetchUserInfo` 返回 401 时可能触发无限 SSO 重定向循环的问题。
+
+## 问题分析
+
+### 原始流程（存在缺陷）
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 立即删除 redirect_count        ← 问题根因
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 0（已被删除）
+  → 允许重定向 → 跳转 SSO
+  → SSO 自动登录回跳 → 重复以上流程 → 无限循环
+```
+
+### 根因
+
+`ensureSsoSession()` 在 ticket 换取 token 成功后**立即删除** URL 中的 `redirect_count` 参数，但后续的 `fetchUserInfo` 尚未执行。当 `fetchUserInfo` 返回 401 且 token 刷新失败时，`handleAuthFailureRedirect()` 因检测不到 `redirect_count` 而误判为首次重定向，触发循环。
+
+## 技术方案
+
+### 核心思路
+
+将 `redirect_count` 的清除时机从"SSO ticket 换 token 成功后"延后到"整个认证流程（SSO + fetchUserInfo）完全成功后"。
+
+### 修复后流程
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count              ← 修复点
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 1
+  → 已达最大重定向次数 → 停止重定向 ✅
+```
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count
+  → fetchUserInfo() 成功
+  → clearRedirectCount() 清除 redirect_count ✅
+```
+
+## 文件清单
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `src/common/request/sso.ts` | 移除 `ensureSsoSession` 中过早删除 `redirect_count` 的逻辑；新增 `clearRedirectCount()` 函数 |
+| `src/app.tsx` | 导入 `clearRedirectCount`，在 `fetchUserInfo` 成功后调用 |
+
+## API / 组件接口
+
+### clearRedirectCount
+
+```typescript
+export const clearRedirectCount = (): void
+```
+
+清除 URL 中的 `redirect_count` 参数。仅在整个认证流程完全成功后调用。
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| redirect_count 清除时机 | 延后到 fetchUserInfo 成功后 | 最小改动，不改变现有 URL 参数机制，仅调整调用时序 |
+| clearRedirectCount 放置位置 | `sso.ts` | 与 `handleAuthFailureRedirect` 同属 SSO 模块，保持内聚 |
+
+## 注意事项
+
+- `handleAuthFailureRedirect` 可能在 `request/index.ts`（refresh 失败时）和 `app.tsx`（fetchUserInfo 返回 null 时）被双重调用，但修复后两处检查到 `redirect_count >= 1` 均会停止重定向，不影响正确性
+- `redirect_count` 最大值为 1，即只允许一次自动 SSO 重定向尝试
+
+## 相关文档
+
+- [请求模块架构](./arch-请求模块.md)
+- [菜单权限控制](./feature-菜单权限控制.md)

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

@@ -0,0 +1,324 @@
+# 时区工具函数
+
+> 创建时间：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/constants/index.ts` | 存储键常量定义（`TIMEZONE`、`STORAGE_KEYS` 等） |
+| `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/api.mock.ts

@@ -6,73 +6,93 @@
 
 export default {
   // 获取用户信息
-  // 'GET /api/user/info': {
+  'GET /api/user/info': {
+    "code": 200,
+    "data": {
+        "id": 381,
+        "last_login": "2026-03-06T02:37:10.050735Z",
+        "is_superuser": true,
+        "username": "本地测试mock用户",
+        "first_name": "",
+        "last_name": "",
+        "email": "本地测试mock用户@micous.com",
+        "is_staff": true,
+        "is_active": true,
+        "type": 1,
+        "phone": "",
+        "agency_id": 0,
+        "avatar": "https://gw.alipayobjects.com/zos/antfincdn/XAosXuNZyF/BiazfanxmamNRoxxVxka.png",
+        "user_name": "Easton",
+        "permission_tree": [
+        ],
+        "miss_permissions": [],
+        "side_menus": [
+          '首页',
+          '示例模块.示例页面',
+          '微应用示例.子应用页面',
+          '外部链接',
+          '权限管理',
+        ],
+        "region_permissions": []
+    },
+    "msg": "ok"
+},
+
+  // 获取统计数据
+  // 'GET /api/dashboard/stats': {
   //   success: true,
   //   data: {
-  //     id: 1001,
-  //     name: '张三',
-  //     email: 'zhangsan@example.com',
-  //     avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=homepage',
-  //     role: 'admin',
-  //     department: '技术部',
+  //     totalUsers: 12580,
+  //     activeUsers: 3420,
+  //     pendingTasks: 156,
+  //     completedTasks: 8934,
+  //     lastUpdated: new Date().toISOString(),
   //   },
   // },
 
-  // 获取统计数据
-  'GET /api/dashboard/stats': {
-    success: true,
-    data: {
-      totalUsers: 12580,
-      activeUsers: 3420,
-      pendingTasks: 156,
-      completedTasks: 8934,
-      lastUpdated: new Date().toISOString(),
-    },
-  },
-
   // 获取列表数据
-  'GET /api/items': {
-    success: true,
-    data: {
-      list: [
-        {
-          id: 1,
-          title: '待审核内容 A',
-          status: 'pending',
-          createdAt: '2025-12-27 10:00:00',
-        },
-        {
-          id: 2,
-          title: '待审核内容 B',
-          status: 'pending',
-          createdAt: '2025-12-27 09:30:00',
-        },
-        {
-          id: 3,
-          title: '已通过内容 C',
-          status: 'approved',
-          createdAt: '2025-12-26 15:00:00',
-        },
-        {
-          id: 4,
-          title: '已拒绝内容 D',
-          status: 'rejected',
-          createdAt: '2025-12-26 14:00:00',
-        },
-      ],
-      total: 4,
-      page: 1,
-      pageSize: 10,
-    },
-  },
+  // 'GET /api/items': {
+  //   success: true,
+  //   data: {
+  //     list: [
+  //       {
+  //         id: 1,
+  //         title: '待审核内容 A',
+  //         status: 'pending',
+  //         createdAt: '2025-12-27 10:00:00',
+  //       },
+  //       {
+  //         id: 2,
+  //         title: '待审核内容 B',
+  //         status: 'pending',
+  //         createdAt: '2025-12-27 09:30:00',
+  //       },
+  //       {
+  //         id: 3,
+  //         title: '已通过内容 C',
+  //         status: 'approved',
+  //         createdAt: '2025-12-26 15:00:00',
+  //       },
+  //       {
+  //         id: 4,
+  //         title: '已拒绝内容 D',
+  //         status: 'rejected',
+  //         createdAt: '2025-12-26 14:00:00',
+  //       },
+  //     ],
+  //     total: 4,
+  //     page: 1,
+  //     pageSize: 10,
+  //   },
+  // },
 
   // POST 请求示例
-  'POST /api/items/approve': (req: any, res: any) => {
-    const { id } = req.body || {};
-    res.json({
-      success: true,
-      message: `Item ${id} approved successfully`,
-      data: { id, status: 'approved' },
-    });
-  },
+  // 'POST /api/items/approve': (req: any, res: any) => {
+  //   const { id } = req.body || {};
+  //   res.json({
+  //     success: true,
+  //     message: `Item ${id} approved successfully`,
+  //     data: { id, status: 'approved' },
+  //   });
+  // },
 };

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

@@ -2,10 +2,120 @@
  * Mock 菜单数据
  * 用于开发环境测试
  *
- * 注意：实际数据存放在 menus.json 中
- * 修改菜单数据请编辑 menus.json 文件，不会触发服务器重启
+ * 菜单结构说明:
+ * - id: 菜单唯一标识
+ * - name: 菜单名称
+ * - type: 'page' | 'group' (page: 页面, group: 分组)
+ * - path: 路由路径 (type=page 时与 PAGES 中的 route 一致, group 类型为 null)
+ * - icon: 图标名称
+ * - enabled: 是否启用
+ * - sortOrder: 排序权重
+ * - pageId: 关联的页面 ID (通过 pageId 与 __MICO_PAGES__ 关联)
+ * - children: 子菜单数组
  */
-import mockMenusData from './menus.json';
 
-export const mockMenus = mockMenusData;
+import type { MenuItem } from '@/common/menu/types';
+
+/** Mock 菜单项 */
+type MockMenuItem = Omit<MenuItem, 'children'> & {
+  children: MockMenuItem[];
+};
+
+const mockMenus: MockMenuItem[] = [
+  {
+    id: 1,
+    name: '首页',
+    nameEn: 'Home',
+    nameKey: 'cs_web_menu_home',
+    type: 'page',
+    path: '/',
+    icon: 'Home',
+    enabled: true,
+    sortOrder: 0,
+    pageId: 1,
+    children: [],
+  },
+  {
+    id: 2,
+    name: '示例模块',
+    nameEn: 'Example Module',
+    nameKey: 'cs_web_menu_example_module',
+    type: 'group',
+    path: null,
+    icon: 'List',
+    enabled: true,
+    sortOrder: 1,
+    pageId: null,
+    children: [
+      {
+        id: 3,
+        name: '示例页面',
+        nameEn: 'Example Page',
+        nameKey: 'cs_web_menu_example_page',
+        type: 'page',
+        path: '/example/page',
+        icon: 'File',
+        enabled: true,
+        sortOrder: 1,
+        pageId: 45,
+        children: [],
+      },
+    ],
+  },
+  {
+    id: 5,
+    name: '微应用示例',
+    nameEn: 'Microapp Example',
+    nameKey: 'cs_web_menu_microapp_example',
+    type: 'group',
+    path: null,
+    icon: 'Apps',
+    enabled: true,
+    sortOrder: 2,
+    pageId: null,
+    children: [
+      {
+        id: 6,
+        name: '子应用页面',
+        nameEn: 'Subapp Page',
+        nameKey: 'cs_web_menu_subapp_page',
+        type: 'page',
+        path: '/subapp',
+        icon: 'Desktop',
+        enabled: true,
+        sortOrder: 1,
+        pageId: 55,
+        children: [],
+      },
+    ],
+  },
+  {
+    id: 7,
+    name: '外部链接',
+    nameEn: 'External Link',
+    nameKey: 'cs_web_menu_external_link',
+    type: 'link',
+    path: 'https://github.com',
+    icon: 'Link',
+    enabled: true,
+    sortOrder: 3,
+    pageId: null,
+    children: [],
+  },
+  {
+    id: 8,
+    name: '权限管理',
+    nameEn: 'Permission Management',
+    nameKey: 'cs_web_menu_permission_management',
+    type: 'page',
+    path: '/permission',
+    icon: 'Permission',
+    enabled: true,
+    sortOrder: 3,
+    pageId: null,
+    adminOnly: true,
+    children: [],
+  },
+];
+
 export default mockMenus;