@stago/cli

云台 (Stago) 模块创建脚手架 - 为分析师和开发者提供模块开发的标准模板。

快速开始

引导模式（适合分析师）

交互式问答，逐步配置模块参数，有详细说明和最佳实践引导：

# 直接运行，进入引导模式
npx create-stago-module

# 或显式指定引导模式
npx create-stago-module --guided

快速模式（适合开发者）

命令行参数快速创建，适合熟悉流程的开发者：

# 最简参数
npx create-stago-module --name my-dashboard --desc "销售仪表板"

# 完整参数
npx create-stago-module \
  --name sales-dashboard \
  --output ./sales-dashboard \
  --desc "销售数据可视化仪表板" \
  --author "张三" \
  --category dashboard \
  --table sales_data \
  --menu-level primary \
  --menu-icon DashboardOutlined \
  --page multi-page

CLI 参数

模式控制

| 参数 | 说明 | |-----|-----| | --guided | 强制使用引导模式 | | --quick | 强制使用快速模式 | | --help, -h | 显示帮助信息 |

快速模式参数

| 参数 | 简写 | 说明 | 默认值 | |-----|-----|-----|-------| | --name | -n | 模块名称（必须，kebab-case 格式） | - | | --output | -o | 输出目录 | ./{模块名} | | --desc | -d | 模块描述 | 模块描述 | | --author | -a | 作者名称 | 分析师 | | --category | -c | 分类 | dashboard | | --table | -t | 数据表前缀 | data | | --registry | -r | 注册服务地址 | http://localhost:3000 | | --menu-level | 菜单级别（primary/secondary） | primary | | --menu-parent | 父菜单名称（二级菜单时使用） | - | | --menu-title | 菜单标题 | 使用模块描述 | | --menu-order | 菜单排序 | 100 | | --menu-icon | 菜单图标 | AppstoreOutlined | | --page | 页面模板（multi-page/single-page/blank） | multi-page |

命名规范

• 模块名称：使用 kebab-case 格式（小写字母开头，只包含字母、数字、连字符）

  • 例如：sales-dashboard, inventory-tracker, order-management

• 数据表前缀：使用 snake_case 格式（小写字母开头，只包含字母、数字、下划线）

  • 例如：sales_data, inventory_item, order_record

菜单图标选项

| 图标名称 | 适合场景 | |---------|---------| | AppstoreOutlined | 通用应用 | | DashboardOutlined | 仪表板/数据可视化 | | TableOutlined | 数据表格/数据管理 | | BarChartOutlined | 统计图表/数据分析 | | SettingOutlined | 系统设置/配置管理 | | FileTextOutlined | 文档报表 | | TeamOutlined | 团队管理/人员管理 | | ShopOutlined | 商城/销售业务 | | DatabaseOutlined | 数据库/数据存储 | | CalendarOutlined | 日历/日程管理 |

页面模板类型

| 类型 | 说明 | 适合场景 | |-----|-----|---------| | multi-page | 多页面 SPA（列表页、详情页、统计页） | 数据管理场景 | | single-page | 单页面应用 | 简单展示需求 | | blank | 空白模板 | 完全自定义开发 |

生成的目录结构

多页面 SPA 模板

my-dashboard/
├─ src/
│  ├─ pages/
│  │  ├─ index.tsx      # 页面入口（路由配置）
│  │  ├─ List.tsx       # 列表页（带筛选、分页）
│  │  ├─ Detail.tsx     # 详情页（数据详情展示）
│  │  └─ Stats.tsx      # 统计页（图表汇总）
│  ├─ components/
│  │  └─ Layout.tsx     # 共享布局组件
│  └─ api/
│     └─ index.ts       # 接口路由
├─ public/              # 静态资源
├─ module.json          # 模块配置
├─ package.json         # 依赖配置
├─ tsconfig.json        # TypeScript 配置
└─ vite.config.ts       # Vite + Module Federation 配置

单页面模板

my-dashboard/
├─ src/
│  ├─ pages/
│  │  └─ index.tsx      # 单页面入口
│  └─ api/
│     └─ index.ts       # 接口路由
├─ public/
├─ module.json
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

空白模板

my-dashboard/
├─ src/
│  ├─ pages/
│  │  └─ index.tsx      # 最小化入口
│  └─ api/
│     └─ index.ts       # 接口路由
├─ public/
├─ module.json
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

开发规范

module.json 配置

{
  "name": "模块名称",
  "version": "语义化版本号",
  "pageEntry": "./src/pages/index.tsx",
  "apiEntry": "./src/api/index.ts",
  "menu": {
    "level": "primary",
    "title": "菜单标题",
    "order": 100,
    "icon": "DashboardOutlined"
  },
  "federation": {
    "exposes": ["./Page"],
    "shared": {
      "react": { "singleton": true },
      "antd": { "singleton": true }
    }
  }
}

页面开发

页面入口必须是 React 组件，默认导出：

import React from 'react'
import { Card } from 'antd'

export default function MyComponent() {
  return (
    <Card title="模块标题" bordered={false}>
      {/* 模块内容 */}
    </Card>
  )
}

接口开发

使用 defineApiRouter 定义接口路由：

import { defineApiRouter, apiSuccess } from '@stago/sdk'

export default defineApiRouter({
  prefix: '/my-module',
  routes: {
    '/data': {
      GET: async (c, ctx) => {
        const result = await ctx.db.query('SELECT * FROM my_table')
        return apiSuccess(c, result.rows)
      }
    }
  }
})

工具函数

模块可以直接使用成熟的开源库：

// 日期格式化 - 使用 dayjs
import dayjs from 'dayjs'
dayjs(date).format('YYYY-MM-DD')

// 数据请求 - 自定义 hook
const useApi = (path: string) => {
  const baseUrl = window.__MODULE_CONFIG__?.apiUrl || ''
  // fetch logic...
}

// CSV 下载 - 简单实现
const downloadCsv = (data, filename) => {
  const csv = data.map(row => Object.values(row).join(',')).join('\n')
  // Blob download...
}

// UI 组件 - 直接使用 antd
import { Card, Table, Button, Input } from 'antd'

// 图表 - 直接使用 echarts-for-react
import ReactECharts from 'echarts-for-react'

本地开发

生成的模块可以立即本地开发：

cd my-dashboard
npm install
npm run dev

开发服务器将在 http://localhost:3000 启动。

发布模块

1. 推送代码到 Git 仓库
2. CI/CD 流水线自动触发构建
3. 构建完成后注册到云台底座

详见：云台 (Stago) 系统设计文档

SDK 类型

ModuleContext

接口处理函数接收的上下文对象：

interface ModuleContext {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE'
  path: string
  params: Record<string, string>
  body: Record<string, unknown>
  db: DatabaseAccess
  json: <T>(data: T) => ApiResponse<T>
  error: (code: string, message: string) => ApiResponse
}

DatabaseAccess

interface DatabaseAccess {
  query: (sql: string, params?: unknown[]) => Promise<unknown[]>
  execute: (sql: string, params?: unknown[]) => Promise<void>
  transaction: (fn: () => Promise<void>) => Promise<void>
}

MenuConfig

interface MenuConfig {
  level: 'primary' | 'secondary'
  parent?: string  // 二级菜单必填
  title?: string   // 菜单标题
  order?: number   // 排序权重
  icon?: string    // Ant Design Icons 图标名称
}