## 🗄️ PostgreSQL数据对接规范

### 概述

本系统使用PostgreSQL作为主数据库，通过PostgREST提供RESTful API接口。所有数据操作统一通过封装的`postgrest-client.ts`模块进行，确保数据访问的一致性和可维护性。

### 技术架构

```
前端组件 (Remix Routes)
    ↓
API层 (app/api/[module]/[api].ts)
    ↓
PostgREST客户端 (postgrest-client.ts)
    ↓
PostgreSQL数据库
```

### 基础封装方法

#### 1. 导入PostgREST客户端

```typescript
import { 
  postgrestGet, 
  postgrestPost, 
  postgrestPut, 
  postgrestDelete,
  type PostgrestParams 
} from "../postgrest-client";
```

#### 2. 查询操作 (GET)

```typescript
// 基础查询
const params: PostgrestParams = {
  select: '*',
  filter: {
    'id': `eq.${id}`,
    'status': `eq.active`
  },
  order: 'created_at.desc',
  limit: 20,
  offset: 0
};

const response = await postgrestGet('table_name', params);

// 复杂查询示例
const complexParams: PostgrestParams = {
  select: 'id,name,status,created_at,user_id,users(name)',  // 关联查询
  filter: {
    'created_at': `gte.2023-01-01`,
    'status': `in.(active,pending)`
  },
  or: 'name.ilike.*keyword*,description.ilike.*keyword*',  // OR条件
  order: 'created_at.desc,name.asc',
  limit: 50
};

const response = await postgrestGet('documents', complexParams);
```

#### 3. 创建操作 (POST)

```typescript
// 单条记录创建
const newRecord = {
  name: '文档名称',
  document_number: 'DOC001',
  type_id: 1,
  user_id: 123,
  status: 'pending'
};

const response = await postgrestPost('documents', newRecord);

// 批量创建
const batchRecords = [
  { name: '文档1', type_id: 1 },
  { name: '文档2', type_id: 2 }
];

const response = await postgrestPost('documents', batchRecords);
```

#### 4. 更新操作 (PUT/PATCH)

```typescript
// 根据ID更新
const updateData = {
  status: 'completed',
  audit_status: 1,
  updated_at: new Date().toISOString()
};

const response = await postgrestPut(
  'documents', 
  updateData, 
  { id: documentId }
);

// 根据条件批量更新
const response = await postgrestPut(
  'evaluation_results',
  { status: 'reviewed' },
  { document_id: docId, status: 'pending' }
);
```

#### 5. 删除操作 (DELETE)

```typescript
// 根据ID删除
const response = await postgrestDelete('documents', {
  filter: { 'id': `eq.${id}` }
});

// 条件删除
const response = await postgrestDelete('temp_files', {
  filter: { 'created_at': `lt.2023-01-01` }
});
```

### API层实现规范

#### 1. 文件结构
```
app/api/
├── [module]/              # 功能模块
│   ├── [feature].ts       # 具体功能API
│   └── types.ts           # 类型定义 (可选)
├── postgrest-client.ts    # PostgREST客户端
├── axios-client.ts        # HTTP客户端
└── error-handler.ts       # 错误处理
```

#### 2. API文件模板

