makemd/docs/05_AI/04_Quick_Reference_Card.md

# AI 开发快速参考卡片（AI Development Quick Reference Card）

> **模块**: 05_AI - AI 开发快速参考  
> **更新日期**: 2026-03-20  
> **用途**: AI 开发时快速查阅的关键约束和规范

---

## 🔴 硬性约束（必须遵守）

### 1. TypeScript 类型安全

| 约束 | 说明 | 示例 |
|------|------|------|
| ❌ **禁止 any** | 使用 `unknown` + 类型守卫 | `function handle(data: unknown)` |
| ✅ **函数返回类型** | 所有函数必须声明返回类型 | `function getUser(): User` |
| ✅ **API 类型定义** | 所有 API 必须定义类型 | `axios.get<ApiResponse<User>>('/api')` |
| ✅ **Schema 驱动** | 类型从 Schema 推导 | `type User = z.infer<typeof UserSchema>` |

### 2. 逻辑集中化

| 层级 | 职责 | 禁止行为 |
|------|------|----------|
| **Controller** | 请求/响应 + 权限校验 | ❌ 业务逻辑 |
| **Service** | 业务逻辑 + 状态流转 | ✅ 核心逻辑 |
| **Repository** | 数据库 CRUD | ❌ 业务逻辑 |

### 3. 数据安全

| 约束 | 说明 |
|------|------|
| **表前缀** | 所有表必须以 `cf_` 开头 |
| **金额字段** | 必须使用 `decimal(10,2)` |
| **五元组** | tenantId, shopId, taskId, traceId, businessType |

### 4. 业务红线

| 场景 | 规则 |
|------|------|
| **B2B 利润率** | < 15% → 禁止报价 |
| **B2C 利润率** | < 20% → 触发风控预警 |
| **决策流程** | SUGGESTED → PENDING_REVIEW → EXECUTED/REJECTED |

---

## 🟡 开发流程

### 标准开发顺序

```
1. Service（业务逻辑）
   ↓
2. Repository（数据访问）
   ↓
3. Controller（接口层）
   ↓
4. Frontend（前端实现）
   ↓
5. Test（测试用例）
```

### 类型转换流程

```
API 返回数据
   ↓
Schema 验证（zod）
   ↓
DTO 转换
   ↓
Domain 模型
```

---

## 🟢 代码模板

### Service 层模板

```typescript
import { z } from 'zod'
import { User, UserDTO } from '@/types'
import { UserSchema } from '@/types/domain/User.schema'

export class UserService {
  constructor(
    private readonly userRepository: UserRepository
  ) {}

  /**
   * 创建用户
   * [BE-U001] 用户创建服务
   */
  async createUser(request: CreateUserRequest): Promise<UserDTO> {
    // 1. 验证请求数据
    const validatedRequest = CreateUserRequestSchema.parse(request)
    
    // 2. 创建领域模型
    const user = UserSchema.parse({
      id: crypto.randomUUID(),
      username: validatedRequest.username,
      email: validatedRequest.email,
      role: validatedRequest.role,
      status: 'ACTIVE',
      createdAt: new Date(),
      updatedAt: new Date()
    })
    
    // 3. 保存到数据库
    const savedUser = await this.userRepository.create(user)
    
    // 4. 转换为 DTO
    return toUserDTO(savedUser)
  }
}
```

### Controller 层模板

```typescript
import { Request, Response } from 'express'
import { CreateUserRequest, CreateUserResponse } from '@/types'
import { createSuccessResponse, createErrorResponse } from '@/types/shared/Response'

export class UserController {
  constructor(private readonly userService: UserService) {}

  async createUser(req: Request, res: Response): Promise<void> {
    try {
      const request: CreateUserRequest = CreateUserRequestSchema.parse(req.body)
      const userDTO = await this.userService.createUser(request)
      
      const response = createSuccessResponse({
        id: userDTO.id,
        username: userDTO.username,
        email: userDTO.email,
        role: userDTO.role,
        createdAt: userDTO.createdAt
      })
      
      res.json(response)
    } catch (error) {
      const response = createErrorResponse(
        'INTERNAL_ERROR',
        error instanceof Error ? error.message : 'Unknown error'
      )
      res.status(500).json(response)
    }
  }
}
```

### Schema 定义模板

