# 首页数据统计 API 分析文档

## 文件位置
`app/api/home/home.ts`

## 概述
该文件提供首页数据统计功能，包括文档审核状态、通过率、问题检测等核心业务指标的统计和同比分析。

## 核心功能

### 主函数：`getHomeData()`

**函数签名：**
```typescript
async function getHomeData(
  reviewType?: string | null,  // 文档类型: 'contract' | 'record' | null
  userId?: string | number,    // 用户ID
  token?: string               // JWT token
): Promise<HomeStatistics>
```

**返回数据结构：**
```typescript
interface HomeStatistics {
  todayPendingFiles: number;              // 今日待审核文件数
  monthlyReviewedFiles: number;           // 本月已审核文件数
  monthlyReviewGrowth: {                  // 本月审核文件同比增长
    value: number;                        // 增长百分比（绝对值）
    isUp: boolean;                        // 是否增长
  };
  monthlyPassRate: number;                // 本月审核通过率
  passRateGrowth: {                       // 通过率同比增长
    value: number;
    isUp: boolean;
  };
  issuesDetected: number;                 // 检测到的问题总数
  issuesGrowth: {                         // 问题数量同比增长
    value: number;
    isUp: boolean;
  };
}
```

---

## 数据库查询详解

### 1. 今日待审核文件数

**业务逻辑：**
统计今天创建的、状态为待审核的文件数量（`audit_status = 0 或 2 或 NULL`）

**PostgREST 参数：**
```typescript
{
  select: 'count',
  filter: {
    or: '(audit_status.eq.0,audit_status.eq.2,audit_status.is.null)',
    created_at: `gte.${startOfToday}`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}
```

**等价 SQL 查询：**
```sql
SELECT COUNT(*)
FROM documents
WHERE (audit_status = 0 OR audit_status = 2 OR audit_status IS NULL)
  AND created_at >= '2025-11-17 00:00:00'  -- 今天开始时间
  AND is_test_document = false
  AND user_id = ${userId}
  AND (type_id = 1);  -- 如果 reviewType = 'contract'
  -- 或 (type_id = 2 OR type_id = 3);  -- 如果 reviewType = 'record'
```

**状态说明：**
- `audit_status = 0`: 未审核
- `audit_status = 2`: 审核中
- `audit_status = NULL`: 未设置状态

---

### 2. 本月已审核文件数

**业务逻辑：**
统计本月上传的、已完成审核的文件数量（`audit_status ≠ 0 且 ≠ 2`）

**PostgREST 参数：**
```typescript
{
  select: 'count',
  filter: {
    and: '(audit_status.neq.0,audit_status.neq.2)',
    upload_time: `gte.${startOfThisMonth}`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}
```

**等价 SQL 查询：**
```sql
SELECT COUNT(*)
FROM documents
WHERE audit_status != 0
  AND audit_status != 2
  AND upload_time >= '2025-11-01 00:00:00'  -- 本月开始
  AND is_test_document = false
  AND user_id = ${userId}
  AND type_id = 1;  -- 根据 reviewType 过滤
```

---

### 3. 上月已审核文件数

**业务逻辑：**
统计上月的已审核文件数量，用于计算同比增长

**PostgREST 参数：**
```typescript
{
  select: 'count',
  filter: {
    and: `(upload_time.gte.${startOfLastMonth},upload_time.lte.${endOfLastMonth},audit_status.neq.0,audit_status.neq.2)`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}
```

**等价 SQL 查询：**
```sql
SELECT COUNT(*)
FROM documents
WHERE upload_time >= '2025-10-01 00:00:00'  -- 上月开始
  AND upload_time <= '2025-10-31 23:59:59'  -- 上月结束
  AND audit_status != 0
  AND audit_status != 2
  AND is_test_document = false
  AND user_id = ${userId}
  AND type_id = 1;
```

