@robsun/create-keystone-app 0.2.13 → 0.4.0

package/template/.claude/skills/keystone-implement/references/SCHEMA.md

@@ -0,0 +1,135 @@
+# Keystone Requirement Document Schema v1.1
+
+> 需求收集与开发实现之间的交接契约。
+> 此格式是两个 skill 之间唯一的交接文件标准。
+
+## 文件命名
+
+```
+requirements/REQ-{序号}-{module-name}.yaml
+```
+
+示例: `requirements/REQ-002-order-management.yaml`
+
+## 完整 Schema
+
+```yaml
+version: "1.1"                    # 必需: Schema 版本
+type: module                      # 必需: 文档类型 (module | feature | bugfix)
+completeness: "draft"             # 必需: draft | review | approved
+
+metadata:
+  name: "module-name"             # 必需: kebab-case 模块名
+  chinese_name: "模块中文名"       # 必需: 用于 UI 显示
+  description: "模块描述"          # 必需: 一句话描述
+  author: "作者"                  # 必需: 需求提出者
+  created_at: "YYYY-MM-DD"        # 必需: 创建日期
+  priority: "medium"              # 必需: low | medium | high | critical
+
+narrative:
+  summary: "业务摘要"              # 必需: 1-2 句话概述
+  background: "背景说明"           # 必需: 现状和痛点
+  problem: "问题陈述"              # 必需: 需要解决的核心问题
+  goals:                          # 必需: 期望达成的目标
+    - "目标 1"
+    - "目标 2"
+  non_goals:                      # 可选: 明确不做的事项
+    - "不做的事项 1"
+  user_story: "As a..., I want..., so that..."  # 必需: 用户故事
+  workflow: "操作流程描述"          # 必需: 用户操作流程
+  acceptance_criteria:            # 必需: 验收标准
+    - "验收条件 1"
+    - "验收条件 2"
+  open_questions:                 # 可选: 待确认问题
+    - "待确认问题 1"
+
+module:
+  name: "module"                  # 必需: Go package 名 (小写, 无连字符)
+  resource:
+    singular: "entity"            # 必需: 单数资源名 (小写)
+    plural: "entities"            # 必需: 复数资源名 (小写)
+
+entities:                         # 必需: 实体定义列表
+  - name: "EntityName"            # 必需: PascalCase 实体名
+    chinese_name: "实体中文名"     # 必需: 用于 UI 显示
+    description: "实体描述"        # 可选: 实体说明
+    fields:                       # 必需: 字段列表
+      - name: "fieldName"         # 必需: camelCase 或 snake_case
+        type: "string"            # 必需: 见下方类型说明
+        chinese_name: "字段中文名" # 必需: 用于表单/表格标签
+        required: true            # 必需: 是否必填
+        unique: false             # 可选: 是否唯一
+        default: null             # 可选: 默认值
+        values: []                # 条件: type=enum 时必需
+        validation:               # 可选: 验证规则
+          min_length: null
+          max_length: null
+          min: null
+          max: null
+          pattern: ""
+
+features:
+  with_crud: true                 # 必需: 基础 CRUD 功能
+  with_approval: false            # 必需: 审批流程
+  with_import: false              # 必需: 批量导入
+  with_export: false              # 必需: 批量导出
+
+assumptions:                      # 可选: 开发假设
+  - "假设说明 1"
+```
+
+## 字段类型
+
+| 类型 | Go 类型 | TS 类型 | GORM 标签 | 说明 |
+|------|---------|---------|-----------|------|
+| `string` | `string` | `string` | `gorm:"size:200"` | 短文本 |
+| `text` | `string` | `string` | `gorm:"type:text"` | 长文本 |
+| `int` | `int` | `number` | - | 整数 |
+| `uint` | `uint` | `number` | - | 无符号整数 |
+| `float` | `float64` | `number` | - | 浮点数 |
+| `bool` | `bool` | `boolean` | - | 布尔值 |
+| `enum` | `string` (自定义类型) | `string` 联合类型 | `gorm:"size:20"` | 枚举 |
+| `datetime` | `time.Time` | `string` | - | 日期时间 |
+| `date` | `time.Time` | `string` | - | 仅日期 |
+| `json` | `datatypes.JSON` | `object` | `gorm:"type:json"` | JSON 对象 |
+
+## 特殊字段约定
+
+以下字段由框架自动处理，无需在 entities 中定义：
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 主键，自动生成 |
+| `tenant_id` | 租户 ID，自动注入 |
+| `created_at` | 创建时间，自动设置 |
+| `updated_at` | 更新时间，自动更新 |
+| `created_by` | 创建人 ID（可选） |
+| `updated_by` | 更新人 ID（可选） |
+
+## 审批流特殊字段
+
+当 `features.with_approval: true` 时，自动添加：
+
+| 字段 | 说明 |
+|------|------|
+| `status` | 扩展为 draft/pending/approved/rejected |
+| `approval_instance_id` | 审批实例 ID |
+| `reject_reason` | 拒绝原因 |
+
+## Completeness 状态说明
+
+| 状态 | 说明 | 允许操作 |
+|------|------|----------|
+| `draft` | 草稿，需求收集中 | 可继续编辑完善 |
+| `review` | 评审中，等待确认 | 仅允许小修改 |
+| `approved` | 已批准，可进入开发 | keystone-implement 可执行 |
+
+## 验证规则
+
+需求文档必须满足以下条件才能进入开发：
+
+1. `completeness` 必须为 `approved`
+2. 所有 `必需` 字段必须有值
+3. 每个 entity 至少有一个业务字段（不含 id/tenant_id 等）
+4. `values` 数组在 `type: enum` 时必须非空
+5. `open_questions` 应为空或已全部解决

