# 打包与发布指南

本仓库提供三套打包脚本，分别用于**主框架整站升级包**、**单个插件市场包**、**批量插件市场包**。
三者均已支持**自动递增版本号**，并配套「框架在线升级的数据库变更」机制。

> 部署（中心站 / 客户端如何对接）不在本文范围，参见 `docs/DEPLOY_INTEGRATION.md`。

## 0.0 产物与用途总览

`package_framework.php` **一次运行同时产出三个文件**；插件包由独立脚本产出：

| 产物 | 来源命令 | 输出位置 | 用途 |
| --- | --- | --- | --- |
| 框架整包 `ywxapp-<ver>.zip` | `package_framework.php` | `build/framework/` | 框架升级（整站覆盖） |
| 框架补丁 `ywxapp-<ver>-patch.zip` | `package_framework.php` | `build/framework/` | 框架增量升级（`from_version` 起 git diff） |
| 完整安装包 `ywxapp-<ver>-install.zip` | `package_framework.php` | `build/framework/` | **新站首次部署**（白名单：app/config/extend/public/ywxapp/route + 根文件；不含插件、不含真实 `.env`/`database.php`/`ywxapp.php`，内置 `.env` 占位模板） |
| 插件市场 zip + 测试 SQL | `package_all_addon.php` / `package_appmarket_addon.php` | `build/addon/`、`build/sql/` | 上传到应用市场后台，供客户机**后台购买后下载安装** |

> ⚠️ **重要约定**
> - 框架整包与完整安装包**都刻意不含 `addon/` 插件目录**（整包经 `includeDirs` 排除；安装包用白名单 + 排除 `public/static/<插件>/`、`public/addon/`）。全新部署框架后，插件需经后台应用市场**独立下载安装**，不要把插件打进框架包。
> - `package_install.php` 已废弃并合并进 `package_framework.php`（安装包产物由后者统一产出），请勿再单独调用。
> - 插件走「后台购买 → 下载 → 安装」的在线分发链路，与框架整包互相独立，二者不要混包。

---

## 0. 版本号来源（重要）

| 产物 | 版本号来源 | 是否进包 | 写回位置 |
|---|---|---|---|
| 主框架整站包 | `config/ywxapp.php` 第 37 行 `version` | 不进包（被排除） | `config/ywxapp.php` |
| market 插件包 | `addon/appmall/info.php` 的 `version` | 不进包（随插件本身） | `addon/appmall/info.php` |
| 其他插件包 | `addon/<name>/info.php` 的 `version` | 不进包（随插件本身） | `addon/<name>/info.php` |

- **框架版本与各插件版本互相独立**，各自维护、各自递增。
- 打包脚本每次都会把新版本**写回对应文件**，保证下次打包在此基础上再 `+1`。
- 写回会改动 git 跟踪文件，属预期行为；但该文件被排除在升级包外，不会覆盖客户机。

---

## 1. 主框架整站升级包 — `scripts/package_framework.php`

生成「整站升级包」（含 `app/config/extend/ywxapp/public/route` + 根文件 `think/composer.json/README.md/LICENSE.txt`），
客户端 `ywxapp/service/FrameworkService::apply()` 解压即完成整站升级。

**产物**（`build/framework/`，非 Web 可访问）：
- `ywxapp-<version>.zip` —— 整包（整站，**不含插件**）
- `ywxapp-<version>-patch.zip` —— 增量补丁包（`from_version` = 基础版本）

**安全排除**（绝不进包，避免覆盖客户机本地配置与数据）：
`runtime/`、`vendor/`、`data/`、`.git`、`public/uploads`、`config/database.php`、`config/ywxapp.php`、`.env`、`install.lock`、`addon/`（插件独立分发）。

### 用法（支持自动递增版本号）

```bash
# 不带版本号：自动按 patch +1（读 config/ywxapp.php 当前版本，写回新值）
php scripts/package_framework.php

# 按段递增
php scripts/package_framework.php minor      # 如 1.0.2 -> 1.1.0
php scripts/package_framework.php major      # 如 1.0.2 -> 2.0.0

# 显式指定新版本
php scripts/package_framework.php 1.2.3
```

- `baseVersion` 为第二可选参数（升级起点/补丁基础版本），缺省取写回前的旧值。
- 打包前会跑 `regressionCheckConfigVersion()` 校验，拦截「写坏配置」的历史 bug 写法（若触发直接中断打包）。

### 数据库升级 SQL 约定