```typescript
// app/api/evaluation_points/reviews.ts
import { postgrestGet, type PostgrestParams, postgrestPut, postgrestPost } from "../postgrest-client";
import { getDocument } from "~/api/files/documents";
import { formatDate } from "~/utils";

/**
 * 数据提取工具函数
 * 统一处理不同格式的API响应
 */
function extractApiData<T>(responseData: unknown): T | null {
  if (!responseData) return null;

  // 格式1: { code: number, msg: string, data: T }
  if (typeof responseData === 'object' && responseData !== null && 
      'code' in responseData && 
      'data' in responseData && 
      (responseData as { data: unknown }).data) {
      return (responseData as { data: T }).data;
  }

  // 格式2: 直接是数据对象
  return responseData as T;
}

// 类型定义
interface EvaluationResult {
  id: string | number;
  document_id: string | number;
  evaluation_point_id: string | number;
  evaluated_results?: {
    result?: boolean;
    message?: string;
    data?: string;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}

interface EvaluationPoint {
  id: string | number;
  evaluation_point_groups_id: string | number;
  suggestion_message_type?: string;
  suggestion_message?: string;
  score?: number;
  updated_at?: string;
  [key: string]: unknown;
}

// 前端使用的结果类型
interface ReviewPointResult {
  id: string | number;
  title: string;
  groupName: string;
  status: string;
  content: string;
  suggestion: string;
  result?: boolean;
  score: number;
}

/**
 * 获取评查点数据
 * @param fileId 文件ID
 * @returns 评查点结果列表和统计数据
 */
export async function getReviewPoints(fileId: string) {
  try {
    // 步骤1: 获取文档基础数据
    const documentData = await getDocument(fileId);
    if (documentData.error) {
      return { error: documentData.error, status: documentData.status || 500 };
    }

    // 步骤2: 查询评查结果
    const evaluationResultsParams: PostgrestParams = {
      select: '*',
      filter: { 'document_id': `eq.${fileId}` }
    };
    const evaluationResultsResponse = await postgrestGet('evaluation_results', evaluationResultsParams);

    if (evaluationResultsResponse.error) {
      return { error: evaluationResultsResponse.error, status: evaluationResultsResponse.status };
    }

    const evaluationResultsData = extractApiData<EvaluationResult[]>(evaluationResultsResponse.data) || [];
    
    if (evaluationResultsData.length <= 0) {
      return { 
        data: [], 
        stats: { total: 0, success: 0, warning: 0, error: 0, score: 0 },
        error: '获取评查结果数据失败' 
      };
    }

    // 步骤3: 获取评查点详情
    const evaluationPointIds = evaluationResultsData.map(item => item.evaluation_point_id).filter(Boolean);
    
    const evaluationPointsParams: PostgrestParams = {
      select: '*',
      filter: { 'id': `in.(${evaluationPointIds.join(',')})` }
    };
    const evaluationPointsResponse = await postgrestGet('evaluation_points', evaluationPointsParams);

    if (evaluationPointsResponse.error) {
      return { error: evaluationPointsResponse.error, status: evaluationPointsResponse.status };
    }

    const evaluationPointsData = extractApiData<EvaluationPoint[]>(evaluationPointsResponse.data) || [];

    // 步骤4: 数据处理和转换
    const resultData: ReviewPointResult[] = evaluationResultsData.map(result => {
      const point = evaluationPointsData.find(p => p.id === result.evaluation_point_id);
      
      return {
        id: result.id,
        title: result.evaluated_results?.message || '',
        groupName: point?.group_name || '',
        status: point?.suggestion_message_type || '',
        content: result.evaluated_results?.data || '',
        suggestion: point?.suggestion_message || '',
        result: result.evaluated_results?.result,
        score: point?.score || 0
      };
    });

    // 步骤5: 统计数据计算
    const stats = {
      total: resultData.length,
      success: resultData.filter(item => item.result === true).length,
      warning: resultData.filter(item => item.status === 'warning').length,
      error: resultData.filter(item => item.status === 'error').length,
      score: resultData.reduce((sum, item) => sum + item.score, 0)
    };

    return { 
      data: resultData, 
      stats, 
      document: documentData.data 
    };
  } catch (error) {
    console.error('获取评查数据失败:', error);
    return { 
      error: error instanceof Error ? error.message : '获取评查数据失败',
      status: 500 
    };
  }
}

/**
 * 更新评查结果
 * @param resultId 评查结果ID
 * @param editAuditStatusId 审核状态ID
 * @param result 评查结果
 * @param message 评查意见
 */
export async function updateReviewResult(
  resultId: string, 
  editAuditStatusId: string | number, 
  result: string, 
  message: string
): Promise<{
  data?: unknown;
  error?: string;
  status?: number;
}> {
  try {
    if (!resultId) {
      return { error: '评查结果ID不能为空', status: 400 };
    }
    
    // 获取当前数据
    const currentResultResponse = await postgrestGet('evaluation_results', {
      select: '*',
      filter: { id: `eq.${resultId}` }
    });
    
    if (currentResultResponse.error) {
      return { error: currentResultResponse.error, status: currentResultResponse.status };
    }
    
    const currentResultData = extractApiData<EvaluationResult[]>(currentResultResponse.data);
    
    if (!currentResultData || currentResultData.length === 0) {
      return { error: '未找到评查结果数据', status: 404 };
    }
    
    const currentResult = currentResultData[0];
    const currentEvaluatedResults = currentResult.evaluated_results || {};
    
    // 构建更新数据
    const isReview = result === 'review';
    const updatedEvaluatedResults = {
      ...currentEvaluatedResults,
      ...(isReview ? { message } : { result: result === 'true', message }),
    };
    
    // 更新评查结果
    const resultResponse = await postgrestPut(
      'evaluation_results',
      { evaluated_results: updatedEvaluatedResults },
      { id: resultId }
    );
    
    if (resultResponse.error) {
      return { error: resultResponse.error, status: resultResponse.status };
    }
    
    // 处理审核状态
    const editAuditStatusValue = isReview ? 0 : 1;
    
    if (editAuditStatusId && editAuditStatusId !== '') {
      // 更新现有记录
      const auditStatusResponse = await postgrestPut(
        'audit_status',
        { edit_audit_status: editAuditStatusValue },
        { id: editAuditStatusId }
      );
      
      if (auditStatusResponse.error) {
        return { error: auditStatusResponse.error, status: auditStatusResponse.status };
      }
    } else {
      // 创建新记录
      const newAuditStatus = {
        document_id: currentResult.document_id,
        evaluation_point_id: currentResult.evaluation_point_id,
        evaluation_result_id: resultId,
        edit_audit_status: editAuditStatusValue
      };
      
      const postResponse = await postgrestPost('audit_status', newAuditStatus);
      
      if (postResponse.error) {
        return { error: postResponse.error, status: postResponse.status };
      }
    }
    
    return { data: extractApiData<unknown>(resultResponse.data) };
  } catch (error) {
    console.error('更新评查结果失败:', error);
    return {
      error: error instanceof Error ? error.message : '更新评查结果失败',
      status: 500
    };
  }
}
```

