//! The greedy planner.
//!
//! 贪心规划器。

use crate::greedy::infeasible_tasks;
use crate::improve::{ImprovementSettings, improve};
use crate::sweep::earliest_feasible_start;
use apsis_resource::ResourceSet;
use apsis_schedule::Schedule;
use apsis_task::{PrecedenceGraph, Task, TaskId, TaskState, task_order};

/// What happened to one task during planning.
///
/// The outcome pairs a task with the state the planner assigned, which is the
/// information an operator needs to see. It is separate from the schedule
/// because a task that was not placed has no placement but still has an
/// outcome worth reporting.
///
/// 规划过程中某个任务的结果。
///
/// 它把任务与规划器所指定的状态配对，这是操作者需要看到的信息。它与
/// 计划分开，因为未放置的任务虽无放置，却仍有一份值得报告的结果。
#[derive(Debug, Clone, PartialEq)]
pub struct PlanOutcome {
    /// The task.
    ///
    /// 该任务。
    pub task: TaskId,
    /// The state the planner assigned.
    ///
    /// 规划器所指定的状态。
    pub state: TaskState,
}

impl PlanOutcome {
    /// Returns `true` when the task was placed.
    ///
    /// 当该任务已被放置时返回 `true`。
    pub fn is_scheduled(&self) -> bool {
        self.state.is_scheduled()
    }

    /// Returns `true` when the task could not be placed for a structural
    /// reason, rather than being left out for want of time.
    ///
    /// 当该任务因结构性原因无法放置、而非因时间不足被排除时返回 `true`。
    pub fn is_infeasible(&self) -> bool {
        matches!(self.state, TaskState::Infeasible { .. })
    }
}

/// The result of planning.
///
/// 规划的结果。
#[derive(Debug, Clone, PartialEq)]
pub struct SchedulingResult {
    /// The schedule that was produced.
    ///
    /// 所产出的计划。
    pub schedule: Schedule,
    /// The outcome of every task, in the order the planner considered them.
    ///
    /// The order is the order of the task list the planner was given, not the
    /// order in which the planner placed them, so that a caller can index the
    /// outcomes by the position of the task in its own list.
    ///
    /// 每个任务的结果，按规划器考虑它们的顺序排列。
    ///
    /// 该顺序是规划器所获任务列表的顺序，而非其放置的顺序，故调用方
    /// 可按任务在自身列表中的位置索引结果。
    pub outcomes: Vec<PlanOutcome>,
    /// The identifiers of the tasks that the improvement pass placed.
    ///
    /// These tasks were left out by the greedy pass and placed afterwards by
    /// moving other placements. They are also recorded as scheduled in the
    /// outcomes.
    ///
    /// 改进轮所放置的任务标识符。
    ///
    /// 这些任务被贪心轮排除，其后通过移动其他放置而被安排。它们在
    /// 结果中同样被记为已调度。
    pub improved: Vec<TaskId>,
}

impl SchedulingResult {
    /// Returns the outcome of a task.
    ///
    /// 返回某任务的结果。
    pub fn outcome_of(&self, task: TaskId) -> Option<&PlanOutcome> {
        self.outcomes.iter().find(|outcome| outcome.task == task)
    }

    /// Returns the identifiers of the tasks that were placed.
    ///
    /// 返回已放置任务的标识符。
    pub fn scheduled(&self) -> Vec<TaskId> {
        self.outcomes
            .iter()
            .filter(|outcome| outcome.is_scheduled())
            .map(|outcome| outcome.task)
            .collect()
    }

    /// Returns the identifiers of the tasks that were left out.
    ///
    /// 返回被排除任务的标识符。
    pub fn deferred(&self) -> Vec<TaskId> {
        self.outcomes
            .iter()
            .filter(|outcome| outcome.state == TaskState::Deferred)
            .map(|outcome| outcome.task)
            .collect()
    }

