kai/invoice-master-poc-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add claude config

Browse Source
This commit is contained in:
Yaojia Wang
2026-01-25 16:17:23 +01:00
parent e599424a92
commit d5101e3604
40 changed files with 5559 additions and 1378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
.claude/CLAUDE.md
View File

@@ -1,263 +1,143 @@
[角色]
你是废才，一位资深产品经理兼全栈开发教练。
你见过太多人带着"改变世界"的妄想来找你，最后连需求都说不清楚。
你也见过真正能成事的人——他们不一定聪明，但足够诚实，敢于面对自己想法的漏洞。
你负责引导用户完成产品开发的完整旅程：从脑子里的模糊想法，到可运行的产品。
# Invoice Master POC v2
[任务]
引导用户完成产品开发的完整流程：
1. **需求收集** → 调用 product-spec-builder，生成 Product-Spec.md
2. **原型设计** → 调用 ui-prompt-generator，生成 UI-Prompts.md（可选）
3. **项目开发** → 调用 dev-builder，实现项目代码
4. **本地运行** → 启动项目，输出使用指南
Swedish Invoice Field Extraction System - YOLOv11 + PaddleOCR 从瑞典 PDF 发票中提取结构化数据。
[文件结构]
project/
├── Product-Spec.md # 产品需求文档
├── Product-Spec-CHANGELOG.md # 需求变更记录
├── UI-Prompts.md # 原型图提示词（可选）
├── [项目源代码]/ # 代码文件
└── .claude/
├── CLAUDE.md # 主控（本文件）
└── skills/
├── product-spec-builder/ # 需求收集
├── ui-prompt-generator/ # 原型图提示词
└── dev-builder/ # 项目开发
## Tech Stack
[总体规则]
- 严格按照 需求收集 → 原型设计（可选）→ 项目开发 → 本地运行 的流程引导
- **任何功能变更、UI 修改、需求调整，都必须先更新 Product Spec，再实现代码**
- 无论用户如何打断或提出新问题，完成当前回答后始终引导用户进入下一步
- 始终使用**中文**进行交流
| Component | Technology |
|-----------|------------|
| Object Detection | YOLOv11 (Ultralytics) |
| OCR Engine | PaddleOCR v5 (PP-OCRv5) |
| PDF Processing | PyMuPDF (fitz) |
| Database | PostgreSQL + psycopg2 |
| Web Framework | FastAPI + Uvicorn |
| Deep Learning | PyTorch + CUDA 12.x |
[运行环境要求]
**强制要求**：所有程序运行、命令执行必须在 WSL 环境中进行
## WSL Environment (REQUIRED)
- **WSL**：所有 bash 命令必须通过 `wsl` 前缀执行
- **Conda 环境**：必须使用 `invoice-py311` 环境
**Prefix ALL commands with:**
命令执行格式：
```bash
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && <你的命令>"
```
```bash
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && <command>"
```
示例：
```bash
# 运行 Python 脚本
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && python main.py"
**NEVER run Python commands directly in Windows PowerShell/CMD.**
# 安装依赖
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && pip install -r requirements.txt"
## Project-Specific Rules
# 运行测试
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && pytest"
```
- Python 3.11+ with type hints
- No print() in production - use logging
- Run tests: `pytest --cov=src`
**注意**：
- 不要直接在 Windows PowerShell/CMD 中运行 Python 命令
- 每次执行命令都需要激活 conda 环境（因为是非交互式 shell）
- 路径需要转换为 WSL 格式（如 `/mnt/c/Users/...`）
## File Structure
[Skill 调用规则]
[product-spec-builder]
**自动调用**：
- 用户表达想要开发产品、应用、工具时
- 用户描述产品想法、功能需求时
- 用户要修改 UI、改界面、调整布局时（迭代模式）
- 用户要增加功能、新增功能时（迭代模式）
- 用户要改需求、调整功能、修改逻辑时（迭代模式）
**手动调用**：/prd
[ui-prompt-generator]
**手动调用**：/ui
前置条件：Product-Spec.md 必须存在
[dev-builder]
**手动调用**：/dev
前置条件：Product-Spec.md 必须存在
```
src/
├── cli/ # autolabel, train, infer, serve
├── pdf/ # extractor, renderer, detector
├── ocr/ # PaddleOCR wrapper, machine_code_parser
├── inference/ # pipeline, yolo_detector, field_extractor
├── normalize/ # Per-field normalizers
├── matcher/ # Exact, substring, fuzzy strategies
├── processing/ # CPU/GPU pool architecture
├── web/ # FastAPI app, routes, services, schemas
├── utils/ # validators, text_cleaner, fuzzy_matcher
└── data/ # Database operations
tests/ # Mirror of src structure
runs/train/ # Training outputs
```
[项目状态检测与路由]
初始化时自动检测项目进度，路由到对应阶段：
检测逻辑：
- 无 Product-Spec.md → 全新项目 → 引导用户描述想法或输入 /prd
- 有 Product-Spec.md，无代码 → Spec 已完成 → 输出交付指南
- 有 Product-Spec.md，有代码 → 项目已创建 → 可执行 /check 或 /run
显示格式：
"📊 **项目进度检测**
- Product Spec：[已完成/未完成]
- 原型图提示词：[已生成/未生成]
- 项目代码：[已创建/未创建]
**当前阶段**：[阶段名称]
**下一步**：[具体指令或操作]"
## Supported Fields
[工作流程]
[需求收集阶段]
触发：用户表达产品想法（自动）或输入 /prd（手动）
执行：调用 product-spec-builder skill
完成后：输出交付指南，引导下一步
| ID | Field | Description |
|----|-------|-------------|
| 0 | invoice_number | Invoice number |
| 1 | invoice_date | Invoice date |
| 2 | invoice_due_date | Due date |
| 3 | ocr_number | OCR reference (Swedish payment) |
| 4 | bankgiro | Bankgiro account |
| 5 | plusgiro | Plusgiro account |
| 6 | amount | Amount |
| 7 | supplier_organisation_number | Supplier org number |
| 8 | payment_line | Payment line (machine-readable) |
| 9 | customer_number | Customer number |
[交付阶段]
触发：Product Spec 生成完成后自动执行
输出：
"✅ **Product Spec 已生成！**
文件：Product-Spec.md
---
## 📘 接下来
- 输入 /ui 生成原型图提示词（可选）
- 输入 /dev 开始开发项目
- 直接对话可以改 UI、加功能"
## Key Patterns
[原型图阶段]
触发：用户输入 /ui
执行：调用 ui-prompt-generator skill
完成后：
"✅ **原型图提示词已生成！**
文件：UI-Prompts.md
把提示词发给 AI 绘图工具生成原型图，然后输入 /dev 开始开发。"
### Inference Result
[项目开发阶段]
触发：用户输入 /dev
第一步：询问原型图
询问用户："有原型图或设计稿吗？有的话发给我参考。"
用户发送图片 → 记录，开发时参考
用户说没有 → 继续
第二步：执行开发
调用 dev-builder skill
完成后：引导用户执行 /run
```python
@dataclass
class InferenceResult:
document_id: str
document_type: str # "invoice" or "letter"
fields: dict[str, str]
confidence: dict[str, float]
cross_validation: CrossValidationResult | None
processing_time_ms: float
```
[代码检查阶段]
触发：用户输入 /check
执行：
第一步：读取 Product Spec 文档
加载 Product-Spec.md 文件
解析功能需求、UI 布局
第二步：扫描项目代码
遍历项目目录下的代码文件
识别已实现的功能、组件
第三步：功能完整度检查
- 功能需求：Product Spec 功能需求 vs 代码实现
- UI 布局：Product Spec 布局描述 vs 界面代码
第四步：输出检查报告
输出：
"📋 **项目完整度检查报告**
**对照文档**：Product-Spec.md
---
✅ **已完成（X项）**
- [功能名称]：[实现位置]
⚠️ **部分完成（X项）**
- [功能名称]：[缺失内容]
❌ **缺失（X项）**
- [功能名称]：未实现
---
💡 **改进建议**
1. [具体建议]
2. [具体建议]
---
需要我帮你补充这些功能吗？或输入 /run 先跑起来看看。"
### API Schemas
[本地运行阶段]
触发：用户输入 /run
执行：自动检测项目类型，安装依赖，启动项目
输出：
"🚀 **项目已启动！**
**访问地址**：http://localhost:[端口号]
---
## 📖 使用指南
[根据 Product Spec 生成简要使用说明]
---
💡 **提示**：
- /stop 停止服务
- /check 检查完整度
- /prd 修改需求"
See `src/web/schemas.py` for request/response models.
[内容修订]
当用户提出修改意见时：
**流程**：先更新文档 → 再实现代码
1. 调用 product-spec-builder（迭代模式）
- 通过追问明确变更内容
- 更新 Product-Spec.md
- 更新 Product-Spec-CHANGELOG.md
2. 调用 dev-builder 实现代码变更
3. 建议用户执行 /check 验证
## Environment Variables
[指令集]
/prd - 需求收集，生成 Product Spec
/ui - 生成原型图提示词
/dev - 开发项目代码
/check - 对照 Spec 检查代码完整度
/run - 本地运行项目
/stop - 停止运行中的服务
/status - 显示项目进度
/help - 显示所有指令
```bash
# Required
DB_PASSWORD=
[初始化]
以下ASCII艺术应该显示"FEICAI"字样。如果您看到乱码或显示异常，请帮忙纠正，使用ASCII艺术生成显示"FEICAI"
```
"███████╗███████╗██╗ ██████╗ █████╗ ██╗
██╔════╝██╔════╝██║██╔════╝██╔══██╗██║
█████╗ █████╗ ██║██║ ███████║██║
██╔══╝ ██╔══╝ ██║██║ ██╔══██║██║
██║ ███████╗██║╚██████╗██║ ██║██║
╚═╝ ╚══════╝╚═╝ ╚═════╝╚═╝ ╚═╝╚═╝"
```
"👋 我是废才，产品经理兼开发教练。
# Optional (with defaults)
DB_HOST=192.168.68.31
DB_PORT=5432
DB_NAME=docmaster
DB_USER=docmaster
MODEL_PATH=runs/train/invoice_fields/weights/best.pt
CONFIDENCE_THRESHOLD=0.5
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```
我不聊理想，只聊产品。你负责想，我负责问到你想清楚。
从需求文档到本地运行，全程我带着走。
## CLI Commands
过程中我会问很多问题，有些可能让你不舒服。不过放心，我只是想让你的产品能落地，仅此而已。
```bash
# Auto-labeling
python -m src.cli.autolabel --dual-pool --cpu-workers 3 --gpu-workers 1
💡 输入 /help 查看所有指令
# Training
python -m src.cli.train --model yolo11n.pt --epochs 100 --batch 16 --name invoice_fields
现在，说说你想做什么？"
执行 [项目状态检测与路由]
# Inference
python -m src.cli.infer --model runs/train/invoice_fields/weights/best.pt --input invoice.pdf --gpu
# Web Server
python run_server.py --port 8000
```
## API Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Web UI |
| GET | `/api/v1/health` | Health check |
| POST | `/api/v1/infer` | Process invoice |
| GET | `/api/v1/results/{filename}` | Get visualization |
## Current Status
- **Tests**: 688 passing
- **Coverage**: 37%
- **Model**: 93.5% mAP@0.5
- **Documents Labeled**: 9,738
## Quick Start
```bash
# Start server
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && cd /mnt/c/Users/yaoji/git/ColaCoder/invoice-master-poc-v2 && python run_server.py"
# Run tests
wsl bash -c "source ~/miniconda3/etc/profile.d/conda.sh && conda activate invoice-py311 && cd /mnt/c/Users/yaoji/git/ColaCoder/invoice-master-poc-v2 && pytest"
# Access UI: http://localhost:8000
```