# @winner-fed/winner-deploy

> 用于生成 SEE 平台部署包的工具库

## 简介

`@winner-fed/winner-deploy` 是一个专门为 SEE 平台设计的部署包生成工具。它可以将前端项目打包成符合 SEE 平台规范的部署包，支持多种应用类型和部署模式。

## 特性

- 🚀 支持外框架（bizframe）和子系统（subsystem）两种应用类型
- 📦 自动生成 SEE 平台所需的 manifest.json 和 deploy.xml 配置文件
- 🐳 支持 Docker 容器化部署
- 🔧 灵活的模板变量配置系统
- 📝 支持 Python 和 Bash 两种脚本类型
- 🎯 可自定义文件拷贝和配置生成逻辑

## 安装

```bash
npm install @winner-fed/winner-deploy
# 或
yarn add @winner-fed/winner-deploy
# 或
pnpm add @winner-fed/winner-deploy
```

## 快速开始

### 基础用法

```javascript
import { generateSeePackageZip } from '@winner-fed/winner-deploy';

// 最简单的使用方式
generateSeePackageZip({
  name: 'my-app',
  version: '1.0.0',
  description: '我的应用'
});
```

### 完整配置示例

```javascript
import { generateSeePackageZip } from '@winner-fed/winner-deploy';

generateSeePackageZip(
  {
    system: 'winner-front',
    type: 'subsystem',
    name: 'my-app',
    appType: 'my-app',
    version: '1.0.0',
    group: 'bizframe',
    configName: 'config.local',
    outputName: 'dist',
    description: '我的应用部署包',
    seePackageType: 'web',
    scriptsType: 'python',
    copyFiles: ['version.js', 'logo.png'],
    templateFunc: () => {
      return './dist/config.local.js';
    },
    variablesFunc: () => {
      return [
        {
          type: 'input',
          label: '应用标题',
          name: 'APP_TITLE',
          default: '默认标题'
        }
      ];
    }
  },
  (err, result) => {
    if (err) {
      console.error('生成失败:', err);
    } else {
      console.log('生成成功:', result);
    }
  }
);
```

## API 文档

### generateSeePackageZip(options, callback)

生成 SEE 平台部署包的主要函数。

#### 参数说明

| 参数名         | 类型          | 默认值                         | 必填 | 说明                                                     |
| -------------- | ------------- | ------------------------------ | ---- | -------------------------------------------------------- |
| system         | string        | 'winner-front'                 | 否   | 系统类型，SEE 平台的分组维度                             |
| type           | string        | 'subsystem'                    | 否   | 应用类型：'bizframe'（外框架）或 'subsystem'（子系统）   |
| name           | string        | -                              | 是   | 发布物名称                                               |
| appType        | string        | name 的值                      | 否   | 发布物类型                                               |
| version        | string        | -                              | 是   | 发布包版本                                               |
| group          | string        | 'bizframe'                     | 否   | 应用分组                                                 |
| configName     | string        | 'config.local'                 | 否   | 配置文件名称（不含 .js 后缀）                            |
| outputName     | string        | 'dist'                         | 否   | 输出目录名称                                             |
| description    | string        | -                              | 否   | 发布包说明                                               |
| seePackageName | string        | `${system}-${name}-${version}` | 否   | SEE 发布物的包名（zip 文件名）                           |
| seePackageType | string        | 'web'                          | 否   | SEE 平台发布物包类型：'web' 或 'docker'                  |
| dockerImage    | string        | -                              | 否   | Docker 容器化镜像名（seePackageType 为 'docker' 时生效） |
| scriptsType    | string        | 'python'                       | 否   | 脚本类型：'python' 或 'bash'                             |
| copyFiles      | Array<string> | []                             | 否   | 需要直接拷贝到 SEE 包的文件列表                          |
| templateFunc   | function      | -                              | 否   | 自定义变量配置文件生成函数                               |
| variablesFunc  | function      | -                              | 否   | deploy.xml 模板变量配置函数                              |

#### templateFunc 函数

用于自定义变量配置文件的生成逻辑。

```javascript
templateFunc: function() {
  if (type === 'bizframe') {
    return `./dist/config.local.js`;
  }
  // 返回配置文件路径
}
```

#### variablesFunc 函数

用于配置 deploy.xml 模板变量，支持动态配置。

