STM32F4-Base/Drivers/BSP/UI/ui_page_action.c

/*
 * 模块名称：UI 动作确认页（操作页共享实现）实现
 * 模块功能：见 ui_page_action.h 头注释——本文件是那三个钩子的实现体：
 *           init 复位确认链、draw 画问句/态标/观测行/键提示四行、key 走状态机并
 *           只投递不阻塞。实例由页面跳板持有，本文件不再有模块单例，也不建描述符
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-10-25
 * 修改记录：
 *     v1.0  2026-10-25  王建锋  创建（道B task-5 三组件之一）
 *     v1.1  2026-10-26  DTU 项目组  道F task-3：删模块单例 s_act/s_desc 与
 *                                ui_page_action_open()（全仓零调用者），改出
 *                                ui_page_action_init/draw/key 三个收实例指针的
 *                                钩子；新增只读拒绝（need_modify → 态标 LOCK、
 *                                键提示 ESC=返回）与可选观测行（watch_label +
 *                                watch_cb）；返回值只留 uint8_t 分发标志
 */

/* 头文件包含区 */
#include <string.h>

#include "ui_page_action.h"

#include "ui_content_page.h"

#include "ui_tokens.h"

/* 私有宏定义区 */

#define AC_PROMPT_Y     44      /* 问句/结果行 放置 y（内容区上三分之一） */
#define AC_STAGE_Y      66      /* 态标行（"二次确认" / "ERR" / "LOCK"）放置 y */
#define AC_WATCH_Y      88      /* 可选观测行放置 y（实例没配观测行时这行留空） */
#define AC_HINT_Y       110     /* 键提示行 放置 y */

/* 固定文案（用字均已入字体子集：二/次/确/认/取/消/返/回/越/界 及 ASCII；
 * 道F task-3 起新增的"只读"两词沿用同一批用字，未扩字库） */
#define AC_STAGE2_TXT   "二次确认"
#define AC_HINT_DO      "ENTER=确认  ESC=取消"
#define AC_HINT_BACK    "ENTER=返回"
#define AC_HINT_RO      "ESC=返回"      /* 只读：ENTER 无效，提示必须跟着改口 */
#define AC_ERR_TXT      "ERR"
#define AC_RO_TXT       "LOCK"          /* 只读进入的态标（词表与整定保存行一致，
                                         都是 ASCII，见 UI_数据供给设计说明.md §6.3） */

/* 私有函数声明区 */

static void ac_draw_centered(lv_layer_t *a_layer, const char *a_text,
                             int32_t a_y, const lv_area_t *a_clip);

/* 函数定义区 */

/*
 * 函数功能：居中绘制单行文本（框架 cp_draw_centered_text 同法，本文件私有一致拷贝）
 * 入口参数：layer - 绘制层      lv_layer_t *
 *           text  - 文本（Flash 字面量）  const char *
 *           y     - 放置 y      int32_t
 *           clip  - 重绘区      const lv_area_t *
 * 返回值：无
 * 限定条件：text 非空；条带（整宽 x0..159，高 UI_TEXT_BAND_H）与 clip 相交才绘制
 */
static void ac_draw_centered(lv_layer_t *a_layer, const char *a_text,
                             int32_t a_y, const lv_area_t *a_clip) {
    lv_area_t t;
    lv_draw_label_dsc_t ld;

    /* 本 LVGL 版 lv_text_get_width：必须传 strlen（0 = 不测量返回 0，
     * 传 -1 越串尾死循环——框架同款注释警示） */
    t.x1 = 0;
    t.x2 = UI_SCREEN_W - 1;
    t.y1 = a_y;
    t.y2 = a_y + UI_TEXT_BAND_H;
    if (!((t.x1 <= a_clip->x2) && (a_clip->x1 <= t.x2) &&
          (t.y1 <= a_clip->y2) && (a_clip->y1 <= t.y2))) {
        return;    /* 不相交（culling） */
    }

    lv_draw_label_dsc_init(&ld);
    ld.base.layer = a_layer;
    ld.text = a_text;
    ld.text_static = 1u;    /* Flash 字面量：不拷内存 */
    ld.color = UI_COL_FG;
    ld.ofs_x = (UI_SCREEN_W -
                 (int32_t)lv_text_get_width(a_text, (uint32_t)strlen(a_text), LV_FONT_DEFAULT, 0)) / 2;
    ld.ofs_y = 0;
    lv_draw_label(a_layer, &ld, &t);
}