```typescript
import { z } from 'zod'

export const UserSchema = z.object({
  id: z.string().uuid(),
  username: z.string().min(3).max(50),
  email: z.string().email(),
  role: z.enum(['ADMIN', 'MANAGER', 'OPERATOR']),
  status: z.enum(['ACTIVE', 'INACTIVE']).default('ACTIVE'),
  createdAt: z.date(),
  updatedAt: z.date()
})

export type User = z.infer<typeof UserSchema>
```

---

## 🔵 常见错误对比

### ❌ 错误示例 vs ✅ 正确示例

#### 1. 类型定义

```typescript
// ❌ 错误：使用 any
function handle(data: any) {
  return data.name
}

// ✅ 正确：使用 unknown + 类型守卫
function handle(data: unknown) {
  if (typeof data === 'object' && data !== null && 'name' in data) {
    return (data as { name: string }).name
  }
  throw new Error('Invalid data')
}
```

#### 2. 函数返回类型

```typescript
// ❌ 错误：未声明返回类型
function getUser(userId: string) {
  return userRepository.findById(userId)
}

// ✅ 正确：声明返回类型
function getUser(userId: string): Promise<User | null> {
  return userRepository.findById(userId)
}
```

#### 3. API 调用

```typescript
// ❌ 错误：未定义类型
const response = await axios.get('/api/users')

// ✅ 正确：定义类型
const response = await axios.get<ApiResponse<User[]>>('/api/users')
const users = response.data.data
```

#### 4. 业务逻辑位置

```typescript
// ❌ 错误：Controller 中写业务逻辑
async createUser(req: Request, res: Response) {
  const { username, email } = req.body
  if (!username || !email) {
    return res.status(400).json({ error: 'Missing fields' })
  }
  const user = await this.userRepository.create({ username, email })
  res.json(user)
}

// ✅ 正确：Controller 只负责请求/响应
async createUser(req: Request, res: Response) {
  try {
    const userDTO = await this.userService.createUser(req.body)
    res.json(createSuccessResponse(userDTO))
  } catch (error) {
    res.status(500).json(createErrorResponse('ERROR', error.message))
  }
}
```

#### 5. 类型定义方式

```typescript
// ❌ 错误：手动定义类型
interface User {
  id: string
  name: string
  email: string
}

// ✅ 正确：从 Schema 推导类型
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email()
})

type User = z.infer<typeof UserSchema>
```

---

## 🟣 检查清单

### 开发前检查

- [ ] 已阅读相关业务文档
- [ ] 已理解状态机流转
- [ ] 已确认任务依赖关系
- [ ] 已声明文件占用

### 开发中检查

- [ ] 所有函数已声明返回类型
- [ ] 所有 API 调用已定义类型
- [ ] 业务逻辑在 Service 层
- [ ] 类型从 Schema 推导
- [ ] 所有类型从 `/types` 导入

### 提交前检查

- [ ] `tsc --noEmit` 无错误
- [ ] `eslint` 无错误
- [ ] 单元测试通过
- [ ] 五元组已填写
- [ ] JSDoc 注释完整

---

## 🟤 快速导航

| 文档 | 路径 |
|------|------|
| **TypeScript 编译规约** | `docs/01_Architecture/13_TypeScript_Standards.md` |
| **代码质量规范** | `docs/01_Architecture/14_Code_Quality_Standards.md` |
| **Schema 驱动开发** | `docs/01_Architecture/15_Schema_Driven_Development.md` |
| **统一类型管理** | `docs/01_Architecture/16_Unified_Type_Management.md` |
| **AI 开发规则** | `docs/05_AI/02_Rules.md` |
| **项目硬性约束** | `.trae/rules/project-specific-rules.md` |

---

## 🟠 紧急情况处理

### 编译错误

```bash
# 1. 检查类型错误
npm run typecheck

# 2. 修复 ESLint 错误
npm run lint:fix

# 3. 重新编译
npm run build
```

### 类型错误

```typescript
// 快速修复：使用类型守卫
if (isUser(data)) {
  // TypeScript 知道 data 是 User 类型
}

// 快速修复：使用 Schema 验证
const user = UserSchema.parse(data)
```

### 业务逻辑错误

```typescript
// 检查：业务逻辑是否在 Service 层
// 检查：状态流转是否遵循状态机
// 检查：权限校验是否完整
```

---

*本卡片仅供快速参考，详细规范请查阅完整文档。*