leaudit-platform-frontend/docs/home-api-analysis.md

首页数据统计 API 分析文档

文件位置

app/api/home/home.ts

概述

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

核心功能

主函数：getHomeData()

函数签名：

async function getHomeData(
  reviewType?: string | null,  // 文档类型: 'contract' | 'record' | null
  userId?: string | number,    // 用户ID
  token?: string               // JWT token
): Promise<HomeStatistics>

返回数据结构：

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 参数：

{
  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 查询：

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 参数：

{
  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 查询：

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 参数：

{
  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 查询：

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;

增长率计算：

// 同比增长百分比
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 参数：

{
  select: 'count',
  filter: {
    audit_status: 'eq.1',
    created_at: `gte.${startOfThisMonth}`,
    is_test_document: 'eq.false',
    user_id: `eq.${userId}`
  }
}

等价 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;

通过率计算：

const monthlyPassRate = (thisMonthPassTotal > 0 && monthlyReviewedFiles > 0)
  ? parseFloat(((thisMonthPassTotal / monthlyReviewedFiles) * 100).toFixed(1))
  : 0;

---

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

PostgREST 参数：

{
  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 查询：

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};

通过率增长计算：

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 调用参数：

{
  start_time: '2025-11-01 00:00:00',
  end_time: '2025-11-30 23:59:59',
  type_val: [1],  // 合同类型ID
  userid: parseInt(userId)
}

等价 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 调用参数：

{
  start_time: '2025-11-01 00:00:00',
  end_time: '2025-11-30 23:59:59',
  type_val: [2, 3],  // 许可卷宗类型ID
  userid: parseInt(userId)
}

问题增长率计算：

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 过滤条件

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 响应，提取真实数据

支持的响应格式：

// 格式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 调用、错误处理和默认值返回

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 库进行时间计算：

// 今天开始时间
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 表

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 表（推测）

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. 缓存策略

// 建议添加 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. 并行查询优化

当前实现是串行查询，可以改为并行：

const [
  todayPending,
  thisMonthReviewed,
  lastMonthReviewed,
  thisMonthPassed,
  lastMonthPassed,
  thisMonthIssues,
  lastMonthIssues
] = await Promise.all([
  // 所有查询并行执行
]);

---

错误处理机制

1. 单个查询失败

• 返回默认值（如 [] 或 0）
• 记录错误日志但不中断整体流程

2. 整体失败

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 }
  };
}

---

使用示例

// 在 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 类型守卫

function isValidAuditStatus(status: unknown): status is number {
  return typeof status === 'number' && [0, 1, 2, -1].includes(status);
}

3. 提取常量

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. 添加请求日志

console.log(`[HomeStats] User: ${userId}, Type: ${reviewType}, Duration: ${Date.now() - startTime}ms`);