项目开发规范（AI 协作必读）
本文档是项目的唯一事实来源（Single Source of Truth）。每次让 AI 生成代码前，将本文档内容贴入提示词的【项目约束】部分。
一、技术栈约束
1.1 版本锁定
| 组件 | 版本 | 禁止事项 |
|---|---|---|
| PHP | 7.4 | 禁用 PHP 8 语法：match、命名参数、构造器属性提升、readonly、enum |
| MySQL | 5.7 | 禁用 MySQL 8 特性：窗口函数、CTE（WITH）、JSON_TABLE |
| UniApp | Vue 2 语法 | 禁用 Vue 3：<script setup>、ref()、reactive()、computed() 导入式写法 |
| Redis | 6.x | — |
| Nginx | 1.20+ | — |
1.2 PHP 7.4 合规写法对照
| 场景 | ❌ 禁止（PHP 8） | ✅ 正确（PHP 7.4） |
|---|---|---|
| 类型声明 | function foo(int $a) 可以 |
可以用，但不能用联合类型 int|string |
| 属性定义 | class Foo { public int $bar; } |
class Foo { public $bar = 0; } |
| 匹配表达式 | $result = match($x) { 1 => 'a' } |
switch ($x) { case 1: $result = 'a'; break; } |
| 命名参数 | foo(name: 'bar') |
foo('bar') |
| Null 安全运算符 | $obj?->method() |
isset($obj) ? $obj->method() : null |
二、架构规范
2.1 分层架构
Controller（控制器） │ 职责：接收参数、参数校验、调用 Service、返回响应 │ 禁止：直接操作数据库、写业务逻辑 ▼Service（业务逻辑层） │ 职责：核心业务逻辑、事务控制、调用 Model │ 禁止：直接输出 JSON、处理 HTTP 参数 ▼Model（数据访问层） │ 职责：数据库增删改查、缓存读写 │ 禁止：包含业务判断逻辑2.2 目录结构约定
app/├── controller/│ ├── api/ # 前端 API 接口│ └── admin/ # 后台管理接口├── service/ # 业务逻辑├── model/ # 数据模型├── middleware/ # 中间件├── common/ # 公共函数└── config/ # 配置文件三、代码规范
3.1 命名规范
| 类型 | 规范 | 示例 |
|---|---|---|
| 数据库表名 | 蛇形小写，复数或单数统一 | user、product、order_item |
| 数据库字段 | 蛇形小写 | user_id、create_time |
| PHP 变量 | 驼峰 | $orderNo、$userId |
| PHP 类名 | 大驼峰 | OrderService、ProductModel |
| PHP 方法名 | 小驼峰 | createOrder()、getUserInfo() |
| API 路径 | 蛇形小写或 RESTful | /api/v1/products 或 /api/v1/order_list |
| UniApp 页面路径 | 蛇形小写 | /pages/order_detail/order_detail |
3.2 PHP 代码规范
<?php// ✅ 正确示例class OrderService{ /** * 创建订单 * @param array $data 订单数据 * @return string 订单号 * @throws BusinessException */ public function createOrder(array $data): string { $productId = (int)$data['product_id']; $quantity = (int)($data['quantity'] ?? 1); // 参数校验 if ($productId <= 0 || $quantity <= 0) { throw new BusinessException(1001, '参数错误'); } $product = (new ProductModel())->findById($productId); if (!$product) { throw new BusinessException(2001, '商品不存在'); } $amount = bcmul($product['price'], $quantity, 2); // ... 后续逻辑 return $orderNo; }}// ❌ 禁止示例function create($data) { $id = $data['id']; // 没有类型转换 $sql = "SELECT * FROM product WHERE id=" . $id; // SQL 拼接，有注入风险 return json(['code'=>0,'data'=>$sql]); // 直接返回 SQL 结果}3.3 UniApp 前端规范
// ✅ API 请求统一走封装import { request } from '@/api/request.js'export function getOrderList(params) { return request({ url: '/orders', method: 'GET', data: params })}// ❌ 禁止在页面里直接写 uni.request// 页面里直接 uni.request 会导致重复代码、无法统一处理错误// ✅ 页面用 Vue 2 语法export default { data() { return { list: [] } }, methods: { async loadData() { const data = await getOrderList({ page: 1 }) this.list = data.list } }}// ❌ 禁止 Vue 3 setup 语法// import { ref } from 'vue' ← UniApp 默认不支持四、数据库规范
4.1 建表规范
| 规则 | 说明 |
|---|---|
| 引擎 | 统一 InnoDB |
| 字符集 | 统一 utf8mb4、utf8mb4_unicode_ci |
| 主键 | 每张表必须有 id BIGINT UNSIGNED AUTO_INCREMENT |
| 时间字段 | create_time、update_time 用 INT UNSIGNED 存时间戳 |
| 软删除 | delete_time 字段，NULL 表示未删除 |
| 金额字段 | DECIMAL(10,2)，禁止用 FLOAT/DOUBLE |
| 状态字段 | TINYINT，注释标明各值含义 |
| 布尔字段 | TINYINT(1)，0/1 |
| 外键字段 | 命名为 xxx_id，如 user_id |
| 字段注释 | 每个字段必须有 COMMENT |
4.2 建表模板
CREATE TABLE `表名` ( `id` int unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID', `字段名` 类型 NOT NULL DEFAULT '默认值' COMMENT '字段说明', `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态：1正常 0禁用', `create_time` int unsigned NOT NULL COMMENT '创建时间', `update_time` int unsigned NOT NULL COMMENT '更新时间', `delete_time` int unsigned DEFAULT NULL COMMENT '删除时间', PRIMARY KEY (`id`), KEY `idx_字段名` (`字段名`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='表说明';4.3 索引规范
| 规则 | 说明 |
|---|---|
| 索引命名 | 普通索引 idx_字段名，唯一索引 uk_字段名 |
| 联合索引 | 按查询频率从高到低排列字段 |
| 禁止 | 单表索引超过 5 个；大文本字段建索引 |
| 必须加索引 | WHERE 条件字段、JOIN 关联字段、ORDER BY 排序字段 |
五、API 规范
5.1 统一响应格式
// 成功{ "code": 0, "msg": "success", "data": {} }// 失败{ "code": 1001, "msg": "参数错误", "data": null }// 分页{ "code": 0, "msg": "success", "data": { "list": [], "total": 100, "page": 1, "page_size": 20 }}5.2 状态码约定
| 范围 | 含义 |
|---|---|
| 0 | 成功 |
| 1xxx | 参数/校验错误 |
| 2xxx | 业务逻辑错误（如库存不足） |
| 3xxx | 权限错误（未登录、无权限） |
| 4xxx | 限流/安全拦截 |
| 5xxx | 服务端异常 |
5.3 接口规范
| 规则 | 说明 |
|---|---|
| 路径前缀 | /api/v1/ |
| 认证方式 | Header: Authorization: Bearer {token} |
| 分页参数 | page（页码）+ page_size（每页条数，默认 20，最大 100） |
| 时间格式 | 统一用时间戳（秒），前端格式化展示 |
| 列表字段 | 列表接口只返回必要字段，不返回完整详情 |
六、安全规范
| 安全项 | 约束 |
|---|---|
| SQL 注入 | 全部用预处理语句或查询构造器，禁止字符串拼接 SQL |
| XSS | 输出转义 htmlspecialchars()；前端用 v-text 不用 v-html |
| 密码存储 | password_hash() 加密，禁止 MD5/SHA1 |
| Token | JWT 签发，密钥从环境变量读取，不硬编码 |
| 文件上传 | 校验 MIME + 后缀白名单 + 重命名 + 存储到非 Web 目录 |
| 接口限流 | 每用户每分钟最多 60 次请求（Redis 滑动窗口） |
| 越权防护 | 每个接口校验当前用户是否有权操作目标资源 |
| 敏感配置 | 数据库密码、API Key、JWT 密钥写入 .env，不入 Git |
| HTTPS | 全站 HTTPS，禁止 HTTP 传输敏感数据 |
七、版本控制规范
7.1 Git 提交规范
<类型>: <简短描述>类型： feat 新功能 fix 修复 Bug refactor 重构（不改功能） docs 文档变更 style 代码格式（不改逻辑） perf 性能优化 chore 构建/工具变更示例：
feat: 新增商品列表接口fix: 修复订单金额计算精度问题refactor: 重构用户登录逻辑7.2 分支规范
| 分支 | 用途 |
|---|---|
master |
生产环境，只合并经过测试的代码 |
dev |
开发主分支 |
feature/xxx |
功能开发分支 |
fix/xxx |
Bug 修复分支 |
7.3 .gitignore 必须包含
.env/vendor//runtime//node_modules//unpackage/dist/*.log八、性能约束
| 圄景 | 约束 |
|---|---|
| 接口响应时间 | 普通接口 < 200ms，复杂查询 < 500ms |
| 数据库查询 | 单接口 SQL 查询不超过 5 条，禁止 N+1 查询 |
| 分页大小 | 每页最多 100 条，默认 20 条 |
| 缓存 TTL | 详情页 1 小时，列表页 5 分钟，配置类 24 小时 |
| 图片大小 | 单张不超过 500KB，列表缩略图不超过 100KB |
| Redis 使用 | 读取后及时释放连接，禁止在循环中频繁读写 |
九、AI 协作提示词模板
每次让 AI 写代码时，复制以下模板并填充具体任务：
你是一位资深开发工程师，帮我实现以下功能。【项目约束】- 技术栈：PHP 7.4 + MySQL 5.7 + UniApp（Vue 2）+ Redis 6- 禁用 PHP 8 语法、MySQL 8 特性、Vue 3 语法- 三层架构：Controller → Service → Model- SQL 用预处理，禁止拼接- 响应格式：{"code":0,"msg":"","data":{}}- 金额用 bcmath，时间用时间戳【已有表结构】[粘贴相关表结构]【功能需求】[描述具体功能]【输出要求】- 生成完整可运行代码- 关键逻辑加注释- 标注需要手动配置的部分使用方式：本文件是项目的唯一规范来源。新增约束时更新本文件，并在每次 AI 对话时将相关章节贴入提示词。