**增长率计算：**
```typescript
// 同比增长百分比
const growthRate = ((本月数量 - 上月数量) / 上月数量) * 100;
reviewGrowthValue = Math.abs(parseFloat(growthRate.toFixed(1)));
reviewGrowthIsUp = growthRate >= 0;

// 特殊情况：上月为0，本月大于0
if (lastMonthReviewed == 0 && monthlyReviewedFiles > 0) {
  reviewGrowthValue = 100;
  reviewGrowthIsUp = true;
}
```

---

### 4. 本月审核通过数量

**业务逻辑：**
统计本月审核通过的文件数量（`audit_status = 1`）

**PostgREST 参数：**
```typescript
{
  select: 'count',
  filter: {
    audit_status: 'eq.1',
    created_at: `gte.${startOfThisMonth}`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}
```

**等价 SQL 查询：**
```sql
SELECT COUNT(*)
FROM documents
WHERE audit_status = 1  -- 审核通过
  AND created_at >= '2025-11-01 00:00:00'
  AND is_test_document = false
  AND user_id = ${userId}
  AND type_id = 1;
```

**通过率计算：**
```typescript
const monthlyPassRate = (thisMonthPassTotal > 0 && monthlyReviewedFiles > 0)
  ? parseFloat(((thisMonthPassTotal / monthlyReviewedFiles) * 100).toFixed(1))
  : 0;
```

---

### 5. 上月审核通过数量与通过率

**PostgREST 参数：**
```typescript
{
  select: 'count',
  filter: {
    audit_status: 'eq.1',
    and: `(upload_time.gte.${startOfLastMonth},upload_time.lte.${endOfLastMonth})`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}
```

**等价 SQL 查询：**
```sql
SELECT COUNT(*)
FROM documents
WHERE audit_status = 1
  AND upload_time >= '2025-10-01 00:00:00'
  AND upload_time <= '2025-10-31 23:59:59'
  AND is_test_document = false
  AND user_id = ${userId};
```

**通过率增长计算：**
```typescript
const lastMonthPassRate = (lastMonthTotal > 0 && lastMonthReviewed > 0)
  ? parseFloat(((lastMonthTotal / lastMonthReviewed) * 100).toFixed(1))
  : 0;

if (lastMonthPassRate > 0) {
  const passRateGrowth = ((monthlyPassRate - lastMonthPassRate) / lastMonthPassRate) * 100;
  passRateGrowthValue = Math.abs(parseFloat(passRateGrowth.toFixed(1)));
  passRateGrowthIsUp = passRateGrowth >= 0;
} else if (lastMonthPassRate == 0 && monthlyPassRate > 0) {
  passRateGrowthValue = 100;
  passRateGrowthIsUp = true;
}
```

---

### 6. 问题检测统计（调用数据库函数）

**业务逻辑：**
通过 RPC 调用 PostgreSQL 存储函数 `count_evaluation_results_by_type` 统计评估结果中的问题数量

#### 6.1 合同类型（reviewType = 'contract'）

**RPC 调用参数：**
```typescript
{
  start_time: '2025-11-01 00:00:00',
  end_time: '2025-11-30 23:59:59',
  type_val: [1],  // 合同类型ID
  userid: parseInt(userId)
}
```

**等价 SQL（推测函数实现）：**
```sql
-- 数据库函数 count_evaluation_results_by_type 的可能实现
CREATE OR REPLACE FUNCTION count_evaluation_results_by_type(
  start_time TIMESTAMP,
  end_time TIMESTAMP,
  type_val INTEGER[],
  userid INTEGER
) RETURNS TABLE(count BIGINT) AS $$
BEGIN
  RETURN QUERY
  SELECT COUNT(*)
  FROM evaluation_results er
  JOIN documents d ON er.document_id = d.id
  WHERE d.type_id = ANY(type_val)
    AND d.user_id = userid
    AND er.created_at >= start_time
    AND er.created_at <= end_time
    AND d.is_test_document = false;
END;
$$ LANGUAGE plpgsql;
```

#### 6.2 记录类型（reviewType = 'record'）

