@yarch/create-admin 0.1.0 → 0.2.1

package/templates/sub-semi/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "{{description}}",
+  "scripts": {
+    "dev": "vite",
+    "dev:micro": "vite --mode integrated",
+    "build": "tsc --noEmit && vite build",
+    "build:micro": "tsc --noEmit && vite build --mode integrated",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@yarch/contract": "{{yarchContractDep}}",
+    "@yarch/react": "{{yarchReactDep}}",
+    "@douyinfe/semi-ui": "^2"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "react-router-dom": "^7"
+  },
+  "devDependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "react-router-dom": "^7",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4",
+    "typescript": "^5.6",
+    "vite": "^6"
+  }
+}

package/templates/sub-semi/src/app/root.tsx

@@ -0,0 +1,23 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import type { SubAppMountProps } from "@yarch/contract";
+import SubRouter from "./router";
+import { setPopupContainer } from "../ui/popup";
+
+/**
+ * mount 工厂（五-1）：容器与路由 base 由供给层注入（四-2——子应用不感知完整 URL）；
+ * 返回清理函数供 unmount 成对调用（五-2）。
+ */
+export function mountApp(props: SubAppMountProps): () => void {
+  setPopupContainer(props.container); // 六-3：弹层挂载容器指向本应用容器
+  const root = createRoot(props.container);
+  root.render(
+    <StrictMode>
+      <BrowserRouter basename={props.base}>
+        <SubRouter />
+      </BrowserRouter>
+    </StrictMode>
+  );
+  return () => root.unmount();
+}

package/templates/sub-semi/src/app/router.tsx

@@ -0,0 +1,26 @@
+import { useEffect } from "react";
+import { Routes, Route, useNavigate } from "react-router-dom";
+import { supply } from "@supply";
+import SubLayout from "../layouts/sub-layout";
+import Invoices from "../pages/invoices";
+
+function NavigatorSetup() {
+  const navigate = useNavigate();
+  useEffect(() => { supply.setupAppNavigator(navigate); }, [navigate]); // 独立=注册；集成=noop（十-2）
+  return null;
+}
+
+export default function SubRouter() {
+  return (
+    <>
+      <NavigatorSetup />
+      <Routes>
+        <Route path="/" element={<SubLayout />}>
+          <Route index element={<Invoices />} />
+          {/* 基座 manifest 菜单 path="/invoices" 指向的内部路由（四-2：子应用自治路由表） */}
+          <Route path="invoices" element={<Invoices />} />
+        </Route>
+      </Routes>
+    </>
+  );
+}

package/templates/sub-semi/src/events.ts

@@ -0,0 +1,4 @@
+import { defineAppEvents } from "@yarch/contract";
+
+/** 事件上行/广播封装（九-1/九-3）：事件名自动 `{应用名}:` 前缀，业务代码只写「动词-名词」 */
+export const appEvents = defineAppEvents("{{appName}}");

package/templates/sub-semi/src/features/invoices/api.ts

@@ -0,0 +1,19 @@
+import { createClient, type PageData } from "@yarch/contract";
+import { supply } from "@supply";
+import type { Invoice } from "../../types";
+
+/**
+ * 域内 API（十-1/十-3）：token 经供给层取（独立=mock，集成=基座下发函数），
+ * 401 时只抛 ApiError——跳登录唯一归基座（十-2），本应用不做任何跳转。
+ */
+const api = createClient({
+  baseUrl: "/api/v1",
+  getHeaders: (): Record<string, string> => {
+    const token = supply.getAccessToken();
+    return token ? { Authorization: `Bearer ${token}` } : {};
+  },
+});
+
+export function fetchInvoices(page = 1, pageSize = 20): Promise<PageData<Invoice>> {
+  return api.get<PageData<Invoice>>(`/invoices?page=${page}&pageSize=${pageSize}`);
+}

package/templates/sub-semi/src/features/invoices/hooks/use-invoices.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from "react";
+import { fetchInvoices } from "../api";
+import type { Invoice } from "../../../types";
+
+export function useInvoices() {
+  const [invoices, setInvoices] = useState<Invoice[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let alive = true; // 异步回写防卸载后 setState（五-2 清理纪律的邻接面）
+    fetchInvoices()
+      .then((page) => { if (alive) { setInvoices(page.list); setLoading(false); } })
+      .catch(() => { if (alive) setLoading(false); }); // 十-2：错误只上抛不跳转，列表态由页面兜底
+    return () => { alive = false; };
+  }, []);
+
+  return { invoices, loading };
+}

