Skip to content

CLAUDE.md

Latest commit

 

History

History
253 lines (182 loc) · 7.51 KB

CLAUDE.md

File metadata and controls

253 lines (182 loc) · 7.51 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

信用卡支出分析看板 - 基于 Streamlit 构建的信用卡消费数据分析工具，支持多维度消费分析、趋势追踪和 AI 智能洞察。

常用命令

运行应用

# 直接运行
streamlit run app.py

数据提取

# 从 PST 文件提取信用卡账单（招商银行）
python tools/extract_credit_card_bills.py

依赖安装

pip install -r requirements.txt

测试 LLM 连接

# 测试智谱 GLM API 连接
python -m utils.llm_caller

项目架构

目录结构

SpendAnalysis/
├── app.py                      # Streamlit 主应用（数据概览页面）
├── config.py                   # 全局配置
├── utils/                      # 核心工具模块
│   ├── data_loader.py          # CSV 数据加载和预处理
│   ├── analyzer.py             # 数据分析函数
│   ├── classifier.py           # 商户智能分类（含 LLM 二次分类）
│   ├── llm_client.py           # LLM 数据分析封装
│   └── llm_caller.py           # 智谱 GLM API 调用封装
├── pages/                      # Streamlit 多页面
│   ├── 02_Trends.py           # 趋势分析页面
│   ├── 03_Categories.py       # 类别分析页面
│   └── 04_Insights.py         # AI 洞察页面
├── tools/                      # 数据提取工具
│   └── extract_credit_card_bills.py
└── data/                       # CSV 数据文件

数据流架构

PST文件 → pffexport → tools/extract_credit_card_bills.py → CSV数据
                                                           ↓
                                              utils/data_loader.py
                                                           ↓
                                              utils/classifier.py (关键词分类)
                                                           ↓
                                    ┌────────────────┴────────────────┐
                                    ↓                                 ↓
                         pages/ & app.py (分析展示)        llm_caller.py (LLM二次分类)
                                                                 ↓
                                              utils/llm_client.py (AI洞察)

核心设计模式

  1. 数据加载与缓存: @st.cache_data(ttl=3600) 缓存1小时，避免重复加载CSV
  2. 商户分类: 关键词优先匹配（快速），LLM补充（准确）
  3. 多页面导航: Streamlit 原生多页面，侧边栏统一导航
  4. 配置集中: 所有可配置项（主题、分类关键词、LLM模板）集中在 config.py

关键技术细节

日期处理规则

  • 统一使用 transaction_date：所有分析和筛选都基于交易日期，而非账单日（statement_date）
  • 无日期筛选器：默认使用全部数据，仅提供卡号筛选
  • 年份推断：数据提取时从 OutlookHeaders.txt 的 Delivery time 自动提取正确年份

商户分类机制

两层分类策略：

  1. 关键词分类（优先）：基于 MERCHANT_KEYWORDS 快速匹配
  2. LLM 二次分类（可选）：使用智谱 GLM 对"其他"类别进行智能细分
# config.py 定义的分类关键词
MERCHANT_KEYWORDS = {
    "餐饮": ["美团", "饿了么", "星巴克", ...],
    "交通": ["滴滴", "特斯拉", "充电", ...],
    # ...
}

# 排除类别（不计入消费统计）
EXCLUDE_CATEGORIES = ["分期", "还款"]

LLM 分类缓存：已分类的商户会被缓存（llm_cache.json），避免重复调用 API。

Streamlit 页面结构

每个页面文件 (app.py, pages/*.py) 都遵循相同模式：

  1. 侧边栏：数据加载、筛选器、导航、API设置
  2. 数据筛选：基于卡号筛选
  3. 主内容区：图表和数据展示

开发指南

添加新分析功能

  1. 在 utils/analyzer.py 添加分析函数
  2. 在 utils/__init__.py 导出函数
  3. 在对应页面调用并可视化

添加新页面

  1. 在 pages/ 创建 XX_YourPage.py
  2. 复制现有页面的侧边栏和筛选逻辑
  3. 在 app.py 导航选项中添加页面名称

修改商户分类

直接编辑 config.py 中的 MERCHANT_KEYWORDS，无需修改代码。

AI 功能开发

LLM Caller (utils/llm_caller.py):

  • 基于 OpenAI SDK，兼容智谱 GLM API
  • 支持单次对话、多轮对话、流式输出
  • 便捷函数：create_caller(api_key, base_url, model)

LLM 二次分类 (utils/classifier.py):

  • llm_classify_merchant(): 单个商户分类
  • batch_llm_classify(): 批量分类，带进度回调
  • 分类结果缓存在 llm_cache.json

数据分析 (utils/llm_client.py):

  • get_analysis(): 基于 DataFrame 获取 AI 分析
  • prepare_data_summary(): 准备数据摘要

使用示例:

from utils.llm_caller import create_caller

# 创建 Caller
caller = create_caller(
    api_key="your_api_key",
    model="glm-4-flash"
)

# 单次对话
response = caller.chat("分析我的消费模式")
print(response.content)

配置管理

环境变量配置

项目使用 python-dotenv 从 .env 文件加载配置。创建 .env 文件（参考 .env.example）：

# LLM API 配置（智谱 GLM，兼容 OpenAI API）
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

获取智谱 API Key: https://open.bigmodel.cn/

安全规则：

  • .env 文件已在 .gitignore 中，不会提交到 git
  • 绝不在代码中硬编码 API Key
  • config.py 在启动时通过 load_dotenv() 加载环境变量

配置优先级

  1. UI 输入 - 用户在侧边栏手动输入（运行时覆盖）
  2. config.py - 从 .env 文件读取的配置
  3. 环境变量 - 系统级环境变量

数据说明

CSV 文件结构

credit_card_transactions.csv:

card_number, statement_date, transaction_date, description, amount
5006, 2025-02-01, 2024-02-13, 预约还款, 19163.39

credit_card_bills.csv:

bank, card_type, card_number, statement_date, new_balance, transactions_count, ...
招商银行, 标准信用卡, 5006, 2025-02-01, 27617.95, 197, ...

当前数据状态

  • 账单记录: 49 条（2023-2026年账单日）
  • 交易记录: 5,668 条
  • 数据时间范围: 2024-01 至 2025-12（按交易日期）

注意：2023年的账单存在，但其 transaction_date 都是2024年及以后（分期、还款等），这是正常的。

注意事项

  1. 硬编码年份问题：提取数据时年份必须从 OutlookHeaders.txt 的 Delivery time 提取，不能硬编码
  2. utils 导入：添加新函数后必须更新 utils/__init__.py
  3. 分类准确性：新商户默认归类为"其他"，定期审查并添加关键词
  4. API Key 安全：
    • 绝不在代码中硬编码 API Key
    • 使用 .env 文件存储，该文件已加入 .gitignore
    • 配置通过 config.py 统一管理，优先从 .env 读取
    • UI 输入仅作为运行时的可选覆盖方式

外部依赖

  • Streamlit: 前端框架
  • Pandas: 数据处理
  • Plotly: 图表可视化
  • openai: OpenAI SDK（用于调用智谱 GLM 等兼容 API）
  • python-dotenv: 环境变量管理
  • pff-tools: PST 文件解析（仅数据提取时需要）