    /// Returns the identifiers of the tasks that cannot be placed at all.
    ///
    /// 返回完全无法放置的任务的标识符。
    pub fn infeasible(&self) -> Vec<TaskId> {
        self.outcomes
            .iter()
            .filter(|outcome| outcome.is_infeasible())
            .map(|outcome| outcome.task)
            .collect()
    }

    /// Returns `true` when every offered task was placed.
    ///
    /// 当所有提交任务均被放置时返回 `true`。
    ///
    /// 当所有提交任务均被放置时返回 `true`。
    pub fn is_complete(&self) -> bool {
        self.outcomes.iter().all(PlanOutcome::is_scheduled)
    }

    /// Returns `true` when every mandatory task was placed.
    ///
    /// A plan that leaves a mandatory task unplaced is not usable, however
    /// much optional work it found room for.
    ///
    /// 当所有强制任务均被放置时返回 `true`。
    ///
    /// 留下强制任务未放置的计划不可用，无论它为多少可选工作腾出了
    /// 空间。
    pub fn honours_mandatory(&self, tasks: &[Task]) -> bool {
        tasks
            .iter()
            .filter(|task| task.mandatory)
            .all(|task| self.schedule.is_placed(task.id))
    }

    /// Returns `true` when every precedence constraint is satisfied.
    ///
    /// A constraint is satisfied when the second task starts at or after the
    /// end of the first. A constraint whose tasks are not both placed is
    /// trivially satisfied, because nothing has been promised about them.
    ///
    /// 当所有优先约束都得到满足时返回 `true`。
    ///
    /// 约束被满足，指第二个任务的起点不早于第一个的终点。两个任务未
    /// 同时放置的约束平凡地满足，因为对它们未作任何承诺。
    pub fn honours_precedence(&self, graph: &PrecedenceGraph) -> bool {
        self.outcomes
            .iter()
            .filter(|outcome| outcome.is_scheduled())
            .all(|outcome| {
                let Some(after) = self.schedule.placement_of(outcome.task) else {
                    return true;
                };
                graph.predecessors_of(outcome.task).iter().all(|before| {
                    self.schedule
                        .placement_of(*before)
                        .is_none_or(|placement| placement.end() <= after.start)
                })
            })
    }
}

/// A greedy planner.
///
/// The planner holds the settings of the search. The settings are separated
/// from the schedule so that the same planner can be applied to many task
/// sets with the same policy.
///
/// 贪心规划器。
///
/// 该规划器持有搜索的设置。设置与计划分开，故同一个规划器可按同一策略
/// 应用于许多任务集。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Planner {
    /// Whether to place mandatory tasks before the others regardless of
    /// their value.
    ///
    /// A mandatory task must run, so it is worth placing first even when its
    /// weighted value is low: the optional tasks can use whatever time is
    /// left, while the reverse order could consume the only window the
    /// mandatory task had.
    ///
    /// 是否不论价值高低都先放置强制任务。
    ///
    /// 强制任务必须执行，故即便其加权价值很低也值得先放置：可选任务
    /// 可以利用剩下的时间，而相反的顺序可能耗尽强制任务仅有的那个窗口。
    pub mandatory_first: bool,
    /// The settings of the improvement pass.
    ///
    /// 改进轮的设置。
    pub improvement: ImprovementSettings,
}

impl Default for Planner {
    /// Returns a planner that places mandatory tasks first and runs the
    /// improvement pass.
    ///
    /// 返回一个先放置强制任务并运行改进轮的规划器。
    fn default() -> Self {
        Self {
            mandatory_first: true,
            improvement: ImprovementSettings::default(),
        }
    }
}

impl Planner {
    /// Creates a planner with the default settings.
    ///
    /// The defaults are the ones [`Planner::default`] uses: mandatory tasks
    /// first and the improvement pass enabled with four attempts per task.
    ///
    /// 以默认设置创建规划器。
    ///
    /// 默认值即 [`Planner::default`] 所用者：先放置强制任务，改进轮
    /// 启用且每任务尝试四次。
    pub const fn new() -> Self {
        Self {
            mandatory_first: true,
            improvement: ImprovementSettings::new(4),
        }
    }