package/templates/sub-semi/src/layouts/sub-layout.tsx

@@ -0,0 +1,12 @@
+import { Typography } from "@douyinfe/semi-ui";
+import { Outlet } from "react-router-dom";
+
+/** 域内布局（一-1：子应用只做域内页面；外壳/菜单/登录态全部归基座，三-2） */
+export default function SubLayout() {
+  return (
+    <div style={{ minHeight: "100vh" }}>
+      <Typography.Title heading={5}>{{appName}}</Typography.Title>
+      <Outlet />
+    </div>
+  );
+}

package/templates/sub-semi/src/main.tsx

@@ -0,0 +1,28 @@
+import { supply } from "@supply";
+import { createRoot } from "react-dom/client";
+import { semiGlobal } from "@douyinfe/semi-ui";
+// React 19 下 Semi 命令式渲染（Toast/Notification 等）须显式注入 createRoot，否则弹层静默不渲染
+semiGlobal.config.createRoot = createRoot;
+import { mountApp } from "./app/root";
+
+/**
+ * 双模式唯一入口（十一-2）：挂载参数全部来自供给层，业务代码零分支。
+ * 独立模式：vite dev 直开浏览器；集成模式：被基座经 micro-app 加载，supply 已切 integrated 实现。
+ */
+let unmount: (() => void) | null = null;
+
+function mount() {
+  const props = supply.getMountProps();
+  unmount = mountApp(props);
+}
+
+function unmountApp() {
+  unmount?.(); // 五-2：unmount 彻底清理（定时器/监听/动态 DOM——root.unmount 卸掉整棵树）
+  unmount = null;
+}
+
+mount();
+supply.onUnmount(unmountApp);          // 五-2：卸载清理成对
+supply.onRemount(() => {               // 五-3：mount/unmount 幂等——来回切换不崩不重挂
+  if (unmount === null) mount();
+});

package/templates/sub-semi/src/pages/invoices.tsx

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import { Button, Modal, Table, Typography } from "@douyinfe/semi-ui";
+import { useInvoices } from "../features/invoices/hooks/use-invoices";
+import { appEvents } from "../events";
+import { getPopupContainer } from "../ui/popup";
+
+/**
+ * 域内示例页：列表 + 导出。
+ * 导出完成后事件上行（九-1/九-3）：appEvents.emit("export-done", …) → 基座 Toast；
+ * Modal 指定挂载容器为本应用容器（六-3）。
+ */
+export default function Invoices() {
+  const { invoices, loading } = useInvoices();
+  const [open, setOpen] = useState(false);
+
+  const columns = [
+    { title: "账单号", dataIndex: "id" },
+    { title: "金额", dataIndex: "amount" },
+    { title: "状态", dataIndex: "status" },
+  ];
+
+  return (
+    <div>
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 12 }}>
+        <h3>账单列表</h3>
+        <Button theme="solid" onClick={() => setOpen(true)}>导出</Button>
+      </div>
+      <Table
+        columns={columns}
+        dataSource={invoices}
+        loading={loading}
+        pagination={{ pageSize: 10 }}
+        empty={<Typography.Text type="tertiary">暂无数据（后端未起或未登录——独立模式为 mock token）</Typography.Text>}
+      />
+      <Modal
+        title="确认导出"
+        visible={open}
+        getPopupContainer={getPopupContainer}
+        onOk={() => {
+          setOpen(false);
+          appEvents.emit("export-done", { count: invoices.length }); // 九-3：{应用名}:export-done
+        }}
+        onCancel={() => setOpen(false)}
+      >
+        将导出 {invoices.length} 条账单，完成后基座将收到事件上行通知。
+      </Modal>
+    </div>
+  );
+}

package/templates/sub-semi/src/supply/integrated.ts

