@finesoft/front 0.5.0 → 0.5.2

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

@@ -1,244 +1,57 @@
-# 工程实践：CI 与发布流程
+# 工程：验证与发布
 
-框架自身的发布方式，以及给依赖它的应用设置同样 workflow 的方法。
+公开包是 `@finesoft/front` 和 `@finesoft/create-app`。Core、Web、Browser、SSR、Server 保持私有，由 front 构建合入明确的 ESM 入口和声明。各原生渲染器保留所选 UI 的外部依赖。
 
-## 发布什么
+## 本地检查
 
-只有 `@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 }}
+```sh
+vp install
+vp run --filter '@finesoft/front...' build
+vp check
+vp test --coverage
+vp run -r build
+vp exec node scripts/verify-publish-transforms.mjs
+vp exec node scripts/verify-runtime-boundaries.mjs
 ```
 
-多次 push 到 `main` 排队而不是取消。这点很重要：
-
-- publish 中途取消会让 npm 处于不一致状态
-- 每次 push 必须等前一次完成，避免版本号竞争
-- 下一个 run 的对账步骤会捡起前一个已发布的版本
-
-## 幂等
-
-`changeset publish` 跳过 npm 上已有的版本。所以 push 到 `main` 在 publish 之后失败：
+`vp pack` 构建库，`vp pm pack` 生成本地安装包。Front 的 prepack/postpack 成对改写并恢复原始发布清单；准备失败也会恢复。脚手架准备脚本复制六套当前模板，并生成可独立安装的依赖与 TypeScript 配置。
 
-- npm：有 0.1.75
-- main：还是 0.1.74
+## 仓库自动化
 
-下一次 release run 的对账步骤检测到 `main < npm`，拒绝「往回 catch-up」并报错。人工补救：开一个 PR 把 `packages/front/package.json` bump 到 npm 版本并合并。之后 push 正常。
+Quality 的两个作业都会先构建 front 及其工作区依赖。根 Vite 配置加载的控制器类型生成器会导入 core 的构建产物，因此全新检出必须先完成这一步。
 
-## 给应用设置同样的
+PR 运行 Quality（`vp check` 和 `vp test --coverage`）。推送到 `main` 时启动 Release，复用同一份 Quality 工作流，并等待两项检查通过。CodeQL 独立扫描 `packages/{core,web,browser,ssr,server,front}/src/**`。
 
-大多数应用不需要 publish 步骤 —— 它们有部署。但 changeset + 自动 bump 形状仍然管用：
+Release 检出通过检查的提交，为两个公开包生成 patch changeset，应用 Changesets（保留手写 changeset 的 minor/major 意图），同步锁文件并构建。随后使用内置 `GITHUB_TOKEN` 把版本提交推回 `main`，成功后才发布 npm。如果 `main` 已被其他推送推进，发布会停止，由新提交重新验证和发布；不会把旧构建强行变基，也不会覆盖后续提交。npm 发布成功后再推送 Git 标签。
 
-```yaml
-name: Release
+发布作业使用 GitHub 托管 runner、`id-token: write` 和 npm OIDC Trusted Publishing，不使用依赖缓存或 npm token。Changesets 经 Vite+ 调用仓库指定的 pnpm 11；它原生支持 npm OIDC 和自动 provenance。两个公开包声明了源码仓库与公开 registry。工作流不再使用 `RELEASE_PUSH_TOKEN`、`NPM_TOKEN`。
 
-on:
-    push:
-        branches:
-            - main
+### npm 配置
 
-concurrency: release-${{ github.ref }}
+在 `@finesoft/front` 和 `@finesoft/create-app` **各自**的 Settings 页面添加 GitHub Actions Trusted Publisher：
 
-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 }}
+| 字段                 | 值                                 |
+| -------------------- | ---------------------------------- |
+| Organization or user | `GaKireiTsuki`                     |
+| Repository           | `finesoft-front`                   |
+| Workflow filename    | `release.yml`                      |
+| Environment name     | 留空；工作流未使用 environment     |
+| Allow npm publish    | 勾选，允许当前自动发布流程直接发布 |
 
-            - uses: voidzero-dev/setup-vp@v1
-              with:
-                  node-version: 24
-                  cache: true
+保留 “Require two-factor authentication and disallow bypass 2fa tokens” 设置；它与 Trusted Publishing 兼容。当前流程直接发布，只有 stage 权限的连接无法授权。详见 [npm 官方文档](https://docs.npmjs.com/trusted-publishers/)。保存连接不等于发布成功，须检查首次 Release 运行和 npm 上的实际版本。
 
-            - 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"
+修复原因后，在 **Release → Run workflow → main** 手动运行，或执行：
 
-            - 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
+```sh
+gh workflow run release.yml --ref 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 会从那里接着写。
-
-## 可能出错的情况
+手动运行会检查、构建并发布 `main` 已有的版本，**不会**再生成 changeset 或升版。Changesets 跳过 npm 已存在的版本，因此两个包只成功一个时可以补发另一个；标签步骤也会补齐缺失标签。如果失败发生在版本提交推回 `main` 之前，可在原始提交仍是分支头时重跑原推送任务，或推送修复提交来重新发版。
 
-| 症状                                   | 原因                                                                         | 修法                                                   |
-| -------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `[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；重跑                    |
+本地使用 `vp run changeset`、`vp run version` 管理版本。`vp run release` 构建并发布，`vp run release:publish` 仅发布已有构建。本地构建和安装包验证不等于推送、发布、部署或外部环境验收。
 
-## 参考
+## 应用项目
 
-- 实际的 release workflow：`.github/workflows/release.yml`
-- 实际的 quality workflow：`.github/workflows/quality.yml`
-- [Changesets 文档](https://github.com/changesets/changesets) —— 理解 `vp run version` 和 `vp run release`
+使用生成项目自身的 `vp run build` 和部署配置。密钥放在所选主机的绑定中，只安装应用使用的渲染器与主机依赖。完整本地运行时和独立安装消费者证据见仓库 `docs/application-boundaries-acceptance.md`。

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

@@ -1,296 +1,53 @@
-# 工程实践：项目结构
+# 应用结构
 
-应用规模超过脚手架起点后的推荐布局。这是 ~20 路由、~10 工程师不大改就能用的形态。
+React、Vue、Svelte 的六个模板保留 full、minimal 两档。同档位的页面、路由、数据、文案和交互一致；生成的每个项目都能独立使用，只依赖公开包入口。
 
-## 布局
+## 选择档位
 
-```
-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";
+| 档位    | 页面与路由                                                          | 示例能力                                                                           |
+| ------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Full    | 首页 `/`、商品 `/products/:id`、搜索 `/search?q=...`、关于 `/about` | SSR、关于页 CSR、URL 动作、类型化参数、DI、数据映射与 HTTP 客户端、认证和 SEO 守卫 |
+| Minimal | Feed `/`、详情 `/item/:id`、Notes `/notes`                          | 标签与栈导航、页面草稿、全局资料、会话恢复、JSON 语言文件和 SSR 水合               |
 
-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` 分支：
+两档模板都使用一个原生 App，布局包住 Outlet。这是两类业务示例，不代表框架能力的高低。
 
-```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>
+```text
+src/config.ts          # 应用标识，也是会话存储的命名空间
+src/app-definition.ts  # 页面定义、路由、守卫及可选导航结构
+src/views.ts           # 浏览器与 SSR 共用的原生视图注册表
+src/main.ts            # 标准浏览器启动与 HMR 销毁
+src/ssr.ts             # 所选框架的标准 SSR renderer
+src/App.<native>       # full 布局，或 minimal 的导航栏与全局资料
+src/pages/             # 原生页面组件（.tsx / .vue / .svelte）
+src/components/        # full 的可复用展示组件
+src/lib/controllers/   # BaseController 页面加载器及显式公开数据
+src/lib/models/        # 页面与数据类型
+src/styles.css         # 同档位一致的样式
+src/locales/           # minimal：en-US 与 zh-Hans 语言文件
 ```
 
-discriminant 在每个分支里把类型收窄 —— view 组件拿到完整强类型 `page` prop，不用 cast。
+Full 的商品数据、mapper、HTTP 客户端和守卫继续放在 `src/lib/`。Minimal 通过原生 useSnapshot 绑定读取已提交快照。资料状态与组件根归原生应用所有，框架负责导航事务与持久化。
 
-## 拆分 SSR 和浏览器入口
+## 控制器与页面声明
 
-`ssr.ts` 和 `main.ts` 保持薄。两者只在：
+六个模板都使用 `BaseController`：`lib/controllers/` 中的类实现业务加载，`app-definition.ts` 用 `definePage({ id, create: () => new HomeController() })` 注册工厂，并复用返回引用的 `route()`、`leaf()` 和 `bindView()`。`views.ts` 绑定原生组件，组件通过 `page` 接收结果。
 
-- `ssr.ts` 调 `createSSRRender` 并 export `render` + `serializeServerData`
-- `main.ts` 调 `startBrowserApp` 挂载视图层
+控制器、Web 页面类型和 `markPublic` 统一从 `@finesoft/front` 导入。控制器在实际执行时创建，页面草稿和全局资料分别交给页面实例与应用 store。错误页由 `getErrorPage` 工厂生成。完整的参数、DI、`fallback` 和函数 `handler` 用法见[路由、控制器与类型化页面](../02-routing-and-controllers.md)。
 
-其他一切 —— 路由、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);
-    },
-});
-```
+Minimal 的详情输入框和 Notes 文本框标记 `data-restore-root`。切换标签保留草稿，刷新恢复草稿；返回并移除详情实例后，其草稿被销毁。姓名属于当前应用实例的全局资料，可跨标签、跨刷新恢复。嵌入第二个应用时，调用 `mountApplication(target, persistenceKey, "memory", "/notes")` 并使用独立的存储键。
 
-## 什么时候打破这个布局
+三套 minimal 默认 `zh-Hans`。修改 `src/app-definition.ts` 中的 `configuration.locale` 为 `en-US` 或 `zh-Hans` 后重新启动或构建。该示例展示语言文件加载及水合后的翻译；导航标签和示例条目保持英文。
 
-上面的形状能撑到 ~50 路由。过了之后考虑：
+Full 的 `/admin` 在缺少认证时重定向至 `/login?from=...`；实际登录页和认证服务由应用补充。示例 `auth_token` cookie 用于演示守卫放行。
 
-- **按特性的文件夹**（`src/features/checkout/{routes,controllers,views,api}.ts`）—— 大型应用。每个特性独立可理解。
-- **懒加载路由 bundle**，在路由定义里 `import()`。Vite 插件自动拆分。
-- **workspace 包** —— 多应用共享 Controller / API 客户端时。共享代码搬到 `packages/shared`，从那里 import。
+## 保持三框架一致
 
-不要预先重组。扁平的 `routes/` + `controllers/` 形状到上百文件都没问题。
+同档位的公共 TypeScript 和样式直接包含在各项目中，并保持文件内容一致。允许的差异为原生 UI 语法、renderer 导入、框架依赖与应用标识。项目无需导入相邻模板，也没有私有运行包路径别名。脚手架复制这些相同源码，并附带当前档位的 README。
 
-## 参考
+仓库维护时运行 `vp test packages/create-app/test` 检查结构与文件差异；构建六套模板后，运行 `vp exec node scripts/verify-template-renderers.mjs` 验证同一组浏览器交互。使用 `vp exec node scripts/verify-created-consumers.mjs /absolute/path/to/front.tgz`，可以在仓库外对六个生成项目分别安装和构建。
 
-- [工程实践 · 测试](./testing.md) —— 怎么针对这个结构测
-- [DI 容器](../07-di-container.md) —— 注册模式
+独立数据操作、Node、Worker 宿主可分别放入 `src/data-app.ts`、`src/node.ts`、`src/worker.ts`，通过公开入口使用应用契约。