若本次升级涉及数据库结构/数据变更，把**增量 SQL** 放到仓库 `ywxapp/upgrade.sql`：
- 整站包包含 `ywxapp/` 目录，`upgrade.sql` 会自动打进包，解压后位于 `项目根/ywxapp/upgrade.sql`。
- `apply()` 解压完成后自动检测并执行（`coreDir/upgrade.sql` 或 `root/upgrade.sql`）。
- 按语句拆分（忽略 `--` 行注释与 `/* */` 块注释），用 `Db::connect()->execute()` 执行。
- **幂等**：已执行版本记入 `runtime/framework/sql_applied.json`（`版本:文件名` 为键），重复升级不重复执行；执行成功后会删除该 `upgrade.sql`。
- 执行失败抛 `数据库升级失败：...` 异常，由升级流程提示（文件已提前备份）。
- ⚠️ **无事务回滚**，SQL 须写成幂等（如 `CREATE TABLE IF NOT EXISTS`、`ADD COLUMN IF NOT EXISTS`），并在预发环境先验证。

---

## 2. 单个插件市场包 — `scripts/package_appmarket_addon.php`

把本地插件打包成市场 zip（结构对齐 `AddonService::package()`）：`addon/<name>/` 为 zip 根，`public/static/addon/<name>/` 为 `static/` 前缀。
并生成 `wxapp_appmarket_addon_list` 测试记录 SQL（用于往中心站插一条数据，便于联调）。

**产物**：
- `build/addon/<addon>-<version>.zip`
- `build/sql/<addon>-<version>-appmarket_addon_list.sql`（测试记录，`file_path` 为本地绝对路径，中心站部署时需改成实际路径或走后台上传）

### 用法（支持自动递增版本号）

```bash
# 不带版本号：自动按 patch +1（读 addon/<addon>/info.php 当前版本，写回新值）
php scripts/package_appmarket_addon.php appmall

# 按段递增
php scripts/package_appmarket_addon.php appmall minor      # 1.0.1 -> 1.1.0

# 显式指定
php scripts/package_appmarket_addon.php appmall 1.2.0

# 兼容旧式（带标题等可选参数，version 缺省则按 patch 自动递增）
php scripts/package_appmarket_addon.php mqttbroker "MQTT代理" "" "基于 Workerman 自研 MQTT Broker" 0
```

- 版本参数位于 `$argv[2]`：若匹配 `x.y.z` 或 `major|minor|patch`，则视为版本参数，其后 `title/author/description/price` 整体左移一位，保持旧调用兼容。

---

## 3. 批量插件市场包 — `scripts/package_all_addon.php`

一次性打包 `addon/` 下所有插件。

**产物**：`build/addon/<name>-<version>.zip` + `build/sql/<name>-<version>-appmarket_addon_list.sql`（每个插件一份）。

### 用法

```bash
# 不带 bump：按各插件 info.php 当前版本打包，不改版本号（安全、可重复执行）
php scripts/package_all_addon.php

# bump：每个插件版本按 patch +1 并写回各自 info.php（发版用）
php scripts/package_all_addon.php bump

# 跳过指定插件（与 bump 可组合）
php scripts/package_all_addon.php skip:market
php scripts/package_all_addon.php bump skip:market
```

> ⚠️ `bump` 会修改所有被打包插件的 `info.php` 版本号。日常只想重新生成 zip 时**不要带 `bump`**。

---

## 4. 典型发版流程

```bash
# 1) 框架整站升级（自动 +1，含可选 upgrade.sql）
php scripts/package_framework.php

# 2) 中心站插件（market）发版（自动 +1）
php scripts/package_appmarket_addon.php appmall

# 3) 其余插件批量发版（各 +1）
php scripts/package_all_addon.php bump
```

1. 把 `build/framework/ywxapp-<ver>.zip`（整包）在中心站后台「主框架版本管理」上传并**发布**（客户端方可检测；该整包即**新站安装包**，不含插件）。
2. 把 `build/addon/*.zip` 在中心站「应用市场管理 / 插件审核」上传，或走后台「上传升级包」（客户机后台购买后下载安装）。
3. 涉及数据库变更时，确保打包前已把增量 SQL 写入 `ywxapp/upgrade.sql`（随包发布、升级时自动执行）。

---

## 5. 常见问题

- **Q：怎么让每次打包版本号自动 +1？**
  A：框架包直接空参运行；插件包空参或带 `minor/major`；批量包带 `bump`。三者都会写回版本文件。
- **Q：框架升级改了数据库表结构，客户机怎么同步？**
  A：把增量 SQL 放 `ywxapp/upgrade.sql`，随包发布，`apply()` 自动幂等执行（见第 1 节）。
- **Q：补丁包比整包大 / 变更很多？**
  A：补丁基于 git 工作树相对基础版本的 diff。若工作树相对某基线改动很多，补丁会偏大；先把代码提交到稳定基线后再打，补丁即为当次真实改动。
- **Q：打包提示 LF/CRLF 警告？**
  A：git `autocrlf` 噪声，非错误，可忽略。