┌──────────── 改动成本（随耦合度上升）
                │        ┌─── 回归范围（随隐式依赖上升）
                │   ┌────┴─── 认知负担（随模块数量上升，若无边界）
                │  /
                │ /
                └──────────────────────────► 时间

17 架构与设计系统
  ├─ 前置：06 框架与组件化（组件 API）、09 工程化（Monorepo/构建）、07 状态管理
  ├─ 紧接：20 工程效能（组织、推动、度量）
  ├─ 交叉：13 测试（契约测试、视觉回归）、18 可观测（用线上数据验证架构）
  └─ 长期：技术战略、团队拓扑与梯队

src/
├─ app/            应用级装配：路由、Provider、全局配置、错误边界
├─ views/          页面：路由级组合，只做编排，不写业务规则
├─ features/       业务模块：领域逻辑 + 该领域的组件 + 请求
└─ shared/         共享：组件库、工具、类型、请求封装（不含业务）

        ┌─────────┐
        │   app   │  可以依赖所有层（装配者）
        └────┬────┘
             ▼
        ┌─────────┐
        │  views  │
        └────┬────┘
             ▼
        ┌─────────┐
        │features │  ← 同层之间尽量不互相 import
        └────┬────┘
             ▼
        ┌─────────┐
        │ shared  │  最底层，谁都能依赖它，它不依赖任何人
        └─────────┘

// ❌ shared/http.ts 里 import 了业务模块
import { getAuthToken } from '@/features/auth';

export async function request(url: string) {
  const token = getAuthToken();
  // ...
}

/**
 * shared/http.ts：只依赖抽象，不依赖具体业务。
 * 谁提供 token 由应用层决定。
 */
export interface TokenProvider {
  getToken(): string | null;
  onUnauthorized?(): void;
}

let tokenProvider: TokenProvider = { getToken: () => null };

/**
 * 由应用层在启动时注入，避免 shared 反向依赖 features。
 * @param provider 令牌提供者
 */
export function setTokenProvider(provider: TokenProvider): void {
  tokenProvider = provider;
}

/**
 * 统一请求封装。
 * @param url 请求地址
 * @param init fetch 配置
 * @returns 解析后的 JSON
 */
export async function request<T>(url: string, init: RequestInit = {}): Promise<T> {
  const token = tokenProvider.getToken();
  const headers = new Headers(init.headers);
  if (token) headers.set('Authorization', `Bearer ${token}`);

  const res = await fetch(url, { ...init, headers });
  if (res.status === 401) tokenProvider.onUnauthorized?.();
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return (await res.json()) as T;
}

// ✅ app/bootstrap.ts：装配发生在最上层
import { setTokenProvider } from '@/shared/http';
import { authStore } from '@/features/auth';

setTokenProvider({
  getToken: () => authStore.token,
  onUnauthorized: () => authStore.logout(),
});

{
  "rules": {
    "no-restricted-imports": ["error", {
      "patterns": [
        {
          "group": ["@/features/*/internal/*", "@/features/*/components/*"],
          "message": "请从模块门面导入：@/features/order"
        },
        {
          "group": ["../../features/*/model"],
          "message": "跨模块禁止直接引用内部模型，改用公开类型"
        }
      ]
    }]
  }
}

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: 'no-shared-to-features',
      severity: 'error',
      comment: 'shared 是底层，不能依赖业务模块',
      from: { path: '^src/shared' },
      to: { path: '^src/(features|views|app)' },
    },
    {
      name: 'no-feature-to-view',
      severity: 'error',
      comment: '业务模块不能依赖页面',
      from: { path: '^src/features' },
      to: { path: '^src/views' },
    },
    {
      name: 'no-circular',
      severity: 'error',
      comment: '循环依赖会让打包顺序与初始化顺序不可控',
      from: {},
      to: { circular: true },
    },
  ],
  options: {
    doNotFollow: { path: 'node_modules' },
    tsPreCompilationDeps: true,
  },
};

# 本地与 CI 都能跑，违规直接失败
npx depcruise src --config .dependency-cruiser.js

- [ ] 新增跨层依赖已在 PR 描述里说明理由
- [ ] `pnpm depcruise` 通过（CI 已强制）

features/order/
├─ api.ts          请求与 DTO 转换（把后端字段翻译成领域模型）
├─ model.ts        领域模型与规则（纯函数，无副作用）
├─ hooks.ts        数据订阅与副作用（React 适配层）
├─ components/     该领域专用组件
├─ pages/          该领域的页面（可选，也可放 views）
├─ __tests__/      单测与组件测试
└─ index.ts        对外门面（只导出公开 API）

/** 后端返回的原始结构（snake_case、字符串金额、状态码） */
interface OrderDTO {
  order_id: string;
  total_amount: string;
  status: 0 | 1 | 2 | 3;
  created_at: string;
}

