@robsun/create-keystone-app 0.2.13 → 0.4.0

package/template/.claude/skills/keystone-requirements/references/CONFIRM_TEMPLATE.md

@@ -0,0 +1,170 @@
+# 需求确认模板
+
+**用途**：在用户确认需求前，必须按此模板完整展示所有收集到的信息。
+
+**重要**：每次确认必须严格按此模板展示，确保信息完整一致，不可遗漏任何部分。
+
+---
+
+## 模板格式
+
+```
+📋 需求确认单
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 1. 元信息
+
+| 项目 | 值 |
+|------|-----|
+| 模块名称 | {metadata.chinese_name} |
+| 资源标识 | {module.resource.singular} / {module.resource.plural} |
+| 作者 | {metadata.author} |
+| 优先级 | {metadata.priority} |
+| 创建日期 | {metadata.created_at} |
+
+## 2. 业务背景
+
+**解决的问题**：{narrative.problem}
+
+**业务背景**：{narrative.background}
+
+**目标用户**：{从 user_story 提取角色}
+
+**预期价值**：
+- {narrative.goals[0]}
+- {narrative.goals[1]}
+- ...
+
+## 3. 数据模型
+
+**实体**：{entities[0].name} ({entities[0].chinese_name})
+
+| 字段名 | 中文名 | 类型 | 必填 | 说明 |
+|--------|--------|------|------|------|
+| {field.name} | {field.chinese_name} | {field.type} | {field.required ? "是" : "否"} | {枚举值或备注} |
+| ... | ... | ... | ... | ... |
+
+## 4. 功能范围
+
+- [x/空] 基础 CRUD（增删改查列表）
+- [x/空] 审批流程（提交、审批、拒绝）
+- [x/空] 批量导入（Excel 导入）
+- [x/空] 数据导出（导出为 Excel）
+
+## 5. 验收标准
+
+1. {narrative.acceptance_criteria[0]}
+2. {narrative.acceptance_criteria[1]}
+3. ...
+
+## 6. 关联信息（如有）
+
+- 关联模块：{如果发现与现有模块有关联，列出}
+- 关联字段：{外键关系}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ 确认无误 → 回复"确认"，我将生成 YAML 并保存
+❌ 需要修改 → 告诉我哪里需要调整
+```
+
+---
+
+## 字段说明
+
+### 1. 元信息
+- **模块名称**：用户定义的中文名称，如"客户管理"
+- **资源标识**：英文单复数，如 customer / customers
+- **作者**：需求提出者姓名
+- **优先级**：high / medium / low
+- **创建日期**：自动填充当前日期 YYYY-MM-DD
+
+### 2. 业务背景
+- **解决的问题**：从 Q1 收集的核心痛点
+- **业务背景**：智能推测或从对话中提取
+- **目标用户**：从 Q2 收集的用户角色
+- **预期价值**：根据功能范围智能推导
+
+### 3. 数据模型
+- 必须列出所有从 Q4 收集的字段
+- 每个字段包含：名称、中文名、类型、是否必填、说明
+- 枚举类型需要在说明中列出可选值
+
+### 4. 功能范围
+- 从 Q5 收集的多选结果
+- 使用 `[x]` 表示选中，`[ ]` 表示未选
+
+### 5. 验收标准
+- 从 Q6 收集的验收条件
+- 每条标准独立编号
+
+### 6. 关联信息
+- 从准备阶段发现的关联关系
+- 如果没有关联，可以省略此部分或标注"无"
+
+---
+
+## 使用示例
+
+```
+📋 需求确认单
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 1. 元信息
+
+| 项目 | 值 |
+|------|-----|
+| 模块名称 | 客户管理 |
+| 资源标识 | customer / customers |
+| 作者 | 张三 |
+| 优先级 | medium |
+| 创建日期 | 2025-01-06 |
+
+## 2. 业务背景
+
+**解决的问题**：客户信息分散在 Excel 中，难以统一管理和查询
+
+**业务背景**：销售团队需要统一管理客户资料，目前使用 Excel 导致信息不同步
+
+**目标用户**：业务人员
+
+**预期价值**：
+- 集中管理客户信息
+- 提高客户查询效率
+- 支持数据导出分析
+
+## 3. 数据模型
+
+**实体**：Customer (客户)
+
+| 字段名 | 中文名 | 类型 | 必填 | 说明 |
+|--------|--------|------|------|------|
+| name | 客户名称 | string | 是 | - |
+| phone | 联系电话 | string | 否 | - |
+| email | 邮箱地址 | string | 否 | - |
+| status | 客户状态 | enum | 是 | 潜在客户/正式客户/流失客户 |
+
+## 4. 功能范围
+
+- [x] 基础 CRUD（增删改查列表）
+- [ ] 审批流程（提交、审批、拒绝）
+- [ ] 批量导入（Excel 导入）
+- [x] 数据导出（导出为 Excel）
+
+## 5. 验收标准
+
+1. 能成功创建并查看客户信息
+2. 能导出客户列表为 Excel
+
+## 6. 关联信息
+
+- 关联模块：订单管理
+- 关联字段：订单表中有 customer_id 外键
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ 确认无误 → 回复"确认"，我将生成 YAML 并保存
+❌ 需要修改 → 告诉我哪里需要调整
+```

