001/**
002 * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
003 * <p>
004 * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * <p>
008 * http://www.gnu.org/licenses/lgpl-3.0.txt
009 * <p>
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package dev.tinyflow.core.chain;
017
018/**
019 * 链（Chain）执行生命周期状态枚举
020 * <p>
021 * 该状态机描述了一个 Chain 实例从创建到终止的完整生命周期。
022 * 状态分为三类：
023 * - <b>初始状态</b>：READY
024 * - <b>运行中状态</b>：RUNNING, SUSPEND, WAITING
025 * - <b>终态（Terminal）</b>：SUCCEEDED, FAILED, CANCELLED（不可再变更）
026 * <p>
027 * 设计原则：
028 * - 使用行业通用术语（如 SUCCEEDED/FAILED，而非 FINISHED_NORMAL/ABNORMAL）
029 * - 明确区分人工干预（SUSPEND）与系统调度（WAITING）
030 * - 终态互斥且不可逆，便于状态判断与持久化恢复
031 */
032public enum ChainStatus {
033
034    /**
035     * 初始状态：Chain 已创建，但尚未开始执行。
036     * <p>
037     * 此状态下，Chain 的内存为空，节点尚未触发。
038     * 调用 {@link Chain#execute} 或 {@link Chain#doExecute} 后进入 {@link #RUNNING}。
039     */
040    READY(0),
041
042    /**
043     * 运行中：Chain 正在执行节点逻辑（同步或异步）。
044     * <p>
045     * 只要至少一个节点仍在处理（包括等待 Phaser 同步），状态即为 RUNNING。
046     * 遇到挂起条件（如缺少参数、loop 间隔）时，会转为 {@link #SUSPEND}
047     */
048    RUNNING(1),
049
050    /**
051     * 暂停（人工干预）：Chain 因缺少外部输入而暂停，需用户主动恢复。
052     * <p>
053     * 典型场景：
054     * - 节点参数缺失且标记为 required（等待用户提交）
055     * - 人工审批节点（等待管理员操作）
056     * <p>
057     * 恢复方式：调用 {@link Chain#resume(Map)} 注入所需变量。
058     * 监听器：通过 {@link dev.tinyflow.core.chain.listener.ChainSuspendListener} 感知。
059     */
060    SUSPEND(5),
061
062
063    /**
064     * 错误（中间状态）：执行中发生异常，但尚未终结（例如正在重试）。
065     * <p>
066     * 此状态表示：Chain 遇到错误，但仍在尝试恢复（如重试机制触发）。
067     * 如果重试成功，可回到 RUNNING；如果重试耗尽，则进入 {@link #FAILED}。
068     * <p>
069     * ⚠️ 注意：此状态 <b>不是终态</b>，Chain 仍可恢复。
070     */
071    ERROR(10),
072
073    /**
074     * 成功完成：Chain 所有节点正常执行完毕，无错误发生。
075     * <p>
076     * 终态（Terminal State）—— 状态不可再变更。
077     * 此状态下，Chain 的执行结果（executeResult）有效。
078     */
079    SUCCEEDED(20),
080
081    /**
082     * 失败结束：Chain 因未处理的异常或错误条件而终止。
083     * <p>
084     * 终态（Terminal State）—— 状态不可再变更。
085     * 常见原因：节点抛出异常、重试耗尽、条件校验失败等。
086     * 错误详情可通过 {@link ChainState#getError()} 获取。
087     */
088    FAILED(21),
089
090    /**
091     * 已取消：Chain 被用户或系统主动终止，非因错误。
092     * <p>
093     * 终态（Terminal State）—— 状态不可再变更。
094     * 典型场景：
095     * - 用户点击“取消”按钮
096     * - 超时自动取消（如审批超时）
097     * - 父流程终止子流程
098     * <p>
099     * 与 {@link #FAILED} 的区别：CANCELLED 是预期行为，通常不计入错误率。
100     */
101    CANCELLED(22);
102
103    /**
104     * 状态的数值标识，可用于数据库存储或网络传输
105     */
106    private final int value;
107
108    ChainStatus(int value) {
109        this.value = value;
110    }
111
112    /**
113     * 判断当前状态是否为终态（Terminal State）
114     * <p>
115     * 终态包括：SUCCEEDED, FAILED, CANCELLED
116     * 一旦进入终态，Chain 不可再恢复或继续执行。
117     *
118     * @return 如果是终态，返回 true；否则返回 false
119     */
120    public boolean isTerminal() {
121        return this == SUCCEEDED || this == FAILED || this == CANCELLED;
122    }
123
124    /**
125     * 判断当前状态是否表示成功完成
126     *
127     * @return 如果是 {@link #SUCCEEDED}，返回 true；否则返回 false
128     */
129    public boolean isSuccess() {
130        return this == SUCCEEDED;
131    }
132
133
134    /**
135     * 获取状态对应的数值标识
136     *
137     * @return 状态值
138     */
139    public int getValue() {
140        return value;
141    }
142
143    public static ChainStatus fromValue(int value) {
144        for (ChainStatus status : values()) {
145            if (status.value == value) {
146                return status;
147            }
148        }
149        return null;
150    }
151}