适用场景：
- 单人开发，私有仓库（Gitea）
- WordPress / Laravel / PHP 项目
- 使用 Cursor IDE（自带版本快照）
- 所有发布由本人主动控制
---
## 🗂️ 目录
1. Git 版本管理策略
2. 分支使用约定
3. 提交信息规范
4. PHP 语言约束
5. 命名风格
6. 安全与数据库约束
7. 自动化工具（可选）
8. RIPER-5 模式思维（可选）
9. 回滚与历史管理
10. 推荐执行流程
---
## 1️⃣ Git 版本管理策略
- 所有代码托管于 ** 私有 Gitea 仓库 **
- **`main` 分支即为生产版本 **
✔ 日常直接在 `main` 上开发、提交、推送
✔ 不需要 PR 审核或外部批准
- **Cursor 已提供时间快照，Git 只作远程安全备份 **
- 大型或风险改动（如架构重构、新集成），可用临时分支
示例：
```bash
git checkout -b experiment/new-api
# 修改...
git push origin experiment/new-api
# 合并或放弃
```
---
## 2️⃣ 分支使用约定
- 日常小功能 / 修复：直接在 `main` 开发
- 大型功能 / 不确定试验：`experiment/xxx` 命名
- 合并回 `main` 时，自己手动检查后合并
---
## 3️⃣ 提交信息规范
- 提交需语义化，格式：
```
feat: 新增功能
fix: 修复问题
refactor: 重构
chore: 依赖或杂项
```
示例：
```bash
git commit -m "feat: 新增用户注册功能"
```
---
## 4️⃣ PHP 语言约束
- 所有 PHP 文件必须以 `declare(strict_types=1);` 开头
- 遵循 **PSR-12** 编码规范
- 使用命名空间 + 类型声明 + PSR-4 自动加载
- 命名语义清晰、准确，不使用缩写或无意义变量名
- 避免重复代码，遵循 **DRY** / **KISS** 原则
- 保持高内聚、低耦合的模块结构
- 所有可见输出必须国际化（WordPress）
- WordPress 使用 `$wpdb` / `WP_Query`，禁止裸 SQL
- Laravel 使用 Eloquent ORM 或 Query Builder，禁止裸 SQL
- 使用 PDO 预处理语句，防止 SQL 注入
- 永远过滤用户输入，防止 XSS
---
## 5️⃣ 命名风格
| 元素 | 规则 | 示例 |
|------|------|------|
| 变量 / 方法 | camelCase | `$userName` `getUserName()` |
| 类 / 接口 | PascalCase | `OrderService` |
| 常量 | UPPER_SNAKE_CASE | `MAX_ATTEMPTS` |
| 布尔变量 | is/has/can 开头 | `$isActive` `$hasPermission` |
| 控制器 | PascalCase + Controller | `UserController` |
| 路由别名 | kebab-case | `user-profile` |
| 配置键 | lower_snake_case | `cache_ttl` |
---
## 6️⃣ 安全 & 数据库约束
- 严禁拼接 SQL，必须使用预处理语句
- 严格使用输入验证与输出转义
- 统一用 `.env` 管理数据库连接及密钥
- 不得将明文凭据写死在代码
---
## 7️⃣ 自动化工具（可选）
- 推荐使用：
- `PHP_CodeSniffer`（PSR-12）
- `PHPStan`（Level ≥ 6）
- 非强制，但建议在重大合并前手动执行：
```bash
./vendor/bin/phpcs
./vendor/bin/phpstan analyse
```
---
## 8️⃣ RIPER-5 模式思维（可选）
- 大改动可使用：
- **RESEARCH**：调研、读代码、分解逻辑
- **INNOVATE**：头脑风暴、方案对比
- **PLAN**：写实施清单
- **EXECUTE**：按计划逐步执行
- **REVIEW**：回顾与回滚
---
## 9️⃣ 回滚与历史管理
- Cursor 自带快照可随时撤销
- Git 本地回滚示例：
```bash
git log
git checkout
git revert
```
- 远程出现重大错误：
```bash
git reset --hard <稳定 commit>
git push -f
```
---
## 🔟 推荐执行流程
✅ 日常小改：直接 `main` ➜ `commit` ➜ `push`
✅ 大改 / 试验：开 `experiment/xxx` ➜ 开发 ➜ `merge` ➜ `main`
✅ 出错：Cursor 本地快照或 `git log` 回滚
✅ 定期推送到 Gitea 作为远程备份
---
## 🎯 总原则
** 一切发布节奏由自己掌控 **
** 保持最小可用、最小干扰、最大可回滚 **