npm - @finesoft/front - Versions diffs - 0.1.17 → 0.1.18 - Mend

@finesoft/front 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +408 -263
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,41 +1,42 @@
 # @finesoft/front
-`@finesoft/front` 是一个**聚合型全栈框架包**：
+`@finesoft/front` 是一个面向 SSR Web 应用的聚合包，统一导出了以下四层能力：
-- 用 `@finesoft/core` 负责 **路由 / Intent / Controller / DI / Framework**
-- 用 `@finesoft/browser` 负责 **客户端启动、导航、hydrate**
-- 用 `@finesoft/ssr` 负责 **SSR 渲染与数据注入**
-- 用 `@finesoft/server` 负责 **Hono + Vite + 部署适配器**
+- `@finesoft/core`：路由、Intent、Controller、依赖注入、Framework
+- `@finesoft/browser`：浏览器启动、导航、hydrate、prefetched data
+- `@finesoft/ssr`：SSR 渲染与服务端数据注入
+- `@finesoft/server`：Hono 服务端集成、Vite 插件、部署适配器
-如果你想做一个“**URL → Intent → Controller → Page Model → SSR + Hydration**”的内容型站点，这个包就是把整条链路打包好了。
+它适合这样一类应用：
-这份 README 不讲空话，直接按“**你现在要怎么接入**”来写。照着做，基本就能跑起来。
+$$
+URL \rightarrow Router \rightarrow Intent \rightarrow Controller \rightarrow Page\ Model \rightarrow SSR / Hydration
+$$
+也就是说：URL 决定页面语义，Controller 负责取数和组装页面模型，UI 层只负责渲染页面模型。
 ---
-## 先搞清楚：这个包适合什么项目
+## 适用场景
-它更适合下面这类应用：
+`@finesoft/front` 更适合以下类型的项目：
-- 内容展示站点
-- App Store / Media / 资讯 / 榜单 / 搜索 / 详情页
-- 需要 SSR 的站点
-- URL 和页面状态关系清晰的项目
-- 希望把“页面逻辑”收敛到 Controller，而不是散落在 UI 组件里的项目
+- 需要 SSR 的内容型站点
+- 有明确 URL 语义的多页面 Web 应用
+- 希望将页面获取逻辑集中在 Controller 中的项目
+- 需要同一套页面模型同时服务 SSR 和客户端导航的项目
-如果你的项目是：
+例如：
-- 纯客户端小工具
-- 页面非常少
-- 不需要 SSR / SEO
+- 内容聚合站点
+- 应用商店、媒体展示、排行榜、搜索、详情页
+- 需要 SEO 的展示型前端
-也能用，但可能有点“杀鸡用框架刀”。
+如果你的项目非常轻量、完全不需要 SSR，也可以只使用其中的 Browser/Core 能力。
 ---
-## 这个包实际导出了什么
-`@finesoft/front` 不是单一模块，而是下面几个能力的统一入口。
+## 主要导出
 ### Core
@@ -88,48 +89,45 @@
 ---
-## 三种接入方式，怎么选
+## 选择哪种接入方式
-### 方案 A：**推荐**，直接用 Vite 插件一把梭
+### 方式 A：使用 `finesoftFrontViteConfig()`
-适合绝大多数项目。
+这是推荐方式，适合大多数项目。
-你会得到：
+优点：
-- `vite`：开发
-- `vite build`：客户端 + SSR + adapter 一起构建
-- `vite preview`：本地预览 SSR 产物
+- `vite` 可直接用于开发
+- `vite build` 会同时完成客户端与 SSR 构建
+- 可以直接接入平台适配器输出部署产物
+- `vite preview` 可用于本地预览 SSR 构建结果
-入口是：`finesoftFrontViteConfig()`
+### 方式 B：手动使用 `createServer()`
-> 如果你没有特殊原因，优先选这个。它是现在这套代码里最顺手的工作流。
+适合以下情况：
-### 方案 B：手动用 `createServer()`
+- 你需要完全控制服务启动流程
+- 你已经有自定义的 Hono / Node 集成方式
+- 你不希望依赖 Vite 插件生命周期
-适合：
+### 方式 C：仅使用 Browser/Core
-- 你不想依赖 Vite 插件生命周期
-- 你已经有自己的服务启动逻辑
-- 你要手工控制 Hono/Vite/SSR 的集成方式
+适合以下情况：
-### 方案 C：纯浏览器使用
-适合：
-- 不做 SSR
-- 只想复用 Router / Framework / Action / Controller 这套模型
+- 你不需要 SSR
+- 你只希望复用 Router / Intent / Controller / Framework 模型
 ---
 ## 安装
