lucky-cat/docs/weather-lucky-color-model-command-ui.zh-CN.md

天气与幸运色 UI 指令接入说明

1. 背景与目标

对话模型使用与财位指令相同的注释 JSON 格式返回天气和喜色指令：

/*{"天气":"晴"}*/
/*{"喜色":"红"}*/

本次开发目标如下：

1. 识别并分发“天气”指令。天气 UI 素材尚未完成，本阶段只预留处理入口，不改变 LCD。
2. 识别“喜色”指令，并根据喜色确定性播放项目已有的五行 UI。
3. 保持原有按键触发五行 UI 时的随机行为不变。
4. 集中管理喜色映射，方便后续更换颜色或素材。

2. 问题原因

2.1 原模型指令不支持天气和喜色

原有指令契约只包含转向、校准和抽签。模型即使返回“天气”或“喜色”JSON，指令提取器也不会识别，指令无法进入现有模型命令队列。

2.2 原五行 UI 只能随机显示

项目已有完整的五行 UI 和金木水火土资源，但原逻辑通过随机数选择结果：

const domain_wuxing_result_t *result =
        &s_wuxing_results[esp_random() % result_count];

这适合原有随机五行功能，却不能满足喜色的确定性要求。例如模型返回“红”时，必须固定显示“火”，不能继续随机。

2.3 天气 UI 没有可播放资源

目前尚未确定天气类型、图片资源、播放时序和领域表达式映射。如果直接加入空的 LCD 表达式，可能因资源不存在而回退到基础表情。因此本阶段先打通解析和调度链路，明确保留未来 UI 接入位置。

3. 解决方式与具体代码

3.1 扩展模型指令类型

在原枚举末尾追加天气和幸运色，已有枚举值保持不变：

typedef enum {
    CONTROL_PLANE_MODEL_COMMAND_UNKNOWN = 0,
    CONTROL_PLANE_MODEL_COMMAND_DIRECTION,
    CONTROL_PLANE_MODEL_COMMAND_CALIBRATE,
    CONTROL_PLANE_MODEL_COMMAND_CHOUQIAN,
    CONTROL_PLANE_MODEL_COMMAND_WEATHER,
    CONTROL_PLANE_MODEL_COMMAND_LUCKY_COLOR,
} control_plane_model_command_type_t;

新指令继续复用原有回调、队列和模型命令工作任务，没有新增常驻任务。

3.2 解析天气与喜色

指令提取器仍要求注释 JSON 只有一个字段。新增字段读取和非空校验：

cJSON *weather = cJSON_GetObjectItemCaseSensitive(cmd_json, "天气");
cJSON *lucky_color = cJSON_GetObjectItemCaseSensitive(cmd_json, "喜色");

if (cJSON_IsString(weather) && weather->valuestring != NULL &&
    weather->valuestring[0] != '\0') {
    *out_command_type = CONTROL_PLANE_MODEL_COMMAND_WEATHER;
    strlcpy(out_value, weather->valuestring, out_value_capacity);
    found = true;
} else if (cJSON_IsString(lucky_color) && lucky_color->valuestring != NULL &&
           lucky_color->valuestring[0] != '\0') {
    *out_command_type = CONTROL_PLANE_MODEL_COMMAND_LUCKY_COLOR;
    strlcpy(out_value, lucky_color->valuestring, out_value_capacity);
    found = true;
}

支持的标准喜色指令为：

/*{"喜色":"绿"}*/
/*{"喜色":"红"}*/
/*{"喜色":"黄"}*/
/*{"喜色":"白"}*/
/*{"喜色":"蓝"}*/

3.3 为原五行 UI 增加可选的确定性结果

五行表达式属于领域层，因此在领域契约中声明五行元素：

typedef enum {
    DOMAIN_WUXING_ELEMENT_WATER = 0,
    DOMAIN_WUXING_ELEMENT_WOOD,
    DOMAIN_WUXING_ELEMENT_FIRE,
    DOMAIN_WUXING_ELEMENT_EARTH,
    DOMAIN_WUXING_ELEMENT_METAL,
    DOMAIN_WUXING_ELEMENT_COUNT,
} domain_wuxing_element_t;

统一表达式请求增加可选的五行字段：

