# CISD 初始化真机联调与回滚手册

- 日期：2026-03-02
- 适用版本：`ENTERPRISE` / `INDIRECT` / `DIRECT`
- 适用代码基线：已包含 `APP_MQ_CREDENTIALS_APPLY`、`direct_db_init`、`tlq_init_cfg`

## 1. 目的

1. 在目标设备上完成初始化关键路径联调。
2. 验证三类版本在“预部署完成后，仅做客户化初始化”的边界下可稳定运行。
3. 提供失败后的快速回滚与重试指引。

## 2. 关键实现映射（联调前必须确认）

1. 企业/间参步骤链：
`RENDER_CONFIG -> SET_(RABBITMQ|TLQ) -> MQ_USER_APPLY -> MQ_QUEUE_APPLY -> DB_INIT -> DEPLOY_RECEIVER -> APP_MQ_CREDENTIALS_APPLY -> VERIFY`
2. 轻量化直参（TLQ）步骤链：
`RENDER_CONFIG -> MQ_USER_APPLY -> DB_INIT(direct_db_init) -> TLQ_INIT_CFG(tlq_init_cfg) -> VERIFY`
3. 轻量化直参（CFMQ）步骤链：
`RENDER_CONFIG -> MQ_USER_APPLY -> DB_INIT(direct_db_init) -> CFMQ_APPLY -> VERIFY`
4. 通道账号密码写回应用配置时默认加密：
`DESede(3DES) + secretKey=ABCDEFGHIJKLMN1234567890 + HEX(upper)`。

## 3. 联调前置检查

## 3.1 环境变量基线

在 TMS 进程环境确认以下参数：

```bash
echo "$TMS_CISD_PRESET_PRODUCT_TYPE"
echo "$TMS_INIT_EXECUTOR_MODE"
echo "$TMS_INIT_EXECUTOR_STANDARD_CPCONFIG_PATH"
echo "$TMS_INIT_EXECUTOR_DIRECT_DB_SCRIPT_DIR"
echo "$TMS_INIT_EXECUTOR_DIRECT_TLQ_INIT_CFG_DIR"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_APP_CONFIG_PATTERN_1"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_APP_CONFIG_PATTERN_2"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_ENCRYPT_ENABLED"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_SECRET_KEY"
```

建议值：

1. `TMS_INIT_EXECUTOR_MODE=LOCAL`
2. `TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_ENCRYPT_ENABLED=true`
3. `TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_SECRET_KEY` 与现场收发器解密密钥一致。

## 3.2 目录与脚本存在性

```bash
ls -l /home/cmep4i/cpconfig.cfg
ls -l /home/cmep4i/cpackage/toolsh/{setfraq.sh,setftq.sh,setsql.sh,setsptp.sh}
ls -l /opt/CAE_Install_Base_Resource/DB/setsql.sh
ls -l /opt/CAE_Install_App_Resource/CAE/init_cfg.sh
```

## 3.3 MQ 与配置文件可写性

```bash
ls -l /home/cmep4i/cmsp/application-prd*.properties
ls -l /home/cmep4i/cmtp/application-prd*.properties
which rabbitmqctl
which rabbitmqadmin
```

## 4. 联调执行清单（统一流程）

## 4.1 接口执行顺序

1. `GET /api/v1/device/status`
2. `POST /api/v1/init/preview`
3. `POST /api/v1/init/task`
4. `POST /api/v1/init/task/{taskId}/execute`
5. `GET /api/v1/init/task/{taskId}/steps`
6. 失败时逐步查看日志：`GET /api/v1/init/task/{taskId}/steps/{stepNo}/log`

## 4.2 用例矩阵（最小集合）

1. 企业版 + RabbitMQ
2. 企业版 + TLQ
3. 间参版 + RabbitMQ
4. 轻量化直参 + RABBITMQ_TLQ（必须带 `directTlq` 三字段）
5. 轻量化直参 + RABBITMQ_CFMQ

