@finesoft/front 0.1.76 → 0.1.78

package/docs/zh/advanced/multi-tenant-scopes.md

@@ -0,0 +1,330 @@
+# 高阶：多租户 scope
+
+多租户应用一份部署服务多个客户，每个客户的请求要看到自己的：
+
+- 数据库连接 / API 客户端
+- 带租户 tag 的 logger / 指标
+- Feature flag / 价格 / 品牌
+- 缓存的翻译 / 内容
+
+DI 容器的子 scope 是正确的原语。本配方展示通过 `beforeLoad` 守卫接通按租户隔离。
+
+## 心智模型
+
+```
+Framework
+  └── 父 Container        ← 共享服务（HTTP 池、基础 recorder、...）
+      └── 每个请求 scope  ← 框架为每个 SSR 请求创建
+          ↑
+          └── 一个 beforeLoad 守卫注册的租户覆盖
+```
+
+每请求 scope 由框架自动创建。你的守卫在它之上注册租户级覆盖。你没覆盖的东西都回退到父。
+
+## 步骤 1：识别租户
+
+这是你的业务逻辑。常见来源：
+
+- **子域**：`acme.myapp.com` → `acme`
+- **路径前缀**：`/t/acme/...` → `acme`
+- **头**：`X-Tenant-Id: acme`
+- **鉴权用户**：cookie → session → tenant
+
+```ts
+// src/lib/tenants/resolve.ts
+import type { NavigationContext } from "@finesoft/front";
+
+export function resolveTenant(ctx: NavigationContext): string | null {
+    const host = ctx.url.hostname;
+    const sub = host.split(".")[0];
+    if (sub && sub !== "www" && sub !== "myapp") return sub;
+    return null;
+}
+```
+
+## 步骤 2:加载租户配置
+
+```ts
+// src/lib/tenants/config.ts
+export interface TenantConfig {
+    tenantId: string;
+    displayName: string;
+    upstreamUrl: string;
+    apiToken: string;
+    featureFlags: Record<string, unknown>;
+    locale: string;
+}
+
+const cache = new Map<string, TenantConfig>();
+
+export async function getTenantConfig(tenantId: string): Promise<TenantConfig | null> {
+    if (cache.has(tenantId)) return cache.get(tenantId)!;
+
+    // 从配置存储读 —— 文件、DB、KV
+    const config = await loadFromStore(tenantId);
+    if (!config) return null;
+
+    cache.set(tenantId, config);
+    return config;
+}
+```
+
+真实实现要在配置更新时让缓存失效。多数应用按定时器刷或通过 webhook 即可。
+
+## 步骤 3：在守卫里注册租户服务
+
+```ts
+// src/lib/guards/tenant.ts
+import { deny, next, type NavigationContext, DEP_KEYS } from "@finesoft/front";
+import { resolveTenant } from "../tenants/resolve";
+import { getTenantConfig } from "../tenants/config";
+import { UserApi } from "../api/user";
+import { WithFieldsRecorder } from "@finesoft/front";
+
+export async function tenantGuard(ctx: NavigationContext) {
+    const tenantId = resolveTenant(ctx);
+    if (!tenantId) return deny(404, "Unknown tenant");
+
+    const config = await getTenantConfig(tenantId);
+    if (!config) return deny(404, "Tenant not found");
+
+    // 在请求 scope 上注册租户专属服务
+    const scope = ctx.container;
+    scope.register("tenantConfig", () => config);
+
+    scope.register(
+        "userApi",
+        () =>
+            new UserApi({
+                baseUrl: config.upstreamUrl,
+                defaultHeaders: { Authorization: `Bearer ${config.apiToken}` },
+            }),
+    );
+
+    scope.register(DEP_KEYS.FEATURE_FLAGS, () => ({
+        get: (key, fallback) => config.featureFlags[key] ?? fallback,
+    }));
+
+    // 用租户上下文装饰父的 recorder
+    const baseRecorder = scope.parent!.resolve(DEP_KEYS.EVENT_RECORDER);
+    scope.register(
+        DEP_KEYS.EVENT_RECORDER,
+        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ tenantId }) }]),
+    );
+
+    return next();
+}
+```
+
+要点：
+
+- **scope 已经由框架创建。** 你在 `ctx.container` 上注册 —— 那就是请求 scope。
+- **回退自动。** 这里没注册的会从父容器 resolve。
+- **装饰而不替换。** recorder 用租户字段包起来而不是替换 —— 基础行为（HTTP 传输、批处理）保持原样。
+
+## 步骤 4：全局安装守卫
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { tenantGuard } from "./lib/guards/tenant";
+// ... 其他 import
+
+export function bootstrap(framework: Framework): void {
+    framework.middleware.use("beforeLoad", tenantGuard);
+
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        { path: "/billing", intentId: "billing", controller: new BillingController() },
+        // ...
+    ]);
+}
+```
+
+`tenantGuard` 在任何路由级守卫之前跑，所以任何 Controller 跑时租户 scope 都已经设好。
+
+## 步骤 5：Controller 透明地拿到正确的服务
+
+```ts
+// src/controllers/billing.ts
+export class BillingController extends BaseController<{}, BillingPage> {
+    readonly intentId = "billing";
+
+    async execute(_params, container) {
+        const config = container.resolve<TenantConfig>("tenantConfig");
+        const api = container.resolve<UserApi>("userApi"); // 租户专属客户端
+
+        const usage = await api.getUsage();
+        const invoices = await api.getInvoices();
+
+        return {
+            kind: "billing",
+            tenantName: config.displayName,
+            usage,
+            invoices,
+        };
+    }
+}
+```
+
+Controller 不知道租户存在 —— 它只 resolve `userApi`，拿到本请求对应的那个。
+
+## 跨租户禁止
+
+防 A 租户认证的用户访问 B 租户数据：
+
+```ts
+async function sameTenantGuard(ctx: NavigationContext) {
+    const session = await ctx.container.resolve<SessionService>("session").current();
+    const requestedTenant = ctx.container.resolve<TenantConfig>("tenantConfig").tenantId;
+
+    if (!session) return redirect("/login");
+    if (session.tenantId !== requestedTenant) return deny(403, "Cross-tenant access forbidden");
+
+    return next();
+}
+
+// 在 tenantGuard 之后应用：
+framework.middleware.use("beforeLoad", tenantGuard);
+framework.middleware.use("beforeLoad", sameTenantGuard);
+```
+
+守卫顺序重要 —— `tenantGuard` 必须先注册 `tenantConfig`，`sameTenantGuard` 才能读到。
+
+## Hydration 考虑
+
+租户配置含 `featureFlags`，两端都读。框架的 `PrefetchedIntents` 序列化处理这个 —— 浏览器拿到服务端看到的同样 flag 值，所以客户端读保持一致。
+
+租户配置本身**不**自动序列化。view 要显示 `tenantConfig.displayName` 的话，Controller 应该把它放进 `Page`：
+
+```ts
+async execute(_params, container) {
+    const config = container.resolve<TenantConfig>("tenantConfig");
+    return {
+        kind: "home",
+        tenant: {
+            id: config.tenantId,
+            displayName: config.displayName,
+        },
+        // ...
+    };
+}
+```
+
+`Page` 被序列化所以能跨 SSR → CSR 边界。完整 `TenantConfig`（含秘密）永不应该出现在 `Page` 里。
+
+## 浏览器端考虑
+
+`tenantGuard` 在浏览器也跑 —— 首次导航和每次后续导航。仅浏览器应用（`renderMode: "csr"`）只在这跑。
+
+但浏览器不能安全地 resolve `apiToken` 这种秘密。两种方法：
+
+**方法 1：服务器代理所有 API 调用。** 浏览器打 `/api/users`（你的 proxy），它转发到 `${upstreamUrl}/users` 并从 `process.env[apiTokenEnvKey]` 注入 auth 头。浏览器从不见 token。
+
+**方法 2：短期 session token。** 服务器颁发 scope 到租户的 JWT；浏览器用它直接调上游。token 轮换由你的 auth 层处理。
+
+多数应用走方法 1。框架的 proxy router 就是为这个设计的。
+
+## 注意事项
+
+### 别跨请求缓存租户 scope
+
+```ts
+// 不好
+const tenantScopeCache = new Map<string, Container>();
+
+async function tenantGuard(ctx) {
+    let scope = tenantScopeCache.get(tenantId);
+    if (!scope) {
+        scope = framework.container.createScope();
+        tenantScopeCache.set(tenantId, scope);
+    }
+    // 用 scope...
+}
+```
+
+每个请求需要自己的 scope —— 即使同租户 —— 因为：
+
+- 其他守卫加请求专属覆盖（auth、trace id），不该跨请求泄漏
+- scope 持有有状态服务的 resolve 实例；跨请求共享破坏隔离
+
+租户**配置**可以缓存。租户**scope**不行。
+
+### 共享服务实例要小心
+
+把 `UserApi` 实例缓存到模块级而不是注册工厂，所有请求共享状态：
+
+```ts
+// 不好
+const apiByTenant = new Map<string, UserApi>();
+scope.register("userApi", () => {
+    let api = apiByTenant.get(tenantId);
+    if (!api) {
+        api = new UserApi({ baseUrl: config.upstreamUrl });
+        apiByTenant.set(tenantId, api);
+    }
+    return api;
+});
+```
+
+`UserApi` 有任何请求级状态（捕获请求专属值的拦截器闭包）就跨租户泄。注册新鲜工厂；让容器按 scope 缓存。
+
+## 测试
+
+```ts
+import { describe, test, expect, vi, afterEach } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { tenantGuard } from "./tenant";
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("tenantGuard", () => {
+    test("registers tenant services for known tenant", async () => {
+        const parent = new Container();
+        const scope = parent.createScope();
+
+        vi.spyOn(await import("../tenants/config"), "getTenantConfig").mockResolvedValue({
+            tenantId: "acme",
+            displayName: "Acme Co",
+            upstreamUrl: "https://acme.example",
+            apiToken: "token-123",
+            featureFlags: { darkMode: true },
+            locale: "en-US",
+        });
+
+        const ctx = {
+            url: new URL("https://acme.myapp.com/"),
+            container: scope,
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+
+        expect(result).toEqual({ kind: "next" });
+        expect(scope.resolve("tenantConfig")).toMatchObject({ tenantId: "acme" });
+    });
+
+    test("denies unknown tenant", async () => {
+        const ctx = {
+            url: new URL("https://unknown.myapp.com/"),
+            container: new Container(),
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+        expect(result).toMatchObject({ kind: "deny", status: 404 });
+    });
+});
+```
+
+## 参考
+
+- [第 7 章：DI 容器](../07-di-container.md) —— scope 和回退 resolve
+- [第 3 章：中间件](../03-middleware.md) —— 全局守卫
+- [陷阱：container scope 泄漏](../pitfalls/container-scope-leak.md) —— 缓存 scope 会出什么问题

package/docs/zh/engineering/ci-release-flow.md

@@ -0,0 +1,244 @@
+# 工程实践：CI 与发布流程
+
+框架自身的发布方式，以及给依赖它的应用设置同样 workflow 的方法。
+
+## 发布什么
+
+只有 `@finesoft/front` 发布到 npm。内部的 `core` / `browser` / `ssr` / `server` 包通过 `tsdown` 的 `noExternal: [@finesoft/*]` 打包进 `front`。
+
+这意味着：
+
+- 用户只装一个 npm 包
+- 内部重构不会带动多个版本号
+- 一份 CHANGELOG 可读
+
+`create-finesoft-app` 是它自己发布的包（CLI），独立于框架运行时。
+
+## 发布 workflow
+
+仓库只有一个 `.github/workflows/release.yml`，内联处理一切。触发：push 到 `main`。
+
+```
+push to main
+    │
+    ▼
+Checkout main（用 PAT 而非 GITHUB_TOKEN）
+    │
+    ▼
+对账 npm 注册表与 main
+    ├── npm == main? → 继续
+    ├── main > npm? → catch-up publish 当前 main 版本
+    └── npm > main? → 报错，需人工排查
+    │
+    ▼
+生成自动 changeset（每次 push 一个 patch）
+    │
+    ▼
+应用版本 bump
+    ├── 有变更? → 继续
+    └── 无变更? → 完成，不发布
+    │
+    ▼
+Commit "chore(release): version packages"
+    │
+    ▼
+构建所有包，publish @finesoft/front 到 npm
+    │
+    ▼
+Push commit + tag 回 main（带 rebase 重试）
+```
+
+### 为什么用一个内联 workflow 而不是 changesets/action 的 PR 模式
+
+标准 changesets workflow 开一个 PR（「Version Packages」），合并时触发第二次 workflow run 来发布。**但 `GITHUB_TOKEN` 合并的 commit 不触发后续 workflow**（GitHub 反递归安全策略）—— 发布永远不跑。内联 workflow 一次 run 里做完，没有 PR hop。
+
+### 为什么用 PAT 而不是 `GITHUB_TOKEN`
+
+仓库 ruleset 强制签名 commit、线性历史、`main` 上必须 PR。bypass actor 包括 `RepositoryRole=5 (admin)` 但**不**包括 `github-actions[bot]`。GitHub UI 不允许把这个 bot 加进 bypass list。用 admin 用户拥有的 PAT push 命中已有的 admin bypass 条目。
+
+PAT 只授 `Contents: Read & Write` —— `git push` 需要的最小权限。
+
+## 并发
+
+```yaml
+concurrency: release-${{ github.ref }}
+```
+
+多次 push 到 `main` 排队而不是取消。这点很重要：
+
+- publish 中途取消会让 npm 处于不一致状态
+- 每次 push 必须等前一次完成，避免版本号竞争
+- 下一个 run 的对账步骤会捡起前一个已发布的版本
+
+## 幂等
+
+`changeset publish` 跳过 npm 上已有的版本。所以 push 到 `main` 在 publish 之后失败：
+
+- npm：有 0.1.75
+- main：还是 0.1.74
+
+下一次 release run 的对账步骤检测到 `main < npm`，拒绝「往回 catch-up」并报错。人工补救：开一个 PR 把 `packages/front/package.json` bump 到 npm 版本并合并。之后 push 正常。
+
+## 给应用设置同样的
+
+大多数应用不需要 publish 步骤 —— 它们有部署。但 changeset + 自动 bump 形状仍然管用：
+
+```yaml
+name: Release
+
+on:
+    push:
+        branches:
+            - main
+
+concurrency: release-${{ github.ref }}
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+        if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/checkout@v5
+              with:
+                  ref: main
+                  fetch-depth: 0
+                  token: ${{ secrets.RELEASE_PUSH_TOKEN }}
+
+            - uses: voidzero-dev/setup-vp@v1
+              with:
+                  node-version: 24
+                  cache: true
+
+            - run: vp install --frozen-lockfile
+
+            - name: Configure git
+              run: |
+                  git config user.name "github-actions[bot]"
+                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+            - name: Generate auto changeset
+              run: vp run release:auto:changeset
+
+            - name: Apply version bump
+              id: bump
+              run: |
+                  vp run version
+                  if git diff --quiet; then
+                      echo "should_publish=false" >> "$GITHUB_OUTPUT"
+                  else
+                      NEW=$(node -p "require('./package.json').version")
+                      echo "version=$NEW" >> "$GITHUB_OUTPUT"
+                      echo "should_publish=true" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Commit version
+              if: steps.bump.outputs.should_publish == 'true'
+              run: |
+                  git add -A
+                  git commit -m "chore(release): version packages"
+
+            - name: Build
+              if: steps.bump.outputs.should_publish == 'true'
+              run: vp run build
+
+            - name: Deploy
+              if: steps.bump.outputs.should_publish == 'true'
+              run: vp run deploy # 你的部署命令
+
+            - name: Push tag and commit
+              if: steps.bump.outputs.should_publish == 'true'
+              run: git push --follow-tags origin HEAD:main
+```
+
+把 `vp run deploy` 换成你平台的部署命令（Vercel、Cloudflare、自家基建）。
+
+## Conventional commits + 自动 changeset
+
+`release:auto:changeset` 脚本（本仓库的，每次 push 生成一个 patch changeset）有意简单 —— 每个合并 PR 变成一次 patch bump。要语义化版本驱动，替换为这样的脚本：
+
+- 读上一个 tag 之后的 `git log`
+- 把 commit 前缀（`feat:`、`fix:`、`BREAKING:`）映射到 changeset 类型
+- 写对应的 `.changeset/*.md`
+
+框架仓库用纯 patch，因为：
+
+- 每次 push 是小变更；大变更经过 review 后还是会变成小 commit
+- 真正的破坏性变更很少，值得手写 changeset
+- 避开「前缀撒谎」的一类 bug
+
+按你团队的提交习惯挑策略。
+
+## 按 PR 校验（`quality.yml`）
+
+仓库还有 `quality.yml` workflow，PR 上跑：
+
+```yaml
+on:
+    pull_request:
+    push:
+        branches:
+            - main
+
+jobs:
+    coverage:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: voidzero-dev/setup-vp@v1
+              with: { node-version: 24, cache: true }
+            - run: vp install --frozen-lockfile
+            - run: vp test --coverage
+            - uses: actions/upload-artifact@v7
+              with:
+                  name: coverage-report
+                  path: reports/coverage
+                  if-no-files-found: error
+```
+
+`check` job（fmt + lint + types）在本仓库被 `if: false` 关掉，因为 Vite+ 本地走 pre-commit 跑这些。如果你的团队 pre-commit hook 跑得不稳，重新打开。
+
+## CodeQL
+
+仓库定时和 PR 上跑 CodeQL。扫描范围限定 `packages/{core,browser,ssr,server,front}/src/**`。测试、模板、脚本、脚手架都排除。
+
+应用仓库启用默认 CodeQL 配置即可 —— 噪声低，能抓真实问题（open redirect、SQL 注入、密钥暴露）。
+
+## 必需状态检查
+
+仓库 ruleset 要求：
+
+- `Coverage`（来自 `quality.yml`）
+- `CodeQL`
+
+两个都过才能合 PR。release workflow 通过 admin PAT bypass —— release 在 PR 合并后跑在 `main` 上，那些 check 在 PR 上已经过了。
+
+## 迁移：从 changesets PR 模式到内联
+
+把现有仓库从 `changesets/action`（PR 模式）迁过来：
+
+1. 删旧 release workflow
+2. 创建上面的内联 workflow
+3. 生成一个 fine-grained PAT，存为 `RELEASE_PUSH_TOKEN`
+4. 这次改动后下一次 push 到 main 会：
+    - 检测到 main == npm（不需要 catch-up）
+    - 生成一个 patch changeset
+    - bump + publish + push 回 main
+
+如果有旧 workflow 留下的「Version Packages」PR pending，不要合直接关掉。自动 changeset 会从那里接着写。
+
+## 可能出错的情况
+
+| 症状                                   | 原因                                                                         | 修法                                                   |
+| -------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `[remote rejected] HEAD -> main`       | PAT actor 不在 ruleset bypass；PAT 缺 `Contents: Write`                      | 验 PAT scope；确认 push actor 是 admin 用户            |
+| `npm ... is ahead of main`             | 前一次 run publish 后 push 失败                                              | 开 PR 把 `packages/front/package.json` 同步到 npm 版本 |
+| 一次 release commit 后 workflow 不触发 | `if: "!startsWith(github.event.head_commit.message, 'chore(release):'"` 过滤 | 按设计 —— 防递归                                       |
+| Pre-commit hook（`vp check`）CI 失败   | 本地没跑 formatter                                                           | 本地 `vp check --fix`；commit；重跑                    |
+
+## 参考
+
+- 实际的 release workflow：`.github/workflows/release.yml`
+- 实际的 quality workflow：`.github/workflows/quality.yml`
+- [Changesets 文档](https://github.com/changesets/changesets) —— 理解 `vp run version` 和 `vp run release`