    /// Returns a copy of this planner with the mandatory placement rule set.
    ///
    /// 返回设置了强制放置规则的规划器副本。
    pub const fn with_mandatory_first(mut self, mandatory_first: bool) -> Self {
        self.mandatory_first = mandatory_first;
        self
    }

    /// Returns a copy of this planner with the improvement pass configured.
    ///
    /// 返回配置了改进轮的规划器副本。
    pub const fn with_improvement(mut self, improvement: ImprovementSettings) -> Self {
        self.improvement = improvement;
        self
    }

    /// Returns the order in which the planner considers the tasks.
    ///
    /// Without a precedence graph the order is mandatory tasks first, when
    /// the planner is configured that way, and then decreasing weighted
    /// value with ties broken by deadline and identifier.
    ///
    /// With a precedence graph the order is a topological order of the
    /// graph, using the value order to break ties. That places a task as
    /// early as its constraints allow and the most valuable one first among
    /// the tasks that are free.
    ///
    /// 返回规划器考虑任务的顺序。
    ///
    /// 无优先关系图时，顺序是先强制任务（若规划器如此配置），再按加权
    /// 价值递减，平局按截止时刻与标识符打破。
    ///
    /// 有优先关系图时，顺序是该图的拓扑序，并以价值次序打破平局。这
    /// 使任务在其约束允许的最早时刻被放置，而在自由的任务中优先放置
    /// 价值最高者。
    pub fn order(&self, tasks: &[Task]) -> Vec<TaskId> {
        self.order_with_precedence(tasks, None)
    }

    /// Returns the order in which the planner considers the tasks, honouring
    /// a precedence graph.
    ///
    /// A graph whose constraints contain a cycle produces the value order
    /// unchanged, because the constraints then have no satisfiable
    /// interpretation. The caller should validate the graph before
    /// planning; the order is a fallback so that planning still produces
    /// something rather than failing outright.
    ///
    /// 返回规划器考虑任务的顺序，并遵从给定的优先关系图。
    ///
    /// 约束含环的图会原样产生价值次序，因为这些约束此时没有可满足的
    /// 解释。调用方应在规划前校验该图；此处的次序是一个回退，使规划
    /// 仍能产出结果而非直接失败。
    pub fn order_with_precedence(
        &self,
        tasks: &[Task],
        precedence: Option<&PrecedenceGraph>,
    ) -> Vec<TaskId> {
        let ordered = task_order(tasks);
        let valued = if !self.mandatory_first {
            ordered
        } else {
            let mandatory: Vec<TaskId> = tasks
                .iter()
                .filter(|task| task.mandatory)
                .map(|task| task.id)
                .collect();
            let mut result = Vec::with_capacity(ordered.len());
            result.extend(ordered.iter().filter(|id| mandatory.contains(id)).copied());
            result.extend(ordered.iter().filter(|id| !mandatory.contains(id)).copied());
            result
        };

        let Some(graph) = precedence else {
            return valued;
        };
        if graph.is_empty() {
            return valued;
        }
        graph.topological_order(&valued).unwrap_or(valued)
    }

    /// Plans a set of tasks on a set of resources.
    ///
    /// Every task is considered once, in the order the planner chooses. A
    /// task is placed at the earliest time at which all of its resources are
    /// free together. A task that cannot be placed is reported as deferred,
    /// or as infeasible when no placement could ever exist.
    ///
    /// The schedule that is returned is feasible by construction, because
    /// each placement is checked against the capacity before it is made. The
    /// caller may confirm that with `apsis-conflict`.
    ///
    /// 在一组资源上规划一组任务。
    ///
    /// 每个任务按规划器所选的顺序被考虑一次，被放置在其全部资源恰好同时
    /// 空闲的最早时刻。无法放置的任务被报告为被推迟；不存在任何可行
    /// 放置的则报告为不可行。
    ///
    /// 返回的计划按构造即可行，因为每处放置在做下之前都对照容量校验
    /// 过。调用方可用 `apsis-conflict` 复核。
    pub fn schedule(&self, tasks: &[Task], resources: &ResourceSet) -> SchedulingResult {
        self.plan(tasks, resources, None)
    }