typedef struct {
    domain_expression_id_t id;
    domain_expression_trigger_t trigger;
    size_t direction_index;
    size_t chouqian_result_index;
    bool chouqian_result_index_valid;
    domain_wuxing_element_t wuxing_element;
    bool wuxing_element_valid;
} domain_expression_request_t;

字段含义：

• wuxing_element_valid == false：继续随机选择五行，兼容原有调用。
• wuxing_element_valid == true：使用 wuxing_element 指定的结果。

3.4 复用原有五行资源和播放流程

本次没有复制五行素材，也没有新建第二套播放步骤。仍使用原资源表：

/* Keep this table ordered by domain_wuxing_element_t. */
static const domain_wuxing_result_t s_wuxing_results[] = {
    {.asset_dir = "shui", .icon_id = 0, .icon_x = 124, .icon_y = 8},
    {.asset_dir = "mu", .icon_id = 1, .icon_x = 217, .icon_y = 92},
    {.asset_dir = "huo", .icon_id = 2, .icon_x = 198, .icon_y = 171},
    {.asset_dir = "tu", .icon_id = 3, .icon_x = 46, .icon_y = 178},
    {.asset_dir = "jin", .icon_id = 4, .icon_x = 18, .icon_y = 102},
};

_Static_assert(sizeof(s_wuxing_results) / sizeof(s_wuxing_results[0]) ==
                       DOMAIN_WUXING_ELEMENT_COUNT,
               "Wuxing result assets must match domain_wuxing_element_t");

编译期断言保证五行枚举和资源表数量一致，防止后续修改导致静默错位。

原表达式只扩展结果选择方式，前置画面、图标合成、结果揭示和返回基础表情继续走原流程：

const size_t result_count =
        sizeof(s_wuxing_results) / sizeof(s_wuxing_results[0]);
size_t result_index = esp_random() % result_count;

if (request->wuxing_element_valid) {
    if ((size_t)request->wuxing_element >= result_count) {
        return ESP_ERR_INVALID_ARG;
    }
    result_index = (size_t)request->wuxing_element;
}

const domain_wuxing_result_t *result = &s_wuxing_results[result_index];

因此，原按键调用仍随机；喜色调用则固定显示指定元素。

3.5 集中管理喜色映射

当前映射关系如下：

喜色	五行 UI
绿	木
红	火
黄	土
白	金
蓝	水

代码将映射集中在一个表中：

typedef struct {
    const char *color_name;
    domain_wuxing_element_t element;
} control_plane_lucky_color_mapping_t;

/*
 * Lucky-color names are intentionally mapped in one place so product changes
 * can replace colors without touching model-command parsing or LCD playback.
 */
static const control_plane_lucky_color_mapping_t s_lucky_color_mappings[] = {
    {"绿", DOMAIN_WUXING_ELEMENT_WOOD},
    {"绿色", DOMAIN_WUXING_ELEMENT_WOOD},
    {"红", DOMAIN_WUXING_ELEMENT_FIRE},
    {"红色", DOMAIN_WUXING_ELEMENT_FIRE},
    {"黄", DOMAIN_WUXING_ELEMENT_EARTH},
    {"黄色", DOMAIN_WUXING_ELEMENT_EARTH},
    {"白", DOMAIN_WUXING_ELEMENT_METAL},
    {"白色", DOMAIN_WUXING_ELEMENT_METAL},
    {"蓝", DOMAIN_WUXING_ELEMENT_WATER},
    {"蓝色", DOMAIN_WUXING_ELEMENT_WATER},
};

映射查找代码：

static bool control_plane_resolve_lucky_color(
        const char *color_name,
        domain_wuxing_element_t *out_element)
{
    if (color_name == NULL || out_element == NULL) {
        return false;
    }

    for (size_t i = 0;
         i < sizeof(s_lucky_color_mappings) /
                 sizeof(s_lucky_color_mappings[0]);
         ++i) {
        if (strcmp(color_name, s_lucky_color_mappings[i].color_name) == 0) {
            *out_element = s_lucky_color_mappings[i].element;
            return true;
        }
    }
    return false;
}

映射成功后仍请求原有五行表达式：

const domain_expression_request_t request = {
    .id = DOMAIN_EXPRESSION_WUXING,
    .trigger = DOMAIN_EXPRESSION_TRIGGER_MODEL_LUCKY_COLOR,
    .wuxing_element = element,
    .wuxing_element_valid = true,
};