```javascript
variablesFunc: function() {
  const context = process.cwd();
  if (type === 'bizframe') {
    try {
      const { variables } = require(path.resolve(
        context,
        'build',
        'package',
        './variables.js'
      ));
      return variables || [];
    } catch (error) {
      console.error(error);
      return [];
    }
  }
  return [];
}
```

#### copyFiles 配置

指定需要直接拷贝到 SEE 包中但不包含在 manifest.json 配置中的文件。

```javascript
copyFiles: [
  'version.js', // 项目根目录下的 version.js
  'assets/logo.png', // assets 目录下的 logo.png
  'config/env.json' // config 目录下的 env.json
];
```

#### callback 回调函数

```javascript
function callback(error, result) {
  if (error) {
    // 处理错误
    console.error('生成失败:', error);
  } else {
    // 处理成功结果
    console.log('生成成功:', result);
  }
}
```

## 模板变量配置

SEE 平台支持多种类型的模板变量控件，用于在部署时动态配置应用参数。详细的模板变量配置说明请参考 [TYPE.md](./TYPE.md)。

### 支持的控件类型

- **input**: 普通文本输入框
- **select**: 单选下拉框
- **switch**: 开关组件
- **smallfile**: 文件上传控件（小于 2M）
- **switchForm**: 开关表单
- **complexSelect**: 复杂单选框
- **table**: 表格控件
- **division**: 分栏折叠控件
- **password**: 密码输入框（数据加密存储）
- **hidden**: 隐藏输入框（不显示给用户）

### 示例配置

```javascript
const variables = [
  {
    type: 'input',
    label: '应用标题',
    tooltip: '设置应用的显示标题',
    name: 'APP_TITLE',
    default: '默认应用标题'
  },
  {
    type: 'select',
    label: '环境选择',
    options: 'dev:开发环境;test:测试环境;prod:生产环境',
    tooltip: '选择部署环境',
    name: 'ENVIRONMENT',
    default: 'dev'
  },
  {
    type: 'switch',
    label: '启用调试',
    tooltip: '是否启用调试模式',
    name: 'DEBUG_MODE',
    default: false
  },
  {
    type: 'password',
    label: '数据库密码',
    tooltip: '数据库连接密码',
    name: 'DB_PASSWORD',
    required: true,
    default: ''
  },
  {
    type: 'hidden',
    label: '应用版本号',
    tooltip: '应用内部版本号，用于系统识别',
    name: 'APP_VERSION',
    default: '1.0.0'
  }
];
```

## 项目结构

生成的 SEE 部署包包含以下文件：

```
see-package.zip
├── manifest.json          # 应用清单文件
├── deploy.xml            # 部署配置文件
├── install.py/.sh        # 安装脚本
├── uninstall.py/.sh      # 卸载脚本
├── start.py/.sh          # 启动脚本
├── stop.py/.sh           # 停止脚本
├── config.local.js       # 配置文件（如果存在）
└── dist/                 # 应用文件目录
    └── ...
```

## 使用场景

### 1. 外框架应用（bizframe）

适用于作为主框架的运行的子应用。

```javascript
generateSeePackageZip({
  type: 'bizframe',
  name: 'main-frame',
  version: '1.0.0',
  description: '主框架应用'
});
```

### 2. 子系统应用（subsystem）

适用于业务子系统，通常作为微前端模块。

```javascript
generateSeePackageZip({
  type: 'subsystem',
  name: 'user-management',
  version: '1.0.0',
  description: '用户管理子系统'
});
```

### 3. Docker 容器化部署

支持生成容器化部署的 SEE 包。

```javascript
generateSeePackageZip({
  name: 'my-app',
  version: '1.0.0',
  seePackageType: 'docker',
  dockerImage: 'my-app:1.0.0',
  description: '容器化应用'
});
```

## 注意事项

1. **文件路径**: `copyFiles` 中的文件路径是相对于项目根目录的
2. **配置文件**: 配置文件名不需要包含 `.js` 后缀
3. **版本号**: 建议使用语义化版本号格式
4. **Docker 镜像**: 使用 Docker 部署时需要确保镜像已构建并推送到镜像仓库
5. **脚本类型**: Python 脚本需要目标环境支持 Python 运行时

## 更新日志

详细的更新日志请查看 [CHANGELOG.md](./CHANGELOG.md)。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。