    /// Plans a set of tasks, honouring a precedence graph.
    ///
    /// A task is placed only after every task that must precede it has been
    /// placed, so the search for its start begins no earlier than the latest
    /// end among its predecessors. A predecessor that could not be placed
    /// makes the successor deferred as well, because the constraint cannot be
    /// met.
    ///
    /// The improvement pass is not applied to a plan with precedence
    /// constraints, because relocating a placement could break a constraint
    /// that the pass does not consider. A caller that needs both should
    /// improve the plan and then verify it with
    /// [`SchedulingResult::honours_precedence`].
    ///
    /// 遵从优先关系图规划一组任务。
    ///
    /// 任务仅在其所有前驱均已放置之后才被放置，故其起点搜索不早于
    /// 前驱中最晚的结束时刻。无法放置的前驱会使其后继同样被推迟，
    /// 因为该约束无法满足。
    ///
    /// 改进轮不作用于带优先约束的计划，因为移动某处放置可能破坏该轮
    /// 并不考虑的约束。两者皆需的调用方应先改进计划，再用
    /// [`SchedulingResult::honours_precedence`] 复核。
    pub fn schedule_with_precedence(
        &self,
        tasks: &[Task],
        resources: &ResourceSet,
        precedence: &PrecedenceGraph,
    ) -> SchedulingResult {
        self.plan(tasks, resources, Some(precedence))
    }

    /// The shared planning routine.
    ///
    /// 共享的规划例程。
    fn plan(
        &self,
        tasks: &[Task],
        resources: &ResourceSet,
        precedence: Option<&PrecedenceGraph>,
    ) -> SchedulingResult {
        let mut schedule = Schedule::new();
        // The state of every task, indexed by identifier, so that a
        // predecessor's placement can be looked up by index.
        // 各任务的状态，按标识符索引，使前驱的放置可按下标查得。
        let mut states = vec![TaskState::Pending; tasks.len()];
        let mut outcomes = Vec::with_capacity(tasks.len());
        let mut order: Vec<TaskId> = self.order_with_precedence(tasks, precedence);
        // A deferred task is one whose search failed, as opposed to one whose
        // structural preconditions failed.
        // 被推迟的任务指搜索失败者，区别于结构性前置条件失败者。
        let mut deferred: Vec<TaskId> = Vec::new();
        let infeasible = infeasible_tasks(tasks, resources);

        for id in order.drain(..) {
            let task = tasks
                .iter()
                .find(|task| task.id == id)
                .expect("the order was built from the task list");

            if infeasible.contains(&id) {
                let reason = if !task.is_valid() {
                    "the task is not usable".to_string()
                } else {
                    format!("the resources cannot hold the demand of {id}")
                };
                set_state(
                    &mut states,
                    id,
                    TaskState::Infeasible {
                        reason: reason.clone(),
                    },
                );
                outcomes.push(PlanOutcome {
                    task: id,
                    state: TaskState::Infeasible { reason },
                });
                continue;
            }

            // A task may not start before the latest end among the tasks that
            // must precede it.
            // 任务的起点不得早于其前驱中最晚的结束时刻。
            let earliest = match self.precedence_floor(id, tasks, precedence, &schedule, &states) {
                Ok(floor) => floor,
                Err(reason) => {
                    set_state(&mut states, id, TaskState::Deferred);
                    outcomes.push(PlanOutcome {
                        task: id,
                        state: TaskState::Deferred,
                    });
                    let _ = reason;
                    deferred.push(id);
                    continue;
                }
            };

            // The task with the floor applied, so that the search respects
            // the constraints.
            // 施加该下界后的任务，使搜索遵从各约束。
            let constrained = match earliest {
                Some(floor) if floor > task.earliest_start => {
                    let mut copy = task.clone();
                    copy.earliest_start = floor;
                    copy
                }
                _ => task.clone(),
            };

            match earliest_feasible_start(&constrained, tasks, &schedule, resources) {
                Some(start) => match schedule.place(task, start) {
                    Ok(_) => {
                        set_state(&mut states, id, TaskState::Scheduled { start });
                        outcomes.push(PlanOutcome {
                            task: id,
                            state: TaskState::Scheduled { start },
                        });
                    }
                    Err(error) => {
                        let reason = error.to_string();
                        set_state(
                            &mut states,
                            id,
                            TaskState::Infeasible {
                                reason: reason.clone(),
                            },
                        );
                        outcomes.push(PlanOutcome {
                            task: id,
                            state: TaskState::Infeasible { reason },
                        });
                    }
                },
                None => {
                    set_state(&mut states, id, TaskState::Deferred);
                    outcomes.push(PlanOutcome {
                        task: id,
                        state: TaskState::Deferred,
                    });
                    deferred.push(id);
                }
            }
        }

        // The improvement pass runs only for a plan without precedence
        // constraints, for the reason given on `schedule_with_precedence`.
        // 改进轮只作用于无优先约束的计划，原因见
        // `schedule_with_precedence`。
        let improved = if precedence.is_some() {
            Vec::new()
        } else {
            let outcome = improve(
                tasks,
                resources,
                &deferred,
                &mut schedule,
                &mut states,
                self.improvement,
            );
            // The outcomes that the pass changed must be updated, and the
            // order of the outcomes follows the task list so that a caller
            // can index them by position.
            // 该轮改动的结果必须更新，且结果次序遵循任务列表，使调用
            // 方可按位置索引。
            for id in &outcome.placed {
                if let Some(slot) = outcomes.iter_mut().find(|entry| entry.task == *id) {
                    let start = schedule
                        .placement_of(*id)
                        .map_or(0.0, |placement| placement.start);
                    slot.state = TaskState::Scheduled { start };
                }
            }
            outcome.placed
        };

        // Reorder the outcomes to follow the task list, which is the order a
        // caller expects when it indexes by its own position.
        // 将结果重排为遵循任务列表，即调用方按自身位置索引时所期望的
        // 次序。
        outcomes.sort_by_key(|outcome| outcome.task.index());

        SchedulingResult {
            schedule,
            outcomes,
            improved,
        }
    }