#### 3. 错误处理规范

```typescript
// 统一的错误处理格式
interface ApiResponse<T> {
  data?: T;
  error?: string;
  status?: number;
}

// 在API函数中的错误处理
export async function apiFunction(): Promise<ApiResponse<DataType>> {
  try {
    const response = await postgrestGet('table_name', params);
    
    if (response.error) {
      return { 
        error: response.error, 
        status: response.status 
      };
    }
    
    const data = extractApiData<DataType>(response.data);
    
    if (!data) {
      return { 
        error: '数据格式错误', 
        status: 500 
      };
    }
    
    return { data };
  } catch (error) {
    console.error('API调用失败:', error);
    return {
      error: error instanceof Error ? error.message : '未知错误',
      status: 500
    };
  }
}
```

### 前端路由集成规范

#### 1. Loader函数中调用API

```typescript
// app/routes/reviews.tsx
import { getReviewPoints, updateReviewResult, confirmReviewResults } from "~/api/evaluation_points/reviews";

export async function loader({ request }: LoaderFunctionArgs) {
  try {
    const url = new URL(request.url);
    const id = url.searchParams.get('id') || undefined;
    const previousRoute = url.searchParams.get('previousRoute') || '';
    
    if (!id) {
      return Response.json({ result: false, message: '文件ID不能为空' });
    }

    // 获取评查点数据
    const reviewData = await getReviewPoints(id);

    if ('error' in reviewData && reviewData.error) {
      console.error("获取评查点数据错误:", reviewData.error);
      return Response.json({ result: false, message: reviewData.error });
    }

    // 确保数据格式正确
    if ('document' in reviewData && 'data' in reviewData && 'reviewInfo' in reviewData && 'stats' in reviewData) {
      return Response.json({
        previousRoute: previousRoute,
        document: reviewData.document,
        reviewPoints: reviewData.data,
        reviewInfo: reviewData.reviewInfo,
        statistics: reviewData.stats
      });
    } else {
      console.error("返回的评查数据格式不正确", JSON.stringify(reviewData, null, 2));
      return Response.json({ result: false, message: '返回的评查数据格式不正确' });
    }
  } catch (error) {
    console.error('获取评查数据失败:', error);
    return Response.json({ result: false, message: '获取评查数据失败' });
  }
}
```