@@ -0,0 +1,48 @@
+/**
+ * 集成运行供给（十一-2）：登录态/主题/token 全部由基座经 __YARCH_SUPPLY__ 下发（五-5/十-1）；
+ * 路由 base = 应用名前缀（四-1/四-2 由基座口径注入，本档直接取同值）。
+ * 仅存在于集成构建（vite --mode integrated alias 到此）。
+ */
+import type { SubAppMountProps, SubAppUser } from "@yarch/contract";
+import type { Supply } from "./types";
+
+interface BaseSupply {
+  getToken(): string | null;
+  user: SubAppUser | null;
+  themeToken?: Record<string, string>;
+}
+
+function baseSupply(): BaseSupply {
+  const s = (globalThis as Record<string, unknown>).__YARCH_SUPPLY__ as BaseSupply | undefined;
+  if (!s) {
+    throw new Error("基座未注册 __YARCH_SUPPLY__（五-5 props 下行）——集成构建必须在基座内运行");
+  }
+  return s;
+}
+
+export const supply: Supply = {
+  getMountProps(): SubAppMountProps {
+    const s = baseSupply();
+    return {
+      container: document.getElementById("root")!, // micro-app 沙箱内自取（五-1 形式由模板档固化）
+      base: "/{{appName}}", // 四-1：路由前缀 = 应用名
+      user: s.user,
+      getToken: () => s.getToken(),
+      themeToken: s.themeToken,
+    };
+  },
+  getAccessToken() {
+    return baseSupply().getToken();
+  },
+  setupAppNavigator() {
+    // 十-2：导航端口与 401 跳转唯一归基座（contract 单例已由基座注册），子应用不注册
+  },
+  onUnmount(cb) {
+    window.addEventListener("unmount", cb); // micro-app 卸载事件（五-2：定时器/监听/DOM 彻底清理）
+    return () => window.removeEventListener("unmount", cb);
+  },
+  onRemount(cb) {
+    window.addEventListener("mounted", cb); // 五-3：脚本缓存复用下的重挂渲染
+    return () => window.removeEventListener("mounted", cb);
+  },
+};

package/templates/sub-semi/src/supply/shims/contract.ts

@@ -0,0 +1,25 @@
+// @yarch/contract shim（集成构建专用）：contract 运行时单例由基座共享（八-1）——
+// 两份实例 = 两个 ApiError 类，instanceof 全失效；本 shim 保证子应用取到的就是基座那份。
+const ns = (globalThis as Record<string, any>).__YARCH_CONTRACT__;
+if (!ns) throw new Error("集成构建须运行在基座内：__YARCH_CONTRACT__ 未注册（八-1 contract 单例由基座共享）");
+
+export const CODE_SUCCESS = ns.CODE_SUCCESS;
+export const errorCodes = ns.errorCodes;
+export const TRACE_ID_HEADER = ns.TRACE_ID_HEADER;
+export const newTraceId = ns.newTraceId;
+export const ApiError = ns.ApiError;
+export const unwrap = ns.unwrap;
+export const unwrapAllowNull = ns.unwrapAllowNull;
+export const setNavigator = ns.setNavigator;
+export const navigateTo = ns.navigateTo;
+export const navigateToLogin = ns.navigateToLogin;
+export const createClient = ns.createClient;
+export const createAppEventBus = ns.createAppEventBus;
+export const getAppEventBus = ns.getAppEventBus;
+export const defineAppEvents = ns.defineAppEvents;
+export const assertAppEventName = ns.assertAppEventName;
+export const createAppStorage = ns.createAppStorage;
+export const subAppRoutePrefix = ns.subAppRoutePrefix;
+export const SHARED_CONTRACT_KEY = ns.SHARED_CONTRACT_KEY;
+export const setSharedContract = ns.setSharedContract;
+export const getSharedContract = ns.getSharedContract;

package/templates/sub-semi/src/supply/standalone.ts