**RPC 调用参数：**
```typescript
{
  start_time: '2025-11-01 00:00:00',
  end_time: '2025-11-30 23:59:59',
  type_val: [2, 3],  // 许可卷宗类型ID
  userid: parseInt(userId)
}
```

**问题增长率计算：**
```typescript
if (lastMonthIssuesCount > 0) {
  const issuesGrowth = ((thisMonthIssuesCount - lastMonthIssuesCount) / lastMonthIssuesCount) * 100;
  issuesGrowthValue = Math.abs(parseFloat(issuesGrowth.toFixed(1)));
  issuesGrowthIsUp = issuesGrowth >= 0;
} else if (lastMonthIssuesCount == 0 && thisMonthIssuesCount > 0) {
  issuesGrowthValue = 100;
  issuesGrowthIsUp = true;
}
```

---

## 辅助函数

### 1. `buildTypeFilter()` - 类型过滤构建

**功能：** 根据 `reviewType` 参数构建 PostgREST 过滤条件

```typescript
function buildTypeFilter(reviewType: string | null): string {
  let typeFilter = '';
  if (reviewType === 'contract') {
    typeFilter = 'type_id.eq.1';           // 合同类型
  } else if (reviewType === 'record') {
    typeFilter = '(type_id.eq.2,type_id.eq.3)';  // 记录类型（OR条件）
  }
  return typeFilter;
}
```

### 2. `extractApiData()` - API 响应数据提取

**功能：** 统一处理不同格式的 API 响应，提取真实数据

**支持的响应格式：**
```typescript
// 格式1: { code: number, msg: string, data: T }
{ code: 0, msg: 'success', data: [...] }

// 格式2: 直接返回数据
[{ count: 10 }]

// 错误格式
{ code: 500, msg: 'error' }
{ error: 'something went wrong' }
```

### 3. `handleApiResponse()` - API 调用错误处理

**功能：** 封装 API 调用、错误处理和默认值返回

```typescript
const handleApiResponse = async <T>(
  apiCall: Promise<ApiResponse>,
  errorMessage: string,
  defaultValue: T
): Promise<T> => {
  try {
    const response = await apiCall;
    if (response.error) {
      console.error(`${errorMessage}: ${response.error}`);
      return defaultValue;
    }
    const data = extractApiData<T>(response.data);
    return data || defaultValue;
  } catch (error) {
    console.error(`${errorMessage}: ${error.message}`);
    return defaultValue;
  }
};
```

---

## 时间范围计算

使用 `dayjs` 库进行时间计算：

```typescript
// 今天开始时间
const startOfToday = dayjs().startOf('day').format('YYYY-MM-DD HH:mm:ss');
// 输出: '2025-11-17 00:00:00'

// 本月开始/结束
const startOfThisMonth = dayjs().startOf('month').format('YYYY-MM-DD HH:mm:ss');
const endOfThisMonth = dayjs().endOf('month').format('YYYY-MM-DD HH:mm:ss');
// 输出: '2025-11-01 00:00:00' ~ '2025-11-30 23:59:59'

// 上月开始/结束
const startOfLastMonth = dayjs().subtract(1, 'month').startOf('month').format('YYYY-MM-DD HH:mm:ss');
const endOfLastMonth = dayjs().subtract(1, 'month').endOf('month').format('YYYY-MM-DD HH:mm:ss');
// 输出: '2025-10-01 00:00:00' ~ '2025-10-31 23:59:59'
```

---

## 数据库表结构（推测）

### `documents` 表
```sql
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  user_id INTEGER NOT NULL,
  type_id INTEGER NOT NULL,  -- 1: 合同, 2/3: 记录
  audit_status INTEGER,       -- 0: 未审核, 1: 通过, 2: 审核中, -1: 不通过
  created_at TIMESTAMP,
  upload_time TIMESTAMP,
  is_test_document BOOLEAN DEFAULT false,
  -- 其他字段...
);

-- 索引优化建议
CREATE INDEX idx_documents_user_status ON documents(user_id, audit_status);
CREATE INDEX idx_documents_created_at ON documents(created_at);
CREATE INDEX idx_documents_upload_time ON documents(upload_time);
CREATE INDEX idx_documents_type_id ON documents(type_id);
```

