npm package: @keqi.gress/plugin-dev-server
Description: Gress 插件前端开发服务器 - 提供热更新和后端联调能力
Author: Gress Team
Latest version: 1.0.13

# @keqi.gress/plugin-dev-server

Gress 插件前端开发服务器 - 提供热更新和后端联调能力

## 🎯 功能特性

- ⚡️ 基于 Vite 的快速热更新 (HMR)
- 🔄 自动代理后端 API 请求
- 🎨 支持自定义 Vite 配置
- 📦 零配置启动，开箱即用
- 🔧 灵活的配置选项
- 🚀 支持多插件并行开发
- 🛣️ 完整支持 Vue Router（History/Hash 模式）
- 🤖 **自动扫描 views 目录生成路由**（约定优于配置）
- 🎯 **Mock API 支持**（模拟后端路由和菜单配置）

## 📦 安装

在插件前端项目中安装：

```bash
npm install @keqi.gress/plugin-dev-server --save-dev
```

或使用本地路径（开发阶段）：

```bash
npm install file:../../gress/gress-plugin-packages/plugin-dev-server --save-dev
```

## 🚀 快速开始

### 零配置模式（推荐）

**只需 3 步，无需创建任何路由文件！**

```bash
# 1. 创建 views 组件
mkdir -p src/views
echo '<template><div>首页</div></template>' > src/views/HomePage.vue

# 2. 创建配置文件
echo 'export default { pluginName: "my-plugin" }' > gress-dev.config.js

# 3. 启动开发服务器
npx gress-dev
```

访问 `http://localhost:3000/` 即可看到页面！

**工作原理：**
- ✅ 自动扫描 `src/views` 目录
- ✅ 自动生成路由配置
- ✅ 自动注入应用入口（main.ts、App.vue、router）
- ✅ 自动启动开发服务器

**你只需要：**
- 创建 Vue 组件
- 配置插件名称

### 1. 创建配置文件

在插件前端根目录创建 `gress-dev.config.js`：

```javascript
export default {
  // 插件名称（必填）
  pluginName: 'appstore',
  
  // 后端服务地址（可选，默认 http://localhost:8080）
  backendUrl: 'http://localhost:8080',
  
  // 开发服务器端口（可选，默认 3000）
  port: 3001,
  
  // API 前缀（可选，默认 /api/plugin/{pluginName}）
  apiPrefix: '/api/plugin/appstore',
  
  // 是否自动扫描 views 目录生成路由（可选，默认 true）
  autoScanRoutes: true,
  
  // 手动配置的路由（可选，会覆盖自动扫描的路由）
  devRoutes: [
    // 特殊路由可以在这里配置
    {
      path: '/custom-path',
      component: 'CustomPage',
      meta: { title: '自定义页面' }
    }
  ],
  
  // 是否启用热更新（可选，默认 true）
  hmr: true,
  
  // 是否自动打开浏览器（可选，默认 false）
  open: false,
  
  // 路由基础路径（可选，默认 '/'）
  // 用于子路径部署，如 '/plugins/appstore/'
  base: '/'
}
```

### 2. 修改 package.json

```json
{
  "scripts": {
    "dev": "gress-dev",
    "build": "vite build"
  },
  "devDependencies": {
    "@keqi.gress/plugin-dev-server": "^1.0.0"
  }
}
```

### 3. 启动开发服务器

```bash
npm run dev
```

## 📖 配置选项

### 基础配置

```typescript
interface GressDevConfig {
  /** 插件名称（必填） */
  pluginName: string
  
  /** 后端服务地址（可选） */
  backendUrl?: string
  
  /** 开发服务器端口（可选） */
  port?: number
  
  /** API 前缀（可选） */
  apiPrefix?: string
  
  /** 是否启用热更新（可选） */
  hmr?: boolean
  
  /** 是否自动打开浏览器（可选） */
  open?: boolean
  
  /** 额外的 Vite 配置（可选） */
  vite?: InlineConfig
  
  /** 额外的代理配置（可选） */
  proxy?: Record<string, any>
}
```