@@ -0,0 +1,38 @@
+/**
+ * 独立运行供给（十一-1/十-6）：登录态 mock/开发态注入，路由 base 从环境取同值（四-2）。
+ * 本模块（含 mock 外壳）不进集成产物——集成构建经 vite alias 指向 integrated.ts。
+ */
+import { createAppStorage, type SubAppMountProps } from "@yarch/contract";
+import { setupReactNavigator } from "@yarch/react";
+import type { Supply } from "./types";
+
+const storage = createAppStorage("{{appName}}"); // 二-2：独立模式 storage 同样带 {应用名}: 前缀，无例外
+if (storage.get<string>("mock-token") === null) {
+  storage.set("mock-token", "standalone-dev"); // 十-6：独立模式登录态以开发态注入
+}
+
+// vite base = "/{{appName}}/"，与集成模式基座注入的路由前缀同值（四-2 同值口径）
+const baseURL = import.meta.env.BASE_URL.replace(/\/$/, "");
+
+export const supply: Supply = {
+  getMountProps(): SubAppMountProps {
+    return {
+      container: document.getElementById("root")!,
+      base: baseURL,
+      user: { id: "dev", name: "独立模式" },
+      getToken: () => storage.get<string>("mock-token"),
+    };
+  },
+  getAccessToken() {
+    return storage.get<string>("mock-token");
+  },
+  setupAppNavigator(navigate) {
+    setupReactNavigator(navigate); // 独立模式由本应用路由实现导航端口（401→/login）
+  },
+  onUnmount() {
+    return () => {}; // 独立模式无卸载方
+  },
+  onRemount() {
+    return () => {};
+  },
+};

package/templates/sub-semi/src/supply/types.ts

@@ -0,0 +1,18 @@
+import type { SubAppMountProps } from "@yarch/contract";
+
+/**
+ * 环境供给层端口（micro-frontend.md 十一-2）：独立/集成双模式差异的唯一容身处——
+ * 业务代码只消费本接口，出现 `if (isMicro)` 分支即设计缺陷。
+ */
+export interface Supply {
+  /** 挂载参数（五-5 最小集：容器/base/用户上下文/取 token/主题 token） */
+  getMountProps(): SubAppMountProps;
+  /** 取 token（十-1：独立=开发态 mock 注入；集成=基座下发函数引用） */
+  getAccessToken(): string | null;
+  /** 导航端口注册（四-3/十-2：独立=注册本应用路由跳转；集成=noop——导航权与 401 跳转唯一归基座） */
+  setupAppNavigator(navigate: (path: string) => void): void;
+  /** 卸载清理钩（五-2：micro-app unmount 事件触发；返回取消函数，七-4 成对） */
+  onUnmount(cb: () => void): () => void;
+  /** 重新挂载钩（五-3 mount/unmount 幂等：micro-app 复用脚本缓存重挂时重渲染） */
+  onRemount(cb: () => void): () => void;
+}

package/templates/sub-semi/src/types/index.ts

@@ -0,0 +1,6 @@
+/** 域内类型（billing 域示例；路径段 kebab-case，四-4） */
+export interface Invoice {
+  id: string;
+  amount: number;
+  status: "open" | "paid";
+}

package/templates/sub-semi/src/ui/popup.ts

@@ -0,0 +1,13 @@
+/**
+ * 弹层容器（六-3）：Modal/Select/Tooltip 等默认挂 body 的组件必须指定挂载容器为本应用容器，
+ * 否则微前端沙箱下弹层逃逸到基座 DOM。页面用法：`<Modal getPopupContainer={getPopupContainer}>`。
+ */
+let container: HTMLElement | null = null;
+
+export function setPopupContainer(el: HTMLElement): void {
+  container = el;
+}
+
+export function getPopupContainer(): HTMLElement {
+  return container ?? document.body;
+}

package/templates/sub-semi/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/sub-semi/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@supply": ["./src/supply/standalone.ts"]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/sub-semi/vite.config.ts

