176 lines
7.1 KiB
Markdown
176 lines
7.1 KiB
Markdown
# 开发准则 — 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 核心文件，必须：
|
||
1. 在 commit 前向用户（`@bigemon`）明确说明改动内容和风险
|
||
2. 获得用户书面同意（chat message）
|
||
3. 改动后立即 commit，commit message 标注 `[CORE-MODIFICATION]`
|
||
|
||
### 2. 数据库操作 🔴
|
||
|
||
**禁止直接修改数据库**。任何数据库 schema 变更（创建表、增删字段、索引、DROP 等）必须：
|
||
|
||
1. 提出申请，说明：操作内容、原因、rollback 方案
|
||
2. 用户二次审阅并明确同意
|
||
3. 以 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` 不会自动赋值给插件视图。
|
||
|
||
**正确写法**：
|
||
|
||
```php
|
||
// 控制器：显式传递 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'),
|
||
]);
|
||
}
|
||
}
|
||
```
|
||
|
||
```html
|
||
<!-- 模板：使用 {{$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">
|
||
```
|
||
|
||
**静态文件来源优先级**：
|
||
1. **ShopXO 自带**：`{{$public_host}}static/common/lib/` 下已有 JsBarcode、jQuery、AmazeUI 等
|
||
2. **国内 CDN**：`cdn.staticfile.net`（ShopXO 无自带时）
|
||
3. **禁止**：国际 CDN（`unpkg.com`、`jsdelivr.net`、`cdnjs.cloudflare.com`）— 大陆阻断
|
||
|
||
**验证方法**：容器内文件是否存在：
|
||
```bash
|
||
# 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](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 西莉雅*
|