## 4.3 直参 TLQ 请求体附加字段

```json
{
  "directTlq": {
    "localNodeSeq": "A",
    "upstreamInstitutions": "CIPSCNSHXXX;CIPSCNWXXXX",
    "upstreamCocCount": 2
  }
}
```

## 5. 关键验收点

1. `RENDER_CONFIG` 后，`cpconfig.cfg` 中机构号、节点、签名参数、`MQ_TYPE` 已替换。
2. `MQ_USER_APPLY` 后，RabbitMQ 中存在通道用户，且具备目标 vhost 权限。
3. `MQ_QUEUE_APPLY` 后，业务队列创建成功（企业/间参）。
4. `APP_MQ_CREDENTIALS_APPLY` 后，`spring.rabbitmq.username/password` 已更新且为密文（非明文）。
5. `DB_INIT` 生成或替换的 SQL 文件可执行，无路径/权限错误。
6. `VERIFY` 成功，任务最终状态 `SUCCESS`。

## 6. 失败定位顺序

1. 配置错误：版本预置、环境变量、路径。
2. 权限错误：TMS 进程用户对脚本和配置文件不可写。
3. 脚本依赖缺失：`rabbitmqctl/rabbitmqadmin`、Java、数据库客户端。
4. 参数不完整：直参 TLQ 缺 `directTlq` 字段。
5. 密钥不一致：写回密文与收发器解密密钥不匹配导致 MQ 连接失败。

## 7. 回滚策略（按层次）

## 7.1 执行前备份（强制）

```bash
TS=$(date +%Y%m%d%H%M%S)
mkdir -p /tmp/cisd-init-backup-$TS
cp -a /home/cmep4i/cpconfig.cfg /tmp/cisd-init-backup-$TS/
cp -a /home/cmep4i/cmsp/application-prd*.properties /tmp/cisd-init-backup-$TS/ 2>/dev/null || true
cp -a /home/cmep4i/cmtp/application-prd*.properties /tmp/cisd-init-backup-$TS/ 2>/dev/null || true
echo "/tmp/cisd-init-backup-$TS"
```

## 7.2 配置回滚

```bash
cp -a /tmp/cisd-init-backup-<TS>/cpconfig.cfg /home/cmep4i/cpconfig.cfg
cp -a /tmp/cisd-init-backup-<TS>/application-prd*.properties /home/cmep4i/cmsp/ 2>/dev/null || true
cp -a /tmp/cisd-init-backup-<TS>/application-prd*.properties /home/cmep4i/cmtp/ 2>/dev/null || true
```

## 7.3 MQ 回滚（按需）

```bash
# 删除通道用户（示例）
rabbitmqctl delete_user <channelUsername>

# 删除业务队列（示例，按实际创建队列名执行）
rabbitmqadmin --username=admin --password=admin --vhost=/ delete queue name=<queueName>
rabbitmqadmin --username=admin --password=admin --vhost=/RQ delete queue name=<queueName>
```

## 7.4 数据库回滚（按实际 SQL 执行情况）

1. 若仅生成 SQL 未执行：删除临时生成物即可。
2. 若已执行入库：使用预先准备的回滚 SQL 或从数据库备份恢复。
3. 严禁在无备份情况下直接清库重建。

## 8. 重试策略

1. 先回滚配置和 MQ 变更，再重建任务重试，不复用失败任务。
2. 每次仅变更一个变量（如路径、密钥、账号），避免多变量同时变化。
3. 连续两次同一步失败，先停止重试，导出该步骤日志并人工排查根因。

## 9. 交付物归档

每次联调需归档：

1. `taskId`、版本类型、请求参数（脱敏后）。
2. 步骤执行日志目录：`/tmp/tms-init-logs/<taskId>/`。
3. 回滚操作记录（是否执行、执行人、时间）。
4. 最终结论：通过/失败及根因。