hugosbl-freelance-toolkit-fr

法国自由职业者工具箱，涵盖发票生成、工时追踪、客户管理与收入仪表盘。纯 Python 3 标准库实现，数据存储于 ~/.freelance/，支持 HTML 发票与法国微型企业合规。

## 概述（中文）

法国自由职业者工具箱，涵盖发票生成、工时追踪、客户管理与收入仪表盘。纯 Python 3 标准库实现，数据存储于 ~/.freelance/，支持 HTML 发票与法国微型企业合规。

## 技能正文

# 自由职业者工具箱

面向法国自由职业者/独立工作者的工具箱：发票、工时追踪、客户管理、仪表盘。

## 脚本

全部位于 `scripts/`。仅使用 Python 3 标准库。数据存储在 `~/.freelance/`。

### config.py — 服务提供方配置
```bash
python3 config.py set --name "Hugo Dupont" --address "42 rue de la Paix, 75002 Paris" \
  --siret "98765432100010" --email "hugo@example.com" --phone "0600000000" \
  --iban "FR76 1234 5678 9012 3456 7890 123" --rate 80 --micro
python3 config.py show [--json]
```
存储：`~/.freelance/config.json`

### clients.py — 客户管理
```bash
python3 clients.py add --name "Acme" --email "contact@acme.fr" --phone "0612345678" \
  --address "10 rue Example, 75001 Paris" --siret "12345678900010" --rate 80 --notes "Client fidèle"
python3 clients.py list [--json]
python3 clients.py show "Acme" [--json]
python3 clients.py edit "Acme" --rate 90 --notes "Nouveau taux"
python3 clients.py remove "Acme"
```
存储：`~/.freelance/clients.json`

### timetrack.py — 工时追踪
```bash
python3 timetrack.py start "Site web Acme" [--client "Acme"]
python3 timetrack.py stop
python3 timetrack.py status [--json]
python3 timetrack.py log [--from 2026-01-01] [--to 2026-01-31] [--project "Site web"] [--json]
python3 timetrack.py report [--month 2026-01] [--json]
```
存储：`~/.freelance/timetrack.json`

### invoice.py — HTML 发票生成
```bash
python3 invoice.py generate --client "Acme" --items "Dev site web:5:400" "Design logo:1:200" \
  [--number 2026-001] [--date 2026-02-15] [--due-days 30] [--no-open]
python3 invoice.py list [--json]
python3 invoice.py show 2026-001
python3 invoice.py paid 2026-001
```
- 在 `~/.freelance/invoices/` 生成专业 HTML 发票
- 省略 `--number` 时自动编号 YYYY-NNN
- 默认在浏览器中打开（`--no-open` 除外）
- 若找到客户则从 `clients.json` 预填客户信息
- 包含法国法定声明（默认微型企业）
- `paid` 标记发票为已付款（在仪表盘中追踪）
- 金额采用法国格式（2 900,00 €）
- 服务提供方姓名首字母作为发票 Logo

### dashboard.py — 收入仪表盘
```bash
python3 dashboard.py summary [--year 2026] [--json]
python3 dashboard.py monthly [--year 2026] [--json]
```
- 汇总发票与工时数据
- 总营业额、按月、按客户
- 工作时长、工作日（工时/7）、实际时薪
- 已付与未付发票
- 实际时薪仅基于有营业额的月份计算

## 配置

可选文件 `~/.freelance/config.json`：
```json
{
  "provider": {
    "name": "Hugo Dupont",
    "address": "42 rue de la Paix, 75002 Paris",
    "siret": "98765432100010",
    "email": "hugo@example.com",
    "phone": "0600000000"
  },
  "default_rate": 80,
  "tva_rate": 0,
  "micro_entreprise": true,
  "payment_delay_days": 30,
  "payment_method": "Virement bancaire",
  "iban": "FR76 1234 5678 9012 3456 7890 123"
}
```

若 `micro_entreprise: true` → 增值税 = 0%，注明 CGI 第 293B 条。
若 `tva_rate > 0` → 每张发票计算增值税。

## 数据

全部位于 `~/.freelance/`：
```
~/.freelance/
├── config.json          — 服务提供方配置
├── clients.json         — 客户数据库
├── timetrack.json       — 工时记录
└── invoices/
    ├── 2026-001.html    — HTML 发票
    ├── 2026-001.json    — 发票元数据
    └── ...
```

## 备注
- 金额以欧元（€）计，输出为法语格式
- 所有命令均支持 `--json` 供机器使用
- HTML 发票针对打印/浏览器导出 PDF 优化
- 法定义务详见 `references/french-law.md`