GithubLedger 项目结构说明

项目状态

当前阶段: 架构规范与核心模型定义完成
最后更新: 2025-12-07

---

目录结构

GithubLedger/
├── docs/                          # 文档目录
│   ├── architecture/              # 架构规范文档
│   │   ├── Standard_Data_Model.md          # 标准数据模型规范 (核心)
│   │   ├── UserProfile_Protocol.md         # 用户配置协议 (AI适配器)
│   │   └── Data_Integrity_Protocol.md      # 数据完整性协议 (质量标准)
│   ├── test_cases/                # 测试用例
│   │   └── CASE_001_Merge_Conflict_Analysis.md  # 合并冲突测试用例
│   └── archive/                   # 归档的旧版文档
│       ├── legacy_PRD_v1.0.md              # 旧版需求文档
│       ├── legacy_config_v1.yaml           # 旧版配置文件
│       └── legacy_quality_checklist_v1.md  # 旧版质量清单
│
├── src/                           # 源代码目录
│   ├── models/                    # 数据模型
│   │   ├── __init__.py                     # 模块导出
│   │   ├── standard_record.py              # StandardRecord 实现
│   │   └── user_profile.py                 # UserProfile 实现
│   ├── processors/                # 数据处理器 (待创建)
│   ├── ai/                        # AI 相关模块 (待创建)
│   └── api/                       # API 接口 (待创建)
│
├── data/                          # 数据目录
│   └── raw/                       # 原始数据文件
│       └── 家庭账本0713 - 家庭账本0713 - 工作表1.csv
│
├── requirements.txt               # Python 依赖
└── README.md                      # 本文件

---

核心设计理念

"铁打的标准模型，流水的适配器"

问题: 如何让一个系统适配无限种用户数据格式，而不需要为每个用户写代码？

解决方案:

1. StandardRecord (标准数据模型): 系统内部唯一的数据格式（地基）
2. UserProfile (AI 适配器): AI 为每个用户生成的配置文件（翻译器）
3. Data Integrity Protocol (质量协议): 数据处理的质量法律（红线）

业务流程（针对已有账本的用户）

┌─────────────────────┐
│ 1. 用户上传历史账本   │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ 2. AI 分析账本结构   │
│   - 识别列映射       │
│   - 检测备注混杂     │
│   - 分析分类体系     │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ 3. 生成 UserProfile  │
│   (AI 适配器配置)    │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ 4. 用户预览与确认    │
│   (修改建议/映射)    │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ 5. 执行数据清洗      │
│   - 维度拆解         │
│   - 实体提取         │
│   - 分类归一化       │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ 6. 转换为 StandardRecord │
│   (存入数据库)       │
└─────────────────────┘

---

已完成的工作

✅ 架构文档

• 标准数据模型规范 (Standard_Data_Model.md)
• 用户配置协议 (UserProfile_Protocol.md)
• 数据完整性协议 (Data_Integrity_Protocol.md)

✅ 核心模型实现

• StandardRecord 类 (Python dataclass)
• UserProfile 类及相关子类
• 数据验证逻辑
• 序列化/反序列化方法

✅ 项目整理

• 归档旧版文档
• 建立新的目录结构
• 保留测试用例

---

待实现的功能

🔨 下一步：数据处理管道

1. CSV/Excel 读取器: 读取用户上传的文件
2. AI 分析器: 调用 LLM 生成 UserProfile
3. 数据清洗器: 根据 UserProfile 清洗数据
4. 转换器: 将清洗后的数据转换为 StandardRecord

🚀 未来功能

1. Web UI: 用户交互界面
2. 数据库: 存储 StandardRecord
3. 统计分析: 月度报告、分类统计
4. 智能提醒: 价格趋势、性价比分析

---

技术栈

• 语言: Python 3.10+
• 数据模型: dataclasses (考虑迁移到 Pydantic)
• 数据处理: pandas
• AI: OpenAI API / Claude API
• 数据库: SQLite (初期) / PostgreSQL (未来)
• 前端: (待定) React / Vue

---

核心原则

1. 真实性原则

系统不得编造任何不存在的数据。

• ❌ 禁止: 为缺失的时间字段自动补全 00:00:00
• ✅ 允许: 保留字段为 None

2. 精度适配原则

输出数据的精度不得高于输入数据的精度。

• 若源数据为日期，不得升级为时间戳
• 若源数据为整数，不得自动添加小数点

3. 溯源性原则

每条记录必须能追溯到原始文件。

• source_file: 来源文件名
• original_row: 原始数据快照

4. 标签 vs 分类

分类是互斥的，标签是叠加的。

• "女儿费用" -> category: "餐饮" + tags: ["女儿"]
• 这样可以既查"餐饮总支出"，又查"女儿相关支出"

---

快速开始（开发者）

安装依赖

pip install -r requirements.txt

运行测试（示例）

from src.models import StandardRecord
from decimal import Decimal
from datetime import datetime

# 创建一条标准记录
record = StandardRecord(
    transaction_time=datetime(2025, 3, 15, 14, 30),
    amount=Decimal("37.68"),
    direction="expense",
    merchant="瑞幸咖啡",
    category_main="餐饮",
    source_file="test.csv",
    original_row={"商户": "瑞幸", "金额": "37.68"}
)

print(record.to_dict())

---

贡献指南

文档优先

• 任何新功能必须先更新 docs/architecture/ 中的规范文档
• 代码必须符合已定义的协议

代码规范

• 使用类型注解
• 编写文档字符串
• 遵循 PEP 8

测试驱动

• 新功能必须有对应的测试用例
• 使用 docs/test_cases/ 中的真实数据验证

---

联系方式

项目负责人: Alexu0317-FATHER
项目仓库: GitHub
文档位置: D:\AI AND ME\projects\GithubLedger

---

最后更新: 2025-12-07
当前版本: v2.0 (架构重构完成)