@@ -0,0 +1,96 @@
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react";
+import { defineConfig, type Plugin } from "vite";
+
+/**
+ * 双构建模式（十一-1/十一-2）：
+ *   独立（默认）  = 全量自足，pnpm dev / build；
+ *   集成（integrated）= 供给层切 __YARCH_SUPPLY__ 实现；react 系与 @yarch/contract
+ *                      由基座经 window 全局提供（八-1/八-2）——集成产物 dist-micro/ 中框架
+ *                      与 contract 体积消失（十三表八-1/八-2 机检的构建口径）。
+ * 集成模式不挂 plugin-react（fast-refresh preamble 与 micro-app 沙箱互扰；esbuild 按 tsconfig 自动转 JSX）。
+ */
+
+/**
+ * 框架运行时 shim（集成构建专用，八-2）：构建期从真实安装的包内省全部导出名，
+ * 生成 `export const X = globalThis.__YARCH_REACT__["<pkg>"].X` 虚拟模块——
+ * 覆盖面与所装 react 系版本逐名全等（三方库如 semi-ui 的任意具名 import 均可解析）。
+ * 类型检查不受影响（tsconfig 仍指向真实包类型）。
+ */
+const RUNTIME_SPECS: Record<string, string> = {
+  // import 说明符 → 基座 __YARCH_REACT__ 下注册名（见 base-semi src/micro/shared.ts）
+  react: "react",
+  "react-dom": "react-dom",
+  "react-dom/client": "react-dom/client",
+  "react/jsx-runtime": "react/jsx-runtime",
+  "react/jsx-dev-runtime": "react/jsx-dev-runtime",
+  "react-router": "react-router",
+  "react-router-dom": "react-router-dom",
+};
+const VIRTUAL_PREFIX = "\0yarch-runtime-shim:";
+
+function yarchRuntimeShims(): Plugin {
+  return {
+    name: "yarch-runtime-shims",
+    // 解析不走插件 resolveId（bare import 在 alias 之后已被 vite 内置解析器接管）——
+    // 由下方 resolve.alias 把说明符改写为虚拟 id，本插件只负责 load 生成完整导出面。
+    async load(id) {
+      if (!id.startsWith(VIRTUAL_PREFIX)) return null;
+      const spec = id.slice(VIRTUAL_PREFIX.length);
+      const globalName = RUNTIME_SPECS[spec];
+      const exported = await import(spec);
+      // CJS 互操作会泄漏 "module.exports" 等非标识符键（cjs-module-lexer 伪影），只保留合法导出名
+      const names = Object.keys(exported).filter((n) => n !== "default" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(n));
+      const lines = [
+        `const ns = (globalThis).__YARCH_REACT__?.[${JSON.stringify(globalName)}];`,
+        `if (!ns) throw new Error(${JSON.stringify(
+          `集成构建须运行在基座内：__YARCH_REACT__[${globalName}] 未注册（八-2 框架运行时由基座统一提供）`,
+        )});`,
+        ...names.map((n) => `export const ${n} = ns[${JSON.stringify(n)}];`),
+        ...("default" in exported ? ["export default ns.default;"] : []),
+      ];
+      return lines.join("\n");
+    },
+  };
+}
+
+const contractShim = fileURLToPath(new URL("./src/supply/shims/contract.ts", import.meta.url));
+
+export default defineConfig(({ mode }) => ({
+  plugins: mode === "integrated" ? [yarchRuntimeShims()] : [react()],
+  // 十二-4：产物资源挂在本应用前缀下（独立模式 URL 形态与集成一致，四-1 全站无方言）
+  base: "/{{appName}}/",
+  server: {
+    host: "127.0.0.1", // 钉死 IPv4 回环：与默认入口 URL/CI 同口径（vite 默认 localhost 在 macOS 为 ::1 only）
+    port: {{port}},
+    cors: true, // 基座跨域加载本应用 dev 产物（micro-app fetch 入口与资源）
+    proxy: {
+      "/api/v1": {
+        target: "{{proxyTarget}}",
+        changeOrigin: true,
+      },
+    },
+  },
+  resolve: {
+    alias: [
+      // 供给层实现按构建模式切换（vite 不读 tsconfig paths，须显式 alias；tsconfig paths 仅供类型检查）
+      {
+        find: /^@supply$/,
+        replacement: fileURLToPath(
+          new URL(mode === "integrated" ? "./src/supply/integrated.ts" : "./src/supply/standalone.ts", import.meta.url),
+        ),
+      },
+      ...(mode === "integrated"
+        ? [
+            ...Object.keys(RUNTIME_SPECS).map((spec) => ({
+              find: new RegExp(`^${spec.replace("/", "\\/")}$`),
+              replacement: VIRTUAL_PREFIX + spec,
+            })),
+            { find: /^@yarch\/contract$/, replacement: contractShim },
+          ]
+        : []),
+    ],
+  },
+  build: { outDir: mode === "integrated" ? "dist-micro" : "dist" },
+  preview: { cors: true }, // 基座跨域加载集成产物（micro-app fetch，与 dev server.cors 同口径）
+}));