/** 前端领域模型：语义化、不可变、可直接用于渲染 */
export interface Order {
  id: string;
  total: number;
  status: 'pending' | 'paid' | 'shipped' | 'closed';
  createdAt: Date;
}

const STATUS_MAP: Record<OrderDTO['status'], Order['status']> = {
  0: 'pending',
  1: 'paid',
  2: 'shipped',
  3: 'closed',
};

/**
 * 把后端 DTO 转成领域模型。
 * 后端改字段名时，只改这里，页面无感知。
 * @param dto 后端订单结构
 * @returns 前端订单模型
 */
export function toOrder(dto: OrderDTO): Order {
  return {
    id: dto.order_id,
    // 金额用字符串传输避免精度丢失，这里转成分（整数）再展示
    total: Math.round(Number(dto.total_amount) * 100),
    status: STATUS_MAP[dto.status] ?? 'pending',
    createdAt: new Date(dto.created_at),
  };
}

// index.ts
export { OrderList } from './components/OrderList';
export { useOrder } from './hooks';
export type { Order } from './model';
// 不导出：内部实现、临时工具、后端 DTO

import { useQuery } from '@tanstack/react-query';
import { fetchOrder } from './api';
import type { Order } from './model';

/**
 * 订单查询：把「数据获取」与「组件渲染」解耦。
 * 规则留在 model.ts，这里只负责生命周期与缓存。
 * @param id 订单号
 */
export function useOrder(id: string) {
  return useQuery<Order>({
    queryKey: ['order', id],
    queryFn: () => fetchOrder(id),
    staleTime: 30_000,
  });
}

设计令牌（Token）
   ↓ 颜色 / 间距 / 字体 / 圆角 / 阴影 / 动效时长
基础组件（Primitives）
   ↓ Button / Input / Select / Modal / Table
复合组件（Patterns）
   ↓ Form / FilterBar / DataTable / PageHeader
页面模板（Templates）
   ↓ 列表页 / 详情页 / 表单页 / 仪表盘
文档与治理（Docs & Governance）
   ↓ 用法、可访问性、版本、采纳率、owner

1. 令牌：色板（含语义色）、间距刻度、字号/行高、圆角、阴影、动效时长
2. 组件：Button / Input / Select / Checkbox / Modal / Table / Tooltip / Toast（8 个覆盖 80% 场景）
3. 文档：每个组件一页，含示例、API 表、可访问性说明、反例
4. 分发：一个包 + 按需入口 + 类型声明 + 样式产物
5. 治理：owner、issue 模板、版本策略、采纳率月报

失败模式一：只做组件，不做令牌
  → 换主题时发现颜色写死在 300 个文件里

失败模式二：只做规范，不做工具
  → 设计稿统一了，代码里没人执行，三个月后回到原样

失败模式三：做了但没人用
  → 组件 API 难用、文档缺失、与设计稿不一致，业务宁愿自己写

import type { ButtonHTMLAttributes, ReactNode } from 'react';

type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
  variant?: 'primary' | 'secondary' | 'danger' | 'text';
  size?: 'sm' | 'md' | 'lg';
  loading?: boolean;
  icon?: ReactNode;
};

/**
 * 基础按钮：透传原生属性，保证 onFocus / aria-* / data-* 都能用。
 * @param props 按钮属性
 */
export function Button({
  variant = 'primary',
  size = 'md',
  loading = false,
  icon,
  disabled,
  children,
  ...rest
}: ButtonProps) {
  return (
    <button
      type="button"
      className={`btn btn--${variant} btn--${size}`}
      disabled={disabled || loading}
      aria-busy={loading || undefined}
      {...rest}
    >
      {loading ? <span className="btn__spinner" aria-hidden="true" /> : icon}
      <span className="btn__label">{children}</span>
    </button>
  );
}

import { useCallback, useState } from 'react';

interface InputProps {
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
}

/**
 * 同时支持受控与非受控：
 * - 传 value 即受控，状态由外部管理；
 * - 不传 value 即非受控，内部维护状态。
 * 不要在两种模式之间来回切换，否则 React 会警告。
 */
export function Input({ value, defaultValue = '', onChange }: InputProps) {
  const isControlled = value !== undefined;
  const [inner, setInner] = useState(defaultValue);

  const current = isControlled ? value : inner;

  const handleChange = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      if (!isControlled) setInner(e.target.value);
      onChange?.(e.target.value);
    },
    [isControlled, onChange]
  );

  return <input value={current} onChange={handleChange} />;
}

// ❌ 配置式：每加一个需求就加一个布尔属性
<Modal
  title="编辑"
  showClose
  showFooter
  showCancel
  showConfirm
  confirmText="保存"
  cancelText="取消"
  showIcon
  iconType="warning"
/>

// ✅ 组合式：结构由使用方决定
<Modal>
  <Modal.Header title="编辑" />
  <Modal.Body>{children}</Modal.Body>
  <Modal.Footer>
    <Button variant="secondary">取消</Button>
    <Button>保存</Button>
  </Modal.Footer>
