卡片判决
classifyCardActionError、cardStateFromSubmit、formAnswersBody:卡片提交的失败判决、落定记录与表单答案请求体。
卡片判决
卡片提交(业务卡动作、选择卡落定、统一提交 POST /api/v1/messages/{id}/card-interactions)用到的三个纯函数:失败怎么判、成功的返回怎么拼成落定记录、表单卡的答案怎么写进请求体。自己写宿主接 OpenMax 时用它们,判法与发出去的东西就和 SDK 一致。状态和全部导出的索引见概览。
失败判决
判决用的是 @openmaxai/chat 契约的词汇:kind 就是 ChatCardActionResult 失败那一支的 kind,文案由各端按 kind 自己映射,这里不出文案。
| 输入 | kind |
stage |
换键 | 失效业务面 |
|---|---|---|---|---|
code 是 network 或 timeout(不看状态) |
unavailable |
transport |
否 | 是 |
COMM_CARD_IDEMPOTENCY_KEY_REUSED |
idempotency-key-reused |
parse |
是 | 否 |
COMM_CARD_OPERATION_RETIRED / COMM_CARD_SUPERSEDED / COMM_CARD_INTERACTION_WINDOW_EXPIRED |
operation-retired / superseded / window-expired |
parse |
否 | 否 |
其余 COMM_ 开头的码 |
按状态(见下) | parse |
否 | 否 |
没有 COMM_ 码,状态是 0 或 5xx |
unavailable |
transport |
否 | 是 |
WORK_ISSUE_ACCEPTANCE_FORBIDDEN |
business-forbidden |
business |
否 | 是 |
| 其余的码 | 按状态 | business |
否 | 是 |
| 没有码(或空串) | 按状态 | unknown |
否 | 否 |
按状态:0 与 5xx 是 unavailable,400 action-invalid,403 forbidden,404 not-found,409 conflict,412 precondition,429 rate-limited,其余 unknown。
分支靠错误码、不靠状态码:两侧的 403、409、412 语义不同(412 同时被「消息已撤回」和「Issue 不在待确认状态」占用)。唯一该换幂等键的是指纹不符那一个码;网络错误、超时、业务拒绝都留着原键,换新键会绕过业务侧去重。
401、状态 0、5xx 在这里只是一档判决,不区分凭据失效与传输失败。要让凭据失效走到 onUnauthorized,调用前自己分流。
classifyCardActionError
function classifyCardActionError(error: {
status: number;
code?: string;
field?: string;
detail?: string;
}): OpenMaxCardErrorVerdict;
一次卡片提交失败的状态与错误码 ⇒ 判决,规则见上表。不是 HTTP 失败的异常(代码缺陷、被中止的请求)没有状态可分,由调用方自己处理。
OpenMaxCardErrorVerdict
interface OpenMaxCardErrorVerdict {
kind: ChatCardActionErrorKind;
stage: OpenMaxCardErrorStage;
resetIdempotencyKey: boolean;
businessMayHaveChanged: boolean;
formError?: ChatCardFormError;
}
classifyCardActionError 的返回值。kind 与 resetIdempotencyKey 原样就是契约判决 { ok: false, kind, resetIdempotencyKey };businessMayHaveChanged 为真时,该失效这张卡 operation 关联的业务数据。表单卡按内容被拒(COMM_CARD_FORM_*)时另带 formError:哪类错、哪道题(取自错误信封的 field 路径)、被过滤时服务端的拒绝文案(取自 detail),原样放进契约判决。
OpenMaxCardErrorStage
type OpenMaxCardErrorStage =
| "parse"
| "business"
| "transport"
| "unknown";
失败发生在哪一跳:parse 是服务端的解析跳(业务没被调用过),business 是业务服务判定,transport 是传输层与 5xx(客户端报错而业务已经做成是这条链的常态,所以也当作业务面可能已变),unknown 是没有可分支的码。
cardStateFromSubmit
function cardStateFromSubmit(result: OpenMaxCardSubmitResult | undefined, input: {
interactionType: "choice";
} | {
interactionType: "form";
} | {
interactionType: "action";
actionId: string;
}, currentMemberId: string | undefined): OpenMaxCardStateRecord | null;
用提交接口的返回拼出这张卡的落定记录;拼不全就返回 null,调用方改为重读那条消息:
replayed不是false(重试,或别人先答了)或缺result_at:返回null。- choice:恰好一个选中项、且给了
currentMemberId时,action_id是那一项、答题人是当前成员。 - action:给了
currentMemberId时,action_id优先取返回里的,没有就用点的那一个;答题人是当前成员。 - form:返回里
actor_id与answers都在时,action_id是form_submit,答案放进form_answers;缺任一就返回null,不渲染半截清单。
OpenMaxCardSubmitResult
interface OpenMaxCardSubmitResult {
interaction_id: string;
interaction_type: "choice" | "form" | "action";
change_seq: number;
card_sender?: {
kind: string;
member_id: string;
};
replayed: boolean;
result_at: string;
status: string;
action_id?: string;
actor_id?: string;
answers?: {
[key: string]: OpenMaxCardFormAnswerRecord;
};
selected_action_ids?: string[] | null;
}
提交接口(POST /api/v1/messages/{id}/card-interactions)返回的 data,与后端契约同形;返回可以直接传给 cardStateFromSubmit。
OpenMaxCardStateRecord
interface OpenMaxCardStateRecord {
action_id: string;
actor_id: string;
form_answers?: {
[key: string]: OpenMaxCardFormAnswerRecord;
};
result_at: string;
status: string;
}
一张卡的落定记录,与消息上的 card_state 同形;cardStateFromSubmit 返回的就是它。
OpenMaxCardFormAnswerRecord
interface OpenMaxCardFormAnswerRecord {
selected_option_ids: string[] | null;
other_text?: string;
text?: string;
}
表单卡一道题的落定答案:提交返回里 answers、落定记录里 form_answers 的值。
formAnswersBody
function formAnswersBody(answers: Readonly<Record<string, ChatCardFormAnswer>>): Record<string, {
selected_option_ids?: string[];
other_text?: string;
text?: string;
}>;
表单卡的答案 ⇒ 请求体里的 form.answers,字段名换成 snake_case、每个字段只在给了时带:selectedOptionIds 换成 selected_option_ids;otherText 换成 other_text,空串也带(勾了「其他」没写说明不等于没勾);填空题的 text 带成 text,不带 selected_option_ids(服务端对填空题带选项 id 判错)。