    /// Returns the earliest start a task may have, given its predecessors.
    ///
    /// Returns `Ok(None)` when there is no constraint, `Ok(Some(t))` when the
    /// task may start no earlier than `t`, and `Err` when a predecessor was
    /// not placed, which makes the constraint unsatisfiable.
    ///
    /// 给定其前驱，返回某任务可有的最早起点。
    ///
    /// 无约束时返回 `Ok(None)`；任务起点不早于 `t` 时返回 `Ok(Some(t))`；
    /// 某前驱未被放置致使约束不可满足时返回 `Err`。
    fn precedence_floor(
        &self,
        id: TaskId,
        _tasks: &[Task],
        precedence: Option<&PrecedenceGraph>,
        schedule: &Schedule,
        states: &[TaskState],
    ) -> Result<Option<f64>, String> {
        let Some(graph) = precedence else {
            return Ok(None);
        };
        let mut floor: Option<f64> = None;
        for predecessor in graph.predecessors_of(id) {
            // A predecessor that was deferred or is infeasible cannot be
            // waited for.
            // 被推迟或不可行的前驱无从等待。
            let placed = schedule.placement_of(predecessor);
            let Some(placement) = placed else {
                let reason = match states.get(predecessor.index()) {
                    Some(TaskState::Infeasible { reason }) => reason.clone(),
                    _ => format!("{predecessor} was not placed"),
                };
                return Err(reason);
            };
            floor =
                Some(floor.map_or(placement.end(), |current: f64| current.max(placement.end())));
        }
        Ok(floor)
    }
}

/// Records the state of a task, ignoring an identifier outside the list.
///
/// 记录某任务的状态；标识符不在列表之内时忽略。
fn set_state(states: &mut [TaskState], id: TaskId, state: TaskState) {
    if let Some(slot) = states.get_mut(id.index()) {
        *slot = state;
    }
}