# 通用能力层 - 快速引用卡片

> 一页纸速查表，快速找到需要的通用能力

---

## 🎯 我需要...

### 💬 AI 对话功能

**前端：**
```tsx
import { AIStreamChat } from '@/shared/components/Chat';
<AIStreamChat apiEndpoint="/api/v1/xxx/chat/stream" enableDeepThinking={true} />
```

**后端：**
```typescript
import { createStreamingService } from '../../../common/streaming';
const service = createStreamingService(reply);
await service.streamGenerate(messages);
```

📚 [详细文档](./00-通用能力层清单.md#2-chat-通用组件)

---

### 🤖 调用 LLM

```typescript
import { LLMFactory } from '../../../common/llm/adapters/LLMFactory';

const llm = LLMFactory.getAdapter('deepseek-v3');
const response = await llm.chat(messages);

// 流式
for await (const chunk of llm.chatStream(messages)) {
  console.log(chunk.content);
}
```

📚 [详细文档](./01-LLM大模型网关/)

---

### 📁 文件存储

```typescript
import { storage } from '../../../common/storage';

// 上传
const url = await storage.upload('path/file.pdf', buffer);

// 下载
const buffer = await storage.download('path/file.pdf');
```

📚 [详细文档](./00-通用能力层清单.md#4-存储服务)

---

### ⚡ 异步任务

```typescript
import { JobFactory } from '../../../common/jobs';

const queue = JobFactory.getQueue();

// 创建任务
await queue.createJob('job-name', { taskId: 'xxx' });

// 注册Worker
queue.registerWorker('job-name', async (job) => {
  // 处理逻辑
});
```

📚 [详细文档](./Postgres-Only异步任务处理指南.md)

---

### 📄 文档处理

```typescript
import { ExtractionClient } from '../../../common/document/ExtractionClient';

const client = new ExtractionClient();
const text = await client.extractText(buffer, 'pdf');
```

📚 [详细文档](./02-文档处理引擎/)

---

### 🔍 知识库检索（RAG）

```typescript
import { DifyClient } from '../../../common/rag/DifyClient';

const dify = new DifyClient(apiKey, baseURL);
const results = await dify.retrievalSearch(query, options);
```

📚 [详细文档](./03-RAG引擎/)

---

### 💾 缓存服务

```typescript
import { cache } from '../../../common/cache';

await cache.set('key', value, 3600);  // TTL: 3600秒
const value = await cache.get('key');
await cache.delete('key');
```

📚 [详细文档](./00-通用能力层清单.md#6-缓存服务)

---

### 📝 日志记录

```typescript
import { logger } from '../../../common/logging';

logger.info('[Module] 操作描述', { userId: 'xxx', detail: 'xxx' });
logger.error('[Module] 错误', { error, stack: error.stack });
```

📚 [详细文档](./00-通用能力层清单.md#7-日志服务)

---

### 🔐 认证授权

**后端：**
```typescript
import { authenticate, getUserId } from '../../../common/auth';

// 路由
fastify.get('/api', { preHandler: [authenticate] }, handler);

// 控制器
const userId = getUserId(request);
```

**前端：**
```typescript
import { getAccessToken } from '@/framework/auth/api';
const token = getAccessToken();

// 或使用 apiClient（自动携带token）
import apiClient from '@/common/api/axios';
await apiClient.get('/api/xxx');
```

📚 [详细文档](../04-开发规范/10-模块认证规范.md)

---

### 📋 Prompt 管理

```typescript
import { PromptService } from '../../../common/prompt/prompt.service';

const promptService = new PromptService();
const prompt = await promptService.getActivePrompt('template_code');
const rendered = promptService.renderPrompt(template, variables);
```

📚 [详细文档](./00-通用能力层清单.md#11-prompt-管理系统)

---

## 🏗️ 架构原则

### ✅ 正确做法

```typescript
// 1. 使用通用能力，不要重复造轮子
import { createStreamingService } from '../../../common/streaming';

// 2. 遵循云原生规范
await storage.upload();  // 不要用 fs.writeFileSync()

// 3. 使用结构化日志
logger.info('[Module] 操作', { detail });  // 不要用 console.log()

// 4. 统一认证
fastify.get('/api', { preHandler: [authenticate] });

// 5. 标准化API格式
// OpenAI Compatible, not 自定义格式
```

### ❌ 错误做法

```typescript
// 1. 自己实现已有的能力
reply.raw.write('data: ...');  // ❌ 应该用 StreamingService

// 2. 直接操作本地文件
fs.writeFileSync('/tmp/file');  // ❌ 应该用 storage

// 3. 使用 console.log
console.log('debug');  // ❌ 应该用 logger

// 4. 硬编码用户ID
const userId = 'test';  // ❌ 应该用 getUserId(request)

// 5. 自定义格式
{ type: 'delta', content: 'xxx' }  // ❌ 应该用 OpenAI Compatible
```

---

## 📚 完整文档

- [通用能力层清单（完整版）](./00-通用能力层清单.md)
- [云原生开发规范](../04-开发规范/08-云原生开发规范.md)
- [模块认证规范](../04-开发规范/10-模块认证规范.md)
- [数据库开发规范](../04-开发规范/09-数据库开发规范.md)

---

**更新时间：** 2026-01-14