package/template/.claude/skills/keystone-requirements/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/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  root: true,
+};

package/template/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: apps/server/go.mod
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build web app
+        run: pnpm -C apps/web build
+      - name: Run Go tests
+        run: go -C apps/server test ./...

package/template/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: apps/server/go.mod
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build release artifacts
+        run: pnpm build
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: keystone-dist
+          path: dist

package/template/.golangci.yml

@@ -0,0 +1,11 @@
+run:
+  timeout: 5m
+
+linters:
+  enable:
+    - govet
+    - staticcheck
+    - errcheck
+
+issues:
+  exclude-use-default: false

package/template/README.md

@@ -1,77 +1,85 @@
-# __RAW_NAME__
-
-Keystone 平台脚手架项目（Web + Server）。
-
-## 快速开始
-1) 安装依赖
-```bash
-pnpm install
-```
-
-2) 启动开发环境（前后端一起）
-```bash
+# __RAW_NAME__
+
+Keystone 平台脚手架项目（Web + Server）。
+
+## 快速开始
+1) 安装依赖
+```bash
+pnpm install
+```
+
+2) 启动开发环境（前后端一起）
+```bash
+pnpm dev
+```
+
+3) 单独启动
+```bash
+pnpm server:dev
 pnpm dev
-```
-
-3) 单独启动
-```bash
-pnpm server:dev
-pnpm web:dev
-```
-
-## 初始化后建议
-- 复制 `apps/web/.env.example` 为 `apps/web/.env`（Vite 会读取）。
-- 检查 `apps/server/config.yaml`（Go 运行配置）。
-- 需要外部依赖时参考 `docker-compose.yml`。
-- 建议阅读：`docs/GETTING_STARTED.md`、`docs/CONVENTIONS.md`、`docs/CODE_STYLE.md`、`apps/web/README.md`、`apps/server/README.md`。
-
-## 常用命令
-- `pnpm dev`：跨平台开发启动（Air + Vite）。
-- `pnpm build`：构建并嵌入前端，生成可执行后端产物。
-- `pnpm test`：Web 类型检查 + Lint + Vitest + Go 测试。
-- `pnpm clean`：清理构建产物。
-
-## 模块生成器
-```bash
-pnpm create:module <module-name> [options]
-```
-不传 options 会进入交互式向导。
-
-选项：
-- `--frontend-only`：只生成前端模块。
-- `--backend-only`：只生成后端模块。
-- `--with-crud`：包含 CRUD 示例代码。
-- `--skip-register`：跳过自动注册步骤。
-
+```
+
+## 初始化后建议
+- 复制 `apps/web/.env.example` 为 `apps/web/.env`（Vite 会读取）。
+- 检查 `apps/server/config.yaml`（Go 运行配置）。
+- 需要外部依赖时参考 `docker-compose.yml`。
+- 建议阅读：`docs/GETTING_STARTED.md`、`docs/CONVENTIONS.md`、`docs/CODE_STYLE.md`、`apps/web/README.md`、`apps/server/README.md`。
+
+## 常用命令
+- `pnpm dev`：跨平台开发启动（Air + Vite）。
+- `pnpm build`：构建并嵌入前端，生成可执行后端产物。
+- `pnpm test`：Web 类型检查 + Lint + Vitest + Go 测试。
+- `pnpm clean`：清理构建产物。
+
+## 模块生成器
+```bash
+pnpm create:module <module-name> [options]
+```
+不传 options 会进入交互式向导。
+
+选项：
+- `--frontend-only`：只生成前端模块。
+- `--backend-only`：只生成后端模块。
+- `--with-crud`：包含 CRUD 示例代码。
+- `--with-approval`：包含审批流代码（自动启用 `--with-crud`）。
+- `--skip-register`：跳过自动注册步骤。
+
+使用 `--with-approval` 时生成：
+- 后端：`domain/service/approval.go`、`domain/service/callback.go`、`api/handler/approval.go`
+- 前端：`components/ApprovalActions.tsx`
+- 模型：添加 `draft/pending/approved/rejected` 状态和审批字段
+- 路由：`POST /:id/submit`、`POST /:id/cancel`
+
 ## AI Skills