### 高级配置示例

```javascript
export default {
  pluginName: 'portal',
  backendUrl: 'http://localhost:8080',
  port: 3002,
  
  // 自定义 Vite 配置
  vite: {
    resolve: {
      alias: {
        '@': '/src'
      }
    },
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "@/styles/variables.scss";`
        }
      }
    }
  },
  
  // 额外的代理配置
  proxy: {
    '/api/other': {
      target: 'http://localhost:9000',
      changeOrigin: true
    }
  }
}
```

## 🔧 命令行选项

```bash
# 使用默认配置
gress-dev

# 指定端口
gress-dev --port 3003

# 自动打开浏览器
gress-dev --open

# 指定配置文件
gress-dev --config custom-config.js
```

## 🌟 使用场景

### 场景 1：零配置开发（推荐）

```bash
cd gress-plugin-appstore/frontend

# 创建 views 组件
mkdir -p src/views
echo '<template><div>首页</div></template>' > src/views/HomePage.vue
echo '<template><div>列表</div></template>' > src/views/ApplicationList.vue

# 启动开发服务器（自动扫描 views 目录生成路由）
npm run dev
```

访问：
- `http://localhost:3001/` → HomePage.vue
- `http://localhost:3001/application-list` → ApplicationList.vue

### 场景 2：自定义路由

```javascript
// gress-dev.config.js
export default {
  pluginName: 'appstore',
  
  // 手动配置特殊路由
  devRoutes: [
    {
      path: '/applications',  // 自定义路径
      component: 'ApplicationList',
      meta: { title: '应用列表', icon: 'Apps' }
    },
    {
      path: '/applications/:id',
      component: 'ApplicationDetail',
      meta: { title: '应用详情' }
    }
  ]
}
```

### 场景 3：多插件并行开发

```bash
# 终端 1 - 启动 appstore 插件
cd gress-plugin-appstore/frontend
npm run dev  # 端口 3001

# 终端 2 - 启动 portal 插件
cd gress-plugin-portal/frontend
npm run dev  # 端口 3002
```

### 场景 3：联调后端 API

所有发送到 `apiPrefix` 的请求会自动代理到后端：

```typescript
// 前端代码
const response = await fetch('/api/plugin/appstore/applications')
// 实际请求: http://localhost:8080/api/plugin/appstore/applications
```

### 场景 4：访问路由

所有前端路由都可以直接访问，支持浏览器刷新：

```
http://localhost:3001/                    # 首页
http://localhost:3001/applications        # 应用列表
http://localhost:3001/settings            # 设置页
```

详见 [路由访问指南](./ROUTING_GUIDE.md)

## 🎨 环境变量注入

开发服务器会自动注入以下全局变量：

```typescript
declare const __PLUGIN_NAME__: string      // 插件名称
declare const __API_PREFIX__: string       // API 前缀
declare const __BACKEND_URL__: string      // 后端地址
```

在代码中使用：

```typescript
console.log('Plugin:', __PLUGIN_NAME__)
console.log('API Prefix:', __API_PREFIX__)
```

## 📝 TypeScript 支持

创建 `env.d.ts` 文件：

```typescript
/// <reference types="vite/client" />

declare const __PLUGIN_NAME__: string
declare const __API_PREFIX__: string
declare const __BACKEND_URL__: string
```

## 🔍 调试

开发服务器会输出代理请求日志：

```
[Proxy] GET /api/plugin/appstore/applications -> http://localhost:8080/api/plugin/appstore/applications
```

## 📄 License

MIT

## 📚 相关文档

- [快速开始](./QUICK_START.md)
- [集成指南](./INTEGRATION_GUIDE.md)
- [路由访问指南](./ROUTING_GUIDE.md)
- [自动路由扫描指南](./AUTO_ROUTES_GUIDE.md) ⭐ 新功能
- [开发环境路由配置](./DEV_ROUTES_GUIDE.md)
- [配置示例](./config/gress-dev.config.example.js)