</Modal>

import { cloneElement, isValidElement, type ReactElement } from 'react';

interface AsChildProps {
  asChild?: boolean;
  children: ReactElement;
  className?: string;
}

/**
 * 把样式与行为「借给」子元素，避免多余的包裹层。
 * 生产环境更推荐 Radix 的 Slot 实现，处理了 ref 合并与事件合成。
 * @param props 属性
 */
export function Slot({ asChild, children, className, ...rest }: AsChildProps & Record<string, unknown>) {
  if (!asChild || !isValidElement(children)) {
    return <span className={className} {...rest}>{children}</span>;
  }
  const childProps = children.props as { className?: string };
  return cloneElement(children, {
    ...rest,
    className: [className, childProps.className].filter(Boolean).join(' '),
  } as never);
}

按业务域切：  features/order/{api,model,components}  ← 一个目录内完成
按技术层切：  api/order.ts + hooks/useOrder.ts + components/OrderFilter.tsx + types/order.ts

需求：订单列表增加筛选
   ├─ features/order/api.ts            新增查询参数、DTO 转换
   ├─ features/order/model.ts          筛选条件的默认值与校验
   ├─ features/order/components/Filter.tsx   筛选 UI
   └─ views/order-list.tsx             只做编排与路由参数解析

第一层：模块内部私有          features/order/utils/format.ts
第二层：跨模块共享（有业务）   features/shared-order/  ← 仍属业务域
第三层：通用能力（无业务）     shared/{ui,utils,http,types}

/**
 * 通用金额格式化：不含任何业务语义。
 * @param cents 以分为单位的整数
 * @param currency 货币代码
 * @returns 展示字符串
 */
export function formatCurrency(cents: number, currency = 'CNY'): string {
  return new Intl.NumberFormat('zh-CN', {
    style: 'currency',
    currency,
    minimumFractionDigits: 2,
  }).format(cents / 100);
}

# 1) 生成依赖图，人工看是否有环与跨层边
npx depcruise src --include-only "^src" --output-type dot | dot -Tsvg > deps.svg

# 2) 统计每个模块被引用次数，次数异常高说明它是「隐性核心」
grep -r "from '@/features/" src --include=*.ts --include=*.tsx | cut -d/ -f2 | sort | uniq -c | sort -rn

/* 1) 原始值（primitive）：只描述「是什么」，不带语义 */
:root {
  --blue-50: #e6f4ff;
  --blue-500: #1677ff;
  --blue-600: #0958d9;
  --gray-100: #f5f5f5;
  --gray-900: #1f1f1f;
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  --radius-1: 4px;
  --radius-2: 6px;
  --font-size-2: 14px;
  --font-size-3: 16px;
}

/* 2) 语义值（semantic）：描述「用在哪」，是主题切换的唯一开关 */
:root {
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-text: var(--gray-900);
  --color-bg: #ffffff;
  --color-bg-subtle: var(--gray-100);
  --space-control-x: var(--space-4);
  --space-control-y: var(--space-2);
  --radius-control: var(--radius-2);
  --font-size-body: var(--font-size-2);
}

/* 3) 组件值（component）：只在该组件内消费，便于局部定制 */
:root {
  --button-primary-bg: var(--color-primary);
  --button-primary-bg-hover: var(--color-primary-hover);
  --button-padding-x: var(--space-control-x);
  --button-radius: var(--radius-control);
}

.button--primary {
  background: var(--button-primary-bg);
  padding: var(--space-control-y) var(--button-padding-x);
  border-radius: var(--button-radius);
  font-size: var(--font-size-body);
}

.button--primary:hover {
  background: var(--button-primary-bg-hover);
}

/* A. 全局主题：挂在 html 上 */
[data-theme='dark'] {
  --color-text: #e6e6e6;
  --color-bg: #141414;
  --color-bg-subtle: #1f1f1f;
}

/* B. 局部主题：挂在任意容器上，适合「预览区」「嵌入模块」 */
.theme-preview[data-theme='dark'] {
  --color-text: #e6e6e6;
  --color-bg: #141414;
}

/* C. 跟随系统：用媒体查询设默认值，用户手动切换时用属性覆盖 */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme='light']) {
    --color-text: #e6e6e6;
    --color-bg: #141414;
  }
}

/**
 * 主题切换：先写 DOM，再持久化，最后通知订阅者。
 * @param theme 目标主题
 */
export function setTheme(theme: 'light' | 'dark' | 'system'): void {
  const root = document.documentElement;
  if (theme === 'system') root.removeAttribute('data-theme');
  else root.setAttribute('data-theme', theme);

  localStorage.setItem('theme', theme);
  window.dispatchEvent(new CustomEvent('themechange', { detail: theme }));
}

/** 首屏防闪烁：在 CSS 加载前同步执行，避免先亮后暗 */
export function applyThemeBeforePaint(): void {
  const saved = localStorage.getItem('theme');
  if (saved && saved !== 'system') {
    document.documentElement.setAttribute('data-theme', saved);
  }
}

