# `releases/` 发布目录

## 目的

`releases/` 用于存放 **可交付的发布包（release bundle）**：从本 reactor 构建的 **Spring Boot fat JAR**、与现场/部署包一致的 **配置文件**、**启动脚本** 与 **校验信息（SHA256）** 的固定组合。  
该目录是 **对外或运维交付的“落盘点”**，与单纯的 Maven `target/` 构建输出区分开。

## 目录命名规范

每个发布包为一个子目录，命名格式：

```text
ninca-common-component-organization-<maven-version>-<YYYYMMDD>/
```

- **`<maven-version>`**：反应堆根 `pom.xml` 中 `<artifactId>ninca-common-component-organization-reactor</artifactId>` 对应的 `<version>`（例如 `2.9.4-xinghewan`）。
- **`<YYYYMMDD>`**：发布日期戳；默认取构建当日 `date +%Y%m%d`，也可用环境变量覆盖（见脚本说明）。

示例：`ninca-common-component-organization-2.9.4-xinghewan-YYYYMMDD/`。

## 每个 bundle 应包含的内容

| 内容 | 说明 |
|------|------|
| **Fat JAR** | 从 `cwos-component-organization-starter/target/` 拷贝的可执行 fat JAR（由 `spring-boot-maven-plugin` repackage，`finalName` 为 `ninca-common-component-organization-${project.version}.jar`）。 |
| **`application-node.properties`** | 节点差异（Consul 主机、instance-id、management-suffix 等）；公共项在 fat jar 内 `application.properties`。从 **`部署包/`** 模板目录复制（见下文）。 |
| **`bootstrap.properties`** | 引导配置；来源同上。 |
| **`sql/`** | 租户访客策略脚本（与 **`源码/docs/sql`** 一致）：电梯库 `tenant_visitor_floor_policy*` + 组织库 **`organization_tenant_visitor_floor_policy*`**（含 **`organization_tenant_visitor_floor_policy_full_install.sql`** 一站式）；内含 **`README.txt`**。 |
| **`start.sh`** | 启动脚本：**`--spring.config.location=classpath:/,file:<发布目录>/`** + **`--spring.config.name=application,application-node`** + **`--logging.path=<发布目录>/logs`**。 |
| **可选符号链接** | 运维友好别名：`ninca-common-component-organization-V<主版本三元组>_<YYYYMMDD>.jar` → 实际 fat JAR（例如 `V2.9.4_20260506` 对应版本 `2.9.4-xinghewan`）。 |
| **`RELEASE.txt`** | 发布说明：版本、目录名、构建命令、文件清单、fat JAR 的 **SHA256**。 |

其中 `application-node.properties` / `bootstrap.properties` 的「权威模板」通常来自现场 **部署包** 目录（与运维目录对齐），路径示例：

`星河湾星中星/部署包/ninca_common_component_organization_01-ninca_common_component_organization/`

若该路径下不存在对应文件，脚本会 **告警并跳过**，不会中断构建（仍可从别处手工放入同名文件）。

## 前置条件

- **JDK 8**：与本 reactor 一致；默认使用 `/usr/lib/jvm/java-8-openjdk-amd64`（可通过 `JAVA_HOME` 覆盖）。
- **`all-lib/`**：反应堆依赖的本地扁平库目录必须存在且齐全，否则 `mvn package` 可能失败（根 `pom.xml` 中 `all-lib.dir` 指向 `${maven.multiModuleProjectDirectory}/all-lib`）。

## JDK / `JAVA_HOME` 说明

- 脚本默认使用 **`/usr/lib/jvm/java-8-openjdk-amd64`** 进行 **`mvn clean package`**。
- 若交互式环境中 **`JAVA_HOME` 已指向 JDK 11+**，仅写 `JAVA_HOME:-默认值` **不会**覆盖已导出变量；脚本会检测并在非 JDK 8 时 **发出 WARN 并强制改用上述 JDK8 路径**，以保证与本 reactor 一致。
- 若需使用其他 JDK 8 安装路径，请先 **`export JAVA_HOME=/path/to/jdk8`**（确保 `java -version` 为 1.8），再执行脚本。

## 自动生成脚本

使用 **`create-release-bundle.sh`**（位于本目录，可执行）从反应堆根执行 **`mvn clean package -DskipTests`**，并生成符合上述规范的目录与 `RELEASE.txt`。

用法示例：

```bash
cd /path/to/maven-ninca-common-component-organization
./releases/create-release-bundle.sh
RELEASE_DATE=20260506 ./releases/create-release-bundle.sh
```

环境变量（可选）：

- **`RELEASE_DATE`**：目录后缀 `YYYYMMDD`，默认当天。
- **`DEPLOY_TEMPLATE_ROOT`**：覆盖部署包模板目录（默认见上文「配置文件来源」）。
- **`DOCS_SQL_ROOT`**：覆盖 **`sql/`** 脚本来源目录（默认 **`源码/docs/sql`**，即反应堆上一级目录下的 `docs/sql`）。

## 与 `deploy-implementation-package/` 的关系

构建产物路径、制品暂存等说明见同仓库：

**[../deploy-implementation-package/README.md](../deploy-implementation-package/README.md)**

（若该文件不存在，请以反应堆根 `pom.xml` 与 starter 模块 `target/` 为准。）

## Git 与大文件

本目录下的 **`ninca-common-component-organization-*/` 发布子目录**（含 fat jar）通过 **`releases/.gitignore`** 忽略，避免将大体积二进制提交入库；**`README.md`** 与 **`create-release-bundle.sh`** 仍正常跟踪。

## 手工 `java -jar`（不用 start.sh）时

若从其它工作目录直接启动，请显式指定配置目录与可写日志路径，例如：

`--spring.config.location=file:<发布包绝对路径>/` 与 `--logging.path=<同目录下 logs 或 /tmp/...>`。

仅写 `--spring.config.location` 时若未覆盖 `logging.path`，且 `application.properties` 仍指向生产路径 `/data/cwos/...`，会因无法创建目录导致 **Logback 初始化失败**。

---

**English (short):** `releases/` holds versioned, deployable bundles (fat JAR + config + `start.sh` + `RELEASE.txt` + optional symlink), named `ninca-common-component-organization-<maven-version>-<YYYYMMDD>/`. Build requires JDK 8 and `all-lib/`. Use `create-release-bundle.sh` to reproduce bundles consistently.