review-order

审查顺序

参数

原始参数：$ARGUMENTS

将参数解析为要比较的基准分支。如果为空，默认使用 main。

目标

生成一份便于浏览的变更索引，概述基准分支与 HEAD 之间的变更，按功能分组，并在每个功能内遵循四步审查顺序（类型 → 数据流 → 业务逻辑 → 边界情况）。

用户会先阅读这份索引，然后自行查看代码。因此每条要点都必须包含 文件:行号，以便他们直接点击。文字尽量精简——每条要点只用一个简短分句。把它当作索引，而不是长篇说明。

不要执行审查。不要提出建议。不要指出任何需要验证、确认、复核或考虑的事项。不要建议测试、修复或改进。不要询问“这是预期行为吗？”或“这样安全吗？”。

你的工作纯粹是描述：列出类型，指出数据流向，说明逻辑功能，并指出边界情况涉及的位置。用户自行阅读索引并决定要检查什么。

审查顺序（结构说明）

大多数人会从头到尾阅读差异。这会遗漏一些内容。用户会在每个功能内部按以下顺序阅读：

1. 先看类型和接口。 描述代码预期接收和生成的数据结构。
2. 再看数据流。 跟踪数据的输入、转换和输出位置。
3. 然后看业务逻辑。 说明代码的功能——方法、保护条件、分支。
4. 最后看边界情况。 指出边界情况涉及的位置（分支、可空值、外部输入、并发路径、队列上下文假设）。只需说明位置和其构成边界情况的原因，不要提供建议。

你的工作是让用户能轻松地按每个功能的顺序阅读，而不是把所有内容混成四个全局分类。

说明

1. 获取差异

运行 git diff <base>...HEAD（三点语法，即显示此分支自分叉以来的变更）查看变更内容。另运行 git diff --name-status <base>...HEAD 快速了解文件级变更概况。如果没有变更，告知用户并停止。

2. 阅读变更文件

阅读每个变更文件的足够内容（仅在理解数据流所需时阅读周边文件），以便进行分类。

跳过自动生成的文件，除非其中包含异常内容：

• 锁文件（composer.lock、package-lock.json、pnpm-lock.yaml 等）
• 编译后的资源（public/build/、dist/）
• 生成的路由/类型定义（例如 Wayfinder action/route 文件、生成的 TS 类型）

3. 识别功能变更

将差异按此分支引入的不同用户可见变更或行为变更分组。功能是一个连贯的行为单元，而不是一个文件或一层代码。以下是划分示例：

• “通过签名链接取消订阅”——控制器、路由、blade 取消订阅 CTA、页面、测试
• “创建想法时自动订阅”——观察器钩子、迁移中的关联使用、测试
• “状态变更时通知订阅者”——观察器、通知类、邮件模板

识别功能时可参考以下经验：

• 新模型/迁移通常至少对应一个功能（即它所代表的内容）。
• 新路由 + 控制器 + 页面几乎总是一个功能。
• 新通知类 + 其触发器（观察器/事件）+ 邮件模板通常是一个功能。
• 对现有流程添加副作用（例如“投票现在也会订阅你”）应作为单独的小功能。
• 不影响行为的纯重构可作为最后一个“重构”功能分组。

如果此分支确实只有一个功能，则输出一个功能标题。不要为了拆分而强行拆分。

4. 输出映射

仅返回 Markdown 文档。不要写前言，也不要在结尾添加总结。按重要性／影响范围大致排列功能（先写身份验证／安全，最后写重构）。

语气。 使用项目符号，不要写段落。每个项目符号的格式为 path/to/file.ext:LINE — 简短说明。说明用通俗语言指出该处内容；file:line 是用户点击后跳转的位置。每个项目符号单独一行。不要写多句解释。想象这是带有便于阅读的说明的 git grep 输出，而不是代码审查。

使用以下结构：

## Feature: [short name of the change]

One sentence describing what behaviour this introduces or changes.

### 1. Types & Interfaces
- `path/file.php:12` — what's there (e.g. "new `subscribers` BelongsToMany on `Idea`")
- `path/migration.php:14` — `idea_subscribers` table, unique on `(idea_id, user_id)`

### 2. Data Flow
- `path/controller.php:23` — entry: `POST /x` → invokable
- `path/observer.php:18` — fan-out: queries subscribers, dispatches notification
- `path/notification.php:30` — exit: queued mail via `mail.foo` template

### 3. Business Logic
- `path/observer.php:22` — short-circuit on `is_internal`
- `path/observer.php:28` — actor-exclusion gate
- `path/controller.php:14` — `detach` runs unconditionally on bound pair

### 4. Edge Cases
- `path/observer.php:25` — `Auth::id()` is null in queue/console contexts
- `path/controller.php:14` — public route, no auth check, signed URL has no expiry

---

## Feature: [next change]

...

如果某个部分没有有意义的内容，就省略。小型功能可能只需要 Logic + Edges。

规则

• 每个项目符号都必须包含 file:line。 这正是重点——用户可以点击跳转。没有引用的项目符号一律不写。如果确实需要说明没有具体行号的内容（功能级备注），请放在功能标题下的一句话简介中，而不是项目符号里。
• 每个项目符号只写一个简短分句。 破折号后尽量控制在约 15 个词以内。写得更长就成了审查意见，而不是映射。可以拆成两个不同位置的项目符号，或删减内容。
• 不要给建议、忠告或提问。 禁止使用以下说法：“verify that…（验证……）”、“confirm…（确认……）”、“make sure…（确保……）”、“consider…（考虑……）”、“check whether…（检查是否……）”、“is this intended?（这是有意的吗？）”、“is this safe?（这样安全吗？）”、“should we…（我们是否应该……）”、“could…（能否……）”、“might want to…（或许可以……）”。只陈述事实。
• 不要使用表情符号。 如果涉及安全敏感内容，请在功能简介中用文字说明，不要加装饰。
• 描述事实，而非提出要求。 “detach 无条件作用于绑定对”是合适的。“确认 detach 无条件运行是否安全”不合适。
• 边缘情况应指出涉及的场景，而不是给出修复方案。 例如：可空输入、未设防的分支、外部状态、队列上下文假设、并发路径。不要告诉审查者该怎么处理。
• 按功能分组，而不是按审查轮次分组。 每个功能内部都按相同顺序列出四轮内容。
• 如果某个功能中没有内容符合某一轮，就省略该轮。 不要用填充内容凑数。
• 跳过自动生成的文件（锁文件、编译产物、生成的路由／类型定义），除非其中包含异常内容。
• 按影响范围排列功能：先写安全／身份验证相关内容，再写面向用户的行为，最后写内部／重构内容。在功能简介中标明敏感场景。
• 同一个文件可以出现在多个功能下（例如，某个控制器新增了两个不相关的端点）。在同一功能中，同一行只能出现一次——选择最合适的分类。