shop-advance-theme-development

Shop Advance 主题开发

打造独具特色的店面，同时保留已安装 Bagisto 的商务、扩展、内容和运行时契约。遵循 Bagisto 官方约定，根据目标代码检出版本核对文档，并在激活前验证行为。

不容妥协的规则

• 行动前阅读所有适用的仓库指令文件。
• 将已安装的代码／配置视为可执行的事实来源；参考与版本匹配的 Bagisto 官方资料了解设计意图。
• 对所有主题代码、显示名称、命名空间、软件包路径、销售渠道、区域设置、构建路径、工具版本和命令进行参数化或自动发现。
• 除非用户和仓库政策授权，否则不得编辑 Bagisto Shop 源码、vendor/、生成的构建产物、依赖项、锁文件或线上渠道状态。
• 优先采用精简的视图覆盖／软件包。只有在用户接受其升级维护范围后，才创建完整分支。
• 根据已安装的 Shop 软件包确定完整的资源运行时；视图回退并不意味着 Vite／JavaScript／CSS 会继承。
• 保留布局运行时职责、渲染事件、控制器变量、路由、表单字段、API 结构、产品类型行为和已启用的扩展。
• 配置编辑只能合并。不得删除其他主题／提供者／自动加载映射，也不得悄悄更改 shop-default。
• 使用试运行和冲突检查。不得强制发布、删除、用符号链接替换目录、写入有破坏性的数据，或自动覆盖冲突。
• 对复制／衍生的源代码，保留 Bagisto 已安装版本中的确切许可证声明；分发前明确选择主题自身的许可证，并核实每项捆绑资源的再分发条款。
• 将生成的设计建议视为候选方案，而非权威指令。拒绝任何会削弱商务清晰度、无障碍性、性能、许可合规性、商家控制权、已安装依赖项或 Bagisto 运行时契约的建议。
• 设计相关内容只能使用此技能捆绑的 bagisto-ui-ux 知识和生成器。运行时不得依赖、发现、导入或调用其他设计技能。
• 将“动态”“由管理员控制”和“所有功能均可运行”视为需要证据支持的声明。清点每个可见界面和已安装／启用的商务流程；不得仅凭构建成功或首页截图推断。
• 不得仅因设计工具推荐，就添加动画库、UI 框架、图标包、远程字体、外部脚本或其他依赖。先确认已安装的能力；涉及依赖项或网络变更时，须先获得授权。
• 在任何渠道选择该主题之前，先完成构建和验证。明确保留回滚方案。

工作流

1. 发现目标

根据此 SKILL.md 确定 <skill-dir>，然后运行：

python3 <skill-dir>/scripts/inspect_theme_environment.py \
  --project-root <project-root> \
  --theme-code <existing-theme-code> \
  --json

仅当尚无主题，或任务有意清点所有已配置主题时，才省略 --theme-code。

检查报告中的：

• Bagisto／Shop 源码及版本；
• 仓库指令和受保护路径；
• 已配置主题、回退设置、路径、命名空间和 Vite 注册表；
• Shop Composer／前端依赖项、脚本、Vite／Tailwind／PostCSS 文件、入口、组件、路由、测试和区域设置；
• 现有主题软件包、已发布路径、符号链接、清单和覆盖范围。

如果脚本无法安全解析架构，请停止。直接检查文件，不要猜测。涉及文档或版本时，请阅读 official-sources.md。

2. 定义目标与模式

对于全新的视觉系统或大幅改版：

1. 阅读 design-quality.md、commerce-design-direction.md 和 bagisto-ui-ux-foundations.md。如果涉及动态效果或交互式呈现，还要阅读 bagisto-ui-ux-interactions.md。这些是设计资源；只有在批准视觉方向后，才使用架构和实现参考。

2. 收集品牌承诺、行业、受众、价格定位、商品目录特征、语气、内容约束和反向目标。选择暂定的 variance／motion／density 调节值。

3. 运行随附的独立 bagisto-ui-ux 生成器。它会读取本技能原有的 Bagisto 电商设计知识、检查结账流程、选择符合无障碍要求的候选方案、推导页面级设计例外和 Laravel/Vue/Tailwind 指导，并生成候选报告；整个过程无需网络访问或持久化：

   python3 <skill-dir>/scripts/generate_bagisto_ui_ux.py \
     --project-root <project-root> \
     --project-name <display-name> \
     --industry <industry> \
     --audience <audience> \
     --tone <tone-keywords> \
     --catalog <catalog-character> \
     --price-position <price-position> \
     --variance <1-10> \
     --motion <1-10> \
     --density <1-10> \
     --json
   