### `evaluation_results` 表（推测）
```sql
CREATE TABLE evaluation_results (
  id SERIAL PRIMARY KEY,
  document_id INTEGER REFERENCES documents(id),
  created_at TIMESTAMP,
  -- 评估结果字段...
);

CREATE INDEX idx_eval_results_doc_created ON evaluation_results(document_id, created_at);
```

---

## 性能优化建议

### 1. 数据库优化
- ✅ 使用复合索引：`(user_id, audit_status, created_at)`
- ✅ 分离时间范围查询：避免在 `AND` 条件中混用多个时间字段
- ✅ 使用物化视图：定期统计常用指标

### 2. 缓存策略
```typescript
// 建议添加 Redis 缓存
const cacheKey = `home:stats:${userId}:${reviewType}:${date}`;
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);

// 查询后缓存 5 分钟
await redis.setex(cacheKey, 300, JSON.stringify(result));
```

### 3. 并行查询优化
当前实现是串行查询，可以改为并行：
```typescript
const [
  todayPending,
  thisMonthReviewed,
  lastMonthReviewed,
  thisMonthPassed,
  lastMonthPassed,
  thisMonthIssues,
  lastMonthIssues
] = await Promise.all([
  // 所有查询并行执行
]);
```

---

## 错误处理机制

### 1. 单个查询失败
- 返回默认值（如 `[]` 或 `0`）
- 记录错误日志但不中断整体流程

### 2. 整体失败
```typescript
catch (error) {
  console.error('获取首页数据失败:', error.message);
  return {
    todayPendingFiles: 0,
    monthlyReviewedFiles: 0,
    monthlyReviewGrowth: { value: 0, isUp: true },
    monthlyPassRate: 0,
    passRateGrowth: { value: 0, isUp: true },
    issuesDetected: 0,
    issuesGrowth: { value: 0, isUp: true }
  };
}
```

---

## 使用示例

```typescript
// 在 Remix loader 中使用
export async function loader({ request }: LoaderFunctionArgs) {
  const session = await getUserSession(request);
  const userId = session.get('user_id');
  const token = session.get('jwt_token');

  const homeData = await getHomeData('contract', userId, token);

  return json({ homeData });
}
```

---

## 注意事项

1. **类型过滤逻辑：**
   - `contract` → `type_id = 1`
   - `record` → `type_id = 2 OR type_id = 3`
   - `null` → 不过滤类型

2. **日期字段不一致：**
   - 待审核文件使用 `created_at`
   - 已审核文件使用 `upload_time`
   - 通过率统计本月用 `created_at`，上月用 `upload_time`

3. **增长率计算边界情况：**
   - 上月为0时，增长率固定为 100%
   - 本月和上月都为0时，增长率为 0%

4. **Token 传递：**
   - JWT token 需要在每个 API 调用中传递
   - 通过 `postgrestGet/postgrestPost` 的 `token` 参数传递

---

## 改进建议

### 1. 统一时间字段
建议数据库统一使用 `created_at` 或 `upload_time`，避免混用造成统计不一致。

### 2. 添加 TypeScript 类型守卫
```typescript
function isValidAuditStatus(status: unknown): status is number {
  return typeof status === 'number' && [0, 1, 2, -1].includes(status);
}
```

### 3. 提取常量
```typescript
const AUDIT_STATUS = {
  PENDING: 0,
  PASSED: 1,
  IN_PROGRESS: 2,
  REJECTED: -1
} as const;

const DOCUMENT_TYPES = {
  CONTRACT: 1,
  RECORD_TYPE_2: 2,
  RECORD_TYPE_3: 3
} as const;
```

### 4. 添加请求日志
```typescript
console.log(`[HomeStats] User: ${userId}, Type: ${reviewType}, Duration: ${Date.now() - startTime}ms`);
```