#### 2. 组件中处理API响应

```typescript
// 在React组件中使用
export default function ReviewDetails() {
  const loaderData = useLoaderData<typeof loader>();
  const { document, reviewPoints, statistics, reviewInfo } = loaderData;
  const [isLoading, setIsLoading] = useState(false);
  
  // 处理loader错误
  useEffect(() => {
    if (Object.keys(loaderData).find(key => key === 'result') && !loaderData.result) {
      messageService.show({
        title: '错误',
        message: loaderData.message,
        type: 'error',
        confirmText: '确定',
        onConfirm: () => {
          navigate(-1);
        }
      });
    }
  }, [loaderData, navigate]);

  // 处理状态更新
  const handleReviewPointStatusChange = async (
    reviewPointResultId: string, 
    editAuditStatusId: string | number, 
    newStatus: string, 
    message: string
  ) => {
    try {
      const response = await updateReviewResult(
        reviewPointResultId, 
        editAuditStatusId, 
        newStatus, 
        message
      );
      
      if (response.error) {
        console.error('更新评查结果失败:', response.error);
        toastService.error(`更新评查结果失败: ${response.error}`);
        return;
      }
      
      // 更新本地状态
      setReviewData(prevData => {
        // 更新逻辑...
      });
      
      toastService.success('评查点状态已更新');
    } catch (error) {
      console.error('更新评查结果出错:', error);
      toastService.error('更新评查结果失败，请稍后重试');
    }
  };
}
```

### 数据类型定义规范

#### 1. 数据库实体类型

```typescript
// 数据库表对应的接口
interface Document {
  id: number;
  user_id: number | null;
  type_id: number;
  name: string;
  document_number: string;
  path: string;
  storage_type: string;
  file_size: number;
  upload_time: string;
  is_test_document: boolean;
  evaluation_level: string;
  status: 'pass' | 'warning' | 'waiting' | 'processing' | 'fail';
  file_status: 'Waiting' | 'Cutting' | 'Extractioning' | 'Evaluationing' | 'Processed';
  audit_status: number; // -1: 不通过, 0: 待审核, 1: 通过, 2: 警告, 3: 审核中
  ocr_result?: Record<string, unknown>;
  extracted_results?: unknown;
  summary?: unknown;
  remark?: string;
  created_at: string;
  updated_at: string;
}
```

#### 2. 前端UI类型

```typescript
// 前端组件使用的接口
interface ReviewFileUI {
  id: string;
  status: string;
  path: string;
  fileName: string;
  fileCode: string;
  fileType: string;
  fileTypeId: number;
  fileSize: number;
  uploadTime: string;
  reviewStatus: string;
  reviewStatusCode: number;
  issueCount: number;
  score?: number;
  auditStatus: number | null;
  issues: Array<{
    severity: 'info' | 'warning' | 'error' | 'critical';
    message: string;
  }>;
  createdBy: string;
  passCount: number;
  warningCount: number;
  failCount: number;
  manualCount: number;
}
```

#### 3. API参数类型

```typescript
// 搜索参数类型
interface DocumentSearchParams {
  keyword?: string;
  status?: string;
  fileType?: string;
  dateRange?: [string, string];
  page?: number;
  pageSize?: number;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
}
```

### PostgREST客户端功能

#### 1. 查询参数转换

```typescript
// 转换通用参数为PostgREST格式
export function transformParams(params: PostgrestParams): QueryParams {
  const result: QueryParams = {};
  
  // 处理select参数
  if (params.select) {
    result.select = params.select;
  }
  
  // 处理过滤条件
  if (params.filter) {
    Object.entries(params.filter).forEach(([key, value]) => {
      if (value !== undefined) {
        result[key] = value as string | number | boolean;
      }
    });
  }
  
  // 处理排序
  if (params.order) {
    result.order = params.order;
  }
  
  // 处理分页
  if (params.limit !== undefined) {
    result.limit = params.limit;
  }
  
  if (params.offset !== undefined) {
    result.offset = params.offset;
  }
  
  // 处理OR条件
  if (params.or) {
    if (typeof params.or === 'string') {
      result.or = params.or;
    } else if (Array.isArray(params.or)) {
      const orConditions = params.or.map(condition => {
        const [field, operator] = Object.entries(condition)[0];
        return `${field}.${operator}`;
      });
      result.or = `(${orConditions.join(',')})`;
    }
  }
  
  return result;
}
```

