进度条数值必须经模型层拦截校验限幅语义化，getProgressAttr需强制截断为0–100并兜底类型，配合status字段协同判断状态，接口响应须固定包含status、progress、message三字段。
直接用状态码（如 0、30、100）当进度条数值是可行的，但不能裸露返回——它必须经过模型层统一拦截、校验、限幅和语义化，否则前端轮询时会看到跳变、负数、超 100 值，甚至空字段崩溃。
getProgressAttr 必须做 min/max 截断和类型兜底
状态码字段（比如数据库存的是 progress 整型）在前端展示前，得强制落在 0–100 范围内。不加限制的话，任务异常中断可能写入 -1，或并发更新导致写入 120，JS 的 Math.min(Math.max(val, 0), 100) 不该由前端承担。
-
getProgressAttr方法里第一行就该写：return (int) min(max($value ?? 0, 0), 100); - 别依赖
$value一定为数字：Redis 缓存未初始化时可能是null，数据库字段允许为NULL时也会传进来null - 不要在
getProgressAttr里查数据库或调用远程接口——访问器需轻量、无副作用，否则toArray()性能崩盘
状态码 ≠ 进度，需配合 status 字段协同判断
仅靠 progress 数值无法区分「正在跑」和「卡死在 80%」。真实场景中，你必须同时暴露 status 字段（如 'running'、'failed'、'success'），且两者逻辑要对齐：
- 当
progress === 100时，status应为'success'或'failed'，绝不能还是'running' - 当
status === 'failed'时，progress可为任意值（包括0），但前端应忽略进度条、只显示错误提示 - 建议在模型里定义
getStatusAttr，根据progress和失败标记字段（如error_message）自动推导，避免前端重复判断逻辑
前端轮询时别只读 progress，要检查整个响应结构
ThinkPHP 接口返回的 JSON 必须固定含 status、progress、message 三字段，哪怕 progress 是通过 getProgressAttr 吐出来的。否则前端 JS 解构时容易因字段缺失报错：
立即学习“PHP免费学习笔记（深入）”；
{"status":"running","progress":75,"message":""}
- 不要返回
{"progress": 75}这种极简结构——它没留扩展余地，下次加个estimated_time就得改所有前端代码 - 后端控制器里统一用
json(['status' => $model->status, 'progress' => $model->progress, 'message' => $model->message])，别手动拼数组 - 若
message来自error_message字段，记得在getMessageAttr里判空：return $value ?: '';，防止前端拿到null
最易被忽略的一点：访问器只在模型属性被读取时触发，如果你在控制器里写 $data = $model->toArray(); echo $data['progress'];，那 getProgressAttr 已经执行过了；但如果你写 $model->getData('progress')，就绕过了访问器，直接拿原始值——进度条逻辑瞬间失效。