package/template/.claude/skills/keystone-implement/references/TESTING.md

@@ -0,0 +1,231 @@
+# Keystone 测试指南
+
+---
+
+## 运行命令
+
+```bash
+# 后端全量测试
+go test ./...
+
+# 后端指定模块
+go test ./tests/unit/modules/{module}/...
+
+# 前端测试
+pnpm -C apps/web test
+
+# 前端指定文件
+pnpm -C apps/web test -- {module}
+```
+
+---
+
+## 后端单元测试
+
+位置：`tests/unit/modules/{module}/service_test.go`
+
+```go
+package service_test
+
+import (
+    "context"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/mock"
+
+    "your-app/apps/server/internal/modules/{module}/domain/models"
+    "your-app/apps/server/internal/modules/{module}/domain/service"
+)
+
+type MockRepository struct {
+    mock.Mock
+}
+
+func (m *MockRepository) Create(ctx context.Context, entity *models.Entity) error {
+    args := m.Called(ctx, entity)
+    return args.Error(0)
+}
+
+func TestService_Create(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   service.CreateInput
+        wantErr bool
+        errType error
+    }{
+        {
+            name:    "success",
+            input:   service.CreateInput{Name: "Test", Status: models.StatusActive},
+            wantErr: false,
+        },
+        {
+            name:    "empty name",
+            input:   service.CreateInput{Name: "", Status: models.StatusActive},
+            wantErr: true,
+            errType: service.ErrNameRequired,
+        },
+        {
+            name:    "invalid status",
+            input:   service.CreateInput{Name: "Test", Status: "invalid"},
+            wantErr: true,
+            errType: service.ErrInvalidStatus,
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            mockRepo := new(MockRepository)
+            if !tt.wantErr {
+                mockRepo.On("Create", mock.Anything, mock.Anything).Return(nil)
+            }
+
+            svc := service.NewService(mockRepo)
+            _, err := svc.Create(context.Background(), 1, tt.input)
+
+            if tt.wantErr {
+                assert.Error(t, err)
+                if tt.errType != nil {
+                    assert.ErrorIs(t, err, tt.errType)
+                }
+            } else {
+                assert.NoError(t, err)
+                mockRepo.AssertExpectations(t)
+            }
+        })
+    }
+}
+```
+
+---
+
+## 后端集成测试
+
+位置：`tests/integration/modules/{module}/api_test.go`
+
+```go
+package api_test
+
+import (
+    "net/http"
+    "net/http/httptest"
+    "strings"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+)
+
+func TestAPI_CRUD(t *testing.T) {
+    app := setupTestApp(t)
+
+    t.Run("Create", func(t *testing.T) {
+        body := `{"name": "Test", "status": "active"}`
+        req := httptest.NewRequest("POST", "/api/v1/{module}/items", strings.NewReader(body))
+        req.Header.Set("Content-Type", "application/json")
+        req.Header.Set("Authorization", "Bearer "+testToken)
+
+        resp := httptest.NewRecorder()
+        app.ServeHTTP(resp, req)
+
+        assert.Equal(t, http.StatusCreated, resp.Code)
+    })
+
+    t.Run("List", func(t *testing.T) {
+        req := httptest.NewRequest("GET", "/api/v1/{module}/items", nil)
+        req.Header.Set("Authorization", "Bearer "+testToken)
+
+        resp := httptest.NewRecorder()
+        app.ServeHTTP(resp, req)
+
+        assert.Equal(t, http.StatusOK, resp.Code)
+    })
+
+    t.Run("Update", func(t *testing.T) {
+        body := `{"name": "Updated"}`
+        req := httptest.NewRequest("PATCH", "/api/v1/{module}/items/1", strings.NewReader(body))
+        req.Header.Set("Content-Type", "application/json")
+        req.Header.Set("Authorization", "Bearer "+testToken)
+
+        resp := httptest.NewRecorder()
+        app.ServeHTTP(resp, req)
+
+        assert.Equal(t, http.StatusOK, resp.Code)
+    })
+
+    t.Run("Delete", func(t *testing.T) {
+        req := httptest.NewRequest("DELETE", "/api/v1/{module}/items/1", nil)
+        req.Header.Set("Authorization", "Bearer "+testToken)
+
+        resp := httptest.NewRecorder()
+        app.ServeHTTP(resp, req)
+
+        assert.Equal(t, http.StatusOK, resp.Code)
+    })
+
+    t.Run("Unauthorized", func(t *testing.T) {
+        req := httptest.NewRequest("GET", "/api/v1/{module}/items", nil)
+        resp := httptest.NewRecorder()
+        app.ServeHTTP(resp, req)
+
+        assert.Equal(t, http.StatusUnauthorized, resp.Code)
+    })
+}
+```
+
+---
+
+## 前端测试
+
+位置：`apps/web/src/modules/{module}/__tests__/`
+
+```tsx
+import { render, screen, waitFor, fireEvent } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { EntityPage } from '../pages/EntityPage'
+
+vi.mock('../services/api', () => ({
+  listEntities: vi.fn().mockResolvedValue([
+    { id: 1, name: 'Test', status: 'active' }
+  ]),
+  createEntity: vi.fn().mockResolvedValue({ id: 2, name: 'New' }),
+  updateEntity: vi.fn().mockResolvedValue({ id: 1, name: 'Updated' }),
+  deleteEntity: vi.fn().mockResolvedValue(undefined),
+}))
+
+describe('EntityPage', () => {
+  it('renders list', async () => {
+    render(<EntityPage />)
+    await waitFor(() => {
+      expect(screen.getByText('Test')).toBeInTheDocument()
+    })
+  })
+
+  it('opens create modal', async () => {
+    render(<EntityPage />)
+    fireEvent.click(screen.getByText('新建'))
+    await waitFor(() => {
+      expect(screen.getByRole('dialog')).toBeInTheDocument()
+    })
+  })
+
+  it('validates required fields', async () => {
+    render(<EntityPage />)
+    fireEvent.click(screen.getByText('新建'))
+    fireEvent.click(screen.getByText('确定'))
+    await waitFor(() => {
+      expect(screen.getByText('名称不能为空')).toBeInTheDocument()
+    })
+  })
+})
+```
+
+---
+
+## 覆盖要求
+
+| 层级 | 必须测试 | 建议测试 |
+|------|----------|----------|
+| Service | 公开方法、错误路径、边界条件 | 并发场景 |
+| API 集成 | CRUD 端点、权限检查、输入验证 | 分页、过滤、排序 |
+| Repository | 基本 CRUD | 复杂查询、事务 |
+| 前端 | 页面渲染、表单验证 | 交互流程、错误处理 |

