# SQL Site Naming Convention

本文档说明了项目中使用的 SQL 站点命名规则及其对应关系。

## 站点命名对照表

| 目录名称 | 对应站点          | IP地址 | 描述 |
|---------|---------------|--------|------|
| afe_ap | Alpha Site    |        |      |
| dls_ap | DLS           |        |      |
| hing_wai_ap | HingWai       |        |      |
| vn-demo | VN Demo       |        |      |
| vn-demo-local | VN Demo Local |        |      |
| 226 | UAT           |        |      |


## 目录结构与执行机制

### update_service_release 目录结构

项目中的 SQL 文件按照以下结构组织：

```
update_service_release/
├── 版本号/                    # 如 1.5.1.20
│   ├── sitename/             # 如 afe_ap, dls_ap 等
│   │   ├── patch/            # 补丁目录
│   │   │   └── 数字版本/      # 如 1, 2 等
│   │   │       └── *.sql     # 补丁 SQL 文件
│   │   └── *.sql             # 该站点特定的 SQL 文件
│   └── *.sql                 # 通用 SQL 文件
└── pending release x.x.x.x/  # 当前开发中的版本
```

### SQL 执行机制

1. **版本发布目录**：
   - 每个版本号目录下包含适用于不同站点的 SQL 文件
   - 站点特定的 SQL 文件放在对应的 `sitename` 子目录中
   - 补丁文件放在对应站点的 `patch` 子目录中，按数字版本号分组
   - 通用 SQL 文件直接放在版本号目录下

2. **当前开发版本**：
   - `update_service_release/pending release x.x.x.x` 是当前正在开发的版本目录
   - 每个版本下必须包含一个修改版本号的 SQL 文件：`set_version_01.sql`
   - 该文件负责更新系统版本信息到 `m_system_setting` 表

3. **Jenkins 自动化执行**：
   - 通过执行 `1-g3fo-db`/`g3fo-db-patch` 任务运行 SQL
   - 大版本升级执行`1-g3fo-db`，只能执行一次
   - 补丁执行`g3fo-db-patch`，可重复执行
   - 系统会根据指定的站点和版本号执行对应目录下的 SQL 文件
   - 默认执行版本号最大的 patch（可重复执行，保证幂等性）

### 版本号更新文件示例

每个版本必须包含 `set_version_01.sql` 文件，其内容如下（控实际情况修改版本号，以下是1.5.1.20版本示例）：

```sql
UPDATE `g3fo_base`.`m_system_setting`
SET `param_value` = '1.5.1.0 M20',
    `update_on` = NOW()
WHERE
    `param_name` = 'base.systemVersion';

UPDATE `g3fo_base`.`m_system_setting`
SET `param_value` = '0',
    `update_on` = NOW()
WHERE
    `param_name` = 'base.patchNo';
```

## 命名一致性要求

为了确保自动化部署和执行流程的正常运行，`sitename` 目录命名必须与以下配置保持严格一致：

1. **Jenkins 配置**：
   - Jenkins -> 系统管理 -> Publish over SSH -> SSH Server Name 中配置的服务名
   - 例如：如果 Jenkins 中配置的 SSH Server Name 为 `afe_ap`，则目录名必须也为 `afe_ap`

2. **执行服务器配置**：
   - 与执行 SQL 的服务器（Build 机或 support 机）上的 `/data/g3dbExecution/db_config.json` 文件中的 key 保持一致
   - 该 JSON 文件中的 key 值必须与目录名称完全匹配

这种一致性确保了：
- Jenkins 能够正确地将 SQL 文件传输到目标服务器
- SQL 脚本能够在正确的环境中执行
- 部署流程能够自动化进行而不会出现配置错误

## 添加新环境

当需要添加新的部署环境时，请遵循以下命名规则：
- 生产环境：使用客户名称的缩写加 `_ap` 后缀
- 测试环境：使用环境用途加版本号或标识符的形式

## 注意事项

- 所有命名应保持简洁明了
- 同一类环境应保持命名风格一致
- 添加新环境后应及时更新此文档
- 修改现有环境名称前需确认关联的所有配置均已同步更新