内容
<p align="center">
<img
src="./.github/assets/banner.png"
alt="minus-tracker — 意大利资本利得与损失跟踪器 / Calcolo Plusvalenze e Minusvalenze"
width="100%"
/>
</p>
# minus-tracker
[](./LICENSE)
[](https://www.npmjs.com/package/@gabrielerandelli/minus-tracker)
[](https://www.npmjs.com/package/@gabrielerandelli/minus-tracker)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
⚠️ **计算辅助，非税务咨询** — 请参阅 [Disclaimer](#disclaimer)。
⚠️ **Calculation aid only, not tax advice** — see the [Disclaimer](#disclaimer).
🤖 **新功能：MCP 服务器** — 任何 AI 代理可以直接计算意大利资本利得/损失，无需经过 CLI。
🤖 **New: MCP server** — any AI agent can compute Italian capital gains/losses directly, no CLI required.
✅ 已根据意大利税务局（Agenzia delle Entrate）的 12 个常见问题场景进行验证 · 120 个自动化测试 · 核心库中无运行时依赖。
✅ Validated against all 12 Agenzia delle Entrate FAQ scenarios · 120 automated tests · zero runtime dependencies in the core library.
_唯一开源工具，直接将 DEGIRO 导出数据转换为意大利税务局（Agenzia delle Entrate）正确的资本利得/损失 — 作为 CLI、库或 MCP 工具，供 AI 代理调用。_
_The only open-source tool that turns a raw DEGIRO export directly into Agenzia-Entrate-correct capital gains/losses — as a CLI, a library, or an MCP tool your AI agent can call._
---
## 中文
minus-tracker 是一个主要使用 TypeScript 开发的开源项目，用于自动计算 **资本利得和损失**，适用于 _申报制度（Regime Dichiarativo）_。它通过 LIFO/FIFO 逻辑管理批次，并使用欧洲央行（BCE）的历史汇率进行多币种标准化。
该工具直接处理从 DEGIRO 导出的 CSV 文件。
### 功能
- **资本利得和损失计算**，支持 **LIFO 或 FIFO** （可配置）
- **集成 DEGIRO CSV 文件解析器**
- **多币种支持**，使用欧洲央行（BCE）历史汇率（EUR、USD、GBP、CHF）
- **金融工具的税务分类**，分为两类（Bucket A/B）- 股票、ETF、国债、衍生品 - 通过 OpenFIGI 和 JSON 边车进行自动分类
- **收益表生成**：生成 Quadro RT（其他收入）和 Quadro RM（资本收入），并回溯以前的损失（4 年规则）
- **测试套件** 与意大利税务局（Agenzia delle Entrate）FAQ 对齐
- **输出支持中文（默认）** 或 **英文** (`--lang en`)
- **作为 NPM 包提供**，支持 CLI
**v0.10.0 新增功能：**
- **CLI 横幅**：`minus-tracker`（无命令）、 `--help` 和新标志 `--version` 现在显示带有项目徽标的 ASCII 横幅（终端颜色渐变，纯文本否则）。
**v0.9.0 新增功能：**
- **`calc` 自动分类**：不再需要单独执行 `classify` - 如果缺少 `*.classify.json` 侧车文件，`calc` 会自行生成（交互式如果终端已连接，否则离线并提示）然后计算。`classify` 仍然可用于显式/交互式使用，并且 `calc` 现在也接受 `--offline` 标志。
**v0.8.0 新增功能：**
- **`Classifier` 无状态模式`**：`classify()` 现在可以在没有文件系统访问权限的情况下工作（无侧车文件），对于与代理和自动化集成的用例非常有用
- **MCP 服务器** (`minus-tracker-mcp`)：在标准输入/输出上公开 `parse_transactions`、`classify_instruments` 和 `calculate_gains` 作为 MCP 工具，供 AI 代理直接使用 - 请参见下面的 [MCP 服务器](#mcp-服务器) 部分
### 快速开始
如果您还没有 DEGIRO 导出文件，可以使用软件包中包含的示例文件进行测试。
**通过 npx（无需全局安装）：**
```bash
curl -O https://raw.githubusercontent.com/gabrielerandelli/minus-tracker/main/samples/sample-trades.csv
npx @gabrielerandelli/minus-tracker calc sample-trades.csv
```
**如果您已经本地安装了软件包：**
```bash
./node_modules/.bin/minus-tracker calc node_modules/@gabrielerandelli/minus-tracker/samples/sample-trades.csv
```
示例文件包含 5 笔虚拟交易（Apple Inc. 美元 + ASML Holding 在欧元）并演示了部分销售的 LIFO 结算，货币转换和净收益。
### 示例输出
在示例文件上运行 `calc` 会产生：
```
方法：LIFO | 税年：2024
ISIN 标题 数量 购买日期 销售日期 购买欧元 销售欧元 收益/损失
US0378331005 Apple Inc 10 2024-01-02 2024-01-05 1371.11 1188.37 -182.75
NL0010273215 ASML Holding N.V. 3 2024-04-01 2024-07-15 2552.00 2849.00 +297.00
NL0010273215 ASML Holding N.V. 3 2024-01-15 2024-07-15 2401.20 2849.00 +447.80
────────────────────────────────────────────────────────────────────────
资本利得： 744.80 欧元
资本损失： 182.75 欧元
净结果： 562.05 欧元
```
使用 `--json` 标志可以直接获得 `GainsReport` 对象，适用于编程集成（参见 [代码中的使用示例](#代码中的使用示例））。
### DEGIRO CSV 格式
从 **活动 → 交易** （非账户报表）导出文件到您的个人 DEGIRO 区域。使用预定义的导出并包含所有列。
支持的货币： **EUR** （无转换）， **USD**， **GBP**， **CHF** （包含历史 BCE 汇率，2019 年至今）。
DEGIRO 文件中的日期为 `GG-MM-AAAA` 格式；解析器会自动将其转换为 ISO 格式。
ISIN 缺失，货币不支持或 3 个工作日内无 BCE 汇率的行将被跳过并显示警告（而非错误）- 使用 `validate` 在计算前检查它们。
### CLI 安装
**全局安装** （使命令在每个目录中可用）：
```bash
npm install -g @gabrielerandelli/minus-tracker
```
**无需全局安装** （即时执行）：
```bash
npx @gabrielerandelli/minus-tracker calc trades.csv
```
### CLI 使用
| 命令 | 主要标志 | 备注 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `calc <file.csv>` | `--method LIFO\|FIFO` （默认：LIFO）， `--lang it\|en`， `--json`， `--export-dichiarazione [path]`， `--carry-forward`， `--offline` | 从不自行更新 BCE 汇率 - 定期执行 `rates --update`。如果找不到 `*.classify.json` 侧车文件，它会自动对工具进行分类（如果终端已连接，则交互式，否则离线并提示）并将其写入磁盘 |
| `classify <file.csv>` | `--offline` | 显式/可选调用：对工具进行分类（Bucket A/B）并创建/更新 `*.classify.json` 侧车文件。 `calc` 在需要时调用它；使用此命令进行交互式确认或脚本/CI 流程 |
| `validate <file.csv>` | `--lang it\|en` | 以 0 状态码退出并显示警告；以 1 状态码退出并显示阻止错误 |
| `rates --check` | — | 显示本地 BCE 快照的覆盖范围 |
| `rates --update` | — | 从 BCE API 下载更新的汇率 |
| `config --lang it\|en` | — | 永久保存首选语言 |
| `config --show` | — | 显示当前设置的语言 |
| `stress-test` | `--range N-M`， `--keep`， `--json`， `--output-dir` | 文档在后面 |
| `--help` | — | 显示横幅和命令列表 |
| `--version` | — | 显示已安装的版本 |
语言优先级： `--lang` > 已保存的语言 > 中文（默认）。
```bash
# 计算资本利得/损失（意大利语输出，LIFO 方法）
minus-tracker calc trades.csv
# FIFO 方法，英文输出，JSON 格式
minus-tracker calc --method FIFO --lang en --json trades.csv
# 验证 CSV 文件而不计算
minus-tracker validate trades.csv
# 检查或更新本地 BCE 汇率
minus-tracker rates --check
minus-tracker rates --update
# 永久设置默认语言
minus-tracker config --lang en # 或： --lang it
minus-tracker config --show
```
### 作为库安装
```bash
npm install @gabrielerandelli/minus-tracker
```
### 代码中的使用示例
```ts
import {
DEGIROParser,
Calculator,
Classifier,
ParseError,
CalculationError,
} from "@gabrielerandelli/minus-tracker";
import type { GainsReport, LotMethod } from "@gabrielerandelli/minus-tracker";
// 1. 解析
const parser = new DEGIROParser();
const transactions = parser.parse(csvString); // 在 CSV 无效时抛出 ParseError
if (parser.warnings.length > 0) {
console.warn("跳过的行：", parser.warnings);
}
// 2. 分类（Bucket A/B）- 可选，启用 Quadro RT/RM 报表
const classification = await new Classifier().classify(
transactions,
"trades.classify.json", // 持久侧车文件；无状态模式下不存在
);
// 3. 计算
const method: LotMethod = "LIFO"; // 或 "FIFO"
const report: GainsReport = new Calculator(transactions, parser.warnings, {
classification,
}).calculateGains(method);
console.log(report.plusvalenze); // 数字，欧元
console.log(report.minusvalenze); // 数字，欧元（绝对值）
console.log(report.netResult); // 资本利得 - 资本损失
console.log(report.lots); // MatchedLot[] - 按批次详细
console.log(report.dichiarazione); // Quadro RT/RM，如果提供了分类
// 4. 错误处理
try {
const txs = parser.parse(csvString);
const r = new Calculator(txs, parser.warnings).calculateGains("LIFO");
} catch (err) {
if (err instanceof ParseError) {
if (err.code === "MISSING_COLUMN") {
console.error("缺少的列：", err.columnName);
} else {
console.error("无效的 CSV");
}
} else if (err instanceof CalculationError) {
console.error(
`销售没有对应的购买： ${err.isin} 于 ${err.date}`,
);
}
}
```
> **注意：** `parser.warningEntries` （在 TypeScript 自动补全中可见）是 CLI 渲染器使用的内部 API。对于编程使用，请使用 `parser.warnings` （`string[]`）。
> 💡 minus-tracker **仅处理税务计算** - 不包括图形界面（UI），身份验证系统，数据库或 PDF 导出。
**要求：** Node.js ≥ 24 ([nodejs.org](https://nodejs.org))
### MCP 服务器
从 v0.8.0 开始，minus-tracker 包含一个 `minus-tracker-mcp` 二进制文件，它在标准输入/输出上公开一个 [MCP 服务器](https://modelcontextprotocol.io)，供 AI 代理直接使用（无需经过 CLI）：
```bash
npx -p @gabrielerandelli/minus-tracker minus-tracker-mcp
```
典型的 MCP 客户端配置（例如 Claude Desktop，`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"minus-tracker": {
"command": "npx",
"args": [
"-y",
"-p",
"@gabrielerandelli/minus-tracker",
"minus-tracker-mcp"
]
}
}
}
```
服务器公开 3 个工具：
| 工具 | 描述 |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `parse_transactions` | 解析 DEGIRO CSV 文件，返回 `transactions`/`warnings`/`incomeRows` |
| `classify_instruments` | 将 ISIN 分类为 Bucket A/B（无状态 - 无侧车文件） |
| `calculate_gains` | 计算资本利得/损失（LIFO/FIFO）和 Quadro RT/RM（如果可用） |
`classify_instruments` 支持 `existingClassification`，`overrides` 和 `offline: true` 以在无网络和无文件系统访问的情况下运行 - 设计为由代理在后续调用中重复调用，保持客户端状态。
### 常见问题
**CSV 文件被拒绝，提示“缺少列”或“CSV 文件无效”**
请确保您从“交易记录” → **交易**导出，而不是从账户报表导出。解析器需要交易记录导出的格式。
**某些行被跳过并显示警告**
当ISIN为空、货币不为EUR/USD/GBP/CHF或交易日期3个工作日内没有欧洲央行利率时，行将被跳过（不会阻止计算）。使用`validate`查看详细信息。
**错误“ISIN X在日期Y没有开放批次”**
CSV文件中包含一个证券的销售记录，但之前没有购买记录。购买记录可能在未包含的早期导出文件中。使用`validate`检查解析的交易。
**欧洲央行利率已过期**
执行`minus-tracker rates --update`。`calc`命令不会自动更新利率：更新始终是一个显式操作。
**后进先出（LIFO）还是先进先出（FIFO）？**
申报制度使用LIFO作为默认方法，符合意大利税法规定。FIFO可用于比较。请咨询您的会计师以确认。
### 已知限制
minus-tracker 将**所有金融工具的资本利得和损失**合并为**单一总额**，无论其税务类别如何。
意大利法规规定**不同收入**（股票、衍生品、凭证 — Art. 67 TUIR）和**资本收入**（ETF/UCITS基金 — Art. 44 TUIR）不能相互抵消：ETF的损失不能减少股票的利得，反之亦然。
**仅股票或仅ETF投资组合：**计算正确。
**混合投资组合（股票 + ETF）：**报告的净结果不可直接用于申报。在这种情况下，您需要按税务类别手动分离批次，然后咨询会计师。
### 注意
minus-tracker 是一个**个人项目**，以私人身份开发，**与作者的雇主或任何其他组织无关**。
该工具**仅用于计算辅助**，**不构成税务、法律或财务咨询**。作者**免除因计算错误、不当使用工具或用户根据生成的报告做出的决定而产生的任何责任**。
建议您**始终与会计师或合格的税务专业人员核实结果**，然后再提交任何申报。
---
## 压力测试
您可以运行集成的压力测试套件，以验证安装是否正确处理所有预期场景：
```bash
minus-tracker stress-test
```
该命令在临时目录中生成100个测试CSV文件，对每个文件执行各种CLI命令，并显示测试结果，而不会修改您的项目文件。
### 可用选项
| 标志 | 默认值 | 描述 |
| --------------------- | --------------------------------- | ------------------------------------------- |
| `--range N-M` | `1-100` | 只运行场景N到M |
| `--keep` | 禁用 | 保留生成的CSV文件 |
| `--json` | 禁用 | 以JSON格式返回结果 |
| `--output-dir <path>` | `/tmp/minus-tracker-stress-<ts>/` | 自定义输出目录 |
### 涵盖的场景
100个场景包括：欧元/美元/英镑/瑞士法郎计价的股票，LIFO vs FIFO计算差异，部分批次使用，多个ISIN投资组合，节假日管理（周末欧洲央行利率回调），警告和错误消息，当日交易（same-day），舍入极限情况和大投资组合（最多200笔交易）。
---
## 中文
minus-tracker是一个开源项目，主要使用TypeScript开发，用于自动计算**资本利得和损失**，适用于**申报制度** — LIFO/FIFO批次匹配，多币种标准化，历史欧洲央行利率。
它加载DEGIRO使用的CSV格式数据。
### 功能
- 资本利得/损失计算，支持**LIFO和FIFO**批次匹配
- **DEGIRO CSV解析器**
- **多币种**处理，支持历史欧洲央行利率（欧元、美元、英镑、瑞士法郎）
- **两桶分类**（桶A/B）金融工具 — 股票、ETF、政府债券、衍生品 — 自动OpenFIGI分类和持久JSON侧车
- **模版Redditi PF**生成：Quadro RT（资本利得）和Quadro RM（资本收入），基于计算批次，前年损失结转（4年规则）
- 基于**Agenzia Entrate常见问题**的测试套件
- **意大利**（默认）或**英文**（`--lang en`）输出
- minus-tracker是一个NPM包，支持CLI
**v0.10.0新增功能：**
- **CLI横幅**: `minus-tracker`（无命令）、`--help`和新的`--version`标志现在显示ASCII横幅，带有项目徽标（终端彩色渐变，纯文本否则）。
**v0.9.0新增功能：**
- **`calc`自动分类**：不再需要单独运行`classify` — 如果`*.classify.json`侧车文件不存在，`calc`现在会自行生成（交互式如果有终端连接，否则离线并带有警告）。
**v0.8.0新增功能：**
- **分类器的无状态模式**：`classify()`现在可以在零文件系统访问的情况下运行（无侧车文件），适用于嵌入代理/自动化。
- **MCP服务器**（`minus-tracker-mcp`）：通过stdio公开`parse_transactions`、`classify_instruments`和`calculate_gains`作为MCP工具，供AI代理直接使用 — 请参见下面的**MCP服务器**部分。
### 快速入门
如果您还没有DEGIRO导出记录？请使用软件包中附带的示例文件。
**通过npx（无需全局安装）：**
```bash
curl -O https://raw.githubusercontent.com/gabrielerandelli/minus-tracker/main/samples/sample-trades.csv
npx @gabrielerandelli/minus-tracker calc sample-trades.csv
```
**如果您已经本地安装了软件包：**
```bash
./node_modules/.bin/minus-tracker calc node_modules/@gabrielerandelli/minus-tracker/samples/sample-trades.csv
```
该文件包含5笔虚拟交易（苹果公司股票，美元 + ASML Holding，欧元）并演示了部分LIFO匹配、货币转换和净结果为正。
### 示例输出
运行`calc`命令生成：
```
方法：LIFO | 税年：2024
ISIN 产品 数量 购买日期 销售日期 购买欧元 销售欧元 利得/损失
US0378331005 苹果公司 10 2024-01-02 2024-01-05 1,371.11 1,188.37 -182.75
NL0010273215 ASML Holding N.V. 3 2024-04-01 2024-07-15 2,552.00 2,849.00 +297.00
NL0010273215 ASML Holding N.V. 3 2024-01-15 2024-07-15 2,401.20 2,849.00 +447.80
────────────────────────────────────────────────────────────────────────
资本利得： 744.80 欧元
资本损失： 182.75 欧元
净结果： 562.05 欧元
```
添加`--json`获取原始`GainsReport`对象 — 对编程集成有帮助（参见[库使用](#库使用)）。
### DEGIRO CSV格式
从DEGIRO账户的**活动 → 交易记录**（不是账户报表）导出。 使用默认导出并选择所有列。
支持的货币：**欧元**（无需转换），**美元**，**英镑**，**瑞士法郎**（捆绑的欧洲央行历史汇率，2019年至今）。
DEGIRO导出中的日期为`DD-MM-YYYY`格式；解析器自动转换为ISO格式。
ISIN为空、货币不受支持或交易日期3个交易日内无欧洲央行利率的行将被跳过并显示警告（非错误） — 运行`validate`检查它们。
### CLI安装
**全局安装**（系统范围内可用命令）：
```bash
npm install -g @gabrielerandelli/minus-tracker
```
**无需全局安装**（无需设置）：
```bash
npx @gabrielerandelli/minus-tracker calc trades.csv
```
### CLI用法
| 命令 | 关键标志 | 备注 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `calc <file.csv>` | `--method LIFO\|FIFO`（默认：LIFO），`--lang it\|en`，`--json`，`--export-dichiarazione [path]`，`--carry-forward`，`--offline` | 从不自行获取欧洲央行利率 — 定期运行`rates --update`。如果没有`*.classify.json`侧车文件，自动分类工具（交互式如果有终端连接，否则离线并带有警告）并写入磁盘 |
| `classify <file.csv>` | `--offline` | 显式/可选调用：分类工具（桶A/B）并创建/更新`*.classify.json`侧车文件。`calc`在需要时自动调用；使用此命令提前运行或获取交互式确认流程。需要交互式终端（TTY），或在脚本/CI环境中使用`--offline`标志 |
| `validate <file.csv>` | `--lang it\|en` | 退出码0并带有警告；退出码1表示硬错误 |
| `rates --check` | — | 显示捆绑的欧洲央行快照覆盖范围 |
| `rates --update` | — | 从欧洲央行API获取最新汇率 |
| `config --lang it\|en` | — | 保存语言偏好 |
| `config --show` | — | 显示当前语言设置 |
| `stress-test` | `--range N-M`，`--keep`，`--json`，`--output-dir` | 文档下方有详细介绍 |
| `--help` | — | 显示横幅和命令列表 |
| `--version` | — | 显示已安装的版本 |
语言优先级：`--lang`标志 > 已保存配置 > 意大利语（默认）。
```bash
# 计算利得/损失（英文输出，LIFO方法）
minus-tracker calc --lang en trades.csv
# FIFO方法，JSON输出
minus-tracker calc --method FIFO --json trades.csv
# 验证CSV文件而非计算
minus-tracker validate trades.csv
# 检查/更新欧洲央行利率
minus-tracker rates --check
minus-tracker rates --update
# 永久设置语言
minus-tracker config --lang en # 或：--lang it
minus-tracker config --show
```
### 库安装
```bash
npm install @gabrielerandelli/minus-tracker
```
### 库使用
```ts
import {
DEGIROParser,
Calculator,
Classifier,
ParseError,
CalculationError,
} from "@gabrielerandelli/minus-tracker";
import type { GainsReport, LotMethod } from "@gabrielerandelli/minus-tracker";
// 1. 解析
const parser = new DEGIROParser();
const transactions = parser.parse(csvString); // 在不良CSV上抛出ParseError
if (parser.warnings.length > 0) {
console.warn("跳过的行：", parser.warnings);
}
// 2. 分类（桶A/B）- 可选，启用报告中的Quadro RT/RM
const classification = await new Classifier().classify(
transactions,
"trades.classify.json", // 持久侧车文件；省略表示无状态模式
);
// 3. 计算
const method: LotMethod = "LIFO"; // 或"FIFO"
const report: GainsReport = new Calculator(transactions, parser.warnings, {
classification,
}).calculateGains(method);
console.log(report.plusvalenze); // 欧元资本利得（数字）
console.log(report.minusvalenze); // 欧元资本损失（数字，绝对值）
console.log(report.netResult); // plusvalenze - minusvalenze
console.log(report.lots); // MatchedLot[] — 按批次详细分类
console.log(report.dichiarazione); // Quadro RT/RM，当分类通过时
// 4. 错误处理
try {
const txs = parser.parse(csvString);
const r = new Calculator(txs, parser.warnings).calculateGains("LIFO");
} catch (err) {
if (err instanceof ParseError) {
if (err.code === "MISSING_COLUMN") {
console.error("缺少列：", err.columnName);
} else {
console.error("无效CSV");
}
} else if (err instanceof CalculationError) {
console.error(`卖出无先前购买： ${err.isin} 在 ${err.date}`);
}
}
```
> **注意：** `parser.warningEntries`（在TypeScript自动补全中可见）是CLI渲染器的内部API。库消费者请使用`parser.warnings`（`string[]`）。
minus-tracker 是**纯税务数学** — 无UI、身份验证、数据库或PDF。
**先决条件：** Node.js ≥ 24 ([nodejs.org](https://nodejs.org))
### MCP 服务器
从 v0.8.0 开始，minus-tracker 附带了一个 `minus-tracker-mcp` 二进制文件，通过 stdio 公开了一个 [MCP 服务器](https://modelcontextprotocol.io)，供 AI 代理直接使用（无需通过 CLI）：
```bash
npx -p @gabrielerandelli/minus-tracker minus-tracker-mcp
```
典型的 MCP 客户端配置（例如 Claude Desktop，`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"minus-tracker": {
"command": "npx",
"args": [
"-y",
"-p",
"@gabrielerandelli/minus-tracker",
"minus-tracker-mcp"
]
}
}
}
```
服务器公开了 3 个工具：
| 工具 | 描述 |
| --- | --- |
| `parse_transactions` | 将 DEGIRO CSV 解析为 `transactions`/`warnings`/`incomeRows` |
| `classify_instruments` | 将 ISIN 分类为 Bucket A/B（无状态模式 — 无 sidecar 文件） |
| `calculate_gains` | 计算收益/损失（LIFO/FIFO），并在可用时计算 Quadro RT/RM |
`classify_instruments` 支持 `existingClassification`、`overrides` 和 `offline: true` 以在无网络访问或文件系统访问的情况下运行 — 设计为由代理跨多次调用，客户端保持状态。
### 常见问题 / 故障排除
**我的 CSV 被拒绝，提示“missing column”或“invalid CSV”**
请确认您从活动 → **交易** 而非账户对账单中导出。解析器需要交易导出格式。
**某些行被跳过并带有警告**
当 ISIN 为空、货币不是 EUR/USD/GBP/CHF 或交易日期后 3 个交易日内无 ECB 汇率时，行将被跳过（不会中止计算）。运行 `validate` 获取详细信息。
**错误“no open lots for ISIN X on date Y”**
CSV 包含某只证券的卖出记录，但该证券在同一文件中没有先前的买入记录。买入记录可能在未包含的上一年的导出中。 使用 `validate` 检查已解析的交易。
**ECB 汇率已过时**
运行 `minus-tracker rates --update`。`calc` 命令永远不会自行获取汇率 — 刷新始终是明确的用户调用操作。
**LIFO 还是 FIFO？**
LIFO 是意大利税法下申报制度的标准批次匹配方法。 FIFO 可用于比较或其他司法管辖区。 请咨询您的税务顾问以确认。
### 已知限制
minus-tracker 将 **所有金融工具的收益和损失聚合为一个总值**，而不管其税务类别如何。
意大利法律要求 **redditi diversi** （个股、衍生品、凭证 — Art. 67 TUIR）和 **redditi di capitale** （ETF / UCITS 基金 — Art. 44 TUIR）应分开保存：ETF 的损失不能抵消股票的收益，反之亦然。
**仅持有股票或仅持有 ETF 的投资组合：** 计算是正确的。
**混合投资组合（股票 + ETF）：** 报告的净结果不能直接用于税务申报。在这种情况下，批次必须在申报前按税务类别手动分离，并由合格的税务顾问协助。
### 免责声明
minus-tracker 是一个 **个人项目**，在私人身份下开发，**与作者的雇主或任何其他组织无关**。
本工具仅作为 **计算辅助工具** 提供，**不构成税务、法律或财务建议**。作者 **不承担输出错误、滥用工具或终端用户根据生成的报告做出的任何决定的责任**。
**始终** 鼓励您在提交任何申报表之前与合格的税务顾问审查结果。
---
## 应激测试套件
运行内置的应激测试以验证您的安装是否能处理所有支持的场景：
```bash
minus-tracker stress-test
```
这将生成 100 个样本 CSV 文件在临时目录中，对每个文件运行所有 CLI 命令，并报告通过/失败结果而不会影响您的项目文件。
### 选项
| 标志 | 默认值 | 描述 |
| --- | --- | --- |
| `--range N-M` | `1-100` | 仅运行场景 N 至 M |
| `--keep` | 关闭 | 在运行后保留生成的 CSV 文件 |
| `--json` | 关闭 | 输出结果为 JSON |
| `--output-dir <path>` | `/tmp/minus-tracker-stress-<ts>/` | 覆盖临时目录 |
### 场景
100 个场景涵盖：欧元/美元/英镑/瑞郎股票，LIFO 与 FIFO 分歧，部分批次消耗，多 ISIN 投资组合，ECB 周末备用，警告和错误情况，当日交易，舍入边缘情况和大投资组合（最多 200 笔交易）。
---
## 许可证
[MIT](./LICENSE) © 2026 Gabriele Randelli
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器