bagisto-change-verification

变更验证

Bagisto 的完成门槛。只有变更所涉及的每一道门槛都通过并汇报后，变更才算完成。这四道门槛对应 .github/workflows/ 中的五个测试工作流——E2E 分为 Admin 和 Shop 两项——因此，在本地通过这些检查的变更，也能通过流水线。

四道门槛

#	门槛	命令	适用条件
1	代码风格	vendor/bin/pint --test	有任何 .php 文件变更
2	测试	vendor/bin/pest	有任何 .php 文件变更
3	E2E	从包目录运行 npm run test:e2e	有任何视图、JS、CSS 或路由变更
4	翻译	php artisan bagisto:translations:check	有任何 Resources/lang/** 变更
5	命名	naming.md 中的 grep 命令	新增任何路由名称、翻译键或存储路径

按此顺序运行——代码风格检查只需几秒，E2E 需要几分钟，而 Pint 未通过会让其余检查失去意义。

1. 代码风格

vendor/bin/pint          # fix
vendor/bin/pint --test   # then confirm: CI runs this form

Pint 不会格式化 .blade.php。Blade 风格需手动处理——参见 bagisto-coding-standards 技能。

2. 测试

vendor/bin/pest                                        # everything
vendor/bin/pest packages/Webkul/Admin/tests/Feature    # one directory
vendor/bin/pest --testsuite="Admin Feature Test"       # one suite

测试套件定义在 phpunit.xml 中，每个包含测试的包对应一个套件。没有 tests/ 目录的包没有测试套件；如果为不存在的路径添加 <testsuite>，PHPUnit 会报错。

3. 端到端测试

Admin、Shop 和 Installer 是独立的 Playwright 项目。Node 依赖按包安装——根目录下没有 node_modules——因此只能从包目录运行：

cd packages/Webkul/Admin   # or Shop, or Installer

npm run typecheck                          # tsc over the suite — seconds
npm run test:e2e -- tests/<area>/<file>.spec.ts

CI 会在安装器任务通过后，针对 MySQL、MariaDB 和 PostgreSQL，各运行 Admin 和 Shop 测试，每项分为 10 个分片。本地运行时，请运行变更涉及的测试文件，而不是整个套件，并汇报运行了哪些文件。

在编写或调试测试之前，先加载 bagisto-playwright-testing。它负责故障分类，其中包括这样一条规则：一个分片或一种数据库驱动失败，并不能证明测试存在偶发性问题。

4. 翻译

php artisan bagisto:translations:check

每个键都必须存在于 Resources/lang/ 下的全部 23 种语言中。缺少任何一种语言都会导致工作流失败。

此检查器只扫描 packages/Webkul。 对于从其他位置安装的包——例如通过符号链接引入的扩展克隆——检查器不会读取其中任何语言文件，却会报告成功。如何验证这类包，以及如何从源文案中获取措辞而非凭空编造，请参见 translations.md。

5. 命名

路由名称使用 snake_case，翻译键使用 kebab-case，存储目录使用复数形式和 kebab-case。naming.md 中的 grep 命令可检查每一项；每个命令都应无输出。

安全检查点

这不是一道门槛——没有任何命令能给出“安全”的结果。在宣布工作完成前，必须回答以下问题：

此变更是否涉及授权、渲染输出、用户输入、上传、原始 SQL、机密信息或支付？

如果是，请加载 bagisto-coding-standards，并针对变更实际涉及的部分完成其中的检查清单。如果不是，请明确说明——“未涉及授权、输出或输入部分”——就像说明跳过了 Playwright 测试一样，不要对此保持沉默。

上述门槛无法回答这个问题。Pint 不会检查查询是否缺少作用域，而测试套件即使存在 IDOR 漏洞也照样会通过。

将变更归咎之前，先确认基线

Bagisto 的测试套件并非每次检出时都能全部通过。有些测试会断言绝对数量（meta.total），而带种子数据的安装环境不一定符合这些断言；此外，测试套件共用一个数据库，运行之间不会回滚，因此计数会发生变化。

未经对比，绝不要将失败数量报告为回归。 撤销变更，重新运行同一条命令，并对比失败测试的名称，而不是数量——运行命令见 baseline.md。差异为空，才是门槛通过的证据。

规则

• 未运行的门禁就是未通过的门禁。 必须逐项明确报告，包括本次差异未涉及的门禁：“没有视图或 JS 变更 — 跳过 Playwright”也是一种结果；保持沉默不算。
• 修复原因，而不是检查。 不要删除或跳过测试、放宽断言，也不要添加 Pint 排除项来让检查通过。
• 你没有造成的既有失败仍须报告，并提供证据证明它早于本次变更。
• 通过破坏修复来证明它有效。 修复 bug 时，撤销修复并观察新测试是否失败。如果测试在修复前后都通过，那它什么也保护不了——这是回归测试最常见的失效方式。
• 任何前端变更后都要重新构建资源，然后重新运行 E2E 门禁： cd packages/Webkul/<Admin|Shop> && npm run build。
• 验证期间不要提交或暂存，除非有人要求。

常见错误

• 只报告数量，不报告名称。 同一套测试运行两次，结果可能在代码未变的情况下有所不同；只有名称差异才有意义。
• 在整个仓库运行 Pint，然后报告别人的遗留问题。 限定范围：vendor/bin/pint --test <changed paths>。
• 只编辑 en 就声称翻译门禁已通过。 检查器会比对全部 23 种语言；只编辑一种语言却什么也不运行，是流水线变红的常见原因。
• 把翻译门禁通过当作扩展也已检查。 它只扫描 packages/Webkul。对于通过符号链接接入的扩展，检查器会报告成功，却没有读取其中任何一个语言文件——参见门禁 4。
• 因为“只是 Blade 变更”就跳过 E2E。 视图正是 E2E 门禁覆盖的内容。