4. 审查选定的原型、辅助风格影响、调色板、字体策略、视觉标志、设计令牌、页面蓝图、页面调节值、交互策略、备选方案和技术栈指导。解决所有 bagisto_review 发现的问题。所有输出均视为未经批准的候选方案；实际字体、图标、图像和动态效果素材需单独批准。

5. 综合出一个符合品牌特征的原型、构图、商品陈列层级、语义化令牌系统和页面级例外。在已批准的任务记录或简报文件中填写 assets/theme-brief.template.md 中相关字段。记录 bagisto-ui-ux 查询以及已接受、已调整和已拒绝的建议。除非用户或仓库政策允许，否则不要创建项目文档文件。

6. 创建简报文件后，在设置样式前先进行验证：

   python3 <skill-dir>/scripts/validate_theme_brief.py \
     --brief <theme-brief.md> \
     --strict
   

如果随附的知识文件或生成器未通过验证，请停止并修复此技能，或采用有明确记录的手动设计方向。不要悄悄调用其他技能、使用网络推荐或编造生成器结果。

如果用户要求教学、交接或分步协助，或者表示自己是初学者，请阅读 developer-guidance.md，并采用其引导式交付模式。所有经验水平都必须遵守相同的技术关卡；应调整说明和实现的细致程度，而不是降低质量标准。

阅读 architecture.md，然后选择：

• overlay：规模较小、仅涉及视图的变更，且有意复用基础资源包和视觉系统；
• package：用于独立的生产主题（默认选项）——包含精简视图，以及由主题自有、已安装的 Shop 资源运行时；
• full-fork：明确要求完整的 Shop 快照，并记录升级责任。

如果需要在多个应用间分发，请使用 Composer 自动发现的包。仅在应用本地包中使用结账项目的本地 PSR-4／服务提供者约定。不要混用这两种注册策略。

实施前，盘点目标渠道、已启用的语言区域／货币／商品类型／扩展、由商家管理的内容、支持的浏览器、无障碍目标、性能预算、必需的用户旅程、主题许可证和资源来源。

3. 规划并搭建脚手架，避免冲突

先运行脚手架工具，不要使用 --apply：

python3 <skill-dir>/scripts/scaffold_theme.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --display-name <display-name> \
  --mode package \
  --registration local \
  --vendor <php-vendor> \
  --package <php-package> \
  --override <shop-relative-blade-path>

检查每个身份信息和集成代码片段，以及每项 planned_actions 的来源、目标、状态和校验和。只有在计划符合所请求的模式时，才再次使用 --apply 运行。脚本会创建新文件、接受字节完全相同的重复运行，并拒绝冲突；它不会编辑宿主配置或激活渠道。

只有在要分发的软件包明确测试过 Bagisto 版本范围且主题许可证已获批准时，才使用 --registration composer --bagisto-constraint <supported-range> --theme-license <spdx-expression> --theme-license-file <project-relative-license-file>。脚手架会单独保留发现的 Bagisto 声明。切勿通过 Composer 安装某个提供者后，又在本地注册同一个提供者。

对于现有主题，不要搭建脚手架。先检查主题，然后比较实际源代码树（而不是仅配置的发布目标）：

python3 <skill-dir>/scripts/diff_theme_overrides.py \
  --project-root <project-root> \
  --theme-path <theme-package-or-views-path> \
  --expected-theme-code <theme-code> \
  --fail-on baseline-drift

diff 会在确切的主题源根目录中自动发现 .bagisto-theme-baseline.json，并区分视图、资源和已发现构建契约图中的主题修改与已安装 Shop 的修改。完整的 Shop 视图／资源／构建契约清单会捕获上游新增和移除的文件；主题自有哈希会捕获新增、移除和并发更改的覆盖项。此基线不会清点 Shop PHP、控制器、提供者或运行时数据契约；这些由记录的 Bagisto 版本和回归测试把关。只有当配置的 views_path 存在且是权威覆盖目录时，才使用 --theme-code <theme-code>。

如果现有主题没有基线，请将非零结果视为“尚不可审计”。检查其当前上游差异；不要仅为消除关卡限制而接受当前哈希。

4. 按照已安装项目的惯例进行集成

只合并必需的主题入口和一种选定的软件包注册策略。保留所有现有配置。保持活动主题的 Vite 设置与 Vite 输出同步；只有在明确调用命名空间资源，或已安装项目要求时，才添加命名 Vite 注册表。

对于仅包含视图和资源的主题，不要注册模型／Concord。暂时不要激活主题。

更改构建文件或依赖项前，请阅读 assets-build.md。遵守目标锁文件和包管理器策略；安装、联网或更改依赖项前须获得批准。

5. 根据已安装的契约进行实现

仅在开发环境中使用 Blade Tracer，并恢复其先前状态。覆盖视图前，先复制与 Shop 相对路径完全一致的视图。