return domain_runtime_request_expression(&request);

3.6 预留天气 UI 接入点

天气指令到达模型命令工作任务后，目前仅记录指令值：

} else if (cmd.command_type == CONTROL_PLANE_MODEL_COMMAND_WEATHER) {
    /*
     * TODO: Request the weather LCD expression here after its assets
     * and domain expression mapping are available. Parsing and
     * dispatch stay active now to preserve the model-command contract.
     */
    ESP_LOGI(TAG,
             "Weather UI pending, received model command: %s",
             cmd.value);
}

天气素材完成后，只需补充领域表达式和此处的请求，不需要再次修改模型协议、解析器、回调或队列。

4. 解决成果

1. 设备能够识别 /*{"天气":"晴"}*/，并将天气值分发至工作任务。
2. 天气指令暂不切换 LCD，避免缺少资源时出现错误或回退画面。
3. 五种标准喜色能够固定显示对应的金、木、水、火、土 UI。
4. 喜色功能完整复用已有五行资源、图标坐标、播放步骤和 LCD 调度。
5. 原按键触发五行 UI 的随机行为保持不变。
6. 不支持的喜色不会随机显示错误结果，而是记录映射失败日志。
7. ESP-IDF 5.5.4 全量构建通过，固件镜像生成成功。

5. 后续影响

5.1 对现有功能的影响

• 财位、校准、抽签等已有模型指令的枚举值未改变。
• 表达式请求结构增加字段，但现有请求均使用指定字段初始化，新增字段默认置零。
• 原五行调用的 wuxing_element_valid 默认为 false，继续随机显示。
• 未新增 LCD 图片，不增加应用镜像中的素材占用。
• 未新增任务、队列或锁，不改变任务生命周期和并发模型。

5.2 当前限制

• 当前支持绿、红、黄、白、蓝五种喜色，同时兼容“绿色”“红色”等带“色”后缀的值。
• 天气值当前只校验为非空字符串，尚未限制为晴、阴、雨等固定枚举。
• 指令 JSON 仍要求只有一个字段，同时包含天气和喜色会被拒绝。
• 沿用原有单次模型命令分发机制，同一次模型响应中的后续指令不会重复触发。
• 当前完成了编译验证，尚未烧录设备进行 LCD 实机验收。

6. 后续开发方式

6.1 接入天气 UI

天气素材完成后按以下顺序开发：

1. 确定允许的天气值，例如晴、多云、阴、雨、雪。
2. 将天气 PNG 加入平台 LCD 资源目录和构建白名单。
3. 在平台资源表注册天气素材名称和帧序列。
4. 在领域表达式枚举中增加天气表达式语义。
5. 在领域适配器中将天气类型映射为平台播放请求。
6. 在天气命令分支中构造表达式请求，替换现有 TODO 占位。
7. 验证 UI 优先级、打断策略、播放时长和返回基础表情行为。

调用方向应保持为：

模型天气指令
    -> 控制层决定显示时机
    -> 领域层表达式请求
    -> 平台层 LCD 播放

控制层不应直接调用平台 LCD API。

6.2 修改或扩展喜色

如果只调整颜色与五行的关系，修改集中映射表即可。例如将绿色改为青色且仍对应木：

{"青", DOMAIN_WUXING_ELEMENT_WOOD},

如果要兼容颜色别名，可以将多个字符串映射到同一元素：

{"红", DOMAIN_WUXING_ELEMENT_FIRE},
{"红色", DOMAIN_WUXING_ELEMENT_FIRE},

如果未来幸运色需要独立于五行 UI，应新增领域表达式和独立资源映射，不应修改原有五行素材含义。

6.3 建议实机验证

烧录设备后至少测试：

/*{"天气":"晴"}*/
/*{"喜色":"绿"}*/
/*{"喜色":"红"}*/
/*{"喜色":"黄"}*/
/*{"喜色":"白"}*/
/*{"喜色":"蓝"}*/
/*{"喜色":"紫"}*/

预期结果：

• 天气“晴”只输出预留日志，不改变 LCD。
• 绿、红、黄、白、蓝分别显示木、火、土、金、水 UI。
• 不支持的“紫”不播放随机五行 UI，并输出失败日志。
• 喜色 UI 播放完成后正常返回基础表情。
• 原按键五行功能继续随机显示结果。