# 📐 Code Style Guide

> 团队代码风格约定，AI 在生成代码时自动遵循

---

## 通用

- 缩进: 2 spaces (前端) / 4 spaces (PHP)
- 行宽: 100 chars (前端) / 120 chars (PHP)
- 行尾: LF
- 文件末尾: 空行
- 字符编码: UTF-8

---

## TypeScript / Vue 3 前端

- 分号: 使用 (`;`)
- 引号: 单引号 (`'`)
- 尾逗号: 无 (`trailing comma: none`)
- 箭头函数参数: 始终括号 (`(x) => x`)

### 导入顺序

```typescript
// 1. Vue 运行时和内置组合式
import { ref, computed, watch } from 'vue'
import { useRoute, useRouter } from 'vue-router'

// 2. 第三方库
// 管理端：import { ElMessage } from 'element-plus'
// 用户端：import { Dialog } from '@headlessui/vue'
import dayjs from 'dayjs'

// 3. 内部模块 (绝对路径)
import AppButton from '@/components/ui/AppButton.vue'
import { useUserStore } from '@/store/modules/user'

// 4. 相对路径
import { helper } from './utils'

// 5. JSDoc 类型引用（JS 项目无需 import type）
// @typedef {import('@/types').User} User

// 6. 样式
import './styles.css'
```

### 文件命名

| 类型 | 规范 | 示例 |
|------|------|------|
| 组件 | PascalCase | `UserProfile.vue` |
| Composable | camelCase + use | `useAuth.ts` |
| 工具函数 | kebab-case | `format-date.ts` |
| 常量 | kebab-case | `api-routes.ts` |
| 类型文件 | kebab-case | `user.types.ts` |
| 测试 | 同源 + .test | `UserProfile.test.ts` |
| Store | camelCase | `user.ts` (in store/modules/) |
| 指令 | camelCase | `auth.ts` (in directives/) |
| API | camelCase | `production.ts` (in api/) |

---

## PHP 后端 (PSR-12)

- 分号: 必须
- 引号: 单引号优先，含变量用双引号
- 缩进: 4 spaces
- 行宽: 120 chars
- 大括号: 类/方法 `{` 换行，控制流 `{` 同行

### PHP 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 类 | PascalCase | `OrderService` |
| 方法 | camelCase | `createOrder()` |
| 变量 | camelCase | `$orderData` |
| 常量 | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
| 数据库字段 | snake_case | `created_at` |
| 路由 | kebab-case 复数 | `/admin/production-orders` |
| 迁移文件 | snake_case 时间戳 | `2026_02_24_100000_create_orders_table.php` |

### PHP 文件结构

```php
<?php

declare(strict_types=1);

namespace App\Service\Production;

use App\Model\Production\ProductionOrder;
use App\Repository\Production\OrderRepository;
use Hyperf\Di\Annotation\Inject;

class OrderService
{
    #[Inject]
    protected OrderRepository $orderRepository;

    public function create(array $data): ProductionOrder
    {
        // ...
    }
}
```

### PHP 必须遵循

- `declare(strict_types=1);` — 所有 PHP 文件
- 类属性使用类型声明
- 方法参数和返回值使用类型声明
- 使用 PHPStan Level max 进行静态分析
- 使用 PHP CS Fixer 格式化代码

---

## Prettier 配置 (.prettierrc)

```json
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always",
  "endOfLine": "lf",
  "plugins": ["prettier-plugin-tailwindcss"]
}
```

---

*最后更新: 2026-02-24*