-### 只做浏览器端
+### 仅浏览器端使用
 ```bash
 pnpm add @finesoft/front
 ```
-### 做 SSR / Vite / 部署适配
+### SSR / Vite / Adapter 使用
 ```bash
 pnpm add @finesoft/front hono @hono/node-server vite
@@ -141,44 +139,42 @@ pnpm add @finesoft/front hono @hono/node-server vite
 pnpm add dotenv
 ```
-### 关于 peerDependencies
-这个包当前依赖这些 peer：
+### 当前 peer dependencies
 - `hono`
 - `@hono/node-server`
 - `vite`
-也就是说：**浏览器-only 项目**不一定都要装全；但只要你用了 SSR / server / Vite 插件，就请把它们装上。
+如果你只使用浏览器侧能力，不一定需要全部安装；如果你使用 SSR、Server 或 Vite 插件，则建议全部安装。
 ---
-## 浏览器与服务端入口行为
+## 入口行为说明
-`@finesoft/front` 带有 `browser` export condition。
+`@finesoft/front` 提供了 `browser` export condition。
 这意味着：
-- 浏览器构建时，导入 `@finesoft/front` 会自动走 **browser-only entry**
-- Node / SSR 环境下，导入 `@finesoft/front` 会走 **完整入口**
+- 浏览器构建时，会优先解析 browser-only entry，避免引入服务端实现
+- Node / SSR 环境下，会解析完整入口，包含 Browser、SSR、Server 全部导出
-所以大多数情况下你可以放心写：
+因此大多数情况下你可以直接这样写：
 ```ts
 import { startBrowserApp } from "@finesoft/front";
 ```
-现代 bundler 会尽量避免把服务端代码拖进浏览器包里。
+现代 bundler 会根据环境自动选择更合适的入口。
 ---
-## 最推荐的用法：Vite + SSR + Hydration + Adapter
+## 推荐工作流：Vite + SSR + Hydration
-下面是一个最小可工作的接入方式。
+下面是一套面向公共用户的最小接入流程。
-### 第 1 步：准备文件结构
+### 1. 准备目录结构
-建议至少有这些文件：
+建议至少包含以下文件：
 ```text
 src/
@@ -186,23 +182,25 @@ src/
   ssr.ts
   lib/
     bootstrap.ts
+    models/
+      page.ts
     controllers/
       home-controller.ts
 index.html
 vite.config.ts
 ```
-如果你还要注册 API 代理或自定义 Hono 路由，再加一个：
+如果你需要注册 API 代理或额外 Hono 路由，可以增加：
 ```text
-src/proxies.ts
+src/setup.ts
 ```
 ---
-### 第 2 步：写 `index.html`
+### 2. 编写 `index.html`
-你的 HTML 模板**必须包含**这四个 SSR 占位符：
+你的 HTML 模板必须包含以下 SSR 占位符：
 ```html
 <!doctype html>
@@ -220,27 +218,24 @@ src/proxies.ts
 </html>
 ```
-它们的含义如下：
-| 占位符 | 会被替换成什么 |
+| 占位符 | 用途 |
 | --- | --- |
-| `<!--ssr-lang-->` | 当前语言，如 `en` / `zh` |
-| `<!--ssr-head-->` | `<head>` 内容和样式 |
+| `<!--ssr-lang-->` | 当前语言 |
+| `<!--ssr-head-->` | SSR `<head>` 内容与样式 |
 | `<!--ssr-body-->` | 服务端渲染后的 HTML |
-| `<!--ssr-data-->` | 序列化后的 server data 脚本 |
-如果少一个，SSR 体验就会开始闹脾气。
+| `<!--ssr-data-->` | 序列化后的服务端数据 |
 ---
