@finesoft/front 0.1.76 → 0.1.78

package/docs/zh/09-server-and-deployment.md

@@ -0,0 +1,242 @@
+# 9. 服务器与部署
+
+框架的服务端。本章覆盖：
+
+- Vite 插件（`finesoftFrontViteConfig`）—— dev server、构建配置、代码生成
+- `createServer` —— 独立的 Hono 服务器
+- Proxy 路由 —— 带 SSRF / 二进制完整性守卫的声明式 API 转发
+- Adapter —— Node、Vercel、Cloudflare、Netlify、静态
+
+## Vite 插件
+
+```ts
+// vite.config.ts
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [
+        // ... 视图层插件（Vue/React/Svelte）
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+            i18n: { messagesDir: "src/locales" },
+            proxies: [{ prefix: "/api", target: "https://upstream.example" }],
+            adapter: "auto",
+            isr: { routes: ["/blog/*"], ttl: 300 },
+        }),
+    ],
+});
+```
+
+### 选项
+
+| 选项               | 类型                      | 说明                                        |
+| ------------------ | ------------------------- | ------------------------------------------- |
+| `ssr.entry`        | `string`                  | SSR 入口路径（默认 `src/ssr.ts`）。         |
+| `i18n.messagesDir` | `string`                  | 含 `{locale}.json` 文件的目录（默认关闭）。 |
+| `proxies`          | `ProxyRouteConfig[]`      | 声明式 API 转发。详见下文。                 |
+| `adapter`          | `"auto" \| "node" \| ...` | 目标平台。`"auto"` 从环境变量检测。         |
+| `isr`              | `{ routes, ttl }`         | Prerendered 路由的 ISR。                    |
+
+### 它做什么
+
+Dev：
+
+- 启动 Hono 服务器，每个请求都跑你的 SSR 入口
+- 通过 Vite 模块图热重载 SSR 代码
+- 本地服务 proxy 路由，让客户端 `fetch("/api/...")` 能跑通
+
+Build：
+
+- 用 Vite 标准管线打包客户端 bundle
+- 把 SSR 入口打包成独立模块
+- 生成 adapter 特定的入口文件（`vercel.func`、`_worker.js`、`node-server.js` 等）
+- 把 `renderMode: "prerender"` 的路由预渲染成静态 HTML
+
+## `createServer` —— 独立 Hono 服务器
+
+Node 部署和测试时，框架导出一个函数给你一个开箱即用的 Hono app：
+
+```ts
+import { createServer } from "@finesoft/front";
+
+const app = createServer({
+    ssrEntry: "./dist/server/ssr.js",
+    proxies: [{ prefix: "/api", target: "https://upstream.example" }],
+    staticDir: "./dist/client",
+    isr: { routes: ["/blog/*"], ttl: 300 },
+});
+
+// app 是 Hono 实例 —— 按你的运行时方式挂载
+import { serve } from "@hono/node-server";
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+### 包含什么
+
+- 客户端 bundle 的静态文件服务
+- 所有 proxy 路由（通过 `registerProxyRoutes` 注册）
+- 带完整中间件管线的 SSR 渲染
+- prerendered 路由的 ISR 缓存
+- 从 `Accept-Language` 解析 locale
+
+## Proxy 路由
+
+带内置 SSRF 保护、二进制安全转发、可配置 auth/cache 的声明式 API 转发。
+
+### 基础配置
+
+```ts
+proxies: [
+    {
+        prefix: "/api",                    // 必须以 / 开头
+        target: "https://api.example.com", // 必须以 https:// 或 http:// 开头
+    },
+],
+```
+
+现在 `GET /api/users/42` → `GET https://api.example.com/users/42`。query 参数和请求头都转发。
+
+### 完整选项
+
+```ts
+{
+    prefix: "/api/apple",
+    target: "https://api.music.apple.com",
+    methods: ["get", "post"],                          // 默认 ["all"]
+    headers: { "X-App": "finesoft" },                  // 注入到每个请求
+    auth: { type: "bearer", envKey: "APPLE_TOKEN" },   // 读 process.env.APPLE_TOKEN
+    cache: "public, max-age=60",                       // 响应的 Cache-Control
+    followRedirects: false,                            // 默认 false（redirect: "manual"）
+}
+```
+
+`auth.type`：`"bearer"` → `Authorization: Bearer <token>`。`"basic"` → `Authorization: Basic <token>`。`envKey` 在请求时读取，所以改它（或 unset）不需要重启。
+
+### 框架强制的保证
+
+- **SSRF 保护**：path 包含任何 `%` 编码字符、以 `//` 开头、或含允许字符集之外的字符（`[/\w.\-~%:@!$&'()*+,;=]`）就被拒。解码后 ≠ 原始也拒（防止 `%2F` 走私）。
+- **开放重定向保护**：构造出的目标 URL 必须与配置的 `target` 同 `origin`。不同 origin → `400 Invalid proxy target`。
+- **二进制完整性**：响应 body 通过 `arrayBuffer()` 转发，不用 `text()` —— 精确保留字节。PDF、图片、protobuf 响应与上游响应字节相同。
+- **大小限制**：10 MB。先查 `Content-Length` 头快速拒绝；fetch 后再查实际 body 长度。
+- **HTTP 警告**：任何 `http://` 目标启动时打 warning。生产用 HTTPS。
+
+### 生成的 proxy 代码（serverless / edge）
+
+serverless 函数下，proxy 逻辑可以内联到部署的函数 bundle 而不依赖运行时的 `registerProxyRoutes`。详见 [advanced/inline-proxy-codegen](./advanced/inline-proxy-codegen.md)。
+
+## Adapter
+
+| Adapter        | 目标                       | 构建产物                                                |
+| -------------- | -------------------------- | ------------------------------------------------------- |
+| `"node"`       | 独立 Node.js 服务器        | `dist/server/index.js` —— `serve({ fetch: app.fetch })` |
+| `"vercel"`     | Vercel Build Output API v3 | `.vercel/output/` 含 `functions/` 和 `static/`          |
+| `"cloudflare"` | Cloudflare Workers         | `dist/_worker.js` + `dist/_routes.json`                 |
+| `"netlify"`    | Netlify Functions v2       | `netlify/functions/` + `_redirects`                     |
+| `"static"`     | 预渲染静态文件             | 只有 `dist/client/`（无服务器）                         |
+| `"auto"`       | 构建期自动检测             | 按环境变量挑上面之一                                    |
+
+### 自动检测
+
+`adapter: "auto"` 按顺序检查：
+
+1. `VERCEL=1` → vercel
+2. `CF_PAGES=1` → cloudflare
+3. `NETLIFY=1` → netlify
+4. 否则 → node
+
+对大多数 CI 环境管用 —— Vercel / Cloudflare / Netlify 构建期都自动设置这些。
+
+## ISR（增量静态再生成）
+
+```ts
+isr: {
+    routes: ["/blog/*", "/products/*"],
+    ttl: 300,  // 秒
+}
+```
+
+工作原理：
+
+1. `/blog/hello-world` 的首次请求：完整渲染、缓存 HTML、过期时间设为 now + 300s
+2. TTL 内的后续请求：直接服务缓存的 HTML
+3. 过期后：下个请求触发重渲染；并发请求拿到陈旧 HTML 直到重渲染完成
+
+缓存按服务器实例存内存。多实例部署且一致性重要时，前置 CDN 用 HTTP `Cache-Control` 头。
+
+`isr.routes` 不匹配的路由总是新渲染。
+
+### 缓存失效
+
+公共 API 不暴露程序化失效。要强制刷新：
+
+- 重启服务器（丢整个缓存）
+- 等 TTL
+- 加 Controller 能忽略但能绕过缓存 key 的 cache-bust query 参数
+
+生产把失效推到 CDN 层 —— 框架的内存缓存为单实例服务而设。
+
+## 自定义 Hono 中间件
+
+如果你需要 proxy 和 SSR 之外的服务端逻辑（如 webhook、健康检查），挂到同一个 Hono app 上：
+
+```ts
+const app = createServer({ ssrEntry: "./dist/server/ssr.js" });
+
+app.get("/health", (c) => c.json({ status: "ok" }));
+app.post("/webhook", async (c) => {
+    const body = await c.req.json();
+    await handleWebhook(body);
+    return c.json({ ok: true });
+});
+
+// SSR catch-all 由 createServer 最后注册 —— 你的路由优先。
+```
+
+## 环境变量
+
+框架读取：
+
+- `NODE_ENV` —— `"production"` 启用生产专用优化
+- `PROXY_TOKEN` / `BASIC_TOKEN` / 任何 `auth.envKey` —— proxy 鉴权密钥
+- `VERCEL`、`CF_PAGES`、`NETLIFY` —— adapter 自动检测
+
+其他都是你的。通过 `process.env` 直接访问，或在 DI 容器里注册 config 对象：
+
+```ts
+framework.container.register("config", () => ({
+    upstreamUrl: process.env.UPSTREAM_URL ?? "https://api.example.com",
+    sessionSecret: requireEnv("SESSION_SECRET"),
+}));
+```
+
+## 健康检查和优雅关闭
+
+负载均衡器后的 Node 部署：
+
+```ts
+import { serve } from "@hono/node-server";
+
+const app = createServer({
+    /* ... */
+});
+app.get("/health", (c) => c.json({ ok: true }));
+
+const server = serve({ fetch: app.fetch, port: 3000 });
+
+process.on("SIGTERM", () => {
+    server.close(() => {
+        // 如果你拿着 Framework 引用，dispose 它
+        framework.dispose();
+        process.exit(0);
+    });
+});
+```
+
+`framework.dispose()` 递归 dispose 容器、对注册的 recorder/logger 调 `destroy()`、注销所有路由。
+
+## 下一步
+
+- [Feature flags、平台、PWA](./10-features-platform-pwa.md) —— 特性开关、平台检测
+- [工程实践 · CI 与发布流程](./engineering/ci-release-flow.md) —— 自动化发布
+- [陷阱：proxy 二进制载荷](./pitfalls/proxy-binary-payloads.md) —— 为什么 `arrayBuffer` 重要