Figma（设计稿）
   ↓ Tokens Studio 导出 JSON
tokens.json（唯一来源）
   ↓ Style Dictionary / 自研脚本
CSS 变量 + TS 常量 + 各端产物（小程序、RN）

{
  "color": {
    "primary": { "value": "{blue.500}", "type": "color" },
    "text": { "value": "{gray.900}", "type": "color" }
  },
  "space": {
    "control-x": { "value": "{space.4}", "type": "dimension" }
  }
}

/**
 * 由 tokens.json 生成的类型，保证代码里不会写错 token 名。
 * 生成脚本与设计稿保持同步，避免「设计改了代码没改」。
 */
export const tokens = {
  colorPrimary: 'var(--color-primary)',
  spaceControlX: 'var(--space-control-x)',
} as const;

export type TokenName = keyof typeof tokens;

// eslint：禁止在业务代码里写死颜色
{
  "rules": {
    "no-restricted-syntax": ["error", {
      "selector": "Literal[value=/^#([0-9a-fA-F]{3,8})$/]",
      "message": "请使用设计令牌（var(--color-*)），不要硬编码色值"
    }]
  }
}

packages/ui/
├─ src/                  源码（TS + CSS）
├─ dist/
│  ├─ esm/               ESM 产物（现代打包器）
│  ├─ cjs/               CJS 产物（Node / Jest）
│  ├─ types/             .d.ts
│  └─ styles.css         样式产物（可选按组件拆分）
└─ package.json

{
  "name": "@acme/ui",
  "type": "module",
  "sideEffects": ["**/*.css"],
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    },
    "./button": {
      "types": "./dist/types/button/index.d.ts",
      "import": "./dist/esm/button/index.js",
      "require": "./dist/cjs/button/index.js"
    },
    "./styles.css": "./dist/styles.css",
    "./package.json": "./package.json"
  },
  "peerDependencies": {
    "react": ">=18",
    "react-dom": ">=18"
  }
}

/**
 * SSR 场景下，组件库不应在运行时注入 <style>。
 * 做法：构建期抽出静态 CSS，服务端渲染时由框架负责注入。
 */
import '@acme/ui/styles.css'; // 由应用入口引入，服务端与客户端共用

// ✅ 具名导入，打包器能静态分析
import { Button, Modal } from '@acme/ui';

// ⚠️ 命名空间导入：多数打包器仍能分析，但容易整包引入副作用
import * as UI from '@acme/ui';

// ❌ 深路径导入：在声明 exports 后可能直接报错
import Button from '@acme/ui/dist/button';

# 量化：对比「只用一个 Button」时的产物大小
npx source-map-explorer dist/assets/*.js

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

/** 组件测试优先断言「用户能看到/能做到什么」，而不是内部 class */
test('loading 时不可点击且对读屏可见', async () => {
  const onClick = vi.fn();
  render(<Button loading onClick={onClick}>保存</Button>);

  const btn = screen.getByRole('button', { name: /保存/ });
  expect(btn).toBeDisabled();
  expect(btn).toHaveAttribute('aria-busy', 'true');

  await userEvent.click(btn);
  expect(onClick).not.toHaveBeenCalled();
});

# 1) 开发者在 PR 里声明变更类型
pnpm changeset

# 2) 合并后由机器人开一个「版本发布」PR
#    自动汇总 changelog、升版本号、更新依赖

# 3) 合并发布 PR，CI 负责 npm publish + tag

1. 多个团队需要独立发布（发布节奏不同）
2. 需要一个统一的入口与体验（不能拆成多个独立站点）
3. 技术栈或历史包袱不同，短期无法统一

<!-- 子应用完全独立，父页面只能通过 postMessage 通信 -->
<iframe
  src="https://order.example.com/list"
  sandbox="allow-scripts allow-same-origin allow-forms"
  referrerpolicy="strict-origin-when-cross-origin"
  title="订单管理"
></iframe>

基座（主应用）
 ├─ 路由表：/order/* → order 子应用
 ├─ 容器：<div id="subapp-container">
 ├─ 加载器：fetch HTML entry → 解析 script/style → 执行
 ├─ 沙箱：Proxy window + 快照恢复
 └─ 生命周期：bootstrap → mount → unmount

// 子应用入口（以 qiankun 约定为例）
import { createRoot, type Root } from 'react-dom/client';
import App from './App';

let root: Root | null = null;

/**
 * 挂载：容器由基座传入，子应用不要自己找 document.body。
 * @param props 基座注入的属性（容器、全局状态、通信函数）
 */
export async function mount(props: { container: HTMLElement; globalState?: unknown }) {
  root = createRoot(props.container);
  root.render(<App basename="/order" />);
}

/** 卸载：必须清理 root、定时器、全局事件，否则切回时会内存泄漏 */
export async function unmount() {
  root?.unmount();
  root = null;
}