-### 第 3 步：写路由和 Controller 注册
+### 3. 编写路由与 Controller 注册
-推荐用 `defineRoutes()`，把 URL 和 Controller 写在同一个数组里。
+推荐使用 `defineRoutes()`，把 URL 与 Controller 声明放在同一处。
 `src/lib/bootstrap.ts`：
 ```ts
 import {
+	BasePage,
 	BaseController,
 	Container,
 	Framework,
@@ -248,11 +243,16 @@ import {
 	type RouteDefinition,
 } from "@finesoft/front";
-class HomeController extends BaseController<Record<string, string>, { title: string }> {
+class HomeController extends BaseController<Record<string, string>, BasePage> {
 	readonly intentId = "home-page";
 	async execute(_params: Record<string, string>, _container: Container) {
-		return { title: "Home" };
+		return {
+			id: "page-home",
+			pageType: "home",
+			title: "Home",
+			description: "A page rendered by @finesoft/front",
+		};
 	}
 }
@@ -264,31 +264,30 @@ export function bootstrap(framework: Framework): void {
 	defineRoutes(framework, routes);
 }
-// 如果你会使用 static adapter，请务必把 routes 导出出来
+// 如果你计划使用 static adapter，建议导出 routes
 export { routes };
 ```
-#### 为什么 `static` 模式一定要导出 `routes`
+#### 为什么 `static` 模式建议导出 `routes`
-因为 `staticAdapter()` 会在构建时去读取你的路由定义，自动预渲染无参数页面。
+`staticAdapter()` 会在构建期读取你的路由定义，并自动预渲染无参数路由。
-如果不导出，静态构建就没法知道应该预渲染哪些 URL。
+如果没有导出 `routes`，静态导出时将无法自动发现这些页面。
 ---
-### 第 4 步：写浏览器入口 `src/browser.ts`
+### 4. 编写浏览器入口 `src/browser.ts`
 ```ts
 import { startBrowserApp } from "@finesoft/front";
-import { bootstrap } from "$lib/bootstrap";
+import { bootstrap } from "./lib/bootstrap";
 startBrowserApp({
 	bootstrap,
 	defaultLocale: "en",
 	mountId: "app",
 	mount: (target, { framework, locale }) => {
-		// 这里接入你的 UI 框架（Svelte / React / Vue 都行）
-		// 返回一个 update 函数，后续导航时会调用它
+		// 在这里接入你的 UI 框架（Svelte / React / Vue）
 		return ({ page, isFirstPage }) => {
 			void target;
 			void framework;
@@ -299,27 +298,22 @@ startBrowserApp({
 	},
 	callbacks: {
 		onNavigate(pathname) {
-			console.log("navigated:", pathname);
+			console.log("navigate:", pathname);
 		},
 		onModal(page) {
-			console.log("open modal:", page);
+			console.log("modal:", page);
 		},
 	},
 });
 ```
-这里有两个很重要的回调：
-- `onNavigate(pathname)`：正常页面跳转后调用
-- `onModal(page)`：当 `FlowAction` 以 modal 方式展示时调用
 ---
-### 第 5 步：写 SSR 入口 `src/ssr.ts`
+### 5. 编写 SSR 入口 `src/ssr.ts`
 ```ts
 import { createSSRRender, serializeServerData } from "@finesoft/front";
-import { bootstrap } from "$lib/bootstrap";
+import { bootstrap } from "./lib/bootstrap";
 export const render = createSSRRender({
 	bootstrap,
@@ -332,8 +326,6 @@ export const render = createSSRRender({
 		};
 	},
 	renderApp(page, locale) {
-		// 这里接入你的 SSR 渲染函数
-		// 比如 Svelte 的 render() / ReactDOMServer / Vue SSR
 		void page;
 		void locale;
 		return {
@@ -347,17 +339,11 @@ export const render = createSSRRender({
 export { serializeServerData };
 ```
-`createSSRRender()` 最终会生成一个：
-```ts
-(url: string, locale: string) => Promise<SSRRenderResult>
-```
-这个签名正好就是 server / Vite 插件所需要的 SSR module 形状。
+`createSSRRender()` 最终会生成一个 `render(url, locale)` 函数，其返回值与服务端 SSR 模块契约一致。
 ---