#### 2. 开发环境日志

```typescript
function logPostgrestQuery(endpoint: string, params?: QueryParams, method: string = 'GET'): void {
  if (process.env.NODE_ENV !== 'production') {
    const baseUrl = 'http://nas.7bm.co:3000';
    const normalizedEndpoint = endpoint.startsWith('/') ? endpoint.substring(1) : endpoint;
    
    // console.log('\n📦 PostgREST 查询日志 ======================start=============');
    // console.log(`📦 HTTP 方法: ${method}`);
    // console.log(`📦 API 端点: ${decodeUrlForDisplay(`${baseUrl}/${normalizedEndpoint}`)}`);
    
    // if (params && Object.keys(params).length > 0) {
    //   console.log('📦 查询参数:');
    //   Object.entries(params).forEach(([key, value]) => {
    //     if (value !== undefined) {
    //       console.log(`  - ${key}: ${JSON.stringify(value)}`);
    //     }
    //   });
    // }
    
    // console.log('PostgREST 查询日志=============================end============\n');
  }
}
```

#### 3. 数据预处理

```typescript
function preprocessData(data: Record<string, unknown>): Record<string, unknown> {
  const processed: Record<string, unknown> = {};
  
  for (const [key, value] of Object.entries(data)) {
    // 处理null值
    if (value === null) {
      processed[key] = null;
      continue;
    }
    
    // 处理布尔值字符串
    if (typeof value === 'string' && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) {
      processed[key] = value.toLowerCase() === 'true';
    }
    // 处理ID字段
    else if ((key === 'id' || key.endsWith('_id') || key === 'pid') && value !== undefined) {
      try {
        const numValue = Number(value);
        if (!isNaN(numValue)) {
          processed[key] = numValue;
        } else {
          processed[key] = value;
        }
      } catch {
        processed[key] = value;
      }
    }
    // 其他值保持不变
    else {
      processed[key] = value;
    }
  }
  
  return processed;
}
```

### 开发最佳实践

#### 1. API命名规范
- 获取数据: `get[EntityName]s()` 或 `get[EntityName]()`
- 创建数据: `create[EntityName]()`
- 更新数据: `update[EntityName]()`
- 删除数据: `delete[EntityName]()`

#### 2. 错误处理策略
- 所有API函数必须返回统一的响应格式
- 在API层处理数据库错误，前端只处理业务逻辑错误
- 使用TypeScript严格类型检查避免运行时错误

#### 3. 性能优化
- 使用`select`参数只获取需要的字段
- 合理使用`limit`和`offset`进行分页
- 避免N+1查询，使用关联查询获取相关数据

#### 4. 调试技巧
- 开发环境自动打印查询日志
- 使用浏览器网络面板检查实际请求
- 通过PostgREST文档验证查询语法

### 数据对接检查清单

#### 新功能开发前
- [ ] 确认数据库表结构和关系
- [ ] 定义TypeScript接口类型
- [ ] 规划API函数命名和参数
- [ ] 设计错误处理策略

#### API实现阶段
- [ ] 导入必要的postgrest方法
- [ ] 实现extractApiData数据提取函数
- [ ] 定义所有相关的类型接口
- [ ] 编写查询参数构建逻辑
- [ ] 实现数据转换和处理逻辑
- [ ] 添加完整的错误处理

#### 前端集成阶段
- [ ] 在loader函数中调用API
- [ ] 处理loading和error状态
- [ ] 实现UI状态更新逻辑
- [ ] 添加用户反馈(toast/message)
- [ ] 测试各种边界情况

#### 上线前检查
- [ ] API函数测试通过
- [ ] 错误处理验证完成
- [ ] 性能测试满足要求
- [ ] 日志输出正常
- [ ] 代码注释完整

---

*此数据对接规范基于实际项目经验总结，将根据项目发展持续更新和完善。*