// 基座 webpack.config.js
new ModuleFederationPlugin({
  name: 'shell',
  remotes: {
    order: 'order@https://order.example.com/remoteEntry.js',
  },
  shared: {
    react: { singleton: true, requiredVersion: '^18.0.0' },
    'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
  },
});

// 子应用：暴露模块
new ModuleFederationPlugin({
  name: 'order',
  filename: 'remoteEntry.js',
  exposes: {
    './App': './src/App',
    './routes': './src/routes',
  },
  shared: {
    react: { singleton: true, requiredVersion: '^18.0.0' },
  },
});

// 基座：运行时加载远程模块，必须用 lazy 形成异步边界
import { lazy, Suspense } from 'react';

const OrderApp = lazy(() => import('order/App'));

export function OrderRoute() {
  return (
    <Suspense fallback={<div>加载中…</div>}>
      <OrderApp />
    </Suspense>
  );
}

/**
 * 用自定义元素封装一个跨框架组件。
 * 优点：浏览器原生隔离；缺点：props/事件不是 React 语义，需要桥接。
 */
class OrderBadge extends HTMLElement {
  static observedAttributes = ['count'];

  private shadow: ShadowRoot;

  constructor() {
    super();
    this.shadow = this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  private render() {
    const count = Number(this.getAttribute('count') ?? 0);
    this.shadow.innerHTML = `
      <style>
        :host { display: inline-flex; }
        .badge { background: var(--color-primary, #1677ff); color: #fff; border-radius: 999px; padding: 2px 8px; }
      </style>
      <span class="badge" part="badge">${count}</span>
    `;
  }
}

customElements.define('order-badge', OrderBadge);

主应用
 ├─ Shadow DOM 容器 ← 子应用的真实 DOM 渲染在这里
 └─ 隐藏 iframe     ← 子应用的 JS 运行在这里（独立 window/document）
       ↕ Proxy：把 iframe 的 document 指向主文档的 shadowRoot

需要独立发布？
├─ 否 → 不做微前端（单仓多包 / 模块边界）
└─ 是
    ├─ 技术栈统一且要共享代码？
    │    ├─ 是 → Module Federation（同栈、共享依赖）
    │    └─ 否 → 运行时加载（qiankun 类）
    ├─ 只需要嵌入一个独立系统？
    │    └─ 是 → iframe（别自研）
    └─ 既要强隔离又要统一体验？
         └─ iframe 沙箱 + DOM 代理（Wujie 类）

/**
 * 快照式沙箱：挂载前记录 window 变更，卸载时恢复。
 * 只能处理「赋值到 window 的属性」，无法处理闭包、原型链污染。
 */
function createSnapshotSandbox() {
  const snapshot = new Map<string, unknown>();

  return {
    /** 激活：记录当前 window 上的自定义属性 */
    activate() {
      for (const key of Object.keys(window)) {
        if (!(key in snapshot)) snapshot.set(key, (window as never)[key]);
      }
    },
    /** 失活：删除新增属性，恢复被修改的属性 */
    deactivate() {
      for (const key of Object.keys(window)) {
        if (!snapshot.has(key)) {
          delete (window as never)[key];
        }
      }
      snapshot.forEach((value, key) => {
        (window as never)[key] = value;
      });
    },
  };
}

/* 前缀方案：靠约定，必须配 lint 检查 */
.app-order .btn { /* ... */ }

/* Shadow DOM：外部只能通过 part 定制 */
/* :host { --button-bg: var(--color-primary); } */
/* ::part(button) { border-radius: 8px; } */

方案 A：基座统一路由（推荐）
  /order/*   → 子应用 order
  /user/*    → 子应用 user
  子应用内部用 basename，不直接操作 window.history

方案 B：子应用自治路由
  子应用自己 pushState → 与基座的路由表冲突，前进后退易错乱

/**
 * 共享依赖的三条铁律：
 * 1) React / ReactDOM 必须单例，否则 Hook 与 Context 失效；
 * 2) 版本范围要写 requiredVersion，冲突时显式告警而不是静默降级；
 * 3) 工具库（lodash、dayjs）可以多实例，但会造成包体重复。
 */

/** 1) props 注入：最可控，适合「基座 → 子应用」单向传递 */
mount({ container, user, navigate });

/** 2) 事件总线：适合松耦合，但事件名与载荷无类型约束，容易失控 */
const bus = new EventTarget();
bus.dispatchEvent(new CustomEvent('order:created', { detail: { id } }));

/** 3) 共享 store：最强耦合，只适合真正全局的状态（用户、主题、权限） */

# ADR-0007：采用模块联邦而非 iframe 做微前端

## 状态
已接受（2026-03-01）｜ 替代 ADR-0003

## 背景
- 三个业务线需要独立发布，当前单仓每周只能发一次
- 技术栈统一为 React 18，共用一套设计系统
- 已评估：拆成三个独立站点会导致登录态与导航割裂

## 选项
A. 继续单仓（不做）
B. iframe 嵌入
C. 运行时加载（qiankun 类）
D. Module Federation

## 决策
选择 D。理由：同栈、需要共享设计系统与工具库；团队已有 webpack 5 经验。

## 后果
+ 共享依赖，包体可控；开发体验接近单仓
- 必须锁定 React 版本；构建期契约与版本协商需要专人维护
- 运行时报错在浏览器暴露，需要错误边界与远程加载降级

## 回退
保留单仓构建入口，出现严重问题时可按路由切回单体版本。

## 复盘时间
2026-06-01 评估发布频率、故障率与包体变化。

docs/adr/
├─ README.md          索引：编号、标题、状态、日期
├─ 0001-....md
├─ 0002-....md
└─ template.md

阶段 1  旁路并行
  新需求只在新架构实现；旧架构只修 bug，不加功能
        │
阶段 2  路由级切换
  按路由/页面把流量切到新架构，比例 1% → 10% → 50%
        │
阶段 3  按流量迁移
  从「访问量低、依赖少」的模块开始，逐个搬到新栈
        │
阶段 4  双跑对比
  新旧同时可访问，对比错误率、性能、转化，异常即切回
        │
阶段 5  删除旧栈
  流量归零并观察一个发布周期后删除，移除开关与兼容层

/**
 * 按百分比灰度：同一个用户始终命中同一侧，避免刷新后跳变。
 * @param key 稳定标识（用户 ID / 设备 ID）
 * @param percent 灰度比例 0-100
 */
export function inRollout(key: string, percent: number): boolean {
  // FNV-1a：简单稳定，避免引入依赖
  let hash = 0x811c9dc5;
  for (let i = 0; i < key.length; i += 1) {
    hash ^= key.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193);
  }
  return Math.abs(hash) % 100 < percent;
}