-- Codex：`.codex/skills/keystone-dev`
-- Claude：`.claude/skills/keystone-dev`
-
-## 目录结构
-- `apps/web/`：React + Vite 壳与业务模块（`src/modules/*`）。
-- `apps/server/`：Go API + 模块注册/迁移/种子数据（含 `config.yaml`）。
-- `apps/server/internal/frontend/`：嵌入式前端目录（`dist/`）。
-- `docs/CONVENTIONS.md`：项目规范与最佳实践。
-- `apps/web/README.md`：前端壳与模块开发说明。
-- `apps/server/README.md`：后端模块与运行说明。
-- `scripts/`：跨平台 dev/build/test/clean。
-
-```
-.
-├─ apps/
-│  ├─ web/            # 前端壳与模块
-│  └─ server/         # Go 服务与模块
-├─ docs/              # 开发规范与说明
-└─ scripts/           # 跨平台脚本
-```
-
-## Example 模块（默认）
+- Codex: `.codex/skills/keystone-requirements`, `.codex/skills/keystone-app-dev`
+- Claude: `.claude/skills/keystone-requirements`, `.claude/skills/keystone-app-dev`
+
+## 目录结构
+- `apps/web/`：React + Vite 壳与业务模块（`src/modules/*`）。
+- `apps/server/`：Go API + 模块注册/迁移/种子数据（含 `config.yaml`）。
+- `apps/server/internal/frontend/`：嵌入式前端目录（`dist/`）。
+- `docs/CONVENTIONS.md`：项目规范与最佳实践。
+- `apps/web/README.md`：前端壳与模块开发说明。
+- `apps/server/README.md`：后端模块与运行说明。
+- `scripts/`：跨平台 dev/build/test/clean。
+
+```
+.
+├─ apps/
+│  ├─ web/            # 前端壳与模块
+│  └─ server/         # Go 服务与模块
+├─ docs/              # 开发规范与说明
+└─ scripts/           # 跨平台脚本
+```
+
+## Example 模块（可选）
 Example 模块展示完整的 CRUD 模式、权限命名与 DDD 分层结构。
-- 菜单：Example Items
-- API：`/api/v1/example/items`
-- 权限：`example:item:view`、`example:item:manage`
-
-## 默认登录
-- Tenant code: `default`
-- Identifier: `admin`
+使用 `create-keystone-app --with-example` 生成。
+- 菜单：Example Items
+- API：`/api/v1/example/items`
+- 权限：`example:item:view`、`example:item:manage`
+
+## 默认登录
+- Tenant code: `default`
+- Identifier: `admin`
 - Password: `Admin123!`

package/template/apps/server/README.md

@@ -3,12 +3,20 @@
 ## 定位
 - Go 后端应用入口在 `cmd/server/main.go`。
 - 业务模块统一放在 `internal/modules/*`。
+- 核心组装由 `server.NewBuilder` 完成，应用只负责注册模块与嵌入式前端。
 
 ## 配置
 - 主配置：`apps/server/config.yaml`。
 - 模板配置：`apps/server/config.example.yaml`。
 - 环境变量：需通过 Shell/工具注入（服务端不读取 `.env`）。
 
+## API 文档
+- Swagger UI：`/api/docs`
+- 生成 OpenAPI：`pnpm contracts:docs`
+
+## 可观测性
+- 指标端点：`/metrics`（默认关闭，需开启 `telemetry.enabled`）
+
 ## 数据与存储
 - SQLite：`apps/server/data/keystone-local.db`。
 - 本地存储：`apps/server/storage/`（`storage.driver=local`）。