/*
 * 函数功能：开页复位确认链（框架 init_cb 的实现体）
 * 入口参数：a_inst - 操作页实例  ui_page_action_t *
 * 返回值：无
 * 限定条件：内容页框架开页链内调用（页面描述符的 init_cb 转发到此）
 * 函数说明：stage 每次进页归零是**判据**不是收尾清洁：上一轮按到"二次确认"就
 *          ESC 退出、下一轮进来看都不看再按 ENTER，如果 stage 跨次保留就直接
 *          执行了——破坏性动作不接受这种路径。err 一并清，否则上一次的投递
 *          失败会挂在新一页的态标行上（用户以为新页一进来就出错）
 */
void ui_page_action_init(ui_page_action_t *a_inst) {
    if (a_inst == NULL) {
        return;    /* 防御：跳板没填实例（编译期就该发现，运行期只保不崩） */
    }
    a_inst->stage = 0u;
    a_inst->err   = 0u;
}

/*
 * 函数功能：只读进入判定（本次开页是否"没有修改权限"）
 * 入口参数：a_inst - 操作页实例  const ui_page_action_t *
 * 返回值：1 = 本页需要修改权限而本次只有查看权限；0 = 其余  uint8_t
 * 限定条件：框架绘制/按键链内（开页时权限已装载，is_editable 读到的就是本次的）
 * 函数说明：判据只在这一处——绘制与按键两侧各自判一次，早晚在"屏上能按但按不动"
 *          这种半套状态上分家
 */
static uint8_t ui_page_action_is_readonly(const ui_page_action_t *a_inst) {
    if (a_inst->need_modify == 0u) {
        return 0u;
    }
    return (ui_content_page_is_editable() == false) ? 1u : 0u;
}

/*
 * 函数功能：自绘（框架内置区块之后：问句 / 态标 / 可选观测行 / 键提示，四行居中）
 * 入口参数：a_inst  - 操作页实例  ui_page_action_t *
 *           a_layer - 绘制层      lv_layer_t *
 *           a_clip  - 重绘区      const lv_area_t *
 * 返回值：无
 * 限定条件：经页面描述符 draw_cb 挂接；实例或 prompt 为 NULL 时空操作
 * 函数说明：行 2 的优先级是刻意的——只读(LOCK) > 二次确认 > 投递失败(ERR)：
 *          没权限时画"二次确认"会让人继续按，比不画更坏
 */
void ui_page_action_draw(ui_page_action_t *a_inst, lv_layer_t *a_layer,
                         const lv_area_t *a_clip) {
    if ((a_inst == NULL) || (a_inst->prompt == NULL)) {
        return;
    }

    /* 行 1：问句（stage 2 换成功结果行；done_text=NULL 时根本走不到 stage 2） */
    if (a_inst->stage == 2u) {
        if (a_inst->done_text != NULL) {
            ac_draw_centered(a_layer, a_inst->done_text, AC_PROMPT_Y, a_clip);
        }
    } else {
        ac_draw_centered(a_layer, a_inst->prompt, AC_PROMPT_Y, a_clip);
    }

    /* 行 2：态标（只读 / 二次确认 / 投递失败） */
    if (ui_page_action_is_readonly(a_inst) != 0u) {
        ac_draw_centered(a_layer, AC_RO_TXT, AC_STAGE_Y, a_clip);
    } else if (a_inst->stage == 1u) {
        ac_draw_centered(a_layer,
                         (a_inst->err != 0u) ? AC_ERR_TXT : AC_STAGE2_TXT,
                         AC_STAGE_Y, a_clip);
    } else {
        /* stage 0/2：这里没有要说的话——留空行比硬凑一个词诚实 */
    }

    /* 行 3：可选观测行（复归页用它把"保护动作 N"钉在确认同一屏上：
     * N 从 >0 变 0 就是"动作位真的复归了"的屏上证据，不用翻页也不用接表） */
    if ((a_inst->watch_label != NULL) && (a_inst->watch_cb != NULL)) {
        char watch[UI_BUF_STRLEN];

        (void)lv_snprintf(watch, sizeof(watch), "%s %u", a_inst->watch_label,
                          (unsigned int)a_inst->watch_cb());
        /* 观测行是拼出来的栈串，不是 Flash 字面量：本函数同帧内绘制完即弃 */
        ac_draw_centered(a_layer, watch, AC_WATCH_Y, a_clip);
    }

    /* 行 4：键提示（只读时 ENTER 无效，提示必须跟着改口——屏上说"ENTER=确认"
     * 而按下去没反应，是现场投诉最多的"设备坏了"误判来源） */
    if (ui_page_action_is_readonly(a_inst) != 0u) {
        ac_draw_centered(a_layer, AC_HINT_RO, AC_HINT_Y, a_clip);
    } else {
        ac_draw_centered(a_layer,
                         (a_inst->stage == 2u) ? AC_HINT_BACK : AC_HINT_DO,
                         AC_HINT_Y, a_clip);
    }
}

