@finesoft/front 0.1.75 → 0.1.77

package/docs/zh/engineering/project-structure.md

@@ -0,0 +1,296 @@
+# 工程实践：项目结构
+
+应用规模超过脚手架起点后的推荐布局。这是 ~20 路由、~10 工程师不大改就能用的形态。
+
+## 布局
+
+```
+my-app/
+├── src/
+│   ├── bootstrap.ts             # 路由 + DI 设置（SSR + CSR 共享）
+│   ├── main.ts                  # 浏览器入口
+│   ├── ssr.ts                   # SSR 入口
+│   ├── App.vue                  # 根组件
+│   │
+│   ├── routes/                  # 路由定义，按领域分组
+│   │   ├── home.ts
+│   │   ├── product.ts
+│   │   ├── checkout.ts
+│   │   └── admin.ts
+│   │
+│   ├── controllers/             # Controller，每个 intent 一个文件
+│   │   ├── home.ts
+│   │   ├── product.ts
+│   │   └── checkout.ts
+│   │
+│   ├── views/                   # 视图组件，与 Controller 镜像对应
+│   │   ├── Home.vue
+│   │   ├── Product.vue
+│   │   └── Checkout.vue
+│   │
+│   ├── lib/
+│   │   ├── api/                 # HttpClient 子类
+│   │   │   ├── user.ts
+│   │   │   └── product.ts
+│   │   ├── guards/              # 可复用的中间件
+│   │   │   ├── auth.ts
+│   │   │   ├── locale.ts
+│   │   │   └── analytics.ts
+│   │   ├── di/
+│   │   │   ├── keys.ts          # APP_KEYS 常量 map
+│   │   │   └── register.ts      # 集中注册
+│   │   ├── i18n/
+│   │   │   └── translator.ts    # Translator 工厂
+│   │   └── pages/
+│   │       └── types.ts         # Page union 类型
+│   │
+│   ├── locales/
+│   │   ├── en-US.json
+│   │   ├── zh-Hans.json
+│   │   └── ja-JP.json
+│   │
+│   └── env.ts                   # 环境变量解析 + 校验
+│
+├── public/                      # 静态资源，从 / 服务
+├── index.html
+├── vite.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+## 为什么是这个形状
+
+### `routes/` 与 `controllers/` 分离
+
+路由是**哪里**暴露一个 intent（URL 模式、守卫、渲染模式）。Controller 是 intent **做什么**。拆分让你：
+
+- 跨多个 URL 复用 Controller，路由定义不会污染 Controller 文件
+- 读一个目录就知道「应用服务哪些 URL」
+- 读一个目录就知道「intent X 计算什么」
+
+### `controllers/` 与 `views/` 镜像
+
+两边每个 intent 一个文件。intent id、Controller 文件、view 文件同名。找 `/products/:id` 的渲染代码变成机械动作。
+
+### 横切关注点都进 `lib/`
+
+不是路由、Controller、view 的都进 `lib/`。框架 `bootstrap()` 通过 `lib/di/register.ts` 做重的注册；Controller 用 `lib/api/*` 里的客户端；守卫住 `lib/guards/`。
+
+### `env.ts` 放在 `src/` 顶层
+
+在一个文件里一次性解析并校验环境变量。用 [zod](https://zod.dev/) 或手写检查。在别处重新导出强类型常量。
+
+```ts
+// src/env.ts
+function requireEnv(name: string): string {
+    const v = process.env[name];
+    if (!v) throw new Error(`Missing env: ${name}`);
+    return v;
+}
+
+export const env = {
+    UPSTREAM_URL: requireEnv("UPSTREAM_URL"),
+    SESSION_SECRET: requireEnv("SESSION_SECRET"),
+    NODE_ENV: process.env.NODE_ENV ?? "development",
+} as const;
+```
+
+让「这个应用需要什么环境变量」一目了然，构建时遇到缺失就立刻失败，而不是请求时崩。
+
+## `bootstrap.ts` 的形态
+
+`bootstrap.ts` 保持薄 —— 它该是编排，不是逻辑：
+
+```ts
+// src/bootstrap.ts
+import { type Framework } from "@finesoft/front";
+import { registerDependencies } from "./lib/di/register";
+import { homeRoutes } from "./routes/home";
+import { productRoutes } from "./routes/product";
+import { checkoutRoutes } from "./routes/checkout";
+import { adminRoutes } from "./routes/admin";
+
+export function bootstrap(framework: Framework): void {
+    registerDependencies(framework.container);
+
+    homeRoutes(framework);
+    productRoutes(framework);
+    checkoutRoutes(framework);
+    adminRoutes(framework);
+}
+```
+
+每个 `*Routes` 函数用自己的路由调 `defineRoutes(framework, [...])`。加一个新路由组就是一个 import + 一次调用。
+
+## 按领域的路由文件
+
+```ts
+// src/routes/product.ts
+import { defineRoutes, type Framework } from "@finesoft/front";
+import { ProductController } from "../controllers/product";
+import { ProductListController } from "../controllers/product-list";
+import { authGuard } from "../lib/guards/auth";
+
+export function productRoutes(framework: Framework): void {
+    defineRoutes(framework, [
+        { path: "/products", intentId: "product-list", controller: new ProductListController() },
+        { path: "/products/:id", intentId: "product", controller: new ProductController() },
+        {
+            path: "/products/:id/edit",
+            intentId: "product-edit",
+            controller: new ProductEditController(),
+            beforeLoad: [authGuard],
+            renderMode: "csr",
+        },
+    ]);
+}
+```
+
+## 集中式 DI 注册
+
+```ts
+// src/lib/di/register.ts
+import { type Container, DEP_KEYS } from "@finesoft/front";
+import { APP_KEYS } from "./keys";
+import { UserApi } from "../api/user";
+import { ProductApi } from "../api/product";
+import { ConsoleLogger } from "@finesoft/front";
+import { env } from "../../env";
+
+export function registerDependencies(container: Container): void {
+    container.register(DEP_KEYS.LOGGER, () => new ConsoleLogger("app"));
+
+    container.register(
+        APP_KEYS.USER_API,
+        () =>
+            new UserApi({
+                baseUrl: env.UPSTREAM_URL,
+            }),
+    );
+    container.register(
+        APP_KEYS.PRODUCT_API,
+        () =>
+            new ProductApi({
+                baseUrl: env.UPSTREAM_URL,
+            }),
+    );
+}
+```
+
+集中式让接线可检视。加服务是一次编辑，不是跨项目搜索。
+
+## 强类型 DI key
+
+```ts
+// src/lib/di/keys.ts
+export const APP_KEYS = {
+    USER_API: "userApi",
+    PRODUCT_API: "productApi",
+    SESSION: "session",
+    FEATURE_BUCKETING: "featureBucketing",
+} as const;
+
+export type AppKey = (typeof APP_KEYS)[keyof typeof APP_KEYS];
+```
+
+然后在任何 Controller 里：
+
+```ts
+import { APP_KEYS } from "../lib/di/keys";
+
+async execute(params, container) {
+    const api = container.resolve<UserApi>(APP_KEYS.USER_API);
+    // ...
+}
+```
+
+`APP_KEYS.USER_PAI` 这种拼错是编译错误。`"userPai"` 这种拼错是运行时错误。
+
+## Page 类型 union
+
+```ts
+// src/lib/pages/types.ts
+import type { HomePage } from "../../controllers/home";
+import type { ProductPage } from "../../controllers/product";
+import type { CheckoutPage } from "../../controllers/checkout";
+import type { ErrorPage } from "./error";
+
+export type Page = HomePage | ProductPage | CheckoutPage | ErrorPage;
+```
+
+带 `kind` 字段的可辨识 union。视图层根组件按 `page.kind` 分支：
+
+```vue
+<script setup lang="ts">
+import type { Page } from "@/lib/pages/types";
+const props = defineProps<{ page: Page }>();
+</script>
+
+<template>
+    <Home v-if="page.kind === 'home'" :page="page" />
+    <Product v-else-if="page.kind === 'product'" :page="page" />
+    <Checkout v-else-if="page.kind === 'checkout'" :page="page" />
+    <Error v-else-if="page.kind === 'error'" :page="page" />
+</template>
+```
+
+discriminant 在每个分支里把类型收窄 —— view 组件拿到完整强类型 `page` prop，不用 cast。
+
+## 拆分 SSR 和浏览器入口
+
+`ssr.ts` 和 `main.ts` 保持薄。两者只在：
+
+- `ssr.ts` 调 `createSSRRender` 并 export `render` + `serializeServerData`
+- `main.ts` 调 `startBrowserApp` 挂载视图层
+
+其他一切 —— 路由、Controller、DI、i18n —— 都通过 `bootstrap.ts` 共享。
+
+```ts
+// src/ssr.ts
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { renderToString } from "vue/server-renderer";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage: () => ({ kind: "error", title: "Server error" }),
+    async renderApp(page) {
+        const html = await renderToString(createSSRApp(App, { page }));
+        return { html, head: `<title>${page.title}</title>`, css: "" };
+    },
+});
+
+export { serializeServerData };
+```
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front/browser";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+startBrowserApp({
+    bootstrap,
+    mount(target, { framework }) {
+        createSSRApp(App, { framework }).mount(target);
+    },
+});
+```
+
+## 什么时候打破这个布局
+
+上面的形状能撑到 ~50 路由。过了之后考虑：
+
+- **按特性的文件夹**（`src/features/checkout/{routes,controllers,views,api}.ts`）—— 大型应用。每个特性独立可理解。
+- **懒加载路由 bundle**，在路由定义里 `import()`。Vite 插件自动拆分。
+- **workspace 包** —— 多应用共享 Controller / API 客户端时。共享代码搬到 `packages/shared`，从那里 import。
+
+不要预先重组。扁平的 `routes/` + `controllers/` 形状到上百文件都没问题。
+
+## 参考
+
+- [工程实践 · 测试](./testing.md) —— 怎么针对这个结构测
+- [DI 容器](../07-di-container.md) —— 注册模式

package/docs/zh/engineering/testing.md

@@ -0,0 +1,317 @@
+# 工程实践：测试
+
+框架为可测试性而设计。路由、Controller、中间件在服务端和浏览器都走同一个 dispatch 路径，所以一个测试同时检验两端。
+
+## 测什么
+
+| 对象           | 断言什么                                                                             | 层级 |
+| -------------- | ------------------------------------------------------------------------------------ | ---- |
+| Controller     | 给定 params + scope 化容器，产出的 page 正确。                                       | 单元 |
+| 守卫           | 给定 `NavigationContext`，结果是 `next` / `redirect` / `rewrite` / `deny` 的预期值。 | 单元 |
+| 路由           | URL → 预期的 intent + 渲染模式。                                                     | 单元 |
+| 完整请求       | URL → 经完整管线产出的最终 HTML / 状态码。                                           | 集成 |
+| Proxy / 服务器 | Hono 路由对合成请求返回正确的响应。                                                  | 集成 |
+
+## Vitest 设置
+
+仓库用 Vite+。总是从 `vite-plus/test` 导入：
+
+```ts
+import { describe, expect, test, vi, beforeEach, afterEach } from "vite-plus/test";
+```
+
+跑测试：
+
+```bash
+vp test                      # 全部
+vp test path/to/file.test.ts # 一个文件
+vp test -t "name match"      # 按测试名过滤
+vp test --coverage           # 带覆盖率
+```
+
+## 测一个 Controller
+
+```ts
+// src/controllers/product.test.ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { ProductController } from "./product";
+
+describe("ProductController", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    test("returns product page on success", async () => {
+        const container = new Container();
+        container.register("productApi", () => ({
+            getById: vi.fn(async (id) => ({ name: "Widget", price: 9.99 })),
+        }));
+
+        const controller = new ProductController();
+        const page = await controller.execute({ id: "42" }, container);
+
+        expect(page).toEqual({
+            kind: "product",
+            id: "42",
+            name: "Widget",
+            price: 9.99,
+        });
+    });
+
+    test("fallback returns degraded page on api failure", () => {
+        const controller = new ProductController();
+        const page = controller.fallback({ id: "42" }, new Error("network down"));
+
+        expect(page).toMatchObject({
+            kind: "product",
+            id: "42",
+            name: "Not available",
+        });
+    });
+});
+```
+
+关键点：**每个测试建一个 `Container`，只注册 Controller 真正需要的。** 别拉一个真实的 `Framework` 进来 —— 那是在测框架而不是测你的 Controller。
+
+## 测一个守卫
+
+守卫接 `NavigationContext` 返回 `MiddlewareResult`。内联构造一个假 context：
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { authGuard } from "./auth";
+
+function makeCtx(overrides: Partial<{ cookie: string | null }> = {}) {
+    return {
+        url: new URL("http://app.test/admin"),
+        intent: { intentId: "admin", params: {} },
+        container: new Container(),
+        getCookie: vi.fn((name: string) => overrides.cookie ?? null),
+        getHeader: vi.fn(() => null),
+        isSsr: true,
+    };
+}
+
+describe("authGuard", () => {
+    test("redirects unauthenticated user to /login", () => {
+        const ctx = makeCtx({ cookie: null });
+        const result = authGuard(ctx);
+
+        expect(result).toEqual({
+            kind: "redirect",
+            url: "/login?next=%2Fadmin",
+            status: 302,
+        });
+    });
+
+    test("passes through when token is present", () => {
+        const ctx = makeCtx({ cookie: "valid-token" });
+        const result = authGuard(ctx);
+
+        expect(result).toEqual({ kind: "next" });
+    });
+});
+```
+
+工厂函数（`makeCtx`）是套路 —— 跟守卫放一起，把测试真正关心的位参数化。
+
+## 测路由
+
+断言 URL → intent 映射：
+
+```ts
+import { describe, expect, test } from "vite-plus/test";
+import { Framework } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+
+describe("routes", () => {
+    test("resolves /products/42 to product intent", () => {
+        const framework = Framework.create({});
+        bootstrap(framework);
+
+        const match = framework.router.resolve("/products/42");
+
+        expect(match).toMatchObject({
+            intent: { intentId: "product", params: { id: "42" } },
+            renderMode: "ssr",
+        });
+    });
+
+    test("returns null for unmatched URL", () => {
+        const framework = Framework.create({});
+        bootstrap(framework);
+
+        expect(framework.router.resolve("/does-not-exist")).toBeNull();
+    });
+});
+```
+
+这能在重构时抓住路由回归 —— 一个改名的 intent 表现为失败的测试，而不是生产里的 404。
+
+## 测完整请求管线
+
+SSR 端到端测试，调 `createSSRRender`：
+
+```ts
+import { describe, expect, test } from "vite-plus/test";
+import { createSSRRender } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+
+describe("SSR pipeline", () => {
+    test("renders home page with serialized data", async () => {
+        const render = createSSRRender({
+            bootstrap,
+            getErrorPage: () => ({ kind: "error", title: "Error" }),
+            async renderApp(page) {
+                return {
+                    html: `<main>${(page as any).title}</main>`,
+                    head: "",
+                    css: "",
+                };
+            },
+        });
+
+        const result = await render("/", {
+            template: `<!doctype html><html><head><!--head--></head><body><!--ssr--></body></html>`,
+        });
+
+        expect(result.status).toBe(200);
+        expect(result.html).toContain("<main>Welcome</main>");
+        expect(result.html).toContain('id="__finesoft_data__"');
+    });
+
+    test("returns 302 when guard redirects", async () => {
+        const render = createSSRRender({
+            /* ... */
+        });
+        const result = await render("/admin");
+
+        expect(result.status).toBe(302);
+        expect(result.redirectUrl).toBe("/login?next=%2Fadmin");
+    });
+});
+```
+
+这是最高价值的测试层 —— 同时检验路由、中间件、Controller、渲染。
+
+## Mock 网络
+
+`HttpClient` 直接用 `fetch`。通过 `vi.stubGlobal` stub：
+
+```ts
+import { afterEach, beforeEach, test, vi, expect } from "vite-plus/test";
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+test("UserApi.list parses JSON response", async () => {
+    fetchMock.mockResolvedValueOnce(
+        new Response(JSON.stringify([{ id: "1", name: "Alice" }]), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        }),
+    );
+
+    const api = new UserApi({ baseUrl: "/api" });
+    const users = await api.list();
+
+    expect(users).toEqual([{ id: "1", name: "Alice" }]);
+    expect(fetchMock).toHaveBeenCalledWith("/api/users", expect.any(Object));
+});
+```
+
+测试里 fetch 多时建个小注册表：
+
+```ts
+function setupFetch(routes: Record<string, () => Response>) {
+    fetchMock.mockImplementation(async (url: string) => {
+        const handler = routes[url];
+        if (!handler) throw new Error(`Unexpected fetch: ${url}`);
+        return handler();
+    });
+}
+
+setupFetch({
+    "/api/users": () => new Response(JSON.stringify(users), { status: 200 }),
+    "/api/products": () => new Response(JSON.stringify(products), { status: 200 }),
+});
+```
+
+让「测试预期 fetch 什么」一眼可读。
+
+## 测试中 dispose scope
+
+测试里创建了 scope，在 `afterEach` 里 dispose：
+
+```ts
+let scope: Container | null = null;
+
+afterEach(() => {
+    scope?.dispose();
+    scope = null;
+});
+
+test("...", () => {
+    scope = framework.container.createScope();
+    scope.register("api", () => mockApi);
+    // ...
+});
+```
+
+Vitest 默认隔离测试，但 dispose 能暴露 scope 含 `destroy()` 资源（recorder 等）时的泄漏。
+
+## 测带 `rewrite` 的中间件
+
+`beforeLoad` 里的 rewrite 通过 router 递归。测试时同时断言 rewrite 信号和最终解析到的路由：
+
+```ts
+test("legacy URL rewrites to canonical", async () => {
+    const render = createSSRRender({ bootstrap /* ... */ });
+    const result = await render("/old/products/42");
+
+    // 用户可见的 URL 不变
+    expect(result.status).toBe(200);
+
+    // 但渲染走的 Controller 是 /products/42 的 —— 通过渲染后 HTML 断言
+    expect(result.html).toContain("Widget"); // product 42 的名字
+});
+```
+
+`afterLoad` rewrite（canonicalization），断言 `Content-Location` 头：
+
+```ts
+const result = await render("/page?utm=x");
+expect(result.headers["Content-Location"]).toBe("/page");
+```
+
+## 覆盖率目标
+
+框架本身在 `core` 上瞄准 >95%，`server` 上 >85%。应用代码目标：
+
+- **Controller**：100% `execute()` 主路径 + 至少一个 `fallback()` 测试。
+- **守卫**：每个分支（通过 / redirect / deny）。
+- **路由**：每个路由组至少一个 URL 解析断言。
+
+视图组件不必追求 100% —— 那是测视图层，不是测框架。测 Controller 产出的 page 形状契约就够了。
+
+## 速度
+
+vite-plus 的 Vitest 很快 —— 单元 ~1ms 一个测试，集成 ~10ms。慢的话：
+
+- 紧密循环里别建完整 `Framework`；直接建 `Container`。
+- 单元测试里 mock 重的 `bootstrap()`。
+- 等 `setTimeout`（重试、debounce）的测试用 `vi.useFakeTimers()`。
+
+## 参考
+
+- [测试 proxy](../09-server-and-deployment.md#proxy-路由) —— 框架自己的 proxy 测试 `packages/server/test/proxy.test.ts` 是好参考