hyk260 API 路由可读性审查
把 src/app/api/**/route.ts 里「能跑但难扫读」的分支改成一眼能跟的 handler。默认只报告；用户确认后再改。
UI / JSX / className 走 code-readability-review。本 skill 只覆盖 API handler。
改写示例与 before/after 见 references/patterns.md。遇到嵌套三元、有序守卫、枚举→文案时先读该文件。
工作流
- 审查（默认）：扫描目标文件/选区，按下方规则出 findings。不改文件。
- 等确认：用户说「改吧」「按建议改」等明确同意后，再进入重构。
- 重构：按 findings 最小 diff 落地；只动书写风格，不改行为。
- 收尾：简述改了哪些点；若某处刻意保留（如单层短三元），说明原因。
本仓库惯例
规范来自现有 src/app/api/ 写法，不发明新架构。
- 正例（early return）：
src/app/api/channels/wechat/webhook/[applicationId]/route.ts、src/app/api/channels/wechat/bind/route.ts— 鉴权 / 校验 / 404 先退出，主路径不缩进。 - 正例（JSDoc）：
METHOD /api/...一行路径 + 一行用途；请求体用@param request。 - 命名布尔：复杂条件先赋名（如
waitingForFirstHeartbeat），再参与分支。 - Helper 留在同文件；不为「风格统一」抽跨文件工具。
规则优先级
P0 — 必查
| 模式 | 判定 | 首选改写 |
|---|---|---|
嵌套三元（≥2 层 ? :） |
有序守卫（rebind → gateway → 心跳 → …） | 同文件小函数 + early return，短路顺序不变 |
嵌套三元（≥2 层 ? :） |
离散枚举 → 文案 | Record lookup + fallback |
P1 — 建议查
| 模式 | 首选改写 |
|---|---|
| 过长单行条件 | 折行或提到命名布尔 |
| JSDoc 路径被拆成多行、缺用途 | METHOD /path + 一行说明 |
| 响应对象里塞多层表达式 | 先算命名变量再放入 JSON |
| 可 early return 仍用大 if/else | 扁平守卫 return |
明确不做
- 改
jsonErrorvsNextResponse.json、withAuthvs 裸export async function - 改响应字段名、字段顺序、HTTP status、文案
- 改短路语义（守卫顺序必须与原三元一致）
- 单层短三元：
error instanceof Error ? message : fallback、x?.toISOString() ?? null、lastErrorCode ? { code, message } : null - 纯偏好（引号风格、无关命名争论）
审查输出模板
## API 路由可读性审查
### 摘要
- N 处建议处理（P0: x / P1: y）
### Findings
1. **[P0] 嵌套三元 → early return** — `path:line`
- 现状：简述
- 建议：给出 5–15 行目标代码片段
2. ...
### 下一步
确认后我可以按上述建议直接改文件（最小 diff，不改行为）。
重构约束
- 行为不变：短路顺序、返回值、HTTP status、文案一致。
- 提取的 helper 放在同文件、默认不 export。
- 单层、两侧都很短的三元可以保留。
- 跑该 route 已有测试；不为风格改写补行为用例。