package/docs/zh/10-features-platform-pwa.md

@@ -0,0 +1,238 @@
+# 10. Feature flags、平台、PWA
+
+三个小而独立的运行时辅助：
+
+- **Feature flags** —— 不重新部署就能变的配置
+- **平台检测** —— 解析 User-Agent 得到 OS / 浏览器 / 引擎
+- **PWA 模式** —— 检测应用是否已安装（standalone）
+
+每个都可替换，每个都可组合自定义 provider。
+
+## Feature flags
+
+```ts
+const framework = Framework.create({
+    featureFlags: {
+        darkMode: true,
+        maxRetries: 3,
+        experimentalCheckout: false,
+    },
+});
+
+const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+flags.get("darkMode"); // true
+flags.get("maxRetries"); // 3
+flags.get("missing"); // undefined
+flags.get("missing", "fallback"); // "fallback"
+```
+
+Flag 值可以是任何 JSON 可序列化的：布尔、字符串、数字、数组、对象。
+
+### 静态配置
+
+最简单的情况 —— flag 跟 bundle 一起发：
+
+```ts
+Framework.create({
+    featureFlags: {
+        darkMode: process.env.NODE_ENV !== "production",
+        analytics: true,
+        cdnUrl: "https://cdn.example.com",
+    },
+});
+```
+
+适用于由环境驱动的 flag，而不是用户属性驱动的。
+
+### 远端 provider
+
+接入从远端服务拉的 provider（LaunchDarkly、GrowthBook、Unleash、自家配置服务）：
+
+```ts
+import { type FeatureFlagsProvider } from "@finesoft/front";
+
+const remoteConfigProvider: FeatureFlagsProvider = {
+    async load() {
+        const resp = await fetch("https://config.example.com/flags");
+        return resp.json(); // { ...flags }
+    },
+};
+
+const framework = Framework.create({
+    featureFlags: {
+        darkMode: false,
+        maxRetries: 3,
+    },
+    featureFlagsProviders: [remoteConfigProvider],
+});
+```
+
+provider 按注册顺序跑。后注册的 provider 对同 key 覆盖之前的值 —— 「后注册者胜」。
+
+### 缓存生命周期
+
+框架在 `Framework.create()` 期间加载一次 provider 值。之后 flag 同步从内存读。
+
+调 `flags.refresh()` 刷新：
+
+```ts
+const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+await flags.refresh(); // 重跑所有 provider
+```
+
+通常按定时器或响应服务端推送事件调。
+
+### 用户级 targeting
+
+内置 flag 是全局的（每个用户同一个值）。需要用户级 targeting 的话，让你的 provider 返回函数，或用单独的评估步骤：
+
+```ts
+class TargetingProvider implements FeatureFlagsProvider {
+    constructor(private userId: string) {}
+    async load() {
+        const resp = await fetch(`https://config.example.com/flags?userId=${this.userId}`);
+        return resp.json();
+    }
+}
+
+// 在 beforeLoad 守卫里按请求注册：
+async function flagsGuard(ctx) {
+    const userId = await getUserIdFromCookie(ctx);
+    const targeting = new TargetingProvider(userId);
+    const flags = await targeting.load();
+    ctx.container.register(DEP_KEYS.FEATURE_FLAGS, () => ({
+        get: (key, fallback) => flags[key] ?? fallback,
+    }));
+    return next();
+}
+```
+
+复杂分桶交给专门的服务（GrowthBook SDK 等），把它的 evaluator 存进 DI。
+
+### SSR / CSR 一致性
+
+服务端评估而浏览器端不重新评估的 flag 会引起 hydration 不匹配。Controller 读 flag 时框架会把 flag 值序列化进 `PrefetchedIntents`。浏览器读到的就是服务端看到的值。
+
+对于*应当*不同的 flag（如 A/B 变体），在 `beforeLoad` 守卫里评估并存到请求 scope 里 —— 服务端和浏览器都会用服务端解析出的值。
+
+## 平台检测
+
+```ts
+import { detectPlatform } from "@finesoft/front";
+
+const info = detectPlatform();
+// {
+//   os: "ios" | "android" | "macos" | "windows" | "linux" | "other",
+//   browser: "safari" | "chrome" | "firefox" | "edge" | ...,
+//   engine: "webkit" | "blink" | "gecko" | "other",
+//   isMobile: boolean,
+//   isTouch: boolean,
+//   isServer: boolean,
+// }
+```
+
+浏览器端 `detectPlatform()` 读 `navigator.userAgent`。服务端框架自动解析请求的 `User-Agent` 头：
+
+```ts
+const platform = framework.getPlatform();
+```
+
+Controller 和守卫从 DI resolve：
+
+```ts
+const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
+if (platform.isMobile) {
+    return rewrite("/m" + ctx.url.pathname);
+}
+```
+
+### 可靠性
+
+User-Agent 字符串会撒谎 —— 每个现代浏览器为了兼容性嵌入了其他浏览器的子串。框架的检测优先匹配众所周知的模式，遇到模糊就回退到 `"other"`。别单纯靠 `browser` 做关键决策：
+
+- ✅ 按 `isMobile` 调整布局
+- ✅ 非 WebKit 浏览器隐藏 Safari 专有特性
+- ❌ 锁定特定浏览器
+- ❌ 按浏览器版本选代码路径
+
+## PWA 检测
+
+```ts
+import { getPWADisplayMode } from "@finesoft/front";
+
+const mode = getPWADisplayMode();
+// "standalone" | "twa" | "browser"
+```
+
+- `"standalone"` —— 作为已安装 PWA 跑（Safari 加到主屏、Chrome install）
+- `"twa"` —— Trusted Web Activity（Android，包装成原生应用）
+- `"browser"` —— 普通浏览器标签
+
+函数读 `window.matchMedia("(display-mode: standalone)")` 和 Android 的 TWA referrer。服务端返回 `"browser"`。
+
+### 常见用途
+
+```ts
+const mode = getPWADisplayMode();
+
+if (mode === "browser") {
+    showInstallBanner();
+}
+
+if (mode === "standalone") {
+    // 自定义导航 —— 已安装的应用不应再显示 install 提示
+    hideInstallButton();
+    enableNativeBackButtonHandling();
+}
+```
+
+### Service worker 注册
+
+PWA install 与 service worker 独立 —— 可以只要一个。注册 service worker：
+
+```ts
+// src/main.ts
+startBrowserApp({
+    bootstrap,
+    mount,
+    onAfterStart() {
+        if ("serviceWorker" in navigator) {
+            navigator.serviceWorker.register("/sw.js");
+        }
+    },
+});
+```
+
+框架不内置 service worker 生成器。用 [Vite PWA](https://vite-pwa-org.netlify.app/) 或手写。
+
+## 组合三者
+
+一个组合三者的常见导航守卫：
+
+```ts
+import { next, rewrite, DEP_KEYS } from "@finesoft/front";
+
+function mobilePwaGuard(ctx) {
+    const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
+    const flags = ctx.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+
+    if (flags.get("mobilePwaRedesign") && platform.isMobile && !ctx.isSsr) {
+        if (getPWADisplayMode() === "standalone") {
+            return rewrite(`/pwa${ctx.url.pathname}`);
+        }
+    }
+    return next();
+}
+```
+
+把已安装移动 PWA 用户路由到不同的页面树，不影响其他用户。
+
+## 注意事项
+
+- **服务端解析出的 flag 会进 HTML。** flag 里别存秘密。
+- **服务端平台检测靠请求头。** 爬虫或 curl 可能没发有用的 User-Agent —— 优雅处理 `"other"`。
+- **服务端 PWA 检测永远返回 `"browser"`。** 不要在 SSR 渲染路径里依赖；按 PWA 模式做条件 UI 应该仅客户端，或用 `<noscript>` 兜底。
+
+## 下一步
+
+- [工程实践 · 项目结构](./engineering/project-structure.md) —— flag config、平台感知代码放哪

package/docs/zh/README.md

@@ -0,0 +1,72 @@
+# `@finesoft/front` 文档
+
+> **语言：** **简体中文**（当前页） · [English](../README.md)
+
+全栈 TypeScript 框架 —— 路由、DI、Action、SSR、服务器，一个包搞定。支持 **Vue**、**React**、**Svelte**。可部署到 Node.js、Vercel、Cloudflare Workers、Netlify 或静态托管。
+
+## 三个入口
+
+按需要选择起点。
+
+### 新手 —— 按顺序读完
+
+线性路径。每章都基于前一章。读完你能构建、渲染并部署一个真实应用。
+
+1. [快速开始](./01-getting-started.md) —— 安装、Vite 配置、第一个页面
+2. [路由与 Controller](./02-routing-and-controllers.md) —— 路由定义、Intent、Controller、渲染模式
+3. [中间件](./03-middleware.md) —— `beforeLoad` / `afterLoad`、redirect / rewrite / deny
+4. [渲染与 Hydration](./04-rendering-and-hydration.md) —— SSR / CSR / Prerender、`PrefetchedIntents`
+5. [国际化](./05-i18n.md) —— `locale`、`Translator`、字典加载、RTL
+6. [HTTP 客户端](./06-http-client.md) —— `HttpClient` 子类化、拦截器、`HttpError`
+7. [DI 容器](./07-di-container.md) —— 注册、scope、`DEP_KEYS`、dispose
+8. [可观测性](./08-observability.md) —— `Logger`、`EventRecorder`、Impression 追踪、`ReportCallback`
+9. [服务器与部署](./09-server-and-deployment.md) —— `createServer`、proxy、adapter、Vite 插件
+10. [Feature flags、平台、PWA](./10-features-platform-pwa.md) —— 特性开关、平台检测、PWA 模式
+
+### 已经在维护项目的工程师 —— 直接看实践
+
+横切关注点和约定。先理解基础后再读。
+
+- [项目结构](./engineering/project-structure.md) —— 推荐布局、`bootstrap.ts` 拆分、单一来源
+- [测试](./engineering/testing.md) —— Controller、中间件、scoped DI、mock 框架
+- [CI 与发布流程](./engineering/ci-release-flow.md) —— changesets、内联发布 workflow、版本对账
+
+### 碰到问题 —— 直接看陷阱
+
+每一篇都是 **症状 → 根因 → 修法**，简短。
+
+- [SSR Hydration 不匹配](./pitfalls/ssr-hydration-mismatch.md)
+- [SSR 与 CSR 的全局变量](./pitfalls/ssr-vs-csr-globals.md)
+- [Redirect 与 Rewrite](./pitfalls/redirect-vs-rewrite.md)
+- [Proxy 二进制载荷](./pitfalls/proxy-binary-payloads.md)
+- [Container scope 泄漏](./pitfalls/container-scope-leak.md)
+- [i18n 包体积](./pitfalls/i18n-bundle-size.md)
+
+### 扩展框架 —— 高阶配方
+
+每个配方都是一个完整、可运行的扩展示例，附说明。
+
+- [自定义 Action handler](./advanced/custom-action-handler.md) —— 超越 `FlowAction` / `ExternalUrlAction`
+- [自定义 Event recorder](./advanced/custom-event-recorder.md) —— 接入 Sentry / Datadog / 自有管线
+- [自定义 adapter](./advanced/custom-adapter.md) —— 适配新平台
+- [内联 proxy 代码生成](./advanced/inline-proxy-codegen.md) —— 为 serverless / edge 生成自包含的 proxy 路由
+- [多租户 scope](./advanced/multi-tenant-scopes.md) —— 按租户隔离 DI 容器
+
+## 一图看懂
+
+```
+URL/Action → Router.resolve()
+          → beforeLoad chain   (NavigationContext: redirect/rewrite/deny/next)
+          → IntentDispatcher   (controller.execute() → Page；出错走 fallback())
+          → afterLoad chain    (PostLoadContext)
+          → render             (SSR: HTML + 序列化的 PrefetchedIntents；CSR: 空壳)
+```
+
+同一个 `bootstrap()` 同时在服务器和浏览器执行。SSR 把 prefetch 后的 intent 结果序列化进 HTML，浏览器再反序列化为 `PrefetchedIntents`，让首次客户端导航复用服务端结果而不重新发请求。
+
+## 约定
+
+- **代码块** 直接可跑，除非注释说明不能。
+- **文件路径** 相对项目根目录（也就是 `vite.config.ts` 所在目录）。
+- **`vp`** 是 [Vite+](https://github.com/voidzero-dev/setup-vp) 的 CLI。用它替代 `pnpm` / `npm` / `vitest` / `tsdown`。
+- **`@finesoft/front`** 是应用代码唯一的导入面。内部包（`core`、`browser`、`ssr`、`server`）打包在内，不对外发布。