weifuwu 0.89.1 → 0.90.0

package/docs/client.md

@@ -0,0 +1,170 @@
+# weifuwu 客户端文档（client）
+
+> 前端开发者入口。**代码即文档**：本文件只写「地图 + 规则要点」——
+> 细节全部指向源码/测试（源码就是最高保真文档）。
+> 组件编写规范入口在本文件 §5（新增/修改组件必读）。
+
+## 目录
+
+- [1. 快速上手](#1-快速上手)
+- [2. 组件清单](#2-组件清单)
+- [3. 设计语言](#3-设计语言)
+- [4. 布局系统](#4-布局系统)
+- [5. 组件编写规范（唯一入口）](#5-组件编写规范唯一入口)
+- [6. 前端架构导论](#6-前端架构导论)
+- [7. 关键范式](#7-关键范式)
+
+---
+
+## 1. 快速上手
+
+```tsx
+import { createApp, Router, Button, Modal } from 'weifuwu'
+
+const app = createApp({ mount: '#root' })
+app.router(Router())
+// 组件 = 工厂同步 + 渲染纯同步——见 §5.1
+```
+
+前端三层：`uiServe`（应用引导）/ `uiSsr`（服务端渲染）/ `components`（UI 组件库）。
+入口实现：`src/client/index.ts` · 中间件：`src/client/middleware/`。
+
+## 2. 组件清单
+
+**134 个组件**——源码目录即清单：`src/client/components/<Comp>/<Comp>.ts`（每个含
+`<Comp>.css` + 契约测试）。展示与使用示例：`apps/showcase/`（localhost:3200——
+`/components/<id>` 每组件一页 + demo 源码即用法）。
+
+组件分类速查（详见 `apps/showcase/src/demos/` 与 registry）：
+
+| 类 | 代表组件 |
+| --- | --- |
+| 通用基础 | Button / Card / Badge / Avatar / Alert / EmptyState / Loading / Modal / Drawer |
+| 表单 | Input / Textarea / Select / DatePicker / Upload / Form / Checkbox / Switch / Slider |
+| 数据展示 | Table / VirtualTable / Chart / Tree / CodeBlock / DiffView / Kanban |
+| 导航 | NavBar / TabBar / Breadcrumb / Pagination / Menu / NavMenu / Anchor |
+| 反馈 | Toast / Confirm / Notification / Popconfirm / ProgressBar / Skeleton |
+| AI 特色 | AiChat / ChatInput / ToolCallCard / ApprovalCard / CitationCard / StreamingText |
+| 命令式 | `toast()` / `confirm()` / `ui.openPopup()` / `ui.render()` |
+
+移动端适配：断点 768px · 44px 命中区 · safe-area 常量——组件与布局内建。
+
+**三库对照**（antd / Element Plus / shadcn-ui 映射）——表格历史长度大，按需查：
+源码键 `apps/showcase/src/registry/components.ts`（每组件 `meta: { antd, ep, shadcn }`
+字段）是**机制化事实源**——查询即 grep，不再维护纸质映射表。
+
+## 3. 设计语言
+
+微流明（Whisper Luminance）：中性色主导、品牌色点睛、动效短促有目的（120–300ms）、
+1px 边界即结构。**Token 即规范**——`src/client/layout/style.css`（183 双层 token：
+色阶/排版/动效/圆角/阴影/z-index）——组件只引用 token、零硬编码（audit 强制）。
+
+品牌换色 = 改 seed 一个值；预设主题 = `data-theme` 一个属性（minimal/dark）。
+
+## 4. 布局系统
+
+`src/client/layout/`——49 原语（`_*.css`）+ 92 工具 + 2 内部，全部 `wf-` 前缀：
+
+- **原语**：`wf-stack` / `wf-row` / `wf-grid` / `wf-center` / `wf-card-surface` / `wf-divider`
+- **工具**：`wf-padding` / `wf-margin` / `wf-text-*` / `wf-bg-*` / `wf-hidden`
+- **命名规则**：三类词根 + 三后缀（完整词根表见 `apps/showcase/src/demos/layout.tsx`
+  与 `src/test/contract/layout-inventory.test.ts` L1 计数断言——**测试即登记表**）
+
+零值形态唯一（`none` 归一）· 对齐域禁方向词 · 双名歼灭——layout-inventory 8 断言锁定。
+
+## 5. 组件编写规范（唯一入口）
+
+> 新建/修改组件前读本节——其余 § 按需。
+> 规则可执行、检查可机制化：**红线写错即响**（§5.6），作者只需记住清单。
+
+### 5.1 作者契约
+
+- 工厂**同步**（类型层强制）· 渲染**纯同步** · 异步全在 hooks/事件回调
+- 状态闭包 mount 作用域 · 稳定回调/ref 定义 mount 层
+- 资源清理 `ctx.ui.hold(fn)` · 浏览器环境经 `ctx.browser`（**零全局 window/document**
+  ——SSR 崩溃铁律，BackTop 实证）
+
+### 5.2 三件套
+
+```
+src/client/components/<Comp>/
+  <Comp>.ts    # 组件
+  <Comp>.css   # 样式（必有——style-audit 文件数基线 +1）
+  <Comp>.test.ts  # 契约 harness（命令流断言——零浏览器）
+```
+
+### 5.3 API 形状
+
+props camelCase · **`className=`（组件 props）`class=`（DOM 元素）** ·
+受控三件套（value/onChange + 缺回调 warn）· 事件经事件表（函数 props 不写 attribute）·
+受控回流门控（引用比较 + live 门控）· value 走 property · aria 布尔归一 ·
+可交互 div 三件套：role + tabindex + onKeyDown
+
+### 5.4 CSS 纪律
+
+全部 `--wf-*` token 化（零硬编码色/字号）· 类名 `wf-` 前缀 ·
+**状态变体类必须有规则或 `:where(.wf-x) {}` 显式声明**（L3 已扩围组件源码——未定义立即红）·
+动效 `--wf-dur-*`/`--wf-ease-*` · transition 含 visibility（隐藏不可 Tab 聚焦）
+
+### 5.5 测试二层（覆盖哨兵 ≥2 层）
+
+1. **契约 harness**（`<Comp>.test.ts`——mount/render/createTable 命令流断言）
+2. **showcase comp**（`apps/showcase/test/comp-<id>.test.ts`——真实 DOM：
+   浮层断言「在哪」（assertPopupGeometry）· 表单断言值回流 · 交互断言操作→状态）
+
+### 5.6 红线（机制化——写错即响）
+
+| 红线 | 机制 |
+| --- | --- |
+| 空串=空洞 · isHoleKind/isTextKind 单源 | audit:semantics |
+| 硬编码色/字号 | audit:theme + style-audit S1/S6 |
+| 状态变体类未定义 | layout-inventory L3 |
+| 受控回流未门控 · 死变量/死函数 | audit:interactivity |
+| renderFn 同步段 timer · 全局 window | effect-guard + audit:vdom |
+| 交互面无测试断言 | audit:interactivity L2 |
+| 事件进 attrs / value 走 attribute | 契约 7/8 |
+
+### 5.7 注册与文档
+
+`src/client/components/index.ts` 导出 · `apps/showcase/src/registry/components.ts`
+**追加不替换**（四字段 + gotchas）· demos 注册（组件名=demo 键）·
+style-audit 文件数基线 +1 · 覆盖哨兵跑绿（`scripts/audit-component-coverage.mjs`）
+
+### 5.8 修改纪律
+
+范围：应用层修用例 · 组件层修组件 · **核心层修核心**（引擎 bug 透过组件暴露）·
+R-03：类名/结构变更**反查测试选择器**（`[class*="..."]` 定位器）·
+行为变化**必带契约测试** · 机制化优先（能进审计不靠记忆）
+
+## 6. 前端架构导论
+
+```
+浏览器导航/URL ──► UIRouter（共享 trie 内核 src/shared/router/）
+                      │
+                    uiServe ──► 渲染周期（src/client/vdom/core/v2/cycle.ts）
+                      │            build/diff → 命令流（13 种 NDJSON）
+                      │            → apply（DOM）→ cleanup（卸载）
+                      └──► ctx 中间件（router/api/auth/ws/i18n/confirm/toast）
+```
+
+- **命令流即文档**：13 种命令（create/insert/remove/setProp/…）序列化可回放——
+  `src/client/vdom/core/patch/types.ts` 类型定义就是协议
+- **状态机**：NodeState/CompState/IntervalState——`patch/state-machine.ts` 单一实现源
+- **SSR ≡ SPA 首帧**：uiSsr 同路由器同 bundle——吸收零差异
+- hooks 面：`src/client/vdom/hooks/`（useAsyncData/useObservable/signal——getter 纪律）
+- 全链路 Observable（cycle/observable.ts）——组合/取消/回放四优势
+
+## 7. 关键范式
+
+- **命令式弹窗唯一形态**：`ctx.ui.openPopup(opts)` → PopupHandle——`src/client/vdom/hooks/popup-manager.ts`
+  ——**anchor 必传**（无 anchor 触发按钮被当外部点击 + toggle 死循环）
+- **焦点管理三范式**：`src/client/components/` 内实现 + `src/test/scenario/e2e-focus*.test.ts`
+  场景断言（Trap 浮层 / 可交互 div 键盘可达 / 列表 roving focus）
+- **受控输入纪律**：onInput 逐键 + onChange 失焦——ChatInput 实现即示例
+- **getter 纪律**：一切会变化的值 = `() => T`——任意位置调用取最新
+- **组件定时器**：工厂期创建 + `ctx.ui.hold` 注册清理（renderFn 窗口内建 timer = dev warn）
+
+---
+
+> **运行**：`npm run test:client`（428 契约）· `npm run test:scenario`（123 场景）·
+> `npm run test:showcase`（324 组件测试）——全量防线见 AGENTS.md §1。

package/docs/server.md

@@ -0,0 +1,112 @@
+# weifuwu 服务端文档（server）
+
+> 后端开发者入口。**代码即文档**：本文件只写「地图 + 协议概要」——
+> 细节全部指向源码/测试（协议类型定义就是规范本体）。
+
+## 目录
+
+- [1. 快速上手](#1-快速上手)
+- [2. 中间件清单](#2-中间件清单)
+- [3. 环境变量](#3-环境变量)
+- [4. AI Stream Protocol](#4-ai-stream-protocol)
+- [5. 数据层](#5-数据层)
+- [6. 实时与渲染](#6-实时与渲染)
+
+---
+
+## 1. 快速上手
+
+```ts
+import { createServer, Router } from 'weifuwu'
+
+const server = createServer()
+server.route(Router()
+  .get('/api/hello', (req, ctx) => ctx.json({ ok: true })))
+server.listen(3000)
+```
+
+入口：`src/server/index.ts` · 路由内核：`src/server/core/`（Router/serve/WS hub——
+与前端 UIRouter 共享 `src/shared/router/` trie/pipeline 五层单源）。
+
+## 2. 中间件清单
+
+`src/server/middleware/`——按 `ctx` 注入能力，Handler 从 ctx 读取：
+
+| 中间件 | ctx 面 | 说明 |
+| --- | --- | --- |
+| `postgres()` | `ctx.sql` | PG v3 自研协议（无 pg 依赖） |
+| `redis()` | `ctx.redis` | RESP2 自研协议 |
+| `scheduler()` | `ctx.schedule` | 任务调度（持久化/恢复） |
+| `queue()` | `ctx.queue` | 任务队列（worker/retry/backoff） |
+| `messager()` | `ctx.msg` | 部门内部消息（面向 agent） |
+| `userSystem()` | `ctx.auth`/`ctx.user` | 注册/登录/token/角色/租户 |
+| `rateLimit()` | — | 令牌桶（per-key/per-user） |
+| `email()` | `ctx.email` | resend/smtp 双 adapter |
+| `ai()` | `ctx.ai` | LLM/embedding adapter（OpenAI 兼容） |
+| `ui()` | `ctx.ui` | SSR + JS/CSS 编译（`html/js/css/ssr`） |
+| `graphql()` | `ctx.gql` | GraphQL 层（Schema/Resolver） |
+| `ws()` | `ctx.ws` | WebSocket hub（订阅/广播） |
+
+依赖注入声明：`injects/depends`——`src/shared/router/ctx-fields.ts`（未注册依赖
+抛错——类型/运行时双层）。
+
+## 3. 环境变量
+
+> 均可经中间件 options 显式传入（env 为默认来源）。默认值与代码对齐
+> （`src/server/middleware/*.ts` 构造处）。
+
+| 变量 | 用途 | 模块 | 默认 |
+| --- | --- | --- | --- |
+| `DATABASE_URL` | PostgreSQL 连接串 | `postgres()` | —（必填） |
+| `REDIS_URL` | Redis 连接串 | `redis()` | —（必填） |
+| `AUTH_SECRET` | userSystem HMAC 密钥（≥16 字符） | `userSystem()` | — |
+| `DEEPSEEK_API_KEY` | LLM provider key | `ai()` | — |
+| `DEEPSEEK_BASE_URL` / `MODEL` | LLM 端点/模型 | `ai()` | `api.deepseek.com/v1` / `deepseek-v4-flash` |
+| `DASHSCOPE_*` | embedding provider | `ai({ embedding })` | `deepseek` 同域 |
+| `RESEND_API_KEY` / `SMTP_*` | 邮件 adapter | `email()` | `localhost:3025` |
+| `PORT` | 服务端口 | `serve()` | `3000` |
+
+## 4. AI Stream Protocol
+
+**协议即类型**（单源）：`src/server/ai/types.ts`——修改协议先改此处，两侧实现对齐。
+
+```
+后端 → 前端（SSE 下行，wf: 事件——见 src/server/ai/sse.ts）
+   wf:message_start / wf:token / wf:tool_call / wf:tool_progress
+   wf:step / wf:approval_request / wf:usage / wf:done / wf:error
+前端 → 后端（POST 上行——src/client/vdom/hooks/chat.ts 编码同构）
+   provider 请求体 + 会话/工具调用回执
+```
+
+语义要点（实现于 `src/server/ai/*.ts` 与客户端解析器——**代码即规范**）：
+
+- 错误即值（`wf:error` 事件——非 HTTP 异常通道）
+- 未知事件透传（`x:*` 自定义扩展）
+- HITL 审批：`wf:approval_request` → 拒绝≠终止 · modified 改参 · 超时兜底
+- 追踪关联：`traceId` 全链路透传
+
+消费端：`ctx.ai.chat()`（服务端流式）与 `useChat`（客户端会话语义层）。
+
+## 5. 数据层
+
+- **postgres**：`src/server/middleware/postgres.ts`——自研 PG v3 wire protocol
+  （无第三方客户端依赖）——`ctx.sql.query/transaction`
+- **redis**：`src/server/middleware/redis.ts`——自研 RESP2——`ctx.redis.get/set/pub`
+- **Query Language**：`src/server/core/query-lang*`——AST 双后端（pg/内存——
+  测试零外部依赖）——`Memory` 实现零数据库跑测试
+- schema 迁移：`src/server/core/migrate*`
+
+## 6. 实时与渲染
+
+- **scheduler**：`src/server/middleware/scheduler.ts`——`ctx.schedule.cron/once` +
+  持久化恢复（重启续跑）
+- **ui**：`ctx.ui.html/js/css/ssr`——TSX 动态编译（esbuild 同步）+ 组件 SSR
+  （`src/ssr.ts`——SSR ≡ SPA 首帧纪律）
+- **graphql**：`src/server/middleware/graphql.ts`——Schema-first
+- **WebSocket**：`src/server/core/ws-hub.ts`——连接/房间/广播 + 心跳
+
+---
+
+> **运行**：`npm run test:server`（163 契约）· 直跑
+> `node --env-file=.env --test src/server/core/*.test.ts src/shared/router/*.test.ts`
+> —— db 真库依赖 docker（无 docker 跑 `src/server/core/*.test.ts` 子集）。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.89.1",
+  "version": "0.90.0",
   "description": "AI SaaS full-stack framework — backend HTTP + frontend VDOM + 129 components + CSS design system + SaaS foundation (auth/queue/AI). Zero-build, zero-dependency.",
   "exports": {
     ".": {
@@ -49,8 +49,6 @@
     "audit:semantics": "node scripts/audit-core-semantics.mjs",
     "audit:showcase": "node scripts/audit-showcase-dev.mjs",
     "audit:all": "npm run audit:semantics && npm run audit:interactivity && npm run audit:vdom && npm run audit:theme && npm run audit:api && npm run audit:bundle && npm run audit:showcase",
-    "bench:server": "node bench/server-bench.ts",
-    "bench:db": "node bench/db-bench.ts",
     "test:contract-components": "node --env-file=.env --test 'src/client/components/**/*.test.ts'",
     "audit:interactivity": "node scripts/audit-interactivity.mjs",
     "audit:theme": "node scripts/audit-theme.mjs",