generator-mico-cli 0.2.29 → 0.2.30

package/generators/micro-react/templates/apps/layout/src/hooks/useTenant.ts

@@ -0,0 +1,41 @@
+import { ETenantModel, type ITenantItem } from '@/common/auth/type';
+import { useModel } from '@umijs/max';
+
+export interface IUseTenantResult {
+  /** 是否多租户模式 */
+  isMultiTenant: boolean;
+  /** 当前租户模式原始值（1 单租户，2 多租户） */
+  tenantModel: number;
+  /** 用户所属租户列表 */
+  tenants: ITenantItem[];
+}
+
+/**
+ * 租户模式 Hook
+ *
+ * 从 initialState.currentUser 读取 tenant_model / tenant 字段，
+ * 对外暴露语义化的 isMultiTenant 标志和 tenants 列表，供业务组件直接使用。
+ *
+ * @example
+ * const { isMultiTenant, tenants } = useTenant();
+ * if (isMultiTenant) {
+ *   // 渲染租户选择器
+ * }
+ */
+export function useTenant(): IUseTenantResult {
+  const { initialState } = useModel('@@initialState');
+  const currentUser = initialState?.currentUser;
+
+  const tenantModel = currentUser?.tenant_model ?? ETenantModel.Single;
+  const tenants = currentUser?.tenant ?? [];
+  const isMultiTenant =
+    currentUser?.isMultiTenant ?? tenantModel === ETenantModel.Multi;
+
+  return {
+    isMultiTenant,
+    tenantModel,
+    tenants,
+  };
+}
+
+export default useTenant;

package/generators/micro-react/templates/apps/layout/src/layouts/components/header/index.tsx

@@ -1,4 +1,4 @@
-import { AvatarDropdown } from '@/components/RightContent';
+import { AvatarDropdown, TenantDropdown } from '@/components/RightContent';
 import { DEFAULT_NAME } from '@/constants';
 import { Layout, Space } from '@mico-platform/ui';
 import React from 'react';
@@ -28,6 +28,9 @@ const LayoutHeader: React.FC = () => {
             {theme === 'dark' ? <IconSunFill /> : <IconMoonFill />}
           </div> */}
 
+          {/* Tenant switcher (仅多租户模式可见) */}
+          <TenantDropdown />
+
           <span className="split-line" />
 
           {/* User info */}

package/generators/micro-react/templates/apps/layout/src/layouts/components/menu/index.tsx

@@ -140,19 +140,31 @@ const LayoutMenu: React.FC<LayoutMenuProps> = () => {
     collapsed,
     handleClickMenuItem,
     handleCollapsed,
+    handleMouseEnter,
+    handleMouseLeave,
     setOpenKeys,
   } = useMenuState({ menuItems });
 
   useEffect(() => {
-    document.documentElement.style.setProperty(
-      '--sider-width',
-      collapsed ? '48px' : '200px',
-    );
+    const layoutContent = document.querySelector('.layout-content');
+    if (layoutContent) {
+      (layoutContent as HTMLElement).style.setProperty(
+        '--sider-width',
+        collapsed ? '48px' : '200px',
+      );
+    }
+  }, [collapsed]);
 
+  useEffect(() => {
+    const sider = siderRef.current;
+    if (!sider) return;
+    sider.addEventListener('mouseenter', handleMouseEnter);
+    sider.addEventListener('mouseleave', handleMouseLeave);
     return () => {
-      document.documentElement.style.removeProperty('--sider-width');
+      sider.removeEventListener('mouseenter', handleMouseEnter);
+      sider.removeEventListener('mouseleave', handleMouseLeave);
     };
-  }, [collapsed]);
+  }, [handleMouseEnter, handleMouseLeave]);
 
   // 点击触发按钮图标
   const clickTriggerBtnIcon = collapsed

package/generators/micro-react/templates/apps/layout/src/locales/en-US.ts

