7.1 KiB

Raw Blame History

开发准则 — vr-shopxo-plugin

所有在此仓库工作的 agent（CClaude Code、Council agents、subagent 等）必须严格遵守。违反即为 P0 安全/质量事件。

一、铁律（绝对禁止违反）

1. 插件边界约束 🔴

禁止修改 ShopXO 核心文件，任何改动必须严格限定在插件目录内：

✅ 允许修改的范围
shopxo/app/plugins/vr_ticket/       ← 插件自身代码
docs/                               ← 项目文档
tests/                              ← 测试文件
.gitignore                          ← 版本控制配置

❌ 禁止修改（绝对禁区）
shopxo/app/                      ← 核心控制器、模型、服务（除 vr_ticket 插件）
shopxo/config/                   ← ShopXO 配置文件
shopxo/public/                   ← 静态资源、入口文件
shopxo/app/common.php            ← 核心公共函数（⚠️ 曾被误改，历史教训）
shopxo/app/event.php             ← 核心事件钩子文件（⚠️ 曾被误改，历史教训）
shopxo/app/index/controller/     ← 前台控制器
shopxo/app/admin/controller/     ← 后台控制器
shopxo/app/service/              ← 核心服务层
shopxo/app/model/                ← 核心模型层
shopxo/app/install/             ← 安装程序
shopxo/config/database.php       ← 数据库配置
shopxo/config/shopxo.php         ← ShopXO 主配置

最小化原则：即使在允许范围内，也应优先考虑 Hook/扩展点/插件配置，而不是直接修改文件。

例外：如确实需要修改 ShopXO 核心文件，必须：

在 commit 前向用户（@bigemon）明确说明改动内容和风险
获得用户书面同意（chat message）
改动后立即 commit，commit message 标注 [CORE-MODIFICATION]

2. 数据库操作 🔴

禁止直接修改数据库。任何数据库 schema 变更（创建表、增删字段、索引、DROP 等）必须：

提出申请，说明：操作内容、原因、rollback 方案
用户二次审阅并明确同意
以 migration 文件形式提交（docs/migrations/ 或 database/migrations/），禁止直接执行 SQL

已规划的数据库操作（如有）须全部列在此文档末尾。

3. Docker 容器操作 ⚠️

禁止直接操作 Docker 容器内环境（docker exec、修改容器内文件、挂载层覆盖等）。

如需测试容器内行为：通过挂载目录的文件修改 + 容器重启实现
如需紧急修复：先告知用户，获得同意后再执行
所有 docker 操作应在 commit message 中记录

二、重要实践建议

4. 调试代码及时清理

任何为了调试目的注入的临时代码（var_dump、@file_put_contents('/tmp/debug.log')、临时 sed 注入、.bak 备份文件）调试完毕后必须立即删除
.bak、.bak2 等备份文件禁止 commit
调试用的临时文件（/tmp/*.log、/tmp/co.php 等）不在 git 管理范围内，注意不要误 commit

5. Pre-commit 自检（必须执行）

每次 commit 前必须确认：

git status 确认改动范围，是否意外修改了 ShopXO 核心文件
无 .bak、.bak2 等备份文件在暂存区
无调试用的临时文件在暂存区
改动与用户原始请求相关，无无关的"优化"或"格式调整"

6. Council / Subagent 行为约束

Council agents 和 Claude Code subagents 的 commit 行为必须约束在 feat/ 分支内，禁止自动 merge 或 push 到 main。输出文件（reviews/、plan.md）不应作为最终交付 commit，应由主 agent 审阅后手动处理。

7. 配置文件隔离

所有敏感配置（数据库密码、API Key、frp token 等）必须写入 docs/PRIVATE_CONFIG.md（不 commit）或 .env（已 gitignore）
禁止将真实密码写入代码或 commit message

8. 插件模板静态文件引用规范

ShopXO 插件模板引用 JS/CSS 时，必须遵循以下规范：

背景：ShopXO 官方模板用 {{$public_host}} 引用静态文件，但插件控制器不继承 index/Common.php，$public_host 不会自动赋值给插件视图。

正确写法：

// 控制器：显式传递 public_host
class Index
{
    public function wallet()
    {
        $user = UserService::LoginUserInfo();
        return MyView('../../../plugins/vr_ticket/view/goods/ticket_wallet', [
            'user' => $user,
            // 关键：插件不继承 Common 基类，必须显式传递
            'public_host' => \think\facade\Config::get('shopxo.host_url'),
        ]);
    }
}

<!-- 模板：使用 {{$public_host}} -->
<!-- ✅ 引用 ShopXO 自带库（优先） -->
<script src="{{$public_host}}static/common/lib/JsBarcode/JsBarcode.all.min.js"></script>

<!-- ✅ 引用插件自己的静态文件 -->
<link rel="stylesheet" href="{{$public_host}}plugins/vr_ticket/static/css/ticket.css">

<!-- ❌ 错误：插件模板里直接用 Config() 散落在模板各处 -->
<link href="<?php echo Config('shopxo.host_url'); ?>plugins/vr_ticket/static/css/ticket.css">

静态文件来源优先级：

ShopXO 自带：{{$public_host}}static/common/lib/ 下已有 JsBarcode、jQuery、AmazeUI 等
国内 CDN：cdn.staticfile.net（ShopXO 无自带时）
禁止：国际 CDN（unpkg.com、jsdelivr.net、cdnjs.cloudflare.com）— 大陆阻断

验证方法：容器内文件是否存在：

# ShopXO 自带 JsBarcode
docker exec shopxo-php ls /var/www/html/public/static/common/lib/JsBarcode/
# 应输出：JsBarcode.all.min.js

双目录陷阱：插件 JS/CSS 文件在 app/plugins/（PHP runtime）和 public/plugins/（Nginx webroot）各有一份副本。修改后必须同步两边。详见 docs/DEBUG_STATIC_FILE_SYNC.md。

三、已知特殊情况记录

已修改的 ShopXO 核心文件（需注意）

以下文件在历史中被修改过，当前仓库状态如下：

文件	状态	备注
`shopxo/app/common.php`	✅ 与官方源码一致	2026-04-23 调试注入已回退
`shopxo/app/event.php`	✅ 与官方源码一致	2026-04-23 调试注入已回退
`shopxo/app/index/controller/Goods.php`	⚠️ 有业务修改	`item_type='ticket'` 路由到 `ticket_detail.html`（Phase 1 必需改动）
`shopxo/app/service/AdminPowerService.php`	⚠️ 有权限修改	ShopXO 后台权限服务（改动内容待确认）

注意：Goods.php 的 item_type 路由是 Phase 1 必需的业务改动，已知例外，无需重复审阅。其他 ShopXO 核心文件应保持原样。

Docker 容器配置（勿直接修改容器内文件）

shopxo-php  →  /Users/bigemon/WorkSpace/vr-shopxo-plugin/shopxo  （挂载目录）
shopxo-mysql →  容器内 MySQL
shopxo-web   →  Nginx

调试时应修改宿主机挂载目录文件，然后重启容器。不要在容器内直接改。

四、违规处理

违反铁律（1、2、3）的行为：

主 agent 有权立即 rollback 并拒绝 merge
视为 P0 安全事件，记录至 MEMORY.md 并通知用户

最后更新：2026-04-24 by 西莉雅

7.1 KiB Raw Blame History Unescape Escape