@h-ai/cli 0.1.0-alpha.54 → 0.1.0-alpha.56

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

@@ -1,397 +1,38 @@
 ---
 name: hai-app-create
-description: 以 TDD 方式在应用中创建新功能：先编写测试定义行为，再编码实现直至测试通过；当需求涉及新增页面/路由、API、服务、数据模型、组件时使用。
+description: "在 hai 应用中新增页面、路由、API、服务、模型或组件。"
 ---
 
-# hai-app-create — TDD 驱动的应用功能创建规范
+# hai-app-create
 
 ## 能力契约
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 以 TDD 方式在应用中创建新功能：先编写测试定义行为，再编码实现直至测试通过；当需求涉及新增页面/路由、API、服务、数据模型、组件时使用。 |
-| 适用场景 | 当任务与 `hai-app-create` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 明确的功能需求、目标路径、现有实现、仓库规范与验收条件 |
-| 输出 | 最小必要的代码、类型、测试和同步文档，以及实际验证结果 |
-| 限制 | 不为假设需求增加抽象，不绕过生命周期/HaiResult/i18n 约定，不覆盖用户已有改动 |
-
-> 面向 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
-   ```
-
-### 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 { kit } from '@h-ai/kit'
-
-export const load: PageServerLoad = async (event) => {
-  // 权限守卫
-  const guard = kit.guard.requireAuth(event)
-  if (!guard.success)
-    return kit.response.redirect('/login')
-
-  // 加载数据
-  const result = await someService.list()
-  if (!result.success)
-    return kit.response.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.requirePermission(locals.session, 'resource:read')
-
-  const result = await service.list()
-  if (!result.success)
-    return kit.response.error(500, result.error.message)
-  return kit.response.ok(result.data)
-})
-
-// POST - 创建
-export const POST = kit.handler(async ({ request, locals }) => {
-  kit.guard.requirePermission(locals.session, 'resource:create')
-
-  const data = await kit.validate.formOrFail(request, CreateSchema)
-
-  const result = await service.create(data)
-  if (!result.success)
-    return kit.response.error(500, result.error.message)
-  return kit.response.created(result.data)
-})
-```
-
-### 要点
-
-- 所有端点**必须**用 `kit.handler(async ({ locals, request, ... }) => { ... })` 包裹，由 handler 统一处理 throw 的 Response
-- 权限守卫使用 `kit.guard.requirePermission(locals.session, 'xxx:yyy')`，它本身就是 throw 模式（未通过时 throw 403 Response），**无需**检查返回值
-- 输入校验使用 `await kit.validate.formOrFail(request, Schema)`，校验失败时 throw 400 Response，**无需**手动判断 valid
-- 返回统一使用 `kit.response.*`
-- HaiResult 错误直接透传，不重新包装
-- 框架模块 API 不抛异常，不要用 `try/catch` 处理模块返回的错误，直接检查 `result.success`
-
----
-
-## 创建服务层
-
-服务层位于 `$lib/server/services/`，处理业务逻辑。
-
-```typescript
-import type { HaiResult } from '@h-ai/core'
-// src/lib/server/services/article.ts
-import { core } from '@h-ai/core'
-import { reldb } from '@h-ai/reldb'
-
-const logger = core.logger
-
-/** 创建文章 */
-export async function createArticle(input: CreateArticleInput): Promise<HaiResult<Article>> {
-  logger.debug('Creating article', { title: input.title })
-
-  const result = await reldb.crud.create('articles', {
-    id: core.id.uuid(),
-    ...input,
-    created_at: new Date().toISOString(),
-  })
-  if (!result.success)
-    return result
-
-  logger.info('Article created', { id: result.data.id })
-  return result
-}
-
-/** 获取文章列表 */
-export async function listArticles(params: ListParams): Promise<HaiResult<PaginatedResult<Article>>> {
-  logger.debug('Listing articles', { page: params.page })
-  return reldb.crud.paginate('articles', 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`：认证与权限管理
+| 能力 | 在 hai 应用中新增页面、路由、API、服务、模型或组件 |
+| 适用场景 | 已确定需求的应用功能实现 |
+| 输入 | 功能需求、现有路由/contract、数据模型和验收场景 |
+| 输出 | 最小实现、必要测试、i18n 与同步文档 |
+| 限制 | 优先复用；TDD 仅让新增目标用例先失败，已有回归保持通过。API workspace 不生成 SvelteKit 路由。 |
+
+## 使用路径
+
+- 从真实路由/contract、UI 组件和服务层扩展；API workspace、SvelteKit 和 SPA 的文件结构不能混用。
+- 对新增行为先写有意义的目标用例，已有回归保持通过；同步 i18n、README 和调用方。
+
+## 按需参考
+
+详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+
+- 适用场景
+- TDD 开发流程（强制）
+- 目录结构约定
+- 创建页面
+- 创建 API 端点
+- 创建服务层
+- 创建数据模型
+- 创建业务组件
+- 初始化顺序
+- 容器交付
+- 检查清单
+- 相关 Skills