/*
 * 函数功能：按键处理（确认链状态机；框架 key_cb 的实现体）
 * 入口参数：a_inst - 操作页实例  ui_page_action_t *
 *           a_key  - LVGL 键值   lv_key_t
 * 返回值：1 = 已消费（框架跳过内置语义）；0 = 未消费（其余键交回框架）
 *                  （键分发标志非错误通道，取 uint8_t——bsp-err/err-type）
 * 限定条件：经页面描述符 key_cb 挂接；LEFT/ESC 不进本函数（框架恒关页 = 取消，
 *           这是"任何一页都退得出去"的框架保证，本组件不得拦截）
 * 函数说明：ENTER——stage0 转二次确认；stage1 调 ok_cb 投递：受理且有 done_text
 *          转 stage2 回报、受理且无 done_text 直接关页、拒收置 err 留在 stage1
 *          （再 ENTER 重走一次投递，不自动重试：连点两次就投两次，
 *          清除记录这类动作要的是"我确实在两下之内只发了一次"）；
 *          stage2 关页返回——回报行必须让用户自己确认看到了才走，
 *          成功即关页的形态只在 done_text=NULL（没什么可回报的）时才成立。
 *          只读进入：先放行 stage2 的返回支（已完成的页总得关得掉），
 *          其余 ENTER 一律消费但不推进、不投递
 */
uint8_t ui_page_action_key(ui_page_action_t *a_inst, lv_key_t a_key) {
    bool ok = false;

    if ((a_inst == NULL) || (a_inst->ok_cb == NULL)) {
        return 0u;    /* 防御：配置不全的实例不该出现在这里 */
    }
    if (a_key != LV_KEY_ENTER) {
        return 0u;
    }

    if (a_inst->stage == 2u) {
        ui_content_page_close();
        return 1u;    /* 已回报：ENTER = 收页回菜单 */
    }

    if (ui_page_action_is_readonly(a_inst) != 0u) {
        return 1u;    /* 只读：吃掉按键，态标行已在说 LOCK，不做任何动作 */
    }

    if (a_inst->stage == 0u) {
        a_inst->stage = 1u;
        a_inst->err   = 0u;
        ui_content_page_invalidate();
        return 1u;
    }

    /* stage 1：第二次 ENTER = 真执行（只投递，不等执行结果） */
    ok = a_inst->ok_cb();
    if (!ok) {
        a_inst->err = 1u;
        ui_content_page_invalidate();
        return 1u;    /* ERR 显示，下一次 ENTER 重新走投递 */
    }
    if (a_inst->done_text == NULL) {
        ui_content_page_close();    /* 成功即关页（无回报行形态） */
        return 1u;
    }
    a_inst->stage = 2u;
    a_inst->err   = 0u;
    ui_content_page_invalidate();
    return 1u;
}