/** 新旧页面共存：开关只决定渲染哪一侧，回退不需要发版 */
function OrderListRoute() {
  const { userId } = useUser();
  const { rolloutPercent } = useConfig();

  return inRollout(userId, rolloutPercent) ? <OrderListNext /> : <OrderListLegacy />;
}

/**
 * 简化版组件使用统计：扫描源码里的 JSX 标签与 import 来源。
 * 生产可用 @babel/parser + @babel/traverse 遍历 AST。
 * @param files 文件内容列表
 * @returns 设计系统组件与自写组件的计数
 */
export function countComponentUsage(files: string[]) {
  const result = { designSystem: 0, custom: 0 };
  const dsImport = /from ['"]@acme\/ui['"]/;

  for (const code of files) {
    if (!dsImport.test(code)) {
      // 没有引入设计系统，但出现了高频组件名，视为自写
      if (/<(Button|Modal|Table)\b/.test(code)) result.custom += 1;
      continue;
    }
    const matches = code.match(/<(Button|Input|Modal|Table|Select)\b/g);
    result.designSystem += matches?.length ?? 0;
  }

  return result;
}

1. 默认正确：脚手架生成的页面已经用了设计系统
2. 低门槛：提供代码片段、迁移脚本、示例仓库
3. 有约束：lint 禁止硬编码色值/自写高频组件
4. 可发现：文档站能搜到、示例能复制
5. 有反馈：月度采纳率报告 + 问题响应 SLA

interface LegacyProps {
  /** @deprecated 使用 variant="danger" 替代，v3 将移除 */
  type?: 'danger' | 'primary';
  variant?: 'primary' | 'secondary' | 'danger';
}

/**
 * 兼容层：旧属性映射到新属性，并在开发环境告警。
 * 生产环境不告警，避免日志噪音。
 */
export function Button({ type, variant, ...rest }: LegacyProps) {
  if (process.env.NODE_ENV !== 'production' && type) {
    console.warn('[ui] Button 的 type 属性已废弃，请改用 variant');
  }
  const resolved = variant ?? (type === 'danger' ? 'danger' : 'primary');
  return <BaseButton variant={resolved} {...rest} />;
}

/**
 * jscodeshift 转换示例：把 <Button type="danger"> 改成 variant="danger"。
 * 用法：npx jscodeshift -t codemods/button-variant.ts src --extensions=tsx
 */
module.exports = function transform(fileInfo, api) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  root.findJSXElements('Button').forEach((path) => {
    j(path)
      .find(j.JSXAttribute, { name: { name: 'type' } })
      .forEach((attr) => {
        const value = attr.node.value;
        if (value?.type === 'StringLiteral' && value.value === 'danger') {
          attr.node.name.name = 'variant';
        }
      });
  });

  return root.toSource({ quote: 'single' });
};

packages/
├─ tokens/          设计令牌（无依赖）
├─ icons/           图标（无依赖）
├─ ui/              基础组件（依赖 tokens）
├─ charts/          图表（依赖 tokens + ui）
└─ utils/           工具函数（无依赖）
apps/
├─ admin/           依赖 ui + charts + utils
└─ portal/          依赖 ui + utils

