@finesoft/front 0.1.75 → 0.1.77

package/docs/zh/02-routing-and-controllers.md

@@ -0,0 +1,197 @@
+# 2. 路由与 Controller
+
+框架的路由层把 URL 映射到 **intent**，把 intent 映射到 **Controller**，Controller 产出 **Page**。本章覆盖这三个概念。
+
+## 心智模型
+
+```
+URL  ──Router.resolve()──▶  RouteMatch { intent, renderMode, guards }
+                                │
+                                ▼
+                       IntentDispatcher.dispatch(intent)
+                                │
+                                ▼
+                         Controller.execute()  →  Page
+```
+
+一条路由定义包含：
+
+- **路径模式**（`/products/:id`）
+- **intent id**（操作的逻辑名；一个 intent 可以对应多条路由）
+- **Controller 实例**（产出页面数据）
+- 可选的**渲染模式**（`ssr` / `csr` / `prerender`）
+- 可选的**守卫**（`beforeLoad` / `afterLoad`）
+
+## 定义路由
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+import { ProductController } from "./lib/controllers/product";
+import { authGuard } from "./lib/guards/auth";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [
+        // 普通 SSR 路由
+        { path: "/", intentId: "home", controller: new HomeController() },
+
+        // 动态参数段
+        { path: "/products/:id", intentId: "product", controller: new ProductController() },
+
+        // 仅 CSR（服务端只返回空壳）
+        {
+            path: "/dashboard",
+            intentId: "dashboard",
+            controller: new DashboardController(),
+            renderMode: "csr",
+        },
+
+        // 构建期静态化
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "prerender",
+        },
+
+        // 受保护路由 —— 复用 home intent，但加守卫
+        {
+            path: "/admin",
+            intentId: "home",
+            controller: new HomeController(),
+            beforeLoad: [authGuard],
+        },
+    ]);
+}
+```
+
+### 路由选项
+
+| 字段         | 类型                             | 说明                                                           |
+| ------------ | -------------------------------- | -------------------------------------------------------------- |
+| `path`       | `string`                         | 路径模式，含 `:param` 占位。结尾的 `/` 会被归一化。            |
+| `intentId`   | `string`                         | 操作的逻辑名。用于注册 Controller。                            |
+| `controller` | `BaseController<TParams, TPage>` | 若 intent 已注册可省略。                                       |
+| `renderMode` | `"ssr" \| "csr" \| "prerender"`  | 默认 `"ssr"`。详见[第 4 章](./04-rendering-and-hydration.md)。 |
+| `beforeLoad` | `BeforeLoadGuard[]`              | Controller 之前执行。详见[第 3 章](./03-middleware.md)。       |
+| `afterLoad`  | `AfterLoadGuard[]`               | Page 产出之后执行。                                            |
+
+### 路径模式
+
+- 静态：`/about`
+- 带参数：`/products/:id`、`/users/:userId/posts/:postId`
+- 尾部通配：`/files/*`
+- **不**支持可选段 —— 写两条路由代替。
+
+参数以字符串键对象的形式传给 `controller.execute(params, container)`。
+
+## 写一个 Controller
+
+```ts
+// src/lib/controllers/product.ts
+import { BaseController, type Container, type HttpClient } from "@finesoft/front";
+
+interface ProductPage {
+    kind: "product";
+    id: string;
+    name: string;
+    price: number;
+}
+
+export class ProductController extends BaseController<{ id: string }, ProductPage> {
+    readonly intentId = "product";
+
+    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
+        const http = container.resolve<HttpClient>("http");
+        const product = await http.get<{ name: string; price: number }>(
+            `/api/products/${params.id}`,
+        );
+        return {
+            kind: "product",
+            id: params.id,
+            name: product.name,
+            price: product.price,
+        };
+    }
+
+    fallback(params: { id: string }, _error: unknown): ProductPage {
+        return { kind: "product", id: params.id, name: "Not available", price: 0 };
+    }
+}
+```
+
+### Controller 契约
+
+| 成员       | 必需 | 用途                                                                        |
+| ---------- | ---- | --------------------------------------------------------------------------- |
+| `intentId` | 是   | 必须与路由的 `intentId` 一致（或与 `IntentDispatcher.register` 调用一致）。 |
+| `execute`  | 是   | 产出页面。接受解析后的路径参数和请求级 DI 容器。                            |
+| `fallback` | 是   | `execute()` 抛错时返回降级页面。必须同步且总能返回。                        |
+
+`BaseController` 把 `execute()` 包在 `try/catch` 里，错误都走 `fallback()`。框架从不让 `dispatch()` 抛错 —— 你的 `fallback()` 是最后一道防线。
+
+### 为什么 `fallback` 是必需的
+
+SSR 期间 `execute()` 抛错本来会让整个请求崩 —— 要么 500，要么渲出空白文档。`fallback()` 让你返回一个结构化的「错误」`Page`，让视图层渲成优雅失败（banner、重试按钮等）。完整模式见 [可观测性 · 错误处理](./08-observability.md#通过-fallback-处理错误)。
+
+## 渲染模式
+
+| 模式          | 服务端返回的内容                 | 适用场景                                    |
+| ------------- | -------------------------------- | ------------------------------------------- |
+| `"ssr"`       | 完整渲染的 HTML + 序列化数据     | 默认。SEO 和 TTFB 敏感的页面。              |
+| `"csr"`       | 空壳 HTML；Controller 在浏览器跑 | 鉴权后的 dashboard、高度个性化的页面。      |
+| `"prerender"` | 部署期生成的静态 HTML            | 营销页、文档、博客。结合 ISR（见第 4 章）。 |
+
+模式是**按路由**配置，可以自由混合。框架在构建期重生成 prerendered 路由；SSR 路由每次请求都执行。
+
+## 不绑路由也能注册 Controller
+
+可以为 intent 注册 Controller 但不暴露成路由。这对只通过 `dispatchAction` 触发的 intent 有用：
+
+```ts
+framework.intentDispatcher.register("checkout", new CheckoutController());
+
+// 别处：
+const page = await framework.intentDispatcher.dispatch({
+    intentId: "checkout",
+    params: { cartId },
+});
+```
+
+路由本质上就是按 URL 索引的 intent dispatch。
+
+## 一个 intent 多个路由
+
+同一个 intent 可以服务不同 URL：
+
+```ts
+defineRoutes(framework, [
+    { path: "/", intentId: "home", controller: new HomeController() },
+    { path: "/welcome", intentId: "home" }, // 复用已注册的 HomeController
+    { path: "/landing/:slug", intentId: "home" }, // 同 intent，参数不同
+]);
+```
+
+避免只是 URL 表面不同就复制 Controller 实例。前面例子里 `/admin` 复用 `home` intent 也是同一个套路。
+
+## 检查解析后的 match
+
+诊断或自定义路由时，可以直接调 `Router.resolve()`：
+
+```ts
+const match = framework.router.resolve("/products/42");
+// {
+//   intent: { intentId: "product", params: { id: "42" } },
+//   action: { kind: "flow", url: "/products/42" },
+//   renderMode: "ssr",
+//   guards: { before: [...], after: [...] },
+// }
+```
+
+未命中返回 `null` —— 在服务端 404 逻辑里处理它。
+
+## 下一步
+
+- [中间件](./03-middleware.md) —— 守卫导航、重定向、拒绝
+- [渲染与 Hydration](./04-rendering-and-hydration.md) —— Controller 产出 Page 之后发生什么

package/docs/zh/03-middleware.md

@@ -0,0 +1,214 @@
+# 3. 中间件
+
+中间件分两个阶段，包在 Controller 周围。守卫检查导航后返回四种结果之一，决定下一步发生什么。
+
+## 管线
+
+```
+Router.resolve()
+     │
+     ▼
+  beforeLoad 链        ← NavigationContext（此时还没有 Page）
+     │
+   next()? ──否──▶ 短路（redirect / rewrite / deny）
+     │ 是
+     ▼
+IntentDispatcher.dispatch()
+     │
+     ▼
+  afterLoad 链         ← PostLoadContext（已有 Page）
+     │
+   next()? ──否──▶ 短路
+     │ 是
+     ▼
+   render
+```
+
+守卫按数组顺序执行。第一个非 `next()` 的结果短路后续链。
+
+## 四种结果
+
+```ts
+import { next, redirect, rewrite, deny } from "@finesoft/front";
+
+next(); // 继续下一个守卫 / dispatcher
+redirect("/login"); // HTTP 302；导航到 URL
+redirect("/old", 301); // HTTP 301（永久）
+rewrite("/canonical"); // beforeLoad 里：内部重路由；afterLoad 里：canonical 信号
+deny(); // 403 Forbidden
+deny(404, "Not found"); // 自定义状态码 + 消息
+```
+
+### `next()`
+
+直通。管线继续。
+
+### `redirect(url, status?)`
+
+浏览器导航到 `url`，原始渲染被丢弃。服务端表现为 HTTP 重定向；浏览器表现为导航（通过 `History.pushState`）。
+
+适用：登录跳转、废弃路径、locale 前缀归一化。
+
+### `rewrite(url)`
+
+**`beforeLoad` 里的 rewrite** —— 内部重路由。Router 改为解析 `url`，_新_ match 的守卫和 Controller 跑。不产生 HTTP 重定向；地址栏保持原 URL。深度限制为 5 层，防死循环。
+
+**`afterLoad` 里的 rewrite** —— canonical 信号。框架在 SSR 响应里包含 `Content-Location` 头，但不重定向。浏览器收到原 URL 加一个提示：存在 canonical 版本。
+
+何时用哪个，见 [redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md)。
+
+### `deny(status?, message?)`
+
+停止请求。默认 `403 Forbidden`。常见：`deny(401, "Login required")`、`deny(404, "Not found")`。
+
+## 写守卫
+
+守卫是从 context 到 `MiddlewareResult`（或 `Promise<MiddlewareResult>`）的函数。
+
+```ts
+// src/lib/guards/auth.ts
+import { next, redirect, type NavigationContext } from "@finesoft/front";
+
+export function authGuard(ctx: NavigationContext) {
+    const token = ctx.getCookie("token");
+    if (!token) {
+        return redirect(`/login?next=${encodeURIComponent(ctx.url.pathname)}`);
+    }
+    return next();
+}
+```
+
+### `NavigationContext`（beforeLoad）
+
+| 字段              | 类型                               | 说明                                    |
+| ----------------- | ---------------------------------- | --------------------------------------- |
+| `url`             | `URL`                              | 完整请求 URL。                          |
+| `intent`          | `Intent`                           | 解析后的 intent，包含路径参数。         |
+| `container`       | `Container`                        | 请求级 DI 容器。                        |
+| `getCookie(name)` | `(name: string) => string \| null` | 读 cookie（服务端 + 浏览器都可用）。    |
+| `getHeader(name)` | `(name: string) => string \| null` | 读请求头（仅服务端；浏览器返回 null）。 |
+| `isSsr`           | `boolean`                          | 服务端 `true`，浏览器 `false`。         |
+
+### `PostLoadContext`（afterLoad）
+
+继承自 `NavigationContext`，新增：
+
+| 字段   | 类型       | 说明                     |
+| ------ | ---------- | ------------------------ |
+| `page` | `BasePage` | Controller 产出的 Page。 |
+
+## 给路由挂守卫
+
+```ts
+defineRoutes(framework, [
+    {
+        path: "/admin",
+        intentId: "admin",
+        controller: new AdminController(),
+        beforeLoad: [authGuard, requireAdminRole],
+        afterLoad: [trackPageView],
+    },
+]);
+```
+
+路由上的守卫**叠加**在框架全局守卫之上（见下）。顺序：先全局，后路由级。
+
+## 全局守卫
+
+注册对每个导航都生效的守卫：
+
+```ts
+framework.middleware.use("beforeLoad", trackingGuard);
+framework.middleware.use("afterLoad", metricsGuard);
+```
+
+慎用。全局守卫每页都跑，包括 SSR —— 慢的全局守卫会乘到整个表面积上。
+
+## 常见模式
+
+### 鉴权
+
+```ts
+function authGuard(ctx: NavigationContext) {
+    const token = ctx.getCookie("session");
+    if (!token) return redirect("/login?next=" + encodeURIComponent(ctx.url.pathname));
+    return next();
+}
+```
+
+### 角色校验
+
+```ts
+async function requireAdmin(ctx: NavigationContext) {
+    const session = await ctx.container.resolve<SessionService>("session").current();
+    if (!session?.isAdmin) return deny(403, "Admin only");
+    return next();
+}
+```
+
+### Locale 前缀重定向
+
+```ts
+function localePrefixGuard(ctx: NavigationContext) {
+    if (/^\/(en|zh|ja)\//.test(ctx.url.pathname)) return next();
+    const detected = detectLocale(ctx); // 你自己的逻辑
+    return redirect(`/${detected}${ctx.url.pathname}`, 301);
+}
+```
+
+### A/B 测试 rewrite
+
+```ts
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    const variant = bucket(ctx.getCookie("uid"));
+    return variant === "B" ? rewrite("/landing-v2") : next();
+}
+```
+
+用户在地址栏看到 `/landing`；服务端渲染 `/landing-v2`。客户端无可见重定向，无闪屏。
+
+### afterLoad 分析
+
+```ts
+function trackPageView(ctx: PostLoadContext) {
+    ctx.container.resolve<EventRecorder>("eventRecorder").record({
+        name: "PageView",
+        fields: { intentId: ctx.intent.intentId, url: ctx.url.pathname },
+    });
+    return next();
+}
+```
+
+## 守卫顺序规则
+
+1. 全局 `beforeLoad` 守卫（注册顺序）
+2. 路由级 `beforeLoad` 守卫（数组顺序）
+3. Controller `execute()`
+4. 全局 `afterLoad` 守卫
+5. 路由级 `afterLoad` 守卫
+
+任一步返回非 `next()` 则停止。后续守卫不再跑。
+
+## 异步守卫
+
+守卫可以 `async`。管线在每个结果之间 await。全局守卫里别 await 太久（会乘到每个请求）。
+
+```ts
+async function rateLimitGuard(ctx: NavigationContext) {
+    const limiter = ctx.container.resolve<RateLimiter>("rateLimiter");
+    const allowed = await limiter.tryConsume(ctx.getCookie("uid") ?? "anon");
+    return allowed ? next() : deny(429, "Too many requests");
+}
+```
+
+## 注意事项
+
+- **守卫对框架状态必须是纯的。** 不要改 `ctx.intent.params` —— 需要改参数就构造新 intent 然后 `rewrite`。
+- **`afterLoad` 里的 `deny()` 会丢弃已产出的页面。** Controller 已经跑过了；deny 只阻断响应。如果 `execute()` 有副作用（写操作），副作用已经发生。
+- **浏览器端守卫拿不到请求头。** `getHeader()` 在客户端返回 `null`。cookie 仍然可用。
+
+## 下一步
+
+- [渲染与 Hydration](./04-rendering-and-hydration.md) —— `afterLoad` 到 HTML 输出之间发生什么
+- [陷阱：redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md) —— 二者之间怎么选

package/docs/zh/04-rendering-and-hydration.md

@@ -0,0 +1,271 @@
+# 4. 渲染与 Hydration
+
+页面从 Controller 输出到字节流再回到活着的浏览器应用要走的路。本章覆盖 SSR、CSR、prerender，以及把两端绑在一起的 `PrefetchedIntents` 机制。
+
+## 三种模式并排比
+
+|                          | SSR                                     | CSR                           | Prerender                               |
+| ------------------------ | --------------------------------------- | ----------------------------- | --------------------------------------- |
+| HTML 何时生成            | 每次请求时在服务端                      | 构建期（仅空壳）              | 构建期，按路由                          |
+| 初始 body                | 完整渲染                                | 空 `<div id="app"></div>`     | 完整渲染                                |
+| Hydration 时需重新请求？ | 不需要（数据在 `PrefetchedIntents` 里） | 需要（Controller 在浏览器跑） | 不需要（数据在 `PrefetchedIntents` 里） |
+| TTFB                     | 一次 Controller 执行                    | 接近零                        | 静态文件直接发                          |
+| 个性化                   | 按请求 OK                               | 最好 —— 完全在客户端跑        | 无（所有人同一份 HTML）                 |
+| SEO                      | 好                                      | 需要支持 JS 的爬虫            | 最好                                    |
+
+模式是**按路由**配置，自由混合。
+
+## SSR 管线
+
+```
+请求 URL
+    │
+    ▼
+Router.resolve()                 → RouteMatch
+    │
+    ▼
+beforeLoad 守卫                  → 可能 rewrite（内部）/ redirect / deny
+    │
+    ▼
+IntentDispatcher.dispatch()      → Page
+    │
+    ▼
+afterLoad 守卫                   → 可能 redirect / deny / 发出 canonical 信号
+    │
+    ▼
+renderApp(page)                  → { html, head, css }
+    │
+    ▼
+injectSSRContent()               → 最终 HTML，含：
+    • 渲染后的 body 放在 <!--ssr--> 里
+    • head 片段放在 <!--head--> 里
+    • 序列化的 PrefetchedIntents 放在 <script> 里
+    • <html lang="..." dir="..."> 属性
+```
+
+### SSR 入口
+
+```ts
+// src/ssr.ts
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { createSSRApp } from "vue";
+import { renderToString } from "vue/server-renderer";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage: () => ({ kind: "error", title: "Something went wrong" }),
+    async renderApp(page) {
+        const app = createSSRApp(App, { page });
+        const html = await renderToString(app);
+        return {
+            html,
+            head: `<title>${escape(page.title)}</title>`,
+            css: "",
+        };
+    },
+});
+
+export { serializeServerData };
+```
+
+Vite 插件和 adapter 替你调用 `render(url, options)`。你返回 `{ html, head, css }`，框架处理注入和序列化。
+
+### `createSSRRender` 替你做了什么
+
+- 服务端跑一次 `bootstrap()`（同一个 worker 内跨请求缓存）
+- 每个请求创建请求级 DI 容器
+- 跑中间件管线
+- 调用你的 `renderApp()` 产出 body
+- 把 prefetched intent 结果序列化进 `<script id="__finesoft_data__">`
+- 根据解析出的 locale 设置 `<html lang dir>`
+- 根据 `deny()` / `redirect()` / `rewrite()` 结果设置 HTTP status
+- `afterLoad` 发出 rewrite 信号时加 `Content-Location` 头
+
+## CSR（客户端渲染）
+
+`renderMode: "csr"` 的路由，服务端返回最小空壳：
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <!-- 这里注入 head -->
+    </head>
+    <body>
+        <div id="app"></div>
+        <!-- 没有 PrefetchedIntents script —— Controller 在浏览器跑 -->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
+```
+
+`startBrowserApp()` 触发首次导航时 Controller 在浏览器跑。CSR 适用：
+
+- 鉴权背后高度个性化的 dashboard
+- SEO 不重要的页面
+- 服务端渲染成本盖过延迟收益的页面
+
+## Prerender（静态 + ISR）
+
+```ts
+{ path: "/about", intentId: "about", controller: new AboutController(), renderMode: "prerender" }
+```
+
+构建期框架：
+
+1. 调 `controller.execute({}, container)`（参数来自静态路径）
+2. 跑 `renderApp()` 产 HTML
+3. 写 `dist/about.html` 到磁盘
+
+adapter 直接服务这些静态文件。请求时不跑 Controller。
+
+### 增量静态再生成（ISR）
+
+打包的服务器（`createServer`）和预览服务器（`vp preview`）支持按需缓存的再生成。通过 `finesoftFrontViteConfig` 配置：
+
+```ts
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    isr: {
+        // 哪些路由按需再生成
+        routes: ["/blog/*"],
+        // 缓存 TTL（秒）
+        ttl: 300,
+    },
+});
+```
+
+过期后的首个请求触发新一轮渲染；并发请求拿到陈旧版本直到新版生成完成。详见 [服务器与部署](./09-server-and-deployment.md#isr)。
+
+## `PrefetchedIntents` —— SSR → CSR 的桥梁
+
+关键机制：**同一个 Controller 在服务器产出页面，浏览器复用结果不重新请求。**
+
+### 工作原理
+
+1. SSR：Controller 跑，返回 `Page`。框架把 `(intentId, paramsKey) → Page` 存入 `PrefetchedIntents` map。
+2. 渲染：map 被 JSON 序列化进 `<script id="__finesoft_data__">{...}</script>`。
+3. 浏览器：`startBrowserApp` 读这个 script，调 `createPrefetchedIntentsFromDom()`，传给 `Framework.create()`。
+4. 浏览器首次导航：`IntentDispatcher.dispatch()` 用 `(intentId, paramsKey)` 查 map —— 命中则直接返回缓存的 `Page`，不调 Controller。
+
+### 稳定 key 生成
+
+查找 key 由 `intentId` + `params` 的**稳定 JSON 字符串化**生成。对象键的顺序不影响 key：
+
+```ts
+// 下面两个产出相同的 paramsKey：
+dispatch({ intentId: "product", params: { id: "42", color: "red" } });
+dispatch({ intentId: "product", params: { color: "red", id: "42" } });
+```
+
+如果你写的 Controller 用不同 `params` 形状解析同一个逻辑请求，dispatch 之前先归一化。
+
+### 缓存什么时候不命中
+
+- 浏览器导航到未在服务端 prefetch 的 intent（例如用户点击的动态路由）
+- `PrefetchedIntents.invalidate(intentId, params)` 之后变陈旧
+- 浏览器端的 mutation 守卫（自定义）
+
+不命中走普通 dispatcher 路径 —— `execute()` 在浏览器跑。
+
+## 一步一步看 Hydration
+
+```
+服务器                          浏览器
+──────                          ───────
+bootstrap(framework)
+    ▼                              │
+controller.execute()                │
+    ▼                              │
+Page A                              │
+    ▼                              │
+serialize → <script>                │
+    ▼                              │
+HTML 响应 ─────────────────────▶  接收 HTML
+                                    ▼
+                              createPrefetchedIntentsFromDom()
+                                    ▼
+                              Framework.create({ prefetchedIntents })
+                                    ▼
+                              bootstrap(framework)    ← 同份代码、同份路由
+                                    ▼
+                              dispatch(currentIntent)
+                                    ▼
+                              缓存命中 → Page A     ← 不重新请求
+                                    ▼
+                              mount(app)
+```
+
+bootstrap 跑两遍 —— 两端各一次 —— 输入相同。这就是浏览器初始路由和服务端渲染 HTML 一致的保证。
+
+## SSR head 注入
+
+`renderApp()` 返回 `head` 片段。框架把它注入到 `<!--head-->` 占位，同时还会注入：
+
+- `<script id="__finesoft_data__">` 序列化数据（仅 SSR 模式）
+- 客户端入口的 `<link>` / `<script>`（生产构建）
+- 来自解析 locale 的 `<html lang="..." dir="...">` 属性
+
+自定义 meta 标签放进你的 `head` 字符串：
+
+```ts
+async renderApp(page) {
+    return {
+        html: await renderToString(/*...*/),
+        head: [
+            `<title>${escape(page.title)}</title>`,
+            `<meta name="description" content="${escape(page.description)}">`,
+            `<meta property="og:title" content="${escape(page.title)}">`,
+        ].join(""),
+        css: "",
+    };
+}
+```
+
+用户提供的字符串永远要 escape —— 它们直接进 HTML。
+
+## CSS 注入
+
+如果渲染产出关键 CSS（如 Vue scoped 样式、`vanilla-extract`），通过 `css` 返回：
+
+```ts
+return {
+    html,
+    head: `<title>${title}</title>`,
+    css: extractedCriticalCss, // 作为 <style> 注入到 <head>
+};
+```
+
+Vite 管理的样式表保持 `css: ""` —— Vite 插件会处理。
+
+## 状态码
+
+SSR 响应的 HTTP 状态按以下优先级决定：
+
+1. 中间件结果：`deny(404)` → 404；`redirect(url, 301)` → 301 + `Location` 头。
+2. 页面级：`fallback()` 返回 `kind: "error"` 的 `Page` → 500（可通过 `getErrorPage` 配置）。
+3. 默认：200。
+
+通过 `afterLoad` 覆盖：
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.page.kind === "not-found") return deny(404, "Not found");
+        return next();
+    },
+],
+```
+
+## 流式 SSR
+
+当前不支持。框架在发字节前完整 await `renderApp()`。对大多数应用够用 —— Controller 内部 `execute()` 里并发 await 多个 HTTP 调用就能并行抓数据。
+
+如果某个大页面确实需要流式渲染，考虑用 CSR 渲染该页面 + 使用视图层自己的流式原语。
+
+## 下一步
+
+- [国际化](./05-i18n.md) —— locale 解析和字典加载
+- [陷阱：SSR Hydration 不匹配](./pitfalls/ssr-hydration-mismatch.md) —— 两端不一致时