package/template/.claude/skills/keystone-requirements/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: keystone-requirements
+description: 当用户想要添加新功能、新模块、新业务时，使用此技能收集需求。通过逐步对话将模糊想法转化为标准化 YAML 需求文档，作为开发的唯一契约。触发词：添加功能、新模块、新增、我想做、客户管理、订单管理等业务模块。
+---
+
+# Keystone Requirements
+
+## 技能概述
+
+### 核心职责
+
+1. 引导用户发现和表达业务需求
+2. 将模糊想法转化为结构化需求
+3. 生成符合 v1.1 schema 的 YAML 文档
+4. 验证需求完整性和可实现性
+
+### 输出物
+
+**唯一输出**: `requirements/REQ-{序号}-{module-name}.yaml`
+
+### 引用文档
+
+- `references/SCHEMA.md` — YAML 格式定义
+- `references/CONFIRM_TEMPLATE.md` — 需求确认模板
+
+---
+
+## 工作流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 0: 项目理解                                           │
+│  ↓ 了解现有模块、关联关系、命名约定                            │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 1: 需求收集                                           │
+│  ↓ 通过 6 个核心问题收集关键业务信息                           │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 2: 智能填充                                           │
+│  ↓ 自动填充固定字段 + 推测填充其他必需字段                      │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 3: 用户确认                                           │
+│  ↓ 按模板展示完整需求，用户确认或修改                          │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 4: 保存文档                                           │
+│  → 生成 YAML 文件，交付给 keystone-implement skill            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 0: 项目理解
+
+**目的**：在提问前了解项目上下文，提出更有针对性的问题。
+
+### 步骤 1: 检查现有需求
+
+```bash
+ls requirements/
+```
+
+- 了解已有哪些模块
+- 识别命名模式和编号规则（确定下一个序号）
+- 理解业务领域
+
+### 步骤 2: 阅读相关需求
+
+如果用户的需求与现有模块相关（如：订单管理 ↔ 客户管理），阅读相关 YAML：
+
+```bash
+cat requirements/REQ-XXX-xxx.yaml
+```
+
+**关注**：实体关系、字段命名风格、业务流程模式
+
+### 步骤 3: 理解项目结构
+
+```bash
+ls apps/server/internal/modules/
+```
+
+**了解**：现有模块列表、代码组织方式
+
+### 步骤 4: 提炼上下文
+
+准备以下信息用于后续提问：
+- **类似模块**：可参考的现有设计
+- **关联实体**：可能需要关联的现有实体
+- **命名约定**：项目的命名风格
+
+---
+
+## Phase 1: 需求收集
+
+**交互方式**：使用 `AskUserQuestion` 工具逐步询问，每个问题提供 2-4 个常见选项。
+
+### Q1: 业务问题
+
+**问题**: "这个功能主要解决什么业务问题？"
+
+```javascript
+{
+  question: "这个功能主要解决什么业务问题？",
+  header: "业务问题",
+  options: [
+    { label: "数据分散难管理", description: "如：Excel 到处都是，信息不同步" },
+    { label: "流程不规范", description: "如：审批靠口头，没有留痕" },
+    { label: "信息不透明", description: "如：不知道进度，查询困难" },
+    { label: "效率低下", description: "如：重复手工操作，容易出错" }
+  ]
+}
+```
+
+**收集信息**: `narrative.problem`, `narrative.background`
+
+---
+
+### Q2: 目标用户
+
+**问题**: "主要使用者是谁？"
+
+```javascript
+{
+  question: "主要使用者是谁？",
+  header: "目标用户",
+  options: [
+    { label: "管理层", description: "查看报表、做决策" },
+    { label: "业务人员", description: "日常操作、录入数据" },
+    { label: "财务/行政", description: "审核、归档" },
+    { label: "技术人员", description: "系统对接" }
+  ]
+}
+```
+
+**收集信息**: 用于生成 `narrative.user_story`
+
+---
+
+### Q3: 核心资源
+
+**问题**: "你要管理的核心对象是什么？"
+
+**引导示例**:
+- 客户关系管理 → 客户 (Customer)
+- 订单处理 → 订单 (Order)
+- 库存管理 → 商品 (Product)
+
+**直接询问**:
+1. "核心对象的中文名称是？（如：客户、订单）"
+2. "对应的英文单复数是？（如：customer/customers）"
+
+**收集信息**: `metadata.name`, `metadata.chinese_name`, `module.name`, `module.resource`
+
+---
+
+### Q4: 关键属性
+
+**Step 1**: 列举字段
+"这个资源需要记录哪些信息？（如：客户的名称、联系方式、地址等）"
+
+**Step 2**: 逐个确认类型
+
+```javascript
+{
+  question: "{字段名} 的数据类型是？",
+  header: "字段类型",
+  options: [
+    { label: "文本", description: "姓名、标题等短文本" },
+    { label: "整数", description: "数量、年龄等" },
+    { label: "小数", description: "价格、金额等" },
+    { label: "日期", description: "创建时间、截止日期等" },
+    { label: "枚举/选项", description: "状态、类型等固定选项" },
+    { label: "布尔值", description: "是/否" }
+  ]
+}
+```
+
+**Step 3**: 如果是枚举，追问可选值
+"有哪些可选值？（如：草稿、待审核、已完成）"
+
+**收集信息**: `entities[].fields[]`
+
+---
+
+### Q5: 功能范围
+
+**问题**: "需要哪些功能？（可多选）"
+
+```javascript
+{
+  question: "需要哪些功能？（可多选）",
+  header: "功能",
+  multiSelect: true,
+  options: [
+    { label: "基础 CRUD", description: "增删改查列表" },
+    { label: "审批流程", description: "提交审批、审批通过/拒绝" },
+    { label: "批量导入", description: "Excel 导入" },
+    { label: "数据导出", description: "导出为 Excel" }
+  ]
+}
+```
+
+**收集信息**: `features.*`
+
+---
+
+### Q6: 验收标准
+
+**问题**: "这个功能上线后，如何验证它是可用的？"
+
+**引导示例**:
+- 能成功创建并查看 XX 信息
+- 审批流程能正常流转
+- 导入 100 条数据不出错
+
+**收集信息**: `narrative.acceptance_criteria[]`
+
+---
+
+## Phase 2: 智能填充
+
+### 自动填充（固定值）
+
+| 字段 | 值 |
+|------|-----|
+| `version` | `"1.1"` |
+| `type` | `"module"` |
+| `completeness` | `"approved"`（用户确认后） |
+| `metadata.author` | `"system"` |
+| `created_at` | 当前日期 `YYYY-MM-DD` |
+| `priority` | `"medium"`（除非用户提到紧急程度） |
+
+### 推测填充（基于收集信息）
+
+| 字段 | 推测来源 |
+|------|----------|
+| `narrative.summary` | 从 `chinese_name` 生成，如 "客户信息管理系统" |
+| `narrative.description` | 从 `chinese_name` + `problem` 组合 |
+| `narrative.background` | 从 Q1 回答提取 |
+| `narrative.problem` | 从 Q1 回答提取 |
+| `narrative.goals` | 从功能范围推导 |
+| `narrative.workflow` | 从功能和角色推导 |
+| `narrative.user_story` | 标准格式：As a {角色}, I want {功能}, so that {价值} |
+
+### 优先级调整
+
+- 用户提到"紧急"、"马上" → `priority: "high"`
+- 用户提到"不急"、"有空" → `priority: "low"`
+
+---
+
+## Phase 3: 用户确认
+
+### 确认模板
+
+**必须严格按 `references/CONFIRM_TEMPLATE.md` 模板展示**，包含：
+
+1. **元信息** — 模块名称、资源标识、作者、优先级、日期
+2. **业务背景** — 问题、背景、用户、价值
+3. **数据模型** — 实体名称、字段表格（名称、中文名、类型、必填、说明）
+4. **功能范围** — CRUD、审批、导入、导出的勾选状态
+5. **验收标准** — 编号列表
+6. **关联信息** — 与现有模块的关联（如有）
+
+### 用户响应处理
+
+- **确认** → 进入 Phase 4
+- **需要修改** → 根据反馈调整，重新展示确认单
+
+---
+
+## Phase 4: 保存文档
+
+### 保存步骤
+
+1. **分配序号**：检查 `requirements/` 目录，使用 N+1
+2. **生成文件名**：`REQ-{序号}-{module-name}.yaml`
+3. **写入文件**：按 `references/SCHEMA.md` 格式生成 YAML
+4. **提示下一步**：`"需求文档已保存为 requirements/REQ-00X-xxx.yaml，可直接交给 keystone-implement skill 开发"`
+
+### 保存前验证
+
+**必需字段** (24 个):
+
+| 分类 | 字段 |
+|------|------|
+| 元数据 | `version`, `type`, `completeness` |
+| metadata | `name`, `chinese_name`, `description`, `author`, `created_at`, `priority` |
+| narrative | `summary`, `background`, `problem`, `goals[]`, `user_story`, `workflow`, `acceptance_criteria[]` |
+| module | `name`, `resource.singular`, `resource.plural` |
+| entities | 至少 1 个实体，每个实体有 `name` 和至少 1 个业务字段 |
+| features | `with_crud`, `with_approval` |
+
+**字段级验证**:
+- enum 类型字段必须有 `values`
+- 所有字段必须有 `chinese_name`
+- 所有字段必须有 `required` 属性