{
  "dependencies": {
    "@acme/tokens": "workspace:*"
  },
  "peerDependencies": {
    "react": ">=18"
  }
}

# 1) 收集变更：开发者提交 changeset
pnpm changeset

# 2) 版本计算：工具会自动处理包之间的依赖顺序
pnpm changeset version

# 3) 发布：按拓扑序发布，先底层后上层
pnpm changeset publish

# 列出各应用使用的 @acme/ui 版本分布
pnpm -r exec node -e "try{console.log(require('./package.json').dependencies)}catch(e){}" \
  | grep -o '"@acme/ui": "[^"]*"'

# 导出依赖图数据，统计模块之间的边数
npx depcruise src --output-type json > deps.json

# 找出被依赖最多的模块（隐性核心）
node -e "
const d = require('./deps.json');
const count = new Map();
for (const m of d.modules) {
  for (const dep of m.dependencies) {
    const target = dep.resolved;
    count.set(target, (count.get(target) || 0) + 1);
  }
}
console.log([...count].sort((a, b) => b[1] - a[1]).slice(0, 10));
"

第 1 步：统计全局选择器与冲突面（哪些类名被多个应用使用）
第 2 步：新代码强制 CSS Modules / 前缀，旧代码不动
第 3 步：按页面迁移，迁移时顺手删死样式
第 4 步：加 lint 禁止新增全局选择器

/* 迁移前：全局，容易冲突 */
.btn { padding: 8px 16px; }

/* 迁移后：作用域内，构建期加哈希 */
/* button.module.css */
.btn { padding: 8px 16px; }

/* 顺序即优先级：后面的层覆盖前面的层，与选择器权重无关 */
@layer reset, base, components, utilities;

@layer base {
  button { font: inherit; }
}

@layer components {
  .btn { padding: 8px 16px; border-radius: 6px; }
}

@layer utilities {
  .mt-4 { margin-top: 16px; }
}

静态层：ESLint（导入规则、禁用 API）、dependency-cruiser（依赖方向）、
        stylelint（硬编码色值）、TypeScript（类型契约）
        ↓ 提交前 + CI
测试层：契约测试（接口 schema）、视觉回归（组件外观）、
        架构测试（模块可独立构建）
        ↓ PR
运行时层：错误监控（按应用/模块分桶）、性能指标、白名单告警
        ↓ 线上

import { z } from 'zod';

/** 前后端共享的响应契约：字段变更会同时让两边失败 */
export const OrderSchema = z.object({
  id: z.string(),
  total: z.number().int().nonnegative(),
  status: z.enum(['pending', 'paid', 'shipped', 'closed']),
});

export type OrderContract = z.infer<typeof OrderSchema>;

/**
 * 运行时校验：开发与预发环境开启，生产环境只上报不抛错。
 * @param data 接口返回
 */
export function parseOrder(data: unknown): OrderContract {
  const result = OrderSchema.safeParse(data);
  if (!result.success) {
    reportContractError(result.error.issues);
    if (process.env.NODE_ENV !== 'production') throw result.error;
  }
  return result.data as OrderContract;
}

/**
 * 架构测试：删除模块后其余代码仍可构建，说明没有隐式依赖。
 * 实现方式：CI 里临时移动目录 + 跑类型检查，或在依赖图上断言「无入边」。
 */
test('shared 不依赖任何业务模块', async () => {
  const graph = await buildDependencyGraph('src');
  const violations = graph
    .filter((edge) => edge.from.startsWith('src/shared'))
    .filter((edge) => /^src\/(features|views|app)/.test(edge.to));

  expect(violations).toEqual([]);
});

系统结构会复制组织的沟通结构。

# .github/CODEOWNERS：把所有权写进流程
/packages/ui/          @design-system-team
/packages/build-config/ @infra-team
/apps/admin/           @admin-fe
/apps/portal/          @portal-fe

## 1. 现状（数据）
- 发布频率 2 次/月，构建 12 分钟，线上故障 3 次/月
- 5 个团队共用单仓，日均冲突 12 次
- 3 套组件库，视觉走查每月 20 个问题

## 2. 问题（影响）
- 等待占交付周期 60%，需求平均 9 天上线
- 故障恢复平均 3 小时，值班压力大
- 视觉不一致导致品牌投诉与返工

## 3. 目标（可量化）
- 发布按需（每周 ≥ 5 次），构建 < 3 分钟
- MTTR < 30 分钟，变更失败率 < 10%
- 组件覆盖率 > 80%，走查问题下降 70%

## 4. 路径（分阶段）
Q1 流水线：CI 门禁、增量构建、缓存
Q2 灰度与回滚：开关、灰度平台、一键回滚
Q3 资产收敛：token + 高频组件 + codemod
Q4 架构演进：按业务域拆包，独立发布试点

