From 1223bcfb23aaaf6ec0512ea87dd13f499abded30 Mon Sep 17 00:00:00 2001
From: snowgitea <haoyuexc100@outlook.com>
Date: Wed, 29 Apr 2026 10:53:41 +0800
Subject: [PATCH] chore: add frontend/src/types/index.ts

---
 frontend/src/types/index.ts | 162 ++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 frontend/src/types/index.ts

diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
new file mode 100644
index 0000000..41caa67
--- /dev/null
+++ b/frontend/src/types/index.ts
@@ -0,0 +1,162 @@
+/**
+ * 类型定义 - Type Definitions
+ * 功能：定义个人财务系统前后端数据契约，确保类型安全
+ * 使用场景：API 请求/响应、状态管理、组件 props、表单数据
+ */
+
+/**
+ * 用户接口 - 对应数据库 fa_user 表
+ */
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+/**
+ * 账户接口 - 对应数据库 fa_account 表
+ * 用于区分不同资金账户（如微信、支付宝、银行卡、现金）
+ */
+export interface Account {
+  id: number;
+  userId: number;       // 所属用户 ID，用于权限校验
+  name: string;         // 账户名称（如"微信钱包"）
+  type: string;         // 账户类型（如"cash"、"bank"、"digital"）
+  color: string;        // 账户图标颜色
+  balance: number;      // 当前余额
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * 账单记录接口 - 对应数据库 fa_record 表
+ * 核心业务实体，记录每一笔收支
+ */
+export interface Record {
+  id: number;
+  userId: number;       // 所属用户 ID
+  accountId: number;    // 关联账户 ID
+  type: 'income' | 'expense';  // 收支类型
+  amount: number;       // 金额（正数）
+  category: string;     // 分类名称（如"餐饮"、"工资"）
+  description: string;  // 备注说明
+  date: string;         // 账单日期（用户选择的日期）
+  account: Account;     // 关联账户详情（JOIN 查询填充）
+  createdAt: string;    // 创建时间（用于排序和相对时间显示）
+  updatedAt: string;
+}
+
+/**
+ * 预算配置接口 - 对应数据库 fa_budget 表
+ * 用于设定各分类的月度预算上限
+ */
+export interface Budget {
+  id: number;
+  userId: number;       // 所属用户 ID
+  category: string;     // 预算分类
+  amount: number;       // 预算金额上限
+  month: string;        // 预算月份（格式：YYYY-MM）
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * 预算使用状态接口 - 扩展 Budget，增加实际支出和使用率
+ * 用于仪表盘和预算页面的进度展示
+ */
+export interface BudgetWithUsage extends Budget {
+  spent: number;        // 当月该分类实际支出总额
+  percentage: number;   // 预算使用百分比（spent / amount * 100）
+}
+
+/**
+ * 仪表盘汇总接口 - GET /api/statistics/dashboard 返回数据
+ * 聚合数据，避免前端多次请求
+ */
+export interface DashboardSummary {
+  totalBalance: number;           // 所有账户总余额
+  monthIncome: number;            // 本月总收入
+  monthExpense: number;           // 本月总支出
+  accounts: Account[];            // 账户列表
+  budgetUsage: BudgetWithUsage[]; // 预算使用情况列表
+}
+
+/**
+ * 月度统计接口 - 用于月度报表页面
+ */
+export interface MonthlyStats {
+  totalIncome: number;
+  totalExpense: number;
+  balance: number;                // 本月结余（收入 - 支出）
+  categoryStats: Array<{
+    category: string;
+    amount: number;
+  }>;
+}
+
+/**
+ * 趋势统计接口 - GET /api/statistics/trend 返回数据
+ * 用于折线图展示每日收支趋势
+ */
+export interface TrendStat {
+  date: string;       // 日期（格式：YYYY-MM-DD）
+  income: number;     // 当日收入
+  expense: number;    // 当日支出
+}
+
+/**
+ * 月度对比接口 - GET /api/statistics/monthly-compare 返回数据
+ * 用于柱状图对比本月与上月的收支差异
+ */
+export interface MonthlyCompare {
+  currentMonth: {
+    label: string;    // 月份标签（如"2024年1月"）
+    income: number;
+    expense: number;
+  };
+  lastMonth: {
+    label: string;
+    income: number;
+    expense: number;
+  };
+}
+
+/**
+ * 统一 API 响应接口 - 所有后端接口返回的标准格式
+ */
+export interface ApiResponse<T> {
+  success: boolean;   // 请求是否成功
+  data: T;            // 响应数据（泛型支持）
+  message?: string;   // 错误信息（可选）
+}
+
+/**
+ * 账单表单数据接口 - 新增/编辑账单时的表单输入
+ * 与 Record 的区别：不含 id、createdAt、updatedAt 等系统字段
+ */
+export interface RecordFormData {
+  type: 'income' | 'expense';
+  amount: number;
+  category: string;
+  description: string;
+  date: string;
+  accountId: number;
+}
+
+/**
+ * 预算表单数据接口 - 新增/编辑预算时的表单输入
+ */
+export interface BudgetFormData {
+  category: string;
+  amount: number;
+  month: string;
+}
+
+/**
+ * 按日期分组的记录接口 - 用于按日期分组展示账单列表
+ * key 为日期字符串（如 "2024-01-15"），值为该日期的记录数组
+ */
+export interface DateGroupedRecords {
+  [key: string]: Record[];
+}