# YMS 命令入口与操作查询方案

> 状态：方案确认，暂不进入代码实现

## 1. 命令职责

命令入口采用 daemon/client 分离，命名参考 `chronyd / chronyc`：

| 命令 | 职责 | 是否常驻 |
|---|---|---:|
| `ymsd` | 更新助手服务端，监听 Unix Socket，执行事务和恢复 | 是 |
| `ymsctl` | 运维和交付 CLI，提交更新、查询状态、诊断和回滚 | 否 |
| `yms-gui` | 客户 PC 图形化中转助手，名称后续确定 | 否 |

`ymsd` 不承担交互式更新命令；更新请求由 `ymsctl` 通过 Unix Socket 提交。POC 阶段不对外提供 `serve` 子命令，systemd 的 `ExecStart` 直接启动 `/usr/sbin/ymsd`。

## 2. systemd 与安装

systemd unit 名称继续固定为：

```text
yms-daemon.service
```

unit 的启动目标为：

```text
/usr/sbin/ymsd
```

POC 阶段不保留 `yms-daemon` 命令兼容入口，直接采用新命名。更新命令统一使用：

```bash
ymsctl update ...
ymsctl restart ...
```

## 3. ymsctl 命令层级

### 3.1 更新与回滚

```bash
ymsctl update --service backend -f <repack.zip>
ymsctl update --service backend --native-jar <backend.jar>
ymsctl update --service backend --container-image <image:tag>
ymsctl restart --service backend
ymsctl rollback --service backend --transaction <transaction-id>
```

`--native-jar` 与 `--container-image` 互斥。`rollback` 必须指定明确的事务 ID 或已提交版本身份，不允许根据目录排序、文件修改时间或镜像 tag 猜测回滚目标。

### 3.2 历史操作查询

```bash
ymsctl list
ymsctl list --limit 50
ymsctl list --state FAILED
ymsctl list --service backend
ymsctl list --json
```

默认显示最近 20 次操作，按创建时间倒序。每条记录至少展示：

- 创建时间和结束时间；
- transaction ID；
- service；
- operation；
- 输入类型和版本或镜像 digest；
- 来源（CLI、PC client、Jenkins、server API）；
- 最终状态；
- 失败原因。

`--json` 输出稳定 JSON，供 Jenkins 和 PC client 使用。列表数据只读取 SQLite，不直接扫描 systemd、Docker 或 Nginx 生成历史记录。

### 3.3 当前状态与诊断

```bash
ymsctl status --service backend
ymsctl doctor --service backend
ymsctl reconcile --service backend
ymsctl reconcile --service backend --apply
```

- `status`：读取 SQLite 后校验当前 systemd、Docker、Nginx 和活动槽位状态；
- `doctor`：只读诊断，输出漂移项和建议动作；
- `reconcile`：只读生成修复计划；
- `reconcile --apply`：执行明确授权的修复动作，并创建可审计事务。

## 4. 状态漂移处理原则

SQLite 是事务事实来源，外部系统是待校验运行状态。发现不一致时默认拒绝更新，不自动覆盖现场。

只有以下类型允许自动修复：

1. SQLite 记录的活动容器存在、身份匹配且健康，Nginx 仅指向错误槽位；
2. 非活动槽位容器存在、已停止且没有提交记录；
3. native 活动 JAR 链接与已提交事务明确记录的 release 不一致，且目标文件身份校验通过；
4. 已完成事务的临时文件可以按照事务凭据清理。

以下情况必须进入 `DRIFT_DETECTED`，等待人工确认：

- SQLite 记录的活动容器已经不存在；
- 两个槽位同时运行且无法确定提交归属；
- SQLite 没有部署记录，但现场已经存在容器或运行中的 native 服务；
- Nginx 配置无法验证或存在非 daemon 管理的冲突；
- systemd unit、容器镜像 digest、JAR SHA-256 与事务记录不一致。

任何修复动作都必须先写入事务，再执行外部变更；修复失败时沿用现有回滚和恢复机制。

## 5. systemd 服务与 ymsd 的边界

`ymsd` 负责：

- 持有进程锁；
- 打开 SQLite；
- 恢复未完成事务；
- 调用 native/container 执行器；
- 通过 Unix Socket 提供请求和进度响应；
- 写入 stdout 和本地日志文件。

`ymsctl` 负责：

- 参数校验；
- 提交请求；
- 展示进度；
- 查询历史和当前状态；
- 发起显式诊断和修复。

`ymsctl` 不直接写 SQLite，不直接修改 Nginx，不直接调用 Docker 或 systemd。

## 6. 实施顺序

1. 增加 SQLite 最近操作查询接口；
2. 实现 `ymsctl list` 和 JSON 输出；
3. 拆分 `ymsd` 与 `ymsctl` 的编译入口；
4. 安装 `ymsd`、`ymsctl` 和兼容入口 `yms-daemon`；
5. 实现 `status` 只读一致性检查；
6. 实现 `doctor` 漂移报告；
7. 实现带事务审计的 `reconcile --apply`；
8. 最后确定 GUI 名称和 PC client 的调用协议。