@h-ai/cli 0.1.0-alpha.53 → 0.1.0-alpha.55

package/templates/skills/hai-app-create/reference.md

@@ -0,0 +1,350 @@
+# hai-app-create — 详细用法
+
+从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
+
+> 面向 AI 助手的应用功能创建指南。**必须遵循 TDD**：先写测试（Red）→ 再实现（Green）→ 再重构（Refactor）。
+> 若目标是纯 API service workspace，优先围绕 `apps/*-contract`、`apps/*-service` 与测试组织改动，而不是套用页面/路由脚手架。
+
+## 适用场景
+
+- 新增页面（路由）
+- 新增 API 端点
+- 新增服务层模块（`$lib/server/services/`）
+- 新增数据库表 / 数据模型
+- 新增业务组件
+
+## TDD 开发流程（强制）
+
+创建任何新功能时，必须按以下顺序执行：
+
+### Step 1：需求分析与测试设计
+
+1. 明确功能的输入、输出、边界条件、错误场景
+2. 确定需要创建的文件（服务、路由、Schema、组件等）
+3. 设计测试用例清单（参照 `hai-app-tests` 技能的覆盖范围要求）
+
+### Step 2：编写测试（Red 阶段）
+
+1. **创建单元测试**：在 `tests/` 下为服务层、Schema 编写 Vitest 测试
+2. **创建 E2E 测试**：在 `e2e/` 下为 API 端点、页面交互编写 Playwright 测试
+3. **创建空的实现文件**：仅包含函数签名和类型定义，不写实际逻辑（确保 import 不报错）
+4. **运行测试确认新增目标用例因预期行为缺失而失败（既有回归保持通过）**：
+   ```bash
+   pnpm --filter <app-name> test        # 新增目标用例应 FAIL，既有回归应 PASS
+   ```
+
+### Step 3：编写实现（Green 阶段）
+
+按照下文的「创建指南」编写实际功能代码，每完成一个功能点立即运行测试确认通过。
+
+### Step 4：重构与验证（Refactor 阶段）
+
+1. 参照 `hai-app-review` 审查代码规范
+2. 运行质量门禁：`pnpm typecheck && pnpm lint && pnpm test`
+3. 运行 E2E：`pnpm --filter <app-name> test:e2e`
+
+## 目录结构约定
+
+```
+src/
+  hooks.server.ts                # `handle` hook 入口
+  app.css                        # 全局样式（TailwindCSS 4）
+  lib/
+    server/
+      init.ts                    # 应用初始化（模块 init 顺序）
+      services/                  # 业务服务层（Server-only）
+        index.ts                 # 服务聚合导出
+        user.ts                  # 示例：用户服务
+      schemas/                   # 请求校验 Schema（Zod）
+    components/                  # 业务组件（非 @h-ai/ui 通用组件）
+    stores/                      # 客户端 Store（Svelte 5 Runes）
+    paraglide/                   # i18n 生成文件（禁止手动修改）
+  routes/
+    +layout.svelte               # 根布局
+    +page.svelte                 # 首页
+    (auth)/                      # 认证分组路由
+      login/+page.svelte
+    admin/                       # 管理区域
+      users/
+        +page.svelte             # 列表页
+        +page.server.ts          # 列表数据加载
+        [id]/
+          +page.svelte           # 详情页
+          +page.server.ts
+    api/                         # API 端点
+      auth/+server.ts
+      health/+server.ts
+      iam/
+        users/+server.ts
+  messages/                      # i18n 消息文件
+    en-US.json
+    zh-CN.json
+  config/                        # 模块配置文件
+    _core.yml
+    _db.yml
+    _cache.yml
+    _iam.yml
+```
+
+## 创建页面
+
+### 页面路由规则
+
+使用 SvelteKit 文件路由，参考 `src/routes/` 约定：
+
+| 类型     | 路径示例                           | 说明                 |
+| -------- | ---------------------------------- | -------------------- |
+| 静态页面 | `routes/about/+page.svelte`        | 常规页面             |
+| 动态路由 | `routes/users/[id]/+page.svelte`   | URL 参数             |
+| 分组路由 | `routes/(auth)/login/+page.svelte` | 共享布局，不影响 URL |
+| API 端点 | `routes/api/users/+server.ts`      | RESTful API          |
+
+### 页面文件模板
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  // Svelte 5 Runes 语法
+  let { data } = $props()
+  let loading = $state(false)
+
+  async function handleAction() {
+    loading = true
+    try {
+      // 业务逻辑
+    } finally {
+      loading = false
+    }
+  }
+</script>
+
+<div class="container mx-auto p-4">
+  <!-- 使用 @h-ai/ui 组件 -->
+</div>
+```
+
+### 数据加载（+page.server.ts）
+
+```typescript
+import type { PageServerLoad } from './$types'
+import { error, redirect } from '@sveltejs/kit'
+
+export const load: PageServerLoad = async ({ locals }) => {
+  if (!locals.session)
+    redirect(303, '/auth/login')
+  const result = await someService.list()
+  if (!result.success)
+    error(500, result.error.message)
+  return { items: result.data }
+}
+```
+
+## 创建 API 端点
+
+### RESTful 端点模板
+
+```typescript
+// src/routes/api/[resource]/+server.ts
+import type { RequestHandler } from './$types'
+import { kit } from '@h-ai/kit'
+import { z } from 'zod'
+
+const CreateSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().optional(),
+})
+
+// GET - 列表
+export const GET = kit.handler(async ({ locals }) => {
+  kit.guard.require(locals.session, 'resource:read')
+
+  const result = await service.list()
+  if (!result.success)
+    return kit.response.error(result.error.code, result.error.message)
+  return kit.response.ok(result.data)
+})
+
+// POST - 创建
+export const POST = kit.handler(async ({ request, locals }) => {
+  kit.guard.require(locals.session, 'resource:create')
+
+  const data = await kit.validate.body(request, CreateSchema)
+
+  const result = await service.create(data)
+  if (!result.success)
+    return kit.response.error(result.error.code, result.error.message)
+  return kit.response.created(result.data)
+})
+```
+
+### 要点
+
+- 所有端点**必须**用 `kit.handler(async ({ locals, request, ... }) => { ... })` 包裹，由 handler 统一处理 throw 的 Response
+- 权限守卫使用 `kit.guard.require(locals.session, 'xxx:yyy')`，它本身就是 throw 模式（未通过时 throw 403 Response），**无需**检查返回值
+- 输入校验使用 `await kit.validate.body(request, Schema)`，校验失败时 throw 400 Response，**无需**手动判断 valid
+- 返回统一使用 `kit.response.*`
+- HaiResult 错误直接透传，不重新包装
+- HaiResult 型业务操作先检查 result.success；流和显式抛错 API 按各自契约处理
+
+## 创建服务层
+
+服务层位于 `$lib/server/services/`，处理业务逻辑。
+
+```typescript
+import type { HaiResult, PaginatedResult } from '@h-ai/core'
+import { core, ok } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+
+// Article/CreateArticleInput/ListParams 为应用类型；已完成建表。
+const articles = reldb.crud.table<Article>({
+  table: 'articles',
+  idColumn: 'id',
+  dbType: 'sqlite', // 与本例初始化后端一致；切换数据库时同步修改
+  select: ['id', 'title', 'created_at AS createdAt'],
+})
+
+export async function createArticle(input: CreateArticleInput): Promise<HaiResult<Article>> {
+  const article = { ...input, id: core.id.generate(), createdAt: new Date().toISOString() }
+  // DB 列映射由应用定义；create 返回 ExecuteResult，不是 Article。
+  const result = await articles.create({ id: article.id, title: article.title, created_at: article.createdAt })
+  if (!result.success) return result
+  return ok(article)
+}
+
+export async function listArticles(params: ListParams): Promise<HaiResult<PaginatedResult<Article>>> {
+  return articles.findPage({ pagination: params })
+}
+```
+
+### 服务层规则
+
+- 统一返回 `HaiResult<T>`
+- 写操作需 `debug`（进入）+ `info`（成功）日志
+- 读操作仅 `debug` 日志
+- 禁止 `console.log`，使用 `core.logger`
+- 服务层不处理 HTTP 响应格式，只返回 HaiResult
+
+## 创建数据模型
+
+### Schema 定义（SQL DDL）
+
+数据库表 Schema 定义在 `$lib/server/init.ts` 中：
+
+```typescript
+const BUSINESS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS articles (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  content TEXT,
+  author_id TEXT NOT NULL,
+  status TEXT DEFAULT 'draft',
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_articles_author_id ON articles(author_id);
+CREATE INDEX IF NOT EXISTS idx_articles_status ON articles(status);
+`
+```
+
+### 类型定义
+
+```typescript
+// 在服务文件或独立类型文件中定义
+interface Article {
+  id: string
+  title: string
+  content: string | null
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  createdAt: string
+  updatedAt: string
+}
+
+interface CreateArticleInput {
+  title: string
+  content?: string
+  authorId: string
+}
+```
+
+## 创建业务组件
+
+业务组件放在 `$lib/components/`，通用 UI 使用 `@h-ai/ui`。
+
+```svelte
+<!-- src/lib/components/ArticleCard.svelte -->
+<script lang="ts">
+  import type { Article } from '$lib/server/services/article'
+
+  let { article, onEdit }: { article: Article, onEdit?: () => void } = $props()
+</script>
+
+<div class="card bg-base-100 shadow">
+  <div class="card-body">
+    <h2 class="card-title">{article.title}</h2>
+    <p>{article.content ?? ''}</p>
+    {#if onEdit}
+      <div class="card-actions justify-end">
+        <button class="btn btn-primary" onclick={onEdit}>编辑</button>
+      </div>
+    {/if}
+  </div>
+</div>
+```
+
+### 组件规则
+
+- 使用 Svelte 5 Runes 语法（`$props()`、`$state()`、`$derived()`、`$effect()`）
+- 事件回调通过 props 传入（非 `createEventDispatcher`）
+- 样式使用 TailwindCSS 4 + DaisyUI 5 class
+- 通用 UI 组件优先使用 `@h-ai/ui`，不重复实现
+- i18n 文本使用 `$lib/paraglide/messages.js` 中的 key
+
+## 初始化顺序
+
+在 `$lib/server/init.ts` 中管理模块初始化顺序：
+
+```
+core.init() → reldb.init() → cache.init() → iam.init() → createBusinessTables()
+```
+
+新增模块时需在此文件中按依赖顺序添加初始化调用。
+
+## 容器交付
+
+- 保持脚手架根目录 `Dockerfile`、`.dockerignore` 与 `package.json` 中 `docker:build*` / `podman:build*` 命令同步。
+- Podman 多阶段构建保持 `--format docker --jobs=1`；前者保留 `HEALTHCHECK`，后者避免部分 Podman 5.8/Buildah 组合在并行 stage 构建时触发内部 semaphore panic。
+- 先复制 lockfile 与 workspace 配置执行 `pnpm fetch`，再复制源码并离线安装、构建；避免源码变化重复下载依赖，同时兼容新增 workspace。
+- SvelteKit 服务使用 Node adapter；纯 Vite 前端使用带 SPA fallback 的静态镜像；fullstack 的 Service 与 Web 分别交付，Service 直接监听且不增加转发进程。
+- Web 的 `PUBLIC_*` 部署配置在容器启动时生成静态运行时配置，不作为 build arg 烘焙，确保同一镜像可跨环境部署。
+- 配置文件随镜像提供，并允许只读挂载覆盖；密钥只通过环境变量或 `--env-file` 注入。
+- 普通构建不携带 `data/`；只有用户明确运行 `docker:build:data` / `podman:build:data` 时才通过 named build context 嵌入 SQLite/本地存储初始快照。
+- 数据库和本地存储的持续写入必须落到 volume，不能依赖镜像可写层。
+- 完成前实际启动镜像，验证健康端点、非 root 用户、环境变量覆盖、配置挂载和预置数据读取。
+
+## 检查清单
+
+- [ ] **TDD 流程已执行**：先写测试 → 确认失败 → 再实现 → 确认通过
+- [ ] 单元测试已编写（服务层、Schema）
+- [ ] E2E 测试已编写（API 端点、页面交互）
+- [ ] 页面使用 Svelte 5 Runes 语法
+- [ ] API 端点有权限守卫与输入校验
+- [ ] 服务层统一返回 `HaiResult<T>`
+- [ ] 日志级别正确（读 debug / 写 debug+info / 失败 warn|error）
+- [ ] 禁止 `console.log`、`any`、硬编码密钥
+- [ ] 用户可见文本走 i18n
+- [ ] Docker / Podman 镜像可启动，配置/环境变量/数据目录行为已验证
+- [ ] 新增表有索引定义
+- [ ] 组件优先使用 `@h-ai/ui`
+- [ ] `pnpm typecheck && pnpm lint && pnpm test` 通过
+
+## 相关 Skills
+
+- `hai-build`：项目架构与模块初始化顺序
+- `hai-app-tests`：TDD 测试规范（Red 阶段详细指引）
+- `hai-app-review`：代码审查规范（Refactor 阶段参照）
+- `hai-kit`：SvelteKit 集成的完整 API
+- `hai-ui`：UI 组件库使用
+- `hai-reldb`：数据库操作详细 API
+- `hai-iam`：认证与权限管理

package/templates/skills/hai-app-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-app-review
-description: 对应用代码进行审查：路由安全 → 认证授权 → i18n → 组件使用 → API 端点 / service workspace → 服务层 → 性能，并补充产品体验与交互走查；当需求涉及代码审查、规范化、质量检查时使用。
+description: "审查 hai 应用的路由、权限、i18n、服务层与交互体验。"
 ---
 
 # hai-app-review — 应用代码审查规范
@@ -9,16 +9,14 @@ description: 对应用代码进行审查：路由安全 → 认证授权 → i18
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 对应用代码进行审查：路由安全 → 认证授权 → i18n → 组件使用 → API 端点 / service workspace → 服务层 → 性能，并补充产品体验与交互走查；当需求涉及代码审查、规范化、质量检查时使用。 |
-| 适用场景 | 当任务与 `hai-app-review` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 用户指定的审查范围、代码/差异、仓库规范与可复现证据 |
-| 输出 | 按优先级排列的问题、影响、定位和修正建议；仅在用户要求时实施修改 |
-| 限制 | 不把风格偏好当缺陷，不猜测未读取的实现，不在审查请求中擅自发布或改动外部状态 |
+| 能力 | 审查 hai 应用的路由、权限、i18n、服务层与交互体验 |
+| 适用场景 | 用户要求应用代码/体验审查或修复评估 |
+| 输入 | 用户指定范围、代码/差异、运行证据与验收要求 |
+| 输出 | 按优先级列出的证据、影响和修正建议 |
+| 限制 | 只读审查不自动改代码；未读取的实现不下结论，不把偏好当缺陷。实现修复需用户已授权。 |
 
 > 面向 AI 助手的应用代码审查指南。用于审查使用 hai-framework 构建的 SvelteKit 应用、纯 Svelte/Vite 客户端与 API service workspace。本技能也是 TDD Refactor 阶段的执行入口。
 
----
-
 ## 适用场景
 
 - 审查应用代码是否符合 hai-framework 规范
@@ -26,8 +24,6 @@ description: 对应用代码进行审查：路由安全 → 认证授权 → i18
 - 规范化现有代码（分层、命名、日志、i18n）
 - 安全审查（权限、输入校验、密钥管理）
 
----
-
 ## 工作准则
 
 1. **先搜索再改动**：用全局检索确认引用关系，避免遗漏更新。
@@ -35,8 +31,6 @@ description: 对应用代码进行审查：路由安全 → 认证授权 → i18
 3. **成套更新**：代码 / 测试 / 文档同步。
 4. **重构后测试必须仍通过**：任何重构都不能破坏已有测试。
 
----
-
 ## 审查清单
 
 ### TDD 合规性
@@ -49,8 +43,6 @@ description: 对应用代码进行审查：路由安全 → 认证授权 → i18
 - [ ] `pnpm test` 单元测试全部通过
 - [ ] `pnpm test:e2e` E2E 测试全部通过
 
----
-
 ## 审查清单
 
 ### 架构分层
@@ -63,9 +55,11 @@ description: 对应用代码进行审查：路由安全 → 认证授权 → i18
 
 ### HaiResult 处理
 
-- [ ] 所有框架模块调用都检查 `result.success`
+- [ ] 投递等业务状态按 `sent` 等字段判断，失败保留用户输入；HTTP/HaiResult 成功不代替业务完成
+
+- [ ] 返回 HaiResult 的调用先检查 `result.success`
 - [ ] 上游 HaiResult 错误直接透传，不重新包装
-- [ ] 不使用 `try/catch` 来处理框架模块返回的错误（模块 API 不抛异常，统一返回 `HaiResult<T>`）
+- [ ] 不使用 `try/catch` 来处理框架模块返回的错误（HaiResult 型 API 的业务错误在结果中；流/显式抛错 API 另按契约处理）
 
 ```typescript
 // ❌ 重新包装
@@ -82,7 +76,7 @@ if (!result.success)
 
 ### 权限与安全
 
-- [ ] 所有 API 端点和 `load` 函数有 `kit.guard.*` 守卫
+- [ ] 受保护端点/load 有与实际框架匹配的守卫；公开路由显式允许匿名，不给 API service 强加 kit.guard
 - [ ] 所有用户输入通过 Zod Schema 校验（`kit.validate.*`）
 - [ ] 无硬编码 API Key / 密钥
 - [ ] 日志不输出密码、token 明文
@@ -150,8 +144,6 @@ if (!result.success)
 - [ ] 初始化在 `$lib/server/init.ts` 统一管理
 - [ ] 配置文件路径遵循 `config/_<module>.yml` 约定
 
----
-
 ## 质量门禁
 
 审查完成后按顺序执行：
@@ -163,8 +155,6 @@ if (!result.success)
 
 优先使用 `pnpm --filter <app-name>` 指定应用。
 
----
-
 ## 输出要求
 
 - 列出改动文件与原因
@@ -172,10 +162,12 @@ if (!result.success)
 - 明确测试（单元 + E2E）与 lint 结果
 - 确认重构后所有测试仍然通过
 
----
-
 ## 相关 Skills
 
 - `hai-build`：项目架构总览与 TDD 工作流导航
 - `hai-app-create`：TDD 驱动的应用功能创建规范
 - `hai-app-tests`：TDD 测试规范（Red 阶段详细指引）
+
+管理端数据读取在 HTTP 应用边界保留失败：查询异常返回 503 和可刷新错误页，分页任一页或权限关联失败均中止加载，禁止回退为空列表、零统计或空权限。未知权限代码返回 400，权限读取失败时不得继续写入。底层模块仍使用 HaiResult。
+
+失败与降级提示也必须国际化：官网 API 按请求 locale 生成 AI 降级/邮件送达状态；未送达不能称为已接收。CLI 部署状态使用 cliM，Gallery 加密能力限制使用双语消息。中文与英文分别验证未配置、失败和成功路径，无需调用付费服务。