• 阅读 blade-vue-events.md，了解布局、组件、内联 Vue、脚本时序和渲染事件。
• 阅读 cms-channels-data.md，了解首页／页脚／服务内容、频道、CMS、徽标、网站图标和主题自定义记录。
• 如果请求是在 Admin → Settings → Themes 中新增商家可编辑的首页区块，请先判断已安装的类型是否足够，再添加自定义类型。若需新增类型或编辑器，请阅读 admin-theme-customization-components.md，并完成 assets/theme-customization-component.contract.template.md。将扩展限定在所属的程序包内；切勿仅为添加组件而修改已安装的 Admin 或 Theme 程序包。
• 更改目录、商品、购物车、结账、账户、支付、配送或与扩展相关的视图前，请阅读 commerce-contracts.md。
• 阅读 localization-seo-media.md，了解翻译、RTL、元数据、语义、图片、图标和字体。
• 应用主题简介中批准的语义令牌和页面组合。对于继承的视图，保留已安装的 Tailwind 兼容性令牌；不要在 Blade 模板中零散使用原始颜色、任意间距、一次性阴影或无关动效。

以最小且完整的覆盖集进行实现。保持商家内容可编辑，让服务器对电商状态拥有权威性，并在 Vue 增强前保留有意义的服务器端渲染输出。

6. 构建和验证

运行仓库认可的格式化工具、翻译检查器、受影响的 PHP 测试和主题构建。然后运行：

python3 <skill-dir>/scripts/validate_theme.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --package-dir <package-dir>

解决失败项；说明警告。认可的方向发生变化时，重新运行 validate_theme_brief.py。阅读 testing-deployment.md，并运行其中适用的店面测试矩阵，同时提供控制台、页面错误、失败请求、移动端、RTL、无障碍和性能方面的证据。只有当结账流程缺少同等覆盖时，才调整 assets/storefront-smoke.template.spec.ts。

对于每个新建或重新设计的主题、每项启用／发布决策，或任何要求证明动态／管理员控制内容或店面功能完整性的请求，都必须阅读并遵循嵌入的 bagisto-theme-testing skill。使用其文件夹资源来：

1. 清点已安装的 Shop／Admin Playwright 测试覆盖范围，以及有条件适用的产品／扩展功能；
2. 将每个可见的店面区块映射到其 Bagisto 所属方；
3. 在隔离环境中证明管理员保存 → 范围限定的店面传播 → 还原；
4. 执行所有适用的电商流程，并明确说明排除项；
5. 在宣称就绪前，验证已完成的所属关系清单。

静态检查 Blade 和截图仅用于发现问题／提供视觉证据；它们不能证明商家控制能力或电商正确性。

对于新建脚手架，保留生成的 .bagisto-theme-baseline.json；它记录主题自有的 Shop 源文件，以及完整的 Shop 视图／资源／已发现构建契约清单，且不包含绝对主机路径。现有主题完成协调且所有适用测试均通过后，使用 --json 预览完整路径／哈希文档，检查后再使用应用标记重复执行：

python3 <skill-dir>/scripts/snapshot_upgrade_baseline.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --theme-path <theme-package-or-views-path> \
  --scaffold-mode <overlay-or-package-or-full-fork> \
  --json

然后将 --json 替换为 --apply --acknowledge-reviewed。

仅当外部流程必须创建相同架构时，才使用 assets/override-baseline.template.json。升级后重新运行覆盖差异检查，且仅在验证通过后刷新已接受的哈希。 后续完成协调的升级中，先使用 --refresh --json 预览，再使用 --refresh --apply --acknowledge-reviewed 应用；刷新操作会原子性地替换仅绑定到相同主题和 Shop 身份的有效基线。

7. 启用并交接

所有必需的关卡均通过后：

1. 确认主题自定义内容存在，或已批准空内容／回退方案。
2. 记录目标渠道当前使用的主题及回滚操作。
3. 仅在该渠道选择新主题。
4. 在需要时清除／重建相关缓存并重载长时间运行的进程。
5. 运行生产环境冒烟测试；若失败，则同时回滚源文件／资源／渠道选择。

报告更改的文件、发现的基线、脚手架模式、集成策略、许可证／声明和资源来源决策、构建／清单结果、测试及覆盖的浏览器／区域设置／产品类型／扩展、无障碍／性能证据、启用状态、回滚方式、覆盖差异，以及所有跳过的检查和相关风险。

完成定义

在主题具备品牌特色、视觉协调、响应式、便于商家使用、可审计升级，并已针对所要求的电商流程完成验证之前，不得宣称已完成。仅完成需求说明、成功渲染首页或构建资源，都不足以证明任务完成。