@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/main-doc/docs/en/guides/get-started/ultramodern.mdx

@@ -0,0 +1,320 @@
+---
+title: UltraModern.js V3
+sidebar_position: 6
+---
+
+# UltraModern.js V3 vs Modern.js V3
+
+UltraModern.js V3 documents the public `presetUltramodern(...)` Modern.js profile for large, independently deployable super-app and ERP-style systems.
+
+This page is the complete public difference reference for that documented V3 profile.
+
+## Scope (V3 Only)
+
+- Baseline: Modern.js `release-v3.x`.
+- Scope: all user-visible differences shipped in UltraModern.js V3.
+- Excluded: roadmap/mainline-only work that is not shipped to V3.
+
+## Complete Difference Matrix (V3)
+
+| Area | Modern.js V3 baseline | UltraModern.js V3 difference | Status in V3 | Notes |
+| --- | --- | --- | --- | --- |
+| Build diagnostics default | RsDoctor usage is opt-in in most projects | Rspack production build enables RsDoctor by default | Implemented | Can be disabled via `performance.rsdoctor` |
+| Build diagnostics config surface | No `performance.rsdoctor` option in framework docs | Adds `performance.rsdoctor` (`boolean` or `{ enabled, disableClientServer, reportDir, mode }`) | Implemented | `disableClientServer` defaults to `true` |
+| Diagnostics artifact contract | No standardized machine-readable diagnostics pointer | Adds `.rsdoctor/ultramodern-diagnostics.json` contract pointing to manifest | Implemented | Stable consumption path for coding agents |
+| Static asset precompression defaults | Precompressed artifacts and serving are app-defined | Adds default-on `output.precompress` for production web builds and static middleware `Accept-Encoding` negotiation for `.br` / `.gz` | Implemented | Can be disabled or tuned per codec |
+| Router runtime choice | Default runtime path centers on React Router | Adds first-class TanStack Router runtime/CLI route tree support | Implemented | React Router path remains available |
+| Scaffolding template path | Default create templates center on React Router starter path | Adds TanStack-ready and Tailwind-ready create templates | Implemented | React Router starter path remains available |
+| Starter preset gate workflow | Generated starter has no UltraModern preset verification workflow | Adds `ultramodern:check`, opt-out env switches, and `.github/workflows/ultramodern-gates.yml` to the public preset starter | Implemented | Keeps generated apps auditable from the first commit |
+| BFF producer contract wiring | `bff` config does not include producer identity | Adds `bff.requestId` and carries it through client generation | Implemented | Enables explicit producer scoping |
+| Generated BFF client call shape | `createRequest(...)` optional args stop at `fetch` | Generated client appends `requestId` to `createRequest(...)` when configured | Implemented | Keeps legacy call path when no `requestId` |
+| `create-request` runtime isolation | Single mutable request config path | Per-`requestId` request/domain/header config maps | Implemented | Supports multiple producer clients in one app |
+| BFF audit correlation headers | No standardized producer audit propagation for operation and trace | Adds `x-operation-id`, `x-modernjs-bff-operation-context`, and `traceparent` propagation with parsed trace IDs | Implemented | Supports tenant/operation/trace joins in observability |
+| Uninitialized producer behavior | Missing config may silently fall back | Non-default `requestId` now throws `ProducerClientNotInitializedError` | Implemented | Fail-fast contract for cross-project BFF |
+| Node header forwarding behavior | Header forwarding is global | Incoming headers are forwarded only for `requestId === 'default'` | Implemented | Avoids accidental header bleed across producers |
+| Server telemetry config | No standardized `server.telemetry` contract | Adds `server.telemetry` with sampling/batching/redaction/exporter settings | Implemented | Added to app-tools schema and server types |
+| Telemetry exporters | Export pipeline is app-defined | Built-in OTLP and VictoriaMetrics exporters | Implemented | Exporters are non-fatal on failure |
+| Telemetry backpressure contract | No standard queue policy | Registry queue with max size, dropped-event counter, periodic flush | Implemented | Emits `telemetry.queue.dropped` on pressure |
+| Metrics/trace correlation | SSR metrics tags do not parse W3C trace context | `traceparent` is parsed and emits `trace_id` / `span_id` tags | Implemented | Improves cross-system observability joins |
+| App-level MF SSR contract flag | No dedicated app-level MF SSR stability contract switch | Adds `server.ssr.moduleFederationAppSSR` contract and auto-enables env wiring when MF SSR markers are detected | Implemented | Sets `process.env.MODERN_MF_APP_SSR` |
+| App-level MF SSR runtime bridge | Not a stable default bridge path | V3 applies stable bridge defaults for MF SSR node output/runtime env when server rendering + MF markers are present | Implemented | Keeps explicit opt-out path via config/env |
+| MF remote loader reliability contracts | Remote loading fallback patterns are typically app-defined | Adds deterministic timeout/network/contract-error fallback matrix and distributed OTEL continuity assertions | Implemented | `routes-tanstack-mf` reliability suite |
+| BFF runtime choices | Hono runtime path only in Modern.js V3 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-only MF data contracts plus failure-injection coverage for federated data fetch | Implemented (Effect-default + strict split) | Stream is explicit about no Zod introduction |
+| Module SDK contract artifact | No framework-level module contract artifact | Adds machine-readable module contract + typed module SDK interfaces | Implemented | `module-sdk-contracts.json` + `moduleSdk.d.ts` |
+| Boundary anti-pattern CI guards | No dedicated boundary anti-pattern workflow | Adds profile-driven CI checks for boundary imports, required hooks, and forbidden module patterns | Implemented | `.github/workflows/boundary-anti-patterns.yml` |
+| Release/module certification gate automation | No super-app release evidence profile in baseline | Adds RC + module-certification gate profiles, evidence metadata validation, and dedicated CI workflows | Implemented | `.github/workflows/release-contract-gates.yml` + module/bun gate workflows |
+| Contract test coverage | No tests for these new contracts in V3 baseline | Adds focused tests for RsDoctor defaults, BFF requestId, telemetry, SSR MF contract env wiring | Implemented | Reduces regression risk in super-app scenarios |
+| Public docs surface | No UltraModern V3 comparison page | Adds dedicated V3 difference page and linked config docs | Implemented | This page is the reference page for the public preset profile |
+
+## Detailed V3 Differences
+
+### 1) `performance.rsdoctor` and default-on diagnostics
+
+UltraModern.js V3 extends performance config with:
+
+- `performance.rsdoctor: boolean | { enabled?: boolean; disableClientServer?: boolean; reportDir?: string; mode?: 'normal' | 'brief' | 'lite' }`
+- Rspack + production: enabled by default.
+- Rspack + development: disabled by default (unless explicitly enabled).
+- Webpack builds: no RsDoctor injection.
+- RsDoctor contract artifact:
+  - `<reportDir or outputPath>/.rsdoctor/ultramodern-diagnostics.json`
+  - points to `.rsdoctor/manifest.json`
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+      disableClientServer: true,
+      reportDir: './artifacts',
+      mode: 'brief',
+    },
+  },
+});
+```
+
+### 2) Cross-project BFF hardening with `requestId`
+
+UltraModern.js V3 adds explicit producer identity across the BFF toolchain:
+
+- `bff.requestId` in plugin config.
+- Loader/client generation passes `requestId` to `createRequest(...)`.
+- `create-request` now keeps isolated runtime state per `requestId`.
+
+```ts
+configure({
+  requestId: 'erp-inventory',
+  request: customFetch,
+  setDomain: ({ target, requestId }) =>
+    target === 'server'
+      ? `http://inventory-bff.internal`
+      : `https://inventory.example.com`,
+});
+```
+
+Contract behavior in V3:
+
+- Non-default producer calls without prior `configure({ requestId })` throw `ProducerClientNotInitializedError`.
+- `allowedHeaders` / `request` / `setDomain` are isolated by `requestId`.
+- In Node runtime, incoming request headers are only forwarded for the legacy `default` producer path.
+- Non-default producer calls emit operation context and trace correlation headers:
+  - `x-operation-id`
+  - `x-modernjs-bff-operation-context`
+  - `traceparent` (with parsed `traceId` / `spanId` reflected in operation context when present)
+
+### 3) `server.telemetry` standardization and exporters
+
+UltraModern.js V3 adds a unified telemetry contract:
+
+- Config surface in `server.telemetry`.
+- Internal registry with sampling, batching, redaction, backpressure handling.
+- Built-in exporters for OTLP and VictoriaMetrics.
+- Metrics wrapper that mirrors `emitCounter` / `emitTimer` into telemetry envelopes.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    telemetry: {
+      enabled: true,
+      service: 'erp-gateway',
+      module: 'server',
+      environment: 'production',
+      samplingRate: 1,
+      flushIntervalMs: 1000,
+      maxBatchSize: 50,
+      maxQueueSize: 1000,
+      redactionKeys: ['authorization', 'token'],
+      exporters: {
+        otlp: {
+          enabled: true,
+          endpoint: 'http://otel-collector:4318/v1/logs',
+        },
+        victoriaMetrics: {
+          enabled: true,
+          endpoint: 'http://vm:8428/api/v1/import/prometheus',
+          metricPrefix: 'ultramodern',
+        },
+      },
+    },
+  },
+});
+```
+
+Important V3 behavior:
+
+- If no exporter is enabled, telemetry pipeline is not initialized.
+- Exporter failures are treated as non-fatal for request handling.
+
+### 4) Trace tags in SSR metrics
+
+When an incoming request contains W3C `traceparent`, UltraModern.js V3 parses and injects:
+
+- `trace_id`
+- `span_id`
+
+into SSR metric tags, improving correlation between app metrics and distributed tracing backends.
+
+### 5) App-level MF SSR stable contract (`server.ssr.moduleFederationAppSSR`)
+
+UltraModern.js V3 adds:
+
+- Preferred flag: `server.ssr.moduleFederationAppSSR` (also works under `server.ssrByEntries`).
+- Global compile-time env:
+  - `process.env.MODERN_MF_APP_SSR` (`'true' | 'false'`)
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      moduleFederationAppSSR: true,
+    },
+  },
+});
+```
+
+When MF SSR markers are detected in server-rendered entries, V3 now enables the same env/bridge contract path by default and keeps config/env switches as explicit opt-out controls.
+
+### 6) Contract-level test hardening in V3
+
+UltraModern.js V3 adds dedicated coverage for:
+
+- RsDoctor default behavior and opt-out semantics.
+- BFF `requestId` generation/runtime isolation and fail-fast checks.
+- Telemetry redaction/backpressure/exporter behavior.
+- SSR MF contract detection and env injection.
+
+### 7) Module SDK contract + boundary anti-pattern guards
+
+UltraModern.js V3 adds platform-boundary enforcement artifacts for module onboarding:
+
+- Contract artifact: `docs/super-app-rfc-adr/contracts/module-sdk-contracts.json`
+- Example manifest: `docs/super-app-rfc-adr/contracts/module-manifest.example.json`
+- Public type contracts: `packages/toolkit/types/common/moduleSdk.d.ts`
+- Validation tooling:
+  - `scripts/module-sdk-contracts/validate-module-sdk-contracts.js`
+  - `scripts/boundary-guards/check-boundary-violations.js`
+- CI workflow:
+  - `.github/workflows/boundary-anti-patterns.yml`
+  - `.github/workflows/module-certification-gates.yml`
+  - `.github/workflows/bun-superapp-smoke.yml`
+
+### 8) Default precompression + precompressed static serving
+
+UltraModern.js V3 changes default output and serving behavior for production web assets:
+
+- `output.precompress` defaults to `true` in app-tools config.
+- Build emits gzip (`.gz`) and brotli (`.br`) variants for static assets.
+- Node static middleware selects precompressed variants via `Accept-Encoding` and sets:
+  - `Content-Encoding`
+  - `Vary: Accept-Encoding`
+- Codec-level tuning is supported per project (`gzip` / `brotli` options).
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    precompress: {
+      gzip: true,
+      brotli: {
+        threshold: 8 * 1024,
+      },
+    },
+  },
+});
+```
+
+### 9) First-class TanStack Router + Tailwind scaffolding
+
+UltraModern.js V3 adds a first-class TanStack path in runtime and project scaffolding:
+
+- Runtime/CLI support for TanStack route tree generation and SSR/stream integration.
+- Create templates include TanStack-ready scaffolds and Tailwind starter wiring.
+- Dedicated integration suites cover:
+  - `tests/integration/routes-tanstack`
+  - `tests/integration/routes-tanstack-mf`
+- Existing React Router workflow remains supported.
+
+### 10) Effect-first MF data reliability and data-platform contracts
+
+UltraModern.js V3 shipped additional reliability work aligned to Beads stream D:
+
+- `@modern-js/plugin-bff` runtime path migrated to Effect v4.
+- Effect-only MF data-fetch contract guidance (explicitly no Zod layer in this stream).
+- MF reliability matrix includes deterministic failure injection (timeout/network/contract error).
+- Distributed trace continuity checks were re-enabled for build and serve paths.
+- Data-platform architecture defines operation identity, envelope integrity, scoped invalidation, and trace propagation contracts.
+
+Reference materials:
+
+- `docs/super-app-rfc-adr/ADR-0003-effect-only-mf-data-fetch-reliability.md`
+- `packages/cli/plugin-bff/docs/data-platform-architecture.md`
+- `tests/integration/routes-tanstack-mf/test/remote-loader-reliability.test.ts`
+
+### 11) Release and module certification gate model
+
+This public UltraModern preset profile includes a machine-verifiable gate model beyond baseline Modern.js V3:
+
+- Gate profiles:
+  - `scripts/release-gates/rc-contract-profile.json`
+  - `scripts/release-gates/module-certification-profile.json`
+- Required evidence contracts under:
+  - `docs/super-app-rfc-adr/evidence/release-candidate/current`
+  - `docs/super-app-rfc-adr/evidence/module-certification/current`
+- Local validation commands:
+  - `pnpm run validate:module-sdk-contracts`
+  - `pnpm run validate:boundary-guards`
+  - `pnpm run validate:module-certification-gates`
+  - `pnpm run validate:rc-gates`
+  - `pnpm run validate:bun-smoke`
+- CI workflows:
+  - `.github/workflows/release-contract-gates.yml`
+  - `.github/workflows/module-certification-gates.yml`
+  - `.github/workflows/bun-superapp-smoke.yml`
+- Generated starter workflow:
+  - `.github/workflows/ultramodern-gates.yml`
+  - runs `pnpm run ultramodern:check` and `pnpm run build`
+
+## Not Part of UltraModern.js V3
+
+The following are intentionally out of scope for this public V3 preset profile:
+
+- Forcing Effect-only data-fetch runtime as the mandatory default for every app.
+- Forcing app-level MF SSR for every app regardless of readiness.
+
+## Micro Vertical Delivery Path
+
+`presetUltramodern(...)` is also the single public entrypoint for Micro Verticals. The intended adoption sequence is:
+
+1. start with one app and keep route/data ownership inside the shell,
+2. extract stable route subtrees into MF remotes once fallback and compatibility behavior are explicit,
+3. extract shared workflows into strict Effect services when request, identity, locale, and trace context must survive deployment boundaries,
+4. keep Hono only as an explicit compatibility lane for existing Modern.js-style BFF handlers.
+
+In this repo, the reference examples are:
+
+- `routes-tanstack-mf` for shell + remote composition and MF SSR contracts,
+- `bff-corss-project` for cross-project producer/consumer wiring,
+- `bff-runtime-parity` for generated-client build/serve parity,
+- `bff-hono` for the compatibility lane.
+
+## Baseline Switches (Opt-out)
+
+The generated `presetUltramodern(...)` create template enables stricter platform contracts. These env switches are read by generated `modern.config.ts` and can be disabled/overridden per app or per environment:
+
+- `MODERN_BASELINE_ENABLE_MF_SSR` (default: `true`): Enables app-level MF SSR baseline contract (`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`). Disable when the app does not use app-level MF SSR, or when you need plain SSR/CSR behavior first.
+- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` (default: `true`): Enables default BFF producer identity contract (`bff.requestId`). Disable when the app does not need cross-project producer isolation.
+- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` (default: `true`): Enables telemetry exporters in baseline config. Disable when the environment has no telemetry backend yet.
+- `MODERN_BASELINE_APP_ID` (default: `basename(process.cwd())`): Overrides baseline `bff.requestId` identity. Set this when you need a fixed platform-wide producer ID convention.
+- `MODERN_TELEMETRY_OTLP_ENDPOINT` (default: `http://127.0.0.1:4318/v1/logs`): OTLP exporter endpoint. Override when you route telemetry through a different collector endpoint.
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT` (default: `http://127.0.0.1:8428/api/v1/import/prometheus`): VictoriaMetrics exporter endpoint. Override when you use a different VM ingress endpoint.
+- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP` (default: `true`): Fails startup if configured exporters fail startup health checks. Disable in local/dev environments where temporary telemetry outage should not block boot.
+
+## Related Public Docs
+
+- [performance.rsdoctor](/configure/app/performance/rsdoctor)
+- [server.ssr](/configure/app/server/ssr)
+- [BFF guide](/guides/advanced-features/bff/index)
+- [BFF frameworks](/guides/advanced-features/bff/frameworks)
+- [BFF data platform architecture](/guides/advanced-features/bff/data-platform)
+- [BFF Effect runtime config](/configure/app/bff/effect)
+- [Micro-frontend guide](/guides/topic-detail/micro-frontend/c01-introduction)
+- [Module Federation SSR](/guides/topic-detail/module-federation/ssr)

package/main-doc/docs/zh/guides/get-started/ultramodern.mdx

@@ -0,0 +1,304 @@
+---
+title: UltraModern.js V3
+sidebar_position: 6
+---
+
+# UltraModern.js V3 与 Modern.js V3 的完整差异
+
+UltraModern.js V3 记录的是一套“更强默认值的 Modern.js 参考档案”，目标是服务于大型、可独立部署的 Super App / ERP 场景。
+
+本文是这套已文档化 V3 档案的完整公开差异说明。
+
+## 范围（仅 V3）
+
+- 基线版本：Modern.js `release-v3.x`。
+- 覆盖范围：UltraModern.js V3 已落地的全部用户可见差异。
+- 不包含：未进入 V3 发布线的主线路线图能力。
+
+## 完整差异矩阵（V3）
+
+| 领域 | Modern.js V3 基线 | UltraModern.js V3 差异 | V3 状态 | 备注 |
+| --- | --- | --- | --- | --- |
+| 构建诊断默认行为 | 大多数项目中 RsDoctor 为显式开启 | Rspack 生产构建默认开启 RsDoctor | 已实现 | 可通过 `performance.rsdoctor` 关闭 |
+| 构建诊断配置面 | 框架文档无 `performance.rsdoctor` | 新增 `performance.rsdoctor`（`boolean` 或 `{ enabled, disableClientServer, reportDir, mode }`） | 已实现 | `disableClientServer` 默认 `true` |
+| 诊断产物契约 | 无标准化机器可读诊断入口 | 新增 `.rsdoctor/ultramodern-diagnostics.json`，用于定位 manifest | 已实现 | 便于编码代理稳定消费诊断数据 |
+| 静态资源预压缩默认行为 | 预压缩产物与回源策略通常由业务自定义 | 生产 Web 构建默认开启 `output.precompress`，并在 Node 静态中间件按 `Accept-Encoding` 协商 `.br` / `.gz` | 已实现 | 可按 codec 关闭或细调 |
+| 路由运行时选型 | 默认运行时路径以 React Router 为中心 | 新增 TanStack Router 运行时与 CLI 路由树支持 | 已实现 | React Router 路径仍保留 |
+| 脚手架模板选型 | 默认 create 模板以 React Router 起步路径为中心 | 新增 TanStack-ready 与 Tailwind-ready 的 create 模板 | 已实现 | React Router 起步路径仍保留 |
+| Starter 预设 Gate 工作流 | 生成脚手架默认没有 UltraModern 预设校验工作流 | 在公开预设 starter 中新增 `ultramodern:check`、可关闭 env 开关与 `.github/workflows/ultramodern-gates.yml` | 已实现 | 让生成应用从第一笔提交起就可审计 |
+| BFF Producer 契约标识 | `bff` 配置不包含 producer 身份 | 新增 `bff.requestId`，并打通到客户端生成链路 | 已实现 | 支持显式 producer 隔离 |
+| BFF 生成客户端签名 | `createRequest(...)` 可选参数到 `fetch` 结束 | 配置 `requestId` 时，生成代码会附加 `requestId` 参数 | 已实现 | 未配置时保持兼容旧路径 |
+| `create-request` 运行时隔离 | 单一可变请求配置 | 以 `requestId` 为维度隔离 request/domain/header 配置 | 已实现 | 支持同一应用多 producer |
+| BFF 审计关联 Header | 缺少标准化 producer 操作/追踪上下文透传 | 新增 `x-operation-id`、`x-modernjs-bff-operation-context` 与 `traceparent` 传播并解析 trace 标识 | 已实现 | 便于租户/操作/追踪链路关联观测 |
+| 未初始化 producer 行为 | 缺失配置时可能隐式 fallback | 非默认 `requestId` 未初始化会抛 `ProducerClientNotInitializedError` | 已实现 | 跨项目 BFF fail-fast |
+| Node 侧透传 Header 行为 | Header 透传是全局路径 | 仅 `requestId === 'default'` 会透传入站请求头 | 已实现 | 避免 producer 间请求头串扰 |
+| 服务端 Telemetry 配置 | 缺少统一 `server.telemetry` 契约 | 新增 `server.telemetry`（采样/批处理/脱敏/导出器） | 已实现 | 同步扩展 app-tools schema 与 server types |
+| Telemetry 导出器 | 导出链路依赖业务自建 | 内置 OTLP 与 VictoriaMetrics 导出器 | 已实现 | 导出失败不会中断请求链路 |
+| Telemetry 背压契约 | 无统一队列策略 | 内置队列上限、丢弃计数、定时 flush | 已实现 | 背压时上报 `telemetry.queue.dropped` |
+| Metrics 与 Trace 关联 | SSR metrics 不解析 W3C trace 上下文 | 解析 `traceparent` 并注入 `trace_id` / `span_id` 标签 | 已实现 | 提升跨系统观测关联度 |
+| 应用级 MF SSR 合约开关 | 无专门 app-level MF SSR 稳定性契约开关 | 新增 `server.ssr.moduleFederationAppSSR`，并在检测到 MF SSR 标记时自动启用环境变量握手 | 已实现 | 注入 `process.env.MODERN_MF_APP_SSR` |
+| 应用级 MF SSR 运行时桥接 | 非稳定默认桥接路径 | V3 在「服务端渲染 + MF 标记」场景下提供稳定桥接默认行为 | 已实现 | 保留显式关闭路径 |
+| MF 远程加载可靠性契约 | 远程加载重试/降级策略通常由业务自管 | 新增 timeout/network/contract-error 的确定性降级矩阵与分布式 OTEL 连续性断言 | 已实现 | 对应 `routes-tanstack-mf` 可靠性套件 |
+| BFF 运行时选型 | Modern.js V3 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-only MF 数据契约与 failure-injection 覆盖 | 已实现（Effect 默认 + 严格拆分） | 该流明确不引入 Zod |
+| 模块 SDK 合约产物 | 无框架级模块契约产物 | 新增机器可读模块家族契约与类型化模块 SDK 接口 | 已实现 | `module-sdk-contracts.json` + `moduleSdk.d.ts` |
+| 边界反模式 CI 守卫 | 无专门边界反模式工作流 | 新增基于 profile 的边界检查（导入边界/必需钩子/模块禁用模式） | 已实现 | `.github/workflows/boundary-anti-patterns.yml` |
+| 发布 / 模块认证 Gate 自动化 | 基线无 super-app 证据化 gate profile | 新增 RC + 模块认证 gate profile、证据元数据校验与专用 CI 工作流 | 已实现 | `.github/workflows/release-contract-gates.yml` + 模块/Bun gate 工作流 |
+| 合约测试覆盖 | 基线中无上述差异项配套测试 | 增加 RsDoctor、BFF requestId、Telemetry、SSR MF 合约环境变量的针对性测试 | 已实现 | 降低 super-app 场景回归风险 |
+| 公开文档面 | 无 UltraModern V3 差异总览页 | 新增 V3 专用差异页并补齐关联配置文档 | 已实现 | 本页作为这套公开预设档案的参考页 |
+
+## V3 详细差异说明
+
+### 1) `performance.rsdoctor` 与默认开启诊断
+
+UltraModern.js V3 扩展了性能配置：
+
+- `performance.rsdoctor: boolean | { enabled?: boolean; disableClientServer?: boolean; reportDir?: string; mode?: 'normal' | 'brief' | 'lite' }`
+- Rspack + 生产环境：默认开启。
+- Rspack + 开发环境：默认关闭（可显式开启）。
+- Webpack 构建：不会注入 RsDoctor 插件。
+- RsDoctor 契约产物：
+  - `<reportDir 或 outputPath>/.rsdoctor/ultramodern-diagnostics.json`
+  - 用于指向 `.rsdoctor/manifest.json`
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+      disableClientServer: true,
+      reportDir: './artifacts',
+      mode: 'brief',
+    },
+  },
+});
+```
+
+### 2) 通过 `requestId` 强化跨项目 BFF 契约
+
+UltraModern.js V3 在 BFF 工具链中引入显式 producer 身份：
+
+- `bff.requestId` 配置项。
+- Loader/客户端生成链路将 `requestId` 传递给 `createRequest(...)`。
+- `create-request` 运行时以 `requestId` 为粒度隔离状态。
+
+```ts
+configure({
+  requestId: 'erp-inventory',
+  request: customFetch,
+  setDomain: ({ target, requestId }) =>
+    target === 'server'
+      ? `http://inventory-bff.internal`
+      : `https://inventory.example.com`,
+});
+```
+
+V3 合约行为：
+
+- 非默认 `requestId` 若未先 `configure({ requestId })`，会抛出 `ProducerClientNotInitializedError`。
+- `allowedHeaders` / `request` / `setDomain` 都按 `requestId` 隔离。
+- Node 运行时仅在 legacy 的 `default` producer 路径透传入站请求头。
+- 非默认 producer 调用会自动携带操作与追踪关联 Header：
+  - `x-operation-id`
+  - `x-modernjs-bff-operation-context`
+  - `traceparent`（存在时会在 operation context 中反映 `traceId` / `spanId`）
+
+### 3) `server.telemetry` 标准化与导出器
+
+UltraModern.js V3 新增统一 telemetry 契约：
+
+- 在 `server.telemetry` 提供配置面。
+- 内置 registry，支持采样、批处理、脱敏、背压控制。
+- 内置 OTLP 与 VictoriaMetrics 导出器。
+- 对 `emitCounter` / `emitTimer` 自动镜像 telemetry envelope。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    telemetry: {
+      enabled: true,
+      service: 'erp-gateway',
+      module: 'server',
+      environment: 'production',
+      samplingRate: 1,
+      flushIntervalMs: 1000,
+      maxBatchSize: 50,
+      maxQueueSize: 1000,
+      redactionKeys: ['authorization', 'token'],
+      exporters: {
+        otlp: {
+          enabled: true,
+          endpoint: 'http://otel-collector:4318/v1/logs',
+        },
+        victoriaMetrics: {
+          enabled: true,
+          endpoint: 'http://vm:8428/api/v1/import/prometheus',
+          metricPrefix: 'ultramodern',
+        },
+      },
+    },
+  },
+});
+```
+
+V3 重要行为：
+
+- 若没有启用任何导出器，telemetry 管线不会初始化。
+- 导出器异常按非致命处理，不会阻断请求主链路。
+
+### 4) SSR metrics 的 Trace 标签注入
+
+当请求携带 W3C `traceparent` 时，UltraModern.js V3 会在 SSR metrics 标签中注入：
+
+- `trace_id`
+- `span_id`
+
+用于提升应用指标与分布式追踪系统之间的关联能力。
+
+### 5) 应用级 MF SSR 稳定契约（`server.ssr.moduleFederationAppSSR`）
+
+UltraModern.js V3 新增：
+
+- 首选开关：`server.ssr.moduleFederationAppSSR`（`server.ssrByEntries` 同样生效）。
+- 编译期全局变量：
+  - `process.env.MODERN_MF_APP_SSR`（`'true' | 'false'`）
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      moduleFederationAppSSR: true,
+    },
+  },
+});
+```
+
+当检测到 MF SSR 标记且启用了服务端渲染时，V3 会自动进入同一套稳定合约路径；如需灰度，可通过配置/环境变量显式关闭。
+
+### 6) V3 的合约级测试加固
+
+UltraModern.js V3 新增了以下关键测试覆盖：
+
+- RsDoctor 默认行为与显式开关。
+- BFF `requestId` 生成与运行时隔离、fail-fast 行为。
+- Telemetry 脱敏、背压与导出器行为。
+- SSR 分阶段契约识别与环境变量注入。
+
+### 7) 模块 SDK 合约与边界反模式守卫
+
+UltraModern.js V3 新增用于模块准入与平台边界治理的产物：
+
+- 模块契约产物：`docs/super-app-rfc-adr/contracts/module-sdk-contracts.json`
+- 模块 manifest 示例：`docs/super-app-rfc-adr/contracts/module-manifest.example.json`
+- 类型契约：`packages/toolkit/types/common/moduleSdk.d.ts`
+- 校验工具：
+  - `scripts/module-sdk-contracts/validate-module-sdk-contracts.js`
+  - `scripts/boundary-guards/check-boundary-violations.js`
+- CI 工作流：
+  - `.github/workflows/boundary-anti-patterns.yml`
+  - `.github/workflows/module-certification-gates.yml`
+  - `.github/workflows/bun-superapp-smoke.yml`
+
+### 8) 默认预压缩与预压缩静态资源回源
+
+UltraModern.js V3 调整了生产 Web 产物的默认行为：
+
+- app-tools 默认 `output.precompress: true`。
+- 构建阶段会产出 gzip（`.gz`）与 brotli（`.br`）静态资源。
+- Node 静态中间件按 `Accept-Encoding` 协商并设置：
+  - `Content-Encoding`
+  - `Vary: Accept-Encoding`
+- 支持按项目维度细调 `gzip` / `brotli` 选项。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    precompress: {
+      gzip: true,
+      brotli: {
+        threshold: 8 * 1024,
+      },
+    },
+  },
+});
+```
+
+### 9) TanStack Router + Tailwind 一等支持
+
+UltraModern.js V3 在运行时与脚手架层面补齐了 TanStack 路径：
+
+- 运行时/CLI 支持 TanStack 路由树生成与 SSR/stream 集成。
+- Create 模板补齐 TanStack 与 Tailwind 初始化能力。
+- 配套集成测试覆盖：
+  - `tests/integration/routes-tanstack`
+  - `tests/integration/routes-tanstack-mf`
+- 既有 React Router 工作流继续保持可用。
+
+### 10) Effect-first MF 数据可靠性与数据平台契约
+
+UltraModern.js V3 对应 Beads Stream D 落地了额外可靠性能力：
+
+- `@modern-js/plugin-bff` 运行时路径迁移到 Effect v4。
+- MF 数据拉取契约采用 Effect-only 指导（该流明确不引入 Zod）。
+- 远程加载可靠性矩阵覆盖 timeout/network/contract error 的确定性注入场景。
+- build 与 serve 路径重新启用分布式 trace 连续性断言。
+- 数据平台架构补齐 operation identity、请求/水合 envelope 完整性、scope key 与失效路由契约。
+
+参考资料：
+
+- `docs/super-app-rfc-adr/ADR-0003-effect-only-mf-data-fetch-reliability.md`
+- `packages/cli/plugin-bff/docs/data-platform-architecture.md`
+- `tests/integration/routes-tanstack-mf/test/remote-loader-reliability.test.ts`
+
+### 11) 发布与模块认证 Gate 模型
+
+这套公开 UltraModern 预设在基线 Modern.js V3 之外补齐了可机审的发布 gate：
+
+- Gate profile：
+  - `scripts/release-gates/rc-contract-profile.json`
+  - `scripts/release-gates/module-certification-profile.json`
+- 证据目录契约：
+  - `docs/super-app-rfc-adr/evidence/release-candidate/current`
+  - `docs/super-app-rfc-adr/evidence/module-certification/current`
+- 本地校验命令：
+  - `pnpm run validate:module-sdk-contracts`
+  - `pnpm run validate:boundary-guards`
+  - `pnpm run validate:module-certification-gates`
+  - `pnpm run validate:rc-gates`
+  - `pnpm run validate:bun-smoke`
+- CI 工作流：
+  - `.github/workflows/release-contract-gates.yml`
+  - `.github/workflows/module-certification-gates.yml`
+  - `.github/workflows/bun-superapp-smoke.yml`
+- 生成 starter 自带工作流：
+  - `.github/workflows/ultramodern-gates.yml`
+  - 默认执行 `pnpm run ultramodern:check` 与 `pnpm run build`
+
+## 不属于 UltraModern.js V3 的能力
+
+以下能力刻意不纳入这套公开 V3 预设档案：
+
+- 将应用级 MF SSR 强制为所有应用的默认路径。
+- 将 Effect-only 数据获取运行时强制为所有应用的默认路径。
+
+## 基线开关（可按需关闭）
+
+生成的 `presetUltramodern(...)` create 模板会开启更严格的平台契约。以下环境变量会在生成的 `modern.config.ts` 中读取，可按应用或按环境关闭/覆盖：
+
+- `MODERN_BASELINE_ENABLE_MF_SSR`（默认：`true`）：开启应用级 MF SSR 基线契约（`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`）。应用不使用 app-level MF SSR 或希望先走普通 SSR/CSR 路径时可关闭。
+- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`（默认：`true`）：开启默认 BFF producer 身份契约（`bff.requestId`）。应用不需要跨项目 producer 隔离时可关闭。
+- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS`（默认：`true`）：在基线配置中启用 telemetry 导出器。当前环境还没有 telemetry 后端时可关闭。
+- `MODERN_BASELINE_APP_ID`（默认：`basename(process.cwd())`）：覆盖基线 `bff.requestId` 身份。需要固定、可治理的统一 producer ID 命名时建议设置。
+- `MODERN_TELEMETRY_OTLP_ENDPOINT`（默认：`http://127.0.0.1:4318/v1/logs`）：OTLP 导出端点。接入其他 OTLP collector 地址时覆盖。
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT`（默认：`http://127.0.0.1:8428/api/v1/import/prometheus`）：VictoriaMetrics 导出端点。接入其他 VM 写入地址时覆盖。
+- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP`（默认：`true`）：导出器健康检查失败时启动即失败（fail-loud）。本地/开发环境希望 telemetry 故障不阻断启动时可关闭。
+
+## 相关公开文档
+
+- [performance.rsdoctor](/configure/app/performance/rsdoctor)
+- [server.ssr](/configure/app/server/ssr)
+- [BFF 指南](/guides/advanced-features/bff/index)
+- [BFF 运行时框架](/guides/advanced-features/bff/frameworks)
+- [BFF Data Platform 架构](/guides/advanced-features/bff/data-platform)
+- [BFF Effect 运行时配置](/configure/app/bff/effect)
+- [微前端指南](/guides/topic-detail/micro-frontend/c01-introduction)
+- [Module Federation SSR](/guides/topic-detail/module-federation/ssr)