-### 第 6 步：如果你有 API 代理，写 `src/proxies.ts`
+### 6. 如果你有自定义 Hono 路由，编写 `src/setup.ts`
 ```ts
 import type { Hono } from "hono";
@@ -367,18 +353,18 @@ export default function setup(app: Hono) {
 }
 ```
-这里推荐导出 `default` 函数。
+建议优先导出 `default` 函数。
-`setup` 有两种传法：
+`setup` 在插件中有两种用法：
-- 传函数：只在 `dev` / `preview` 时可用
-- 传文件路径字符串：`dev` / `build` / `preview` / adapter 都可用
+- 传入函数：适用于 `dev` / `preview`
+- 传入文件路径字符串：适用于 `dev` / `build` / `preview` / adapter
-如果你要部署到 adapter 环境里，**优先传文件路径字符串**。
+如果你需要让构建产物也包含这些路由，建议传入文件路径字符串。
 ---
-### 第 7 步：配置 `vite.config.ts`
+### 7. 配置 `vite.config.ts`
 ```ts
 import { finesoftFrontViteConfig } from "@finesoft/front";
@@ -390,14 +376,14 @@ export default defineConfig({
 			locales: ["zh", "en"],
 			defaultLocale: "en",
 			ssr: { entry: "src/ssr.ts" },
-			setup: "src/proxies.ts",
+			setup: "src/setup.ts",
 			adapter: "node",
 		}),
 	],
 });
 ```
-`adapter` 支持：
+当前支持的 adapter：
 - `"node"`
 - `"vercel"`
