# 管理工单错误、异步状态与环境

| 阶段 | 错误形态或边界 |
| --- | --- |
| 认证 | 字符串 code/msg；X-API-Key 不适用。401/403/503/500须按实际身份阶段处理。 |
| 列表参数、PATCH解码 | HTTP400，数字code:2与message；不统一改成ErrParamInvalid。 |
| service失败 | code/msg/data:null；文本一般本地化，404/400/409/503等按各错误分类。 |
| 标题/正文校验 | writeTextFieldError先匹配，422/ErrFieldRequired或ErrFieldTooLong；details.field、reason，超长另有字符串limit、actual、unit:unicode_code_point。不回显原正文。 |
| 请求decoder | 当前普通Decode不等于严格拒绝未知键/尾随JSON/重复键，也没有在这些handler中统一设置body大小上限。 |

GitHub最终标题最多256码点、正文65536码点；创建规范化包括移除旧标记、去空白及补当前标记，限额包含最终标记。bug/feature生成标题含前缀，长度也算前缀；auto生成时对事实截断并标记，不推广成任意提交自动截断。

草稿模板会做当前规则的敏感检测与替换，创建请求会重新检测并拒绝命中内容。类别列表不是完整隐私保证；不能因为sensitive_findings为空就直接向外发布。草稿也不证明部署已配置外部创建服务。

## 奖励审批

审批事务锁定工单，校验已存UC主体，按需更新工单并复用或新建唯一事件；不接收金额。提交后另调用详情读取，目录或读取失败可在已提交后返回错误；先GET详情确认reward_event和工单状态，不因HTTP错误就重发。重复调用复用旧审批者和事件，但仍可修改请求中携带的status/admin_reply。

pending只表示等待消费；审批不可当可撤销的普通配置；没有这些接口撤销或删除事件接口。

## GitHub创建

有效输入先校验，再检查本地状态。created复用主Issue，pending/creating返回冲突，failed必须显式retry，重试冻结新内容并生成新request_id。retry不等于通用幂等键，接口不接收调用者提供的request_id。一个工单的主Issue不等于可任意多次创建。

新入队先准备部署工作区负责人和有效角色，再加锁重查并持久化请求及事件，202时不执行同步外部创建。后台执行仍复查冻结身份/角色与载荷；实际状态由GET管理工单中的github_issue回查。created需有issue_number/issue_url，failed看last_error_code；当前没有这些接口专用取消、删除或按request_id查询接口。

已取得外部创建回执而本地保存失败时，不能仅凭超时/HTTP错误认定未创建；需要负责人核对关联回执及执行记录，避免盲目重复。后续独立triage不应抹掉已创建回执；