@@ -38,6 +38,17 @@ export default {
   'cs_web_menu_permission_management': 'Permission Management',
   'cs_web_menu_group_management': 'Group Management',
 
+  // SSO auth failure modal
+  'sso.auth.failure.modal.title': 'Login Required',
+  'sso.auth.failure.modal.content':
+    'Auto login failed. Would you like to try logging in again?',
+  'sso.auth.failure.modal.ok': 'Re-login',
+  'sso.auth.failure.modal.cancel': 'Cancel',
+  sso_auth_failure_modal_title: 'Login Required',
+  sso_auth_failure_modal_content: 'Auto login failed. Would you like to try logging in again?',
+  sso_auth_failure_modal_ok: 'Re-login',
+  sso_auth_failure_modal_cancel: 'Cancel',
+
   // AvatarDropdown
   'avatar.language': 'Language',
   'avatar.language.zh_CN': 'Simplified Chinese',

package/generators/micro-react/templates/apps/layout/src/locales/zh-CN.ts

@@ -36,6 +36,16 @@ export default {
   'cs_web_menu_permission_management': '权限管理',
   'cs_web_menu_group_management': '小组管理',
 
+  // SSO 认证失败弹框
+  'sso.auth.failure.modal.title': '登录提示',
+  'sso.auth.failure.modal.content': '自动登录失败，是否重新尝试登录？',
+  'sso.auth.failure.modal.ok': '重新登录',
+  'sso.auth.failure.modal.cancel': '取消',
+  sso_auth_failure_modal_title: '登录提示',
+  sso_auth_failure_modal_content: '自动登录失败，是否重新尝试登录？',
+  sso_auth_failure_modal_ok: '重新登录',
+  sso_auth_failure_modal_cancel: '取消',
+
   // AvatarDropdown
   'avatar.language': '语言',
   'avatar.language.zh_CN': '简体中文',

package/generators/micro-react/templates/apps/layout/src/pages/Home/index.less

@@ -5,7 +5,34 @@
   color: @color-text-1;
 }
 
+.title {
+  margin: 0 0 12px;
+  font-size: 22px;
+  font-weight: 600;
+}
+
+.hint {
+  margin: 0 0 8px;
+  font-size: 14px;
+  line-height: 1.6;
+  color: @color-text-2;
+}
+
+.meta {
+  margin: 0;
+  font-size: 12px;
+  font-family: ui-monospace, monospace;
+  color: @color-text-3;
+}
+
 .demoCard {
   margin-top: 16px;
   max-width: 720px;
 }
+
+.tzDemoList {
+  width: 100%;
+  font-family: ui-monospace, monospace;
+  font-size: 12px;
+  line-height: 1.8;
+}

package/generators/micro-react/templates/apps/layout/src/pages/Home/index.tsx

@@ -1,29 +1,87 @@
 import PermissionFilter from '@/components/PermissionFilter';
+import { useLayoutIntl } from '@/common/intl';
 import { Alert, Button, Card, Space, Typography } from '@mico-platform/ui';
-import { useIntl } from '@umijs/max';
-import React from 'react';
+import type { FC } from 'react';
+import {
+  TIMEZONE,
+  formatTimestampToDateTime,
+  formatTimestampToDateTimeWithTimezone,
+  getShortcutDateRange,
+  parseDateInTimezone,
+  utcOffsetToTimeZoneStr,
+  utcOffsetToTimezone,
+} from '<%= packageScope %>/shared/timezone';
 import styles from './index.less';
 
 const { Paragraph, Text } = Typography;
 
+/**
+ * shared/timezone 示例：所有函数依赖 app.tsx 顶层的 `configureTimezone({ getTimezone })` 注入。
+ * 这里用一个固定时间戳做确定性展示；业务实际使用时通常传 `Date.now()` 或后端下发值。
+ */
+const DEMO_TIMESTAMP = 1730721621000;
+const DEMO_DATE_STR = '2025-11-04 16:20:21';
+
 /** 与 mock GET /user/info/ button_perms 中的示例 key 对齐 */
 const HOME_BUTTON_PERM_KEY = 'cs_web_btn_home_demo';
 
-const HomePage: React.FC = () => {
-  const intl = useIntl();
+/**
+ * 国际化示例：通过 `useLayoutIntl` 适配层统一调用。
+ * - 未配置 `__MICO_CONFIG__.commonIntl`：等同 `useIntl().formatMessage`，读本地 `locales/*`
+ * - 已配置：优先 <%= packageScope %>/common-intl 的 `i18n()`，无命中再 Umi
+ */
+const HomePage: FC = () => {
+  const { formatMessage, commonIntlEnabled, locale } = useLayoutIntl();
+
+  // shared/timezone 示例输出
+  const tzDemo = {
+    utcOffset8: utcOffsetToTimezone(8),
+    utcOffsetMinus5: utcOffsetToTimezone(-5),
+    iana8: utcOffsetToTimeZoneStr(8),
+    parsed: parseDateInTimezone(DEMO_DATE_STR).format('YYYY-MM-DD HH:mm:ss Z'),
+    thisWeek: (() => {
+      const [start, end] = getShortcutDateRange('week');
+      return `${start.format('MM-DD')} ~ ${end.format('MM-DD')}`;
+    })(),
+    formattedDemo: formatTimestampToDateTime(DEMO_TIMESTAMP),
+    formattedWithTz: formatTimestampToDateTimeWithTimezone(
+      DEMO_TIMESTAMP,
+      TIMEZONE['UTC+8'],
+    ),
+  };
 
   return (
     <div className={styles.container}>
-      <Typography.Title heading={4}>
-        {intl.formatMessage({ id: 'page.home.title' })}
-      </Typography.Title>
+      <h1 className={styles.title}>
+        {
+          formatMessage({
+            id: 'page.home.title',
+            defaultMessage: '首页',
+          })
+        }
+      </h1>
+      <p className={styles.hint}>
+        common-intl 优先样例：{formatMessage({
+          id: 'cs_web_workbench_userlist_chat',
+          defaultMessage: '看到该文案代表未启用 commonIntl 或中台无该 key',
+        })}
+      </p>
+      <p className={styles.hint}>
+        Umi 兜底样例：{formatMessage({
+          id: 'page.home.title',
+          defaultMessage: '看到该文案代表仅 Umi 或兜底路径',
+        })}
+      </p>
+      <p className={styles.meta}>
+        commonIntlEnabled: {String(commonIntlEnabled)} · locale: {locale}
+      </p>
 
       <Card
         className={styles.demoCard}
-        title={intl.formatMessage({ id: 'page.home.permissionDemo.title' })}
+        title={formatMessage({ id: 'page.home.permissionDemo.title' })}
       >
         <Paragraph type="secondary">
-          {intl.formatMessage(
+          {formatMessage(
             { id: 'page.home.permissionDemo.desc' },
             { key: HOME_BUTTON_PERM_KEY },
           )}
@@ -34,10 +92,10 @@ const HomePage: React.FC = () => {
           fallback={
             <Alert
               type="warning"
-              title={intl.formatMessage({
+              title={formatMessage({
                 id: 'page.home.permissionDemo.fallbackTitle',
               })}
-              content={intl.formatMessage(
+              content={formatMessage(
                 { id: 'page.home.permissionDemo.noPerm' },
                 { key: HOME_BUTTON_PERM_KEY },
               )}
@@ -46,7 +104,7 @@ const HomePage: React.FC = () => {
         >
           <Space>
             <Button type="primary" status="success">
-              {intl.formatMessage({ id: 'page.home.permissionDemo.hasPerm' })}
+              {formatMessage({ id: 'page.home.permissionDemo.hasPerm' })}
             </Button>
             <Text type="success">
               ({HOME_BUTTON_PERM_KEY})
@@ -54,6 +112,44 @@ const HomePage: React.FC = () => {
           </Space>
         </PermissionFilter>
       </Card>
+
+      <Card
+        className={styles.demoCard}
+        title={<>shared/timezone 示例</>}
+      >
+        <Paragraph type="secondary">
+          所有函数依赖 app.tsx 顶层的 <Text code>configureTimezone</Text>{' '}
+          注入；时区实时取自 <Text code>@/common/helpers#getTimezone</Text>。
+        </Paragraph>
+
+        <Space direction="vertical" size="mini" className={styles.tzDemoList}>
+          <Text>
+            <Text bold>utcOffsetToTimezone(8):</Text> {tzDemo.utcOffset8}
+          </Text>
+          <Text>
+            <Text bold>utcOffsetToTimezone(-5):</Text> {tzDemo.utcOffsetMinus5}
+          </Text>
+          <Text>
+            <Text bold>utcOffsetToTimeZoneStr(8):</Text> {tzDemo.iana8}
+          </Text>
+          <Text>
+            <Text bold>parseDateInTimezone(&quot;{DEMO_DATE_STR}&quot;):</Text>{' '}
+            {tzDemo.parsed}
+          </Text>
+          <Text>
+            <Text bold>getShortcutDateRange(&quot;week&quot;):</Text>{' '}
+            {tzDemo.thisWeek}
+          </Text>
+          <Text>
+            <Text bold>formatTimestampToDateTime(demo):</Text>{' '}
+            {String(tzDemo.formattedDemo)}
+          </Text>
+          <Text>
+            <Text bold>formatTimestampToDateTimeWithTimezone(demo, UTC+8):</Text>{' '}
+            {String(tzDemo.formattedWithTz)}
+          </Text>
+        </Space>
+      </Card>
     </div>
   );
 };

package/generators/micro-react/templates/apps/layout/src/requestErrorConfig.ts

@@ -131,8 +131,9 @@ export const errorConfig: RequestConfig = {
 
           // 根据 HTTP 状态码区分鉴权错误和业务错误
           if (status === 401 || status === 403) {
+            const notifyInfo = `鉴权失败，状态码：${status}，可能登录态过期，请重新登录`;
             // 鉴权失败
-            notifyHostError(createAuthError(errorMessage, status, 'http'));
+            notifyHostError(createAuthError(notifyInfo, status, 'http'));
           } else {
             // 其他业务错误
             notifyHostError(

package/generators/micro-react/templates/apps/layout/src/services/user.ts

@@ -1,4 +1,6 @@
+import { getStoredTenantCode, setStoredTenantCode } from '@/common/auth/tenant';
 import type { IUserInfo, IUserInfoApiData } from '@/common/auth/type';
+import { ETenantModel } from '@/common/auth/type';
 import { getCurrentLocale, type SupportedLocale } from '@/common/locale';
 import { request } from '@/common/request';
 
@@ -22,6 +24,7 @@ const USER_INFO_API = '/api/user/info/';
 
 function normalizeUserInfo(data: IUserInfoApiData): IUserInfo {
   const name = data.name || '';
+  const tenant_model = data.tenant_model ?? ETenantModel.Single;
   return {
     ...data,
     app_perms: Array.isArray(data.app_perms) ? data.app_perms : [],
@@ -29,6 +32,9 @@ function normalizeUserInfo(data: IUserInfoApiData): IUserInfo {
     menu_perms: Array.isArray(data.menu_perms) ? data.menu_perms : [],
     button_perms: Array.isArray(data.button_perms) ? data.button_perms : [],
     is_superuser: Boolean(data.is_superuser),
+    tenant_model,
+    tenant: Array.isArray(data.tenant) ? data.tenant : [],
+    isMultiTenant: tenant_model === ETenantModel.Multi,
     user_name: name,
     username: name || data.email || '',
   };
@@ -40,20 +46,65 @@ export interface IUserInfoResponse {
   msg: string;
 }
 
+export interface ISimpleUser {
+  id: number;
+  email: string;
+  is_superuser: number;
+  is_active: number;
+  user_name: string;
+}
+
+export interface IAllUsersResponse {
+  code: number;
+  msg: string;
+  data: {
+    count: number;
+    results: ISimpleUser[];
+  };
+}
+
+export async function fetchAllUsers(params?: {
+  email?: string;
+}): Promise<IAllUsersResponse> {
+  return request<IAllUsersResponse>('/api/user/all/', {
+    method: 'GET',
+    skipProxy: true,
+    params,
+  });
+}
+
 /**
  * 获取用户信息
  * @returns 用户信息对象
  * @throws 当接口返回非 200 code 时抛出错误
  */
-export async function fetchUserInfo(): Promise<IUserInfo> {
+export async function fetchUserInfo(params?: {
+  lang?: number;
+  tenant_code?: string;
+}): Promise<IUserInfo> {
   const url = USER_INFO_API;
 
+  // 若未显式指定 tenant_code，则自动注入 localStorage 中的当前租户
+  // 单租户或首次进入时无值，后端会取默认租户并通过 current_tenant 回包
+  const tenantCode = params?.tenant_code ?? getStoredTenantCode() ?? undefined;
+  const requestParams = {
+    ...params,
+    ...(tenantCode ? { tenant_code: tenantCode } : {}),
+  };
+
   const response = await request<IUserInfoResponse>(url, {
     method: 'GET',
     skipProxy: true,
+    params: requestParams,
   });
   if (response.code === 200 && response.data) {
-    return normalizeUserInfo(response.data);
+    const userInfo = normalizeUserInfo(response.data);
+    // 回写当前租户到本地存储，保证后续请求与 UI 展示一致
+    const currentTenantCode = userInfo.current_tenant;
+    if (currentTenantCode) {
+      setStoredTenantCode(currentTenantCode);
+    }
+    return userInfo;
   }
   throw new Error(response.msg || '获取用户信息失败');
 }

package/generators/micro-react/templates/apps/layout/typings.d.ts

@@ -1 +1,17 @@
 import '@umijs/max/typings';
+
+/**
+ * Window 上挂载的构建信息
+ */
+declare global {
+  interface Window {
+    __MICO_BUILD__?: {
+      branchOrTag?: string;
+      gitCommit?: string;
+      version?: string;
+      buildTime?: string;
+      /** Jenkins 等 CI 的构建号 */
+      buildNumber?: string;
+    };
+  }
+}

package/generators/micro-react/templates/docs/package-shared.md

@@ -0,0 +1,189 @@
+# shared 共享包使用说明
+
+> 创建时间：2026-04-23
+
+## 功能概述
+
+`<%= packageScope %>/shared` 是平台跨应用（主应用 + qiankun 子应用）复用的业务服务层骨架，当前对外暴露两个独立模块：
+
+- **`./services`**
+  - `configureRequest` / `getRequest`：统一 request 注入器
+  - `common`：通用类型（分页、响应包装）与 `isSuccess`
+- **`./timezone`**
+  - `TIMEZONE` / `TIMEZONE_HASH` / `TTimezone`：UTC 与 IANA 映射表
+  - `utcOffsetToTimezone` / `utcOffsetToTimeZoneStr`：纯转换
+  - `configureTimezone({ getTimezone })`：注入「当前 IANA 时区」获取器
+  - `parseDateInTimezone` / `getShortcutDateRange` / `formatTimestampToDateTime` / `formatTimestampToDateTimeWithTimezone`
+
+业务接口、业务常量、业务工具等由各项目按需新增，本包只定义骨架与扩展规范。
+
+## 包结构
+
+```
+packages/shared/
+├── package.json        # 仅导出 ./services 与 ./timezone
+├── tsconfig.json
+├── README.md
+├── services/
+│   ├── index.ts        # services 域唯一对外 barrel
+│   ├── request.ts      # request 注入器
+│   └── common/
+│       └── index.ts    # 通用类型与工具
+└── timezone/
+    └── index.ts        # 时区工具 + 时区获取器
+```
+
+## 导出约定
+
+| 约定 | 说明 |
+|---|---|
+| 一目录一入口 | 每个根目录（`services/`、`timezone/` 等）在 `exports` 中只对应一条入口 |
+| 无根入口 | 不导出 `.`、不设置 `main`/`types`，消费方**不能** `import from '<%= packageScope %>/shared'` |
+| 禁止深层路径 | 不允许 `./services/user`、`./services/common`、`./timezone/sub` 等子路径 |
+| 同级扩展 | 新增共享模块时新建与 `services/`、`timezone/` 同级的目录 |
+
+## 消费方使用
+
+### 1. 初始化（必须，仅一次）
+
+主应用与子应用都在 `app.tsx` 顶层注入本应用的 `request`，模板已默认接好：
+
+```ts
+// apps/layout/src/app.tsx
+import { configureRequest } from '<%= packageScope %>/shared/services';
+import { request as commonRequest } from './common/request';
+
+configureRequest(commonRequest);
+```
+
+```ts
+// apps/<subapp>/src/app.tsx
+import { configureRequest } from '<%= packageScope %>/shared/services';
+import { request } from './common/request';
+
+// 子应用 request 内部已自动桥接主应用 / 独立 umi，
+// 顶层注入即可，无需在 mount 里反复设置
+configureRequest(request);
+```
+
+> 子应用 `./common/request` 的实现会在 qiankun 模式下走 `getMainAppRequest()`，独立运行时走 `umiRequest`，因此顶层注入的是同一个稳定函数引用，运行期才决定具体走哪条链路。
+
+未初始化即调用 `getRequest()` 会抛出 `[shared/services] request 未初始化，请先调用 configureRequest()`，提示检查初始化时序。
+
+### 2. 业务代码调用
+
+```ts
+import {
+  getRequest,
+  isSuccess,
+  type IPagedResponse,
+} from '<%= packageScope %>/shared/services';
+
+async function fetchUsers(): Promise<IPagedResponse<IUser>> {
+  const res = await getRequest()<{ code: number; data: IPagedResponse<IUser> }>(
+    '/api/user/',
+    { method: 'GET' },
+  );
+  if (!isSuccess(res)) throw new Error('fetch users failed');
+  return res.data;
+}
+```
+
+### 3. 时区模块初始化
+
+`./timezone` 不内置时区存储，由消费方注入「当前 IANA 时区获取器」（通常代理到主应用的时区管理模块）：
+
+```ts
+// apps/layout/src/app.tsx
+import { configureTimezone } from '<%= packageScope %>/shared/timezone';
+import { getTimezone } from '@/common/helpers';
+
+configureTimezone({ getTimezone });
+```
+
+依赖前置：本模块以 `peerDependencies` 声明 dayjs。**消费方需在入口扩展三个插件**（`utc / timezone / customParseFormat`）：
+
+```ts
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+dayjs.extend(utc);
+dayjs.extend(timezone);
+dayjs.extend(customParseFormat);
+```
+
+> 模板的 `apps/layout/src/common/helpers.ts` 已扩展 `utc / timezone`，仅需补 `customParseFormat`。
+
+业务调用示例：
+
+```ts
+import {
+  TIMEZONE,
+  parseDateInTimezone,
+  getShortcutDateRange,
+  formatTimestampToDateTime,
+  formatTimestampToDateTimeWithTimezone,
+} from '<%= packageScope %>/shared/timezone';
+
+parseDateInTimezone('2025-11-04 16:20:21');
+const [start, end] = getShortcutDateRange('week');
+formatTimestampToDateTime(Date.now());
+formatTimestampToDateTimeWithTimezone(Date.now(), TIMEZONE['UTC+8']);
+```
+
+## 扩展规范
+
+### 场景 A：新增业务接口（归属 services 域）
+
+1. 新建子目录 `services/<module>/`
+2. 在其中创建唯一对外入口 `index.ts`；如需细分，新增 `type.ts` 等文件但只由 `index.ts` re-export
+3. 在 `services/<module>/index.ts` 中：
+   - 用 `export type {...}` 对外暴露类型
+   - 用 `getRequest()` 调后端，导出业务函数
+4. 在 `services/index.ts` 追加一行聚合：`export * from './<module>';`
+5. **不要**改动 `package.json` 的 `exports`
+
+### 场景 B：新增非 services 共享模块（如 constants / utils）
+
+当一类共享内容明显**不属于** services 域，新建与 `services/` 同级的目录，作为全新独立对外模块：
+
+1. 在包根新建目录，例如 `constants/`
+2. 创建唯一对外入口 `constants/index.ts`
+3. 在 `package.json` 的 `exports` 中追加且仅追加一条：
+
+   ```json
+   "./constants": "./constants/index.ts"
+   ```
+
+4. 在 `package.json` 的 `files` 数组追加目录名 `"constants"`
+5. **禁止**新增任何 `./constants/<sub>` 深层路径
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+|---|---|---|
+| 包定位 | 仅骨架，无业务实现 | 模板场景下各项目业务差异大，留空可避免强耦合业务假设 |
+| request 注入器 | 运行时注入而非直接依赖某 request 包 | 主应用 / 子应用在 qiankun 模式下共享同一请求实例，注入模式可一次定义、多处复用 |
+| 仅 `./services` 入口 | 不开放 `.` 根入口与深层路径 | 强约束消费方统一从命名空间入口导入，内部重构不影响外部契约 |
+| 一目录一模块 | 同级目录都只暴露 `index.ts` | 保持"外部可见面 = exports 列表"，依赖图清晰，重构自由度高 |
+| 保留 `common` 内联于 services | 不独立成 `common/` 同级目录 | 当前只有分页和响应结果等通用类型，体量小；后续若通用工具增多再拆 |
+
+## 注意事项
+
+- `configureRequest` 必须在任何业务调用**之前**执行。主应用与子应用模板均在 `app.tsx` 顶层注入；子应用注入的是本地的 `./common/request` 函数（运行期由它自动桥接主应用 / 独立 umi），所以无需在 `mount` 里重复注入 `props.request`。
+- `RequestFn` 签名为 `<T = unknown>(url: string, options?: Record<string, unknown>) => Promise<T>`，各应用的 request 实例需兼容这一签名。
+- 新增子目录时，如果消费方只依赖类型，也要通过 `services/index.ts` re-export，不要引导外部直接 import 内部 `type.ts`。
+- 若后续需要支持多实例 request（例如不同域名的后端），可以在本包扩展成 `configureRequest(name, req)` + `getRequest(name)` 的多命名空间形式，当前版本按单实例设计。
+
+## 相关文件
+
+| 文件 | 说明 |
+|---|---|
+| [packages/shared/package.json](../packages/shared/package.json) | 导出声明，约束外部可见面 |
+| [packages/shared/services/index.ts](../packages/shared/services/index.ts) | 对外 barrel 与扩展规范注释 |
+| [packages/shared/services/request.ts](../packages/shared/services/request.ts) | request 注入器实现 |
+| [packages/shared/services/common/index.ts](../packages/shared/services/common/index.ts) | 通用类型与 `isSuccess` |
+| [packages/shared/timezone/index.ts](../packages/shared/timezone/index.ts) | 时区常量、纯转换、注入器与格式化函数 |
+| [packages/shared/README.md](../packages/shared/README.md) | 包内使用文档 |
+| [apps/layout/src/common/helpers.ts](../apps/layout/src/common/helpers.ts) | 主应用时区管理实现（被 `configureTimezone` 注入） |

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

@@ -32,7 +32,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
-    "@common-web/sentry": "^0.0.4",
+    "@common-web/sentry": "0.0.7",
     "@sentry/webpack-plugin": "^4.9.1",
 		"@typescript-eslint/eslint-plugin": "^8.54.0",
 		"@typescript-eslint/parser": "^8.54.0",

package/generators/micro-react/templates/packages/common-intl/README.md

@@ -112,13 +112,15 @@ const intl = addIntl({
 export default intl;
 ```
 
+> **注意：** 子应用使用独立 tag 模式时，必须移除子应用 config 文件中 `externals` 里的 `'<%= packageScope %>/common-intl': 'CommonIntl'` 配置，确保子应用打包自己的 `@common-web/common-intl` 副本，避免与主应用共享模块级状态。
+
 > `initIntl` 只管身份配置（tag、app_name、存储），`fetchMultilingualData` 管运行时依赖（请求实例、消息提示、语言、API 地址）。`i18n` 函数与 `tag` 绑定，不同 tag 的翻译数据互相隔离。
 
 ## 常见问题
 
 ### Q: 子应用需要调用 initIntl 吗？
 
-默认不需要。主应用负责初始化和获取文案，子应用直接使用共享的 `intl` 对象。仅当子应用需要独立 tag 时才自行调用。
+默认不需要。主应用负责初始化和获取文案，子应用直接使用共享的 `intl` 对象。**仅当子应用需要与主应用不同的 tag** 时，再在子应用内**额外**调用一次 `initIntl`（可从本包 `import { initIntl } from '<%= packageScope %>/common-intl'`），并自行 `render` 拉取。
 
 ### Q: 翻译数据什么时候加载？