@@ -405,11 +391,11 @@ export default defineConfig({
 - `"netlify"`
 - `"static"`
 - `"auto"`
-- 或者一个自定义 `Adapter` 对象
+- 或自定义 `Adapter` 对象
 ---
-### 第 8 步：配置脚本
+### 8. 配置脚本
 ```json
 {
@@ -423,7 +409,9 @@ export default defineConfig({
 ---
-### 第 9 步：启动项目
+### 9. 启动与构建
+开发：
 ```bash
 pnpm dev
@@ -435,7 +423,7 @@ pnpm dev
 pnpm build
 ```
-本地 SSR 预览：
+本地预览：
 ```bash
 pnpm preview
@@ -443,9 +431,239 @@ pnpm preview
 ---
-## Adapter 指南：构建后到底会产出什么
+## 完整 Svelte 示例
+下面是一套不依赖任何仓库内约定、可以独立理解的 Svelte 示例。
+### `src/lib/models/page.ts`
+```ts
+import type { BasePage } from "@finesoft/front";
+export interface HomePage extends BasePage {
+	pageType: "home";
+	body: string;
+}
+export interface ErrorPage extends BasePage {
+	pageType: "error";
+	errorMessage: string;
+	statusCode: number;
+}
+export type Page = HomePage | ErrorPage;
+```
+### `src/lib/bootstrap.ts`
+```ts
+import {
+	BaseController,
+	Container,
+	Framework,
+	defineRoutes,
+	type RouteDefinition,
+} from "@finesoft/front";
+import type { ErrorPage, HomePage, Page } from "./models/page";
+class HomeController extends BaseController<Record<string, string>, Page> {
+	readonly intentId = "home-page";
+	async execute(
+		_params: Record<string, string>,
+		_container: Container,
+	): Promise<HomePage> {
+		return {
+			id: "page-home",
+			pageType: "home",
+			title: "Hello Svelte + Finesoft Front",
+			description: "A minimal SSR page rendered by Svelte",
+			body: "This page is rendered on the server first and hydrated on the client.",
+		};
+	}
+	override fallback(
+		_params: Record<string, string>,
+		error: Error,
+	): ErrorPage {
+		return {
+			id: "page-error",
+			pageType: "error",
+			title: "Error",
+			errorMessage: error.message,
+			statusCode: 500,
+		};
+	}
+}
+const routes: RouteDefinition[] = [
+	{ path: "/", intentId: "home-page", controller: new HomeController() },
+];
+export function bootstrap(framework: Framework): void {
+	defineRoutes(framework, routes);
+}
+export { routes };
+```
+### `src/browser.ts`
+```ts
+import { startBrowserApp } from "@finesoft/front";
+import App from "./App.svelte";
+import { bootstrap } from "./lib/bootstrap";
+import type { Page } from "./lib/models/page";
+startBrowserApp({
+	bootstrap,
+	defaultLocale: "en",
+	mount: (target, { framework, locale }) => {
+		const app = new App({
+			target,
+			hydrate: true,
+			props: {
+				locale,
+				framework,
+			},
+		});
+		return (props) => {
+			app.$set(
+				props as {
+					page: Promise<Page> | Page;
+					isFirstPage?: boolean;
+				},
+			);
+		};
+	},
+	callbacks: {
+		onNavigate(pathname) {
+			console.log("navigate:", pathname);
+		},
+		onModal(page) {
+			console.log("modal:", page);
+		},
+	},
+});
+```
+### `src/ssr.ts`
+```ts
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import App from "./App.svelte";
+import { bootstrap } from "./lib/bootstrap";
+import type { ErrorPage, Page } from "./lib/models/page";
+export { serializeServerData };
+function getErrorPage(status: number, message: string): ErrorPage {
+	return {
+		id: `page-error-${status}`,
+		pageType: "error",
+		title: "Error",
+		errorMessage: message,
+		statusCode: status,
+	};
+}
+export const render = createSSRRender({
+	bootstrap,
+	getErrorPage,
+	renderApp(page, locale) {
+		const result = (App as any).render({
+			page: page as Page,
+			isFirstPage: true,
+			locale,
+		});
+		return {
+			html: result.html ?? "",
+			head: result.head ?? "",
+			css: result.css?.code ?? "",
+		};
+	},
+});
+```
+### `src/App.svelte`
+```svelte
+<script lang="ts">
+	import type { Framework } from "@finesoft/front";
+	import type { ErrorPage, Page } from "./lib/models/page";
+	export let page: Promise<Page> | Page = new Promise(() => {});
+	export let isFirstPage = true;
+	export let locale = "en";
+	export let framework: Framework | undefined = undefined;
+	$: safePage = normalizePage(page);
+	function normalizePage(value: Promise<Page> | Page): Promise<Page> | Page {
+		if (!(value instanceof Promise)) return value;
+		return value.catch(
+			(err): ErrorPage => ({
+				id: "page-error-runtime",
+				pageType: "error",
+				title: "Error",
+				errorMessage:
+					err instanceof Error ? err.message : "Failed to load page",
+				statusCode: 500,
+			}),
+		);
+	}
+	function getMessage(resolved: Page): string {
+		return resolved.pageType === "home"
+			? resolved.body
+			: resolved.errorMessage;
+	}
+</script>
+<svelte:head>
+	<title>Finesoft Front Svelte Example</title>
+	<meta
+		name="description"
+		content="Minimal Svelte SSR example powered by @finesoft/front"
+	/>
+</svelte:head>
+{#await safePage}
+	<main>
+		<h1>Loading...</h1>
+		<p>{isFirstPage ? "Preparing first page" : "Navigating"}</p>
+	</main>
+{:then resolved}
+	<main>
+		<p>locale: {locale}</p>
+		<h1>{resolved.title}</h1>
+		<p>{getMessage(resolved)}</p>
+		<nav>
+			<a href="/">Home</a>
+		</nav>
+		{#if framework}
+			<p>Framework is available on the client and can be passed to child components.</p>
+		{/if}
+	</main>
+{/await}
+```
+### 这个 Svelte 示例的关键点
+1. `browser.ts` 中使用 `hydrate: true`，让客户端接管 SSR HTML。
+2. `ssr.ts` 中使用 `App.render(...)`，并将 `{ html, head, css }` 返回给 `createSSRRender()`。
+3. `App.svelte` 的 `page` 同时支持 `Page` 与 `Promise<Page>`，兼容首屏渲染与客户端导航。
+4. 对 rejected promise 做兜底转换，可以将运行时错误转成可控的错误页面。
+5. 如果你希望子组件直接访问 `Framework`，可以再封装一层 Svelte context 工具。
+---
-这一节非常重要，因为很多人一到部署阶段就开始“咦，我文件呢？”。
+## Adapter 输出说明
 ### `adapter: "node"`
@@ -461,7 +679,7 @@ node dist/server/index.mjs
 适合：
-- 自己管 Node 进程
+- Node 服务器
 - Docker
 - VPS
 - PM2
@@ -476,13 +694,12 @@ node dist/server/index.mjs
 - `.vercel/output/static/`
 - `.vercel/output/functions/ssr.func/`
-注意：
+说明：
-- **它不在 `dist/` 里面，这是正常的**
-- 这是 Vercel Build Output API v3 的约定目录
-- 不是框架任性，是平台规定就这么放
+- 它不在 `dist/` 中，这是平台约定
+- 对应 Vercel Build Output API v3
-建议把 `.vercel/` 加进 `.gitignore`
+建议将 `.vercel/` 加入 `.gitignore`。
 ---
@@ -493,13 +710,12 @@ node dist/server/index.mjs
 - `.netlify/functions-internal/ssr/index.mjs`
 - `dist/client/_redirects`
-注意：
+说明：
-- **`.netlify/` 在 `dist/` 外面也是正常的**
-- 这是 Netlify Functions 的约定目录
-- 真正的 publish 目录通常是 `dist/client/`
+- `.netlify/` 在 `dist/` 外同样属于平台约定
+- 常见发布目录是 `dist/client/`
-同样建议把 `.netlify/` 加进 `.gitignore`
+建议将 `.netlify/` 加入 `.gitignore`。
 ---
@@ -510,10 +726,10 @@ node dist/server/index.mjs
 - `dist/cloudflare/_worker.js`
 - `dist/cloudflare/assets/`
-注意：
+说明：
-- Cloudflare Workers 环境不是完整 Node.js
-- 如果你的 `setup` 或运行时代码依赖 Node API，可能需要 `nodejs_compat`
+- Cloudflare Workers 不是完整 Node.js 环境
+- 如果运行时代码依赖 Node API，可能需要额外兼容配置
 ---
@@ -526,32 +742,32 @@ node dist/server/index.mjs
 适合：
 - 纯静态托管
-- CDN / OSS / Pages
+- CDN / 对象存储 / Pages 类平台
 - 不依赖运行时服务端逻辑的页面
-它会做的事：
+它会执行：
-1. 从你的 `routes` 导出中读取路由
-2. 自动预渲染**无参数路由**
+1. 读取导出的路由配置
+2. 自动预渲染无参数路由
 3. 复制客户端静态资源
-4. 输出纯 HTML/CSS/JS 站点
+4. 输出纯 HTML / CSS / JS 文件
-#### `static` 模式的三个重要限制
+#### `static` 模式的三个注意点
 ##### 1）只会自动预渲染无参数路由
-比如这些会自动生成：
+例如这些通常会自动生成：
 - `/`
 - `/search`
-- `/games`
+- `/about`
-这些不会自动生成：
+这些通常不会自动生成：
 - `/product/:id`
 - `/list/:category`
-如果你要预渲染动态 URL，请补充具体地址，例如：
+如果你要预渲染动态地址，请补充具体 URL：
 ```ts
 import { staticAdapter } from "@finesoft/front";
@@ -563,26 +779,20 @@ finesoftFrontViteConfig({
 });
 ```
-##### 2）构建时必须能拿到页面数据
-`static` 预渲染是**构建期执行 Controller**。
+##### 2）构建时必须能够拿到页面数据
-这意味着：
+`static` 预渲染会在构建期执行 Controller。
-- 如果你的 Controller 会 `fetch` API
-- 而构建时没有 API 服务
-- 那么页面就会渲染失败或退化成错误页
+如果 Controller 依赖外部 API，而构建时这些 API 不可访问，页面可能构建失败或退化为错误页。
-解决方式有两个：
+常见解决方式：
-- 构建时保证 API 可访问
-- 给 Controller 的 `fallback()` 提供 mock 数据回退
+- 构建期确保 API 可访问
+- 为 Controller 提供 fallback / mock 数据
-##### 3）预览静态产物时，要看的是 `dist/static/`
+##### 3）验证静态产物时，应直接查看 `dist/static/`
-`vite preview` 更适合看标准 Vite 构建产物和 SSR 预览。
-如果你要验证 `static` 最终结果，请直接服务 `dist/static/`，例如：
+如果你要验证静态导出的最终结果，可以直接服务这个目录：
 ```bash
 cd dist/static
@@ -593,20 +803,20 @@ python3 -m http.server 3000
 ### `adapter: "auto"`
-会根据环境变量自动选择：
+自动识别顺序：
 - `VERCEL` → `vercel`
 - `CF_PAGES` → `cloudflare`
 - `NETLIFY` → `netlify`
 - 默认 → `node`
-适合 CI / 平台自动识别场景。
+适合 CI 或平台自动识别场景。
 ---
-## 如果你想自己写 Adapter
+## 自定义 Adapter
-可以直接传对象：
+你也可以直接传入自定义 `Adapter` 对象：
 ```ts
 import type { Adapter } from "@finesoft/front";
@@ -614,13 +824,13 @@ import type { Adapter } from "@finesoft/front";
 const customAdapter: Adapter = {
 	name: "my-platform",
 	async build(ctx) {
-		// ctx 里有 root / vite / fs / path / templateHtml
-		// 也有 generateSSREntry / buildBundle / copyStaticAssets 等工具
+		// ctx 中包含 root / vite / fs / path / templateHtml
+		// 以及 generateSSREntry / buildBundle / copyStaticAssets 等工具方法
 	},
 };
 ```
-然后：
+使用方式：
 ```ts
 finesoftFrontViteConfig({
@@ -630,9 +840,9 @@ finesoftFrontViteConfig({
 ---
-## 手动模式：直接用 `createServer()`
+## 手动模式：`createServer()`
-如果你不想依赖 Vite 插件，也可以直接起服务器。
+如果你不希望通过 Vite 插件接入，也可以直接使用 `createServer()`。
 ```ts
 import { createServer } from "@finesoft/front";
@@ -655,28 +865,28 @@ void vite;
 void runtime;
 ```
-### `createServer()` 会帮你做什么
+### `createServer()` 会处理的内容
-1. 解析根目录
-2. 如果存在 `.env`，尝试加载它
+1. 解析项目根目录
+2. 如果存在 `.env`，尝试自动加载
 3. 检测当前运行时
-4. 开发模式下创建 Vite middleware server
+4. 在开发模式下创建 Vite middleware server
 5. 创建 Hono app
-6. 先挂你的业务路由
-7. 再挂 SSR catch-all
+6. 先注册业务路由
+7. 再挂载 SSR catch-all
 8. 启动服务
-### `createServer()` 默认行为
+默认行为：
-- `root` 默认是 `process.cwd()`
-- `port` 默认是 `process.env.PORT ?? 3000`
-- 如果根目录存在 `.env` 且安装了 `dotenv`，会自动尝试加载
+- `root` 默认值：`process.cwd()`
+- `port` 默认值：`process.env.PORT ?? 3000`
+- 根目录存在 `.env` 且安装了 `dotenv` 时，会尝试自动加载
 ---
 ## 纯浏览器模式
-如果你只想要 Framework / Router / Action / Controller，不做 SSR，也能单独使用。
+如果你只需要 Router / Intent / Controller / Framework，也可以单独使用浏览器侧能力。
 ```ts
 import { Framework, defineRoutes, startBrowserApp } from "@finesoft/front";
@@ -704,46 +914,17 @@ startBrowserApp({
 ---
-## 你最常会用到的 API
-### 路由与 Intent
-- `defineRoutes()`：声明式注册路由
-- `Framework.routeUrl()`：把 URL 匹配成 Intent
-- `Framework.dispatch()`：执行 Intent
-- `BaseController`：页面控制器基类
-### 浏览器启动
-- `startBrowserApp()`：一站式 hydration 启动
-- `registerActionHandlers()`：注册 action handlers
-- `History`：浏览器导航状态管理
-### SSR
-- `createSSRRender()`：生成 `render(url, locale)`
-- `serializeServerData()`：序列化服务端数据
-- `injectSSRContent()`：把 SSR 内容注入 HTML 模板
-### 服务端 / 部署
-- `createServer()`：手动启动 SSR 服务
-- `finesoftFrontViteConfig()`：推荐用的 Vite 插件入口
-- `nodeAdapter()` / `vercelAdapter()` / `cloudflareAdapter()` / `netlifyAdapter()` / `staticAdapter()` / `autoAdapter()`
----
-## 常见坑位（强烈建议先看）
+## 常见问题
-### 1. `index.html` 没放 SSR 占位符
+### 1. `index.html` 少了 SSR 占位符
-症状：
+现象：
-- 页面不 hydrate
-- SSR 内容丢失
-- server data 不进页面
+- 页面未正常 hydrate
+- SSR 内容缺失
+- 服务端数据未注入
-解决：检查这四个占位符是否都在：
+请检查以下四个占位符是否全部存在：
 - `<!--ssr-lang-->`
 - `<!--ssr-head-->`
@@ -752,16 +933,16 @@ startBrowserApp({
 ---
-### 2. `setup` 传了函数，但部署产物里没有生效
+### 2. `setup` 传了函数，但构建产物中没有生效
 原因：
-- 直接传函数只适合 `dev/preview`
-- adapter 构建期没法可靠地把内联函数带进去
+- 直接传函数主要适用于 `dev` / `preview`
+- 构建期更适合通过文件路径构建 `setup` 模块
-解决：
+建议：
-- 用文件路径字符串，例如 `setup: "src/proxies.ts"`
+- 使用文件路径字符串，例如 `setup: "src/setup.ts"`
 ---
@@ -771,70 +952,34 @@ startBrowserApp({
 - `staticAdapter()` 只会自动预渲染无参数路由
-解决：
+解决方式：
-- 用 `dynamicRoutes` 传入具体 URL
+- 使用 `dynamicRoutes` 提供具体 URL
 ---
-### 4. `static` 模式构建出来是 500 错误页
+### 4. `static` 模式构建出来的是错误页
-原因：
+原因通常是：
-- 构建时 Controller 调 API 失败
-- 但 `fallback()` 只返回错误页，没有 mock 数据
+- 构建期 Controller 访问外部 API 失败
+- 但 fallback 没有提供可用的本地数据
-解决：
+解决方式：
-- 构建时保证 API 可访问，或者
-- 给 Controller 增加 mock fallback
+- 保证构建期 API 可访问，或
+- 给 Controller 提供 fallback / mock 数据
 ---
 ### 5. `.vercel/` 和 `.netlify/` 为什么不在 `dist/`
-答案：
-- **这是平台规范，不是 bug**
-- Vercel 要求 `.vercel/output/`
-- Netlify 要求 `.netlify/functions-internal/`
-建议：
-- 把它们加入 `.gitignore`
----
-## 一个更完整的推荐心智模型
-你可以把它理解成下面这条链路：
-$$
-URL \rightarrow Router \rightarrow Intent \rightarrow Controller \rightarrow Page\ Model \rightarrow SSR / Browser\ UI
-$$
-也就是说：
-- URL 负责定位页面语义
-- Intent 负责描述“我要什么页面”
-- Controller 负责拉数据和组装页面模型
-- UI 层只负责把 `Page` 渲染出来
-这也是这套框架最值钱的地方：**页面逻辑和 UI 框架解耦**。
----
-## 最后给一个实战建议
-如果你第一次接这个包，建议按下面顺序推进：
+这是平台约定，不是框架异常：
-1. 先只做一个 `/` 首页
-2. 跑通 `browser.ts` + `ssr.ts` + `index.html`
-3. 再接 `finesoftFrontViteConfig()`
-4. 开发阶段先用 `adapter: "node"`
-5. 最后再切 `vercel` / `netlify` / `cloudflare` / `static`
+- Vercel 使用 `.vercel/output/`
+- Netlify 使用 `.netlify/functions-internal/`
-别一上来就同时搞多语言、动态路由、SSR、静态预渲染、平台部署。那样很容易把自己卷成一个调试陀螺。
+建议将这些目录加入 `.gitignore`。
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@finesoft/front",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Full-stack framework: router, DI, actions, SSR, and server — all in one package",
   "license": "MIT",
   "type": "module",