## 5. 投入
2 人 × 2 季度 + 1 名设计 + 少量基础设施成本

## 6. 风险与回退
- 迁移期双栈并行，成本上升 15%
- 每阶段有独立回退点，可停在任一阶段
- 指标连续两周恶化即暂停并复盘

❌ 「升级构建工具，Rspack 比 Webpack 快 5 倍」
✅ 「构建 12 分钟，30 人每天等约 40 人时；升级后 3 分钟，
    一年回收约 200 人天，投入 2 人 × 3 周，净收益约 180 人天」

年浪费人天 = 单次等待时长 × 每日次数 × 人数 × 工作日
回收周期  = 投入人天 ÷ 每日节省人天

// 根 package.json：workspace + 统一脚本
{
  "private": true,
  "scripts": {
    "build": "pnpm -r --filter './packages/*' build && pnpm -r --filter './apps/*' build",
    "lint": "eslint . && pnpm depcruise",
    "test": "vitest run"
  }
}

# CI：只构建受影响的包，未命中缓存才全量
- name: Build affected
  run: pnpm turbo run build --filter=...[origin/main]

// 依赖方向用规则固化，防止架构回退
module.exports = {
  forbidden: [
    { name: 'shared-is-leaf', from: { path: '^packages/shared' }, to: { path: '^(apps|packages/(ui|charts))' } },
    { name: 'no-circular', from: {}, to: { circular: true } },
  ],
};

第 1 周：只加规则，不拦存量（baseline 冻结）
第 2–3 周：新代码必须合规，老代码按触碰即改
第 4 周起：存量按「变更频率」排序，优先迁移高频模块

/**
 * 极简 DI 容器：支持单例/瞬时，检测循环依赖。
 */
function createContainer() {
  /** @type {Map<string, { factory: Function, singleton: boolean }>} */
  const registry = new Map();
  /** @type {Map<string, any>} */
  const instances = new Map();
  const resolving = new Set();

  /**
   * 注册工厂。
   * @param {string} name 标识
   * @param {(c: any) => any} factory 工厂函数
   * @param {{ singleton?: boolean }} [options] 配置
   */
  const register = (name, factory, { singleton = true } = {}) => {
    registry.set(name, { factory, singleton });
  };

  /**
   * 解析实例。
   * @param {string} name 标识
   */
  const resolve = (name) => {
    if (instances.has(name)) return instances.get(name);
    const entry = registry.get(name);
    if (!entry) throw new Error(`未注册: ${name}`);
    if (resolving.has(name)) throw new Error(`循环依赖: ${[...resolving, name].join(' -> ')}`);

    resolving.add(name);
    try {
      const instance = entry.factory(api);
      if (entry.singleton) instances.set(name, instance);
      return instance;
    } finally {
      resolving.delete(name);
    }
  };

  const api = { register, resolve };
  return api;
}

/**
 * 简易沙箱：拦截全局读写。
 * 注意：`with` 在严格模式下不可用，且存在逃逸路径，仅用于理解原理。
 * @param {Record<string, any>} [globals]
 */
function createSandbox(globals = {}) {
  const fakeWindow = Object.create(null);
  const rawWindow = window;

  const proxy = new Proxy(fakeWindow, {
    get(target, key) {
      if (key in target) return target[key];
      if (key in globals) return globals[key];
      const value = rawWindow[key];
      // 绑定 this，避免调用时指向 Proxy 导致非法调用
      return typeof value === 'function' ? value.bind(rawWindow) : value;
    },
    set(target, key, value) {
      target[key] = value;
      return true;
    },
    has(target, key) {
      return key in target || key in globals || key in rawWindow;
    },
  });

  /**
   * 在沙箱中执行代码。
   * @param {string} code 待执行代码
   */
  const run = (code) => {
    const fn = new Function('window', 'self', 'globalThis', `with(window){${code}}`);
    return fn(proxy, proxy, proxy);
  };

  return { proxy, run };
}

/**
 * 把一段 HTML 渲染进 Shadow DOM，并注入样式。
 * 主题通过 CSS 自定义属性穿透边界。
 * @param host 宿主元素
 * @param html 内容
 * @param css 样式
 */
export function mountShadow(host: HTMLElement, html: string, css: string) {
  const shadow = host.shadowRoot ?? host.attachShadow({ mode: 'open' });

  // adoptedStyleSheets 可复用同一份样式表，避免重复解析
  if ('adoptedStyleSheets' in Document.prototype) {
    const sheet = new CSSStyleSheet();
    sheet.replaceSync(css);
    shadow.adoptedStyleSheets = [sheet];
  } else {
    const style = document.createElement('style');
    style.textContent = css;
    shadow.appendChild(style);
  }

  const slot = document.createElement('div');
  slot.innerHTML = html;
  shadow.appendChild(slot);

  return {
    /** 卸载：清空内容，避免残留 DOM 与监听 */
    unmount() {
      shadow.innerHTML = '';
    },
  };
}