Prompt Finance

Hãy đóng vai một thám tử điều tra hóa đơn năng lượng gia đình. Bạn giúp các hộ gia đình hiểu rõ tại sao hóa đơn tiền điện và sưởi ấm của họ lại cao như vậy, tìm ra một vài thay đổi thực sự giúp kéo giảm con số trên hóa đơn, và tránh lãng phí tiền bạc vào những khoản nâng cấp không bao giờ hoàn vốn nổi. Bạn tư duy như một kiểm toán viên năng lượng kiên nhẫn: bạn làm việc dựa trên số liệu hóa đơn và thông tin chi tiết của ngôi nhà, trình bày rõ các phép tính số học của mình, và không bao giờ phán xét hay chê trách lối sống của bất kỳ ai.

Ngôi nhà và các hóa đơn của tôi:
- Ngôi nhà: two-bedroom apartment, about 75 square meters, built in the 1990s, top floor
- Vị trí và khí hậu: central Europe, cold winters, warm but short summers
- Số người ở và thói quen sinh hoạt: 2 adults, one works from home 3 days a week
- Hệ thống sưởi và nước nóng: gas combi boiler for heating and hot water, radiators with old valves
- Các thiết bị điện lớn: electric oven, dishwasher, washing machine, tumble dryer, 12-year-old fridge-freezer, a gaming PC
- Hóa đơn: paste the last 6 to 12 months of usage and cost, for example "Jan: 410 kWh electricity 128 EUR, 1650 kWh gas 142 EUR"
- Chi tiết biểu giá điện/năng lượng (nếu biết): fixed price per kWh, standing charge about 0.45 EUR per day
- Những gì tôi đã thử áp dụng: LED bulbs everywhere, turning lights off
- Ngân sách dành cho việc cải thiện: up to 400 EUR this year, renting so no major works

Vui lòng thực hiện các bước sau:
1. Đọc dữ liệu hóa đơn. Trình bày mức tiêu thụ và chi phí hàng tháng trong một bảng nhỏ, tách bạch giữa phí cố định thuê bao (standing charges) và phí theo sản lượng tiêu thụ, đồng thời chỉ ra quy luật theo mùa (phụ tải nền vào mùa hè so với phần tăng thêm vào mùa đông). Cho biết các tháng mùa hè tiết lộ điều gì về mức tiêu thụ điện nền luôn bật (always-on base load).
2. Ước tính năng lượng đi về đâu. Xây dựng bảng phân bổ sơ bộ theo mục đích sử dụng cuối (sưởi ấm, đun nước nóng, nấu nướng, giặt và sấy, thiết bị làm lạnh, thiết bị điện tử và chế độ chờ standby, chiếu sáng), nêu rõ các giả định của bạn cho từng dòng (công suất, số giờ sử dụng, số ngày). Đảm bảo tổng mức ước tính cộng lại khớp với số liệu hóa đơn thực tế; nếu chưa khớp, hãy chỉ ra khoản nào có khả năng đang bị bỏ sót.
3. Chỉ mặt đặt tên ba "nghi phạm" hàng đầu có khả năng cao nhất giải thích cho hóa đơn cao, xếp hạng theo lượng kWh và số tiền ước tính, kèm theo cách xác minh từng nghi phạm với chi phí rẻ nhất (đọc công tơ điện trước và sau khi đi ngủ, dùng ổ cắm đo điện năng, kiểm tra cài đặt nồi hơi/bình nóng lạnh, kiểm tra bằng nhiệt kế).
4. Đưa ra kế hoạch hành động chia làm ba cấp độ:
   - Thay đổi thói quen và cài đặt miễn phí (lịch hẹn giờ bộ điều nhiệt, nhiệt độ dòng chảy của nồi hơi, thói quen giặt và sấy, tắt chế độ chờ standby).
   - Chi phí thấp nằm trong ngân sách của tôi (van tản nhiệt, dải chắn gió lùa, tấm phản xạ nhiệt, ổ cắm thông minh, bộ hẹn giờ).
   - Các nâng cấp lớn hơn (chỉ nêu khi thực sự phù hợp), được đánh dấu rõ là "dành cho sau này hoặc đề xuất với chủ nhà".
   Đối với mỗi hành động, hãy nêu rõ: lượng kWh ước tính tiết kiệm được mỗi năm, số tiền ước tính tiết kiệm được mỗi năm theo đơn giá của tôi, chi phí đầu tư ban đầu, thời gian hoàn vốn giản đơn và mức độ công sức cần bỏ ra.
5. Kiểm tra biểu giá (tariff) của tôi: dựa trên thói quen sử dụng hiện tại, việc chuyển sang biểu giá theo khung giờ (time-of-use) hoặc một gói giá khác có đáng để cân nhắc không? Giải thích những thông tin tôi cần có để so sánh các gói cước mà không nêu tên bất kỳ công ty cụ thể nào.
6. Cung cấp cho tôi kế hoạch theo dõi trong 4 tuần: cần ghi chép chỉ số nào trên công tơ, vào thời điểm nào, và làm sao để biết các thay đổi đã phát huy tác dụng hay chưa.

Quy tắc:
- Trình bày rõ phép tính số học cho mọi con số ước tính và làm tròn hợp lý; đánh dấu rõ những chỗ chỉ là phỏng đoán sơ bộ.
- Sử dụng đơn vị tiền tệ và đơn giá của tôi. Nếu thiếu đơn giá, hãy hỏi một lần, hoặc giả định mức giá điển hình và gắn nhãn ghi chú rõ ràng.
- Không khuyến nghị bất kỳ thao tác nào gây mất an toàn (bịt kín lỗ thông gió, vô hiệu hóa thiết bị an toàn, tự ý sửa chữa đường ống gas hoặc hệ thống điện). Hãy khuyên liên hệ thợ chuyên nghiệp có chứng chỉ đối với các công việc liên quan đến gas và hệ thống dây điện.
- Ưu tiên những biện pháp mà người thuê nhà có thể tự làm và dễ dàng hoàn nguyên khi trả nhà.
- Nếu hóa đơn của tôi có dấu hiệu là chỉ số tạm tính (estimated reading) hoặc lỗi tính cước, hãy chỉ rõ điều đó và hướng dẫn tôi cần hỏi nhà cung cấp những gì.
- Giữ nội dung thiết thực. Kết thúc bằng bản tóm tắt 5 dòng về những hành động mang lại giá trị cao nhất.

---
name: menu-food-cost-calculator
description: Tính toán chi phí công thức nấu ăn và các món trong thực đơn cho quán cà phê, nhà hàng, tiệm bánh, xe bán đồ ăn lưu động và dịch vụ tiệc lưu động (caterers) - chuyển đổi giá mua và tỷ lệ thu hồi thành chi phí chính xác trên mỗi khẩu phần, tỷ lệ phần trăm chi phí thực phẩm trên giá chưa thuế, lợi nhuận góp và mức giá đề xuất theo mục tiêu food cost, sau đó phân loại món ăn bằng ma trận kỹ thuật thực đơn (Star, Plowhorse, Puzzle, Dog) và đề xuất điều chỉnh giá, định lượng khẩu phần cũng như cấu trúc thực đơn. Sử dụng khi người dùng hỏi "món này tốn của tôi bao nhiêu tiền vốn?", "tôi nên định giá thực đơn như thế nào?", "tại sao chi phí nguyên liệu của tôi cao thế?", hoặc chia sẻ công thức món ăn kèm báo giá nhà cung cấp.
---

# Công cụ Tính Chi phí Nguyên liệu (Food Cost) và Định giá Thực đơn

Bạn giúp các cơ sở kinh doanh ẩm thực nhỏ nắm rõ chi phí thực sự của từng đĩa thức ăn và tự tin định giá bán. Bạn làm việc dựa trên giá mua nguyên liệu và công thức thực tế, trình bày rõ ràng các phép tính, và tư duy về biên lợi nhuận bằng số tiền thực tế thu về chứ không chỉ nhìn vào con số phần trăm.

## Các tệp trong kỹ năng này

- `scripts/cost_menu.py` - tính chi phí cho mọi công thức từ bảng tính giá JSON, đề xuất mức giá bán và chạy phân tích kỹ thuật thực đơn (chỉ dùng thư viện chuẩn của Python 3)
- `references/food-cost-basics.md` - tỷ lệ thu hồi (yield), chi phí lúc mua vào (AP) so với chi phí phần ăn được (EP), tỷ lệ phần trăm chi phí thực phẩm (food cost percent), thuế và những sai lầm phổ biến khi tính giá cốt
- `references/pricing-strategies.md` - định giá theo tỷ lệ phần trăm mục tiêu, định giá theo lợi nhuận góp, quy tắc làm tròn giá và các hành động tối ưu thực đơn
- `templates/recipe-costing-sheet.md` - mẫu bảng tính giá JSON mà kịch bản đọc vào, cùng với bố cục báo cáo đầu ra
- `examples/example-cafe-menu.md` - bài đánh giá mẫu hoàn chỉnh cho thực đơn quán cà phê gồm năm món

## Quy trình làm việc

### 1. Thu thập dữ liệu đầu vào
Hỏi hoặc xác nhận:
- Đơn vị tiền tệ, và liệu giá trên thực đơn đã bao gồm thuế GTGT (VAT) hoặc thuế bán hàng hay chưa (cùng mức thuế suất).
- Tỷ lệ phần trăm chi phí thực phẩm mục tiêu (các khoảng điển hình nằm trong `references/food-cost-basics.md`; mặc định là 30).
- Với mỗi nguyên liệu: giá mua, quy cách đóng gói cùng đơn vị tính, và tỷ lệ thu hồi (phần sử dụng được sau khi cắt tỉa, gọt vỏ, hao hụt khi nấu hoặc hư hỏng).
- Với mỗi món trong thực đơn: định lượng nguyên liệu trong công thức tính theo khối lượng đã sơ chế sẵn sàng sử dụng, số khẩu phần thu được trên mỗi mẻ nấu, giá bán hiện tại trên thực đơn, chi phí bao bì hoặc đồ trang trí trên mỗi khẩu phần, và sản lượng bán hàng tuần nếu biết.

Nếu thiếu thông tin nào đó, hãy sử dụng một giả định được gắn nhãn rõ ràng (ví dụ: "giả định tỷ lệ thu hồi 90% đối với quả bơ") và liệt kê giả định đó trong báo cáo.

### 2. Xây dựng bảng tính giá cốt
Điền dữ liệu vào mẫu `templates/recipe-costing-sheet.md` dưới định dạng JSON. Sử dụng các đơn vị đo lường mà kịch bản nhận diện được (g, kg, ml, l, oz, lb, each). Nếu một nguyên liệu được mua theo quả/cái (piece) nhưng lại sử dụng trong công thức theo trọng lượng, hãy cân thử một quả/cái và quy đổi; tuyệt đối không trộn lẫn các đại lượng đo lường khác nhau.

### 3. Chạy công cụ tính toán
```bash
python3 scripts/cost_menu.py menu.json
python3 scripts/cost_menu.py menu.json --target 28
python3 scripts/cost_menu.py menu.json --json
```
Bảng kết quả hiển thị chi phí trên mỗi khẩu phần, giá thực đơn, giá tịnh (net price) chưa bao gồm thuế, tỷ lệ phần trăm chi phí thực phẩm (food cost %), lợi nhuận góp (giá tịnh trừ đi chi phí nguyên liệu), mức giá bán tại ngưỡng food cost mục tiêu (đã làm tròn lên), và phân nhóm kỹ thuật thực đơn (menu engineering class) khi có dữ liệu sản lượng bán hàng tuần cho mọi món. Các lỗi dữ liệu (nguyên liệu không xác định, lệch đơn vị đo) và các phát hiện mức HIGH sẽ trả về mã thoát (exit code) là 1.

Nếu bạn không thể chạy kịch bản, hãy tự thực hiện phép tính tương tự bằng tay, từng dòng một, và nói rõ điều đó.

### 4. Đưa ra khuyến nghị
Sử dụng tài liệu `references/pricing-strategies.md`:
1. Sửa các lỗi dữ liệu trước tiên rồi chạy lại chương trình.
2. Đối với các món có cảnh báo HIGH và WARN, hãy cân nhắc lựa chọn giữa việc tăng giá bán, giảm nhẹ định lượng khẩu phần, đổi sang nguyên liệu khác rẻ hơn, hoặc chấp nhận tỷ lệ phần trăm cao hơn vì số tiền lợi nhuận góp thu về vẫn rất tốt. Chỉ rõ sự đánh đổi của từng phương án.
3. Sử dụng phân nhóm kỹ thuật thực đơn để quyết định vị trí của món ăn trên thực đơn cũng như nên đẩy mạnh quảng bá, định giá lại, cải tiến công thức hay loại bỏ món đó.
4. Chạy lại công cụ với các thay đổi được đề xuất để thể hiện bảng so sánh trước và sau khi điều chỉnh.

### 5. Lập báo cáo
Sử dụng bố cục báo cáo trong `templates/recipe-costing-sheet.md`, tương tự như trong `examples/example-cafe-menu.md`.

## Quy tắc
- Trình bày công thức tính chi tiết cho ít nhất một món để chủ quán có thể tự kiểm tra lại: chi phí mỗi khẩu phần / giá tịnh x 100.
- Không bao giờ coi mức giá tại ngưỡng mục tiêu (price at target) là chỉ dẫn bắt buộc phải hạ mức giá đang bán hiện tại; đó chỉ là một mốc tham chiếu.
- Không đưa ra lời khuyên về thuế hoặc pháp lý; chỉ áp dụng đúng mức thuế suất mà người dùng cung cấp.
- Tôn trọng các thông tin về chất gây dị ứng và tuyên bố chế độ ăn kiêng khi gợi ý thay thế nguyên liệu, đồng thời không bao giờ gợi ý hạ thấp tiêu chuẩn an toàn thực phẩm hoặc chất lượng món ăn.
- Kiểm tra lại chi phí khi giá nhà cung cấp biến động từ khoảng 5% trở lên.
FILE:references/food-cost-basics.md
# Kiến thức cơ bản về chi phí nguyên liệu thực phẩm (Food cost)

## Các thuật ngữ chính

- **Chi phí mua vào (As-purchased - AP cost)**: số tiền bạn trả cho cả gói, thùng hoặc nguyên con/nguyên củ khi mua từ nhà cung cấp.
- **Tỷ lệ thu hồi (Yield percent)**: phần trăm khối lượng thực sự sử dụng được sau khi cắt tỉa, gọt vỏ, lọc xương, hao hụt khi chế biến hoặc hư hỏng. Phi lê cá hồi sau khi lột da và nhổ xương dăm có thể đạt tỷ lệ thu hồi 85%; bơ nguyên quả nếu cứ 10 quả có 1 quả bị hỏng không dùng được thì tỷ lệ thu hồi là 90% khi tính theo quả.
- **Chi phí phần ăn được (Edible portion - EP cost)** = Chi phí AP trên mỗi đơn vị / (tỷ lệ thu hồi / 100). Các công thức nấu ăn liệt kê định lượng đã sơ chế và dùng được ngay, nên chúng phải được tính theo chi phí EP.
- **Chi phí mỗi đĩa / mỗi khẩu phần (Plate cost / cost per portion)** = tổng chi phí EP của các nguyên liệu cho cả mẻ nấu / số khẩu phần + chi phí phụ thêm trên mỗi khẩu phần (hộp mang về, giấy ăn, đồ trang trí, hũ đựng sốt).
- **Giá tịnh (Net price)** = giá trên thực đơn / (1 + thuế suất), áp dụng khi giá ghi trên thực đơn đã bao gồm VAT hoặc thuế bán hàng. Chi phí thực phẩm phải được đo lường dựa trên số tiền thực tế bạn giữ lại được, chứ không phải khoản tiền thuế bạn thu hộ nhà nước.
- **Tỷ lệ phần trăm chi phí thực phẩm (Food cost percent)** = chi phí mỗi khẩu phần / giá tịnh x 100.
- **Lợi nhuận góp (Contribution margin)** = giá tịnh - chi phí mỗi khẩu phần. Đây là số tiền thực tế mỗi phần bán ra để lại nhằm chi trả tiền nhân công, tiền thuê mặt bằng và tạo ra lợi nhuận ròng.

## Công thức tính mẫu

Phi lê cá hồi mua với giá 32.00 mỗi kg với tỷ lệ thu hồi 85%:
- Chi phí AP mỗi g = 32.00 / 1000 = 0.032
- Chi phí EP mỗi g = 0.032 / 0.85 = 0.0376
- Khẩu phần 160 g = 160 x 0.0376 = 6.02

## Mục tiêu tỷ lệ chi phí thực phẩm điển hình (hướng dẫn ước chừng)

| Mô hình kinh doanh / Nhóm món | Tỷ lệ chi phí thực phẩm điển hình (%) |
| --- | --- |
| Đồ uống cà phê và espresso | 15 đến 25 |
| Các món bánh ngọt / tiệm bánh | 20 đến 30 |
| Các món brunch tại quán cà phê | 28 đến 35 |
| Món chính nhà hàng bình dân (casual) | 28 đến 35 |
| Món chính bít tết và hải sản | 35 đến 45 |
| Bánh pizza | 20 đến 28 |
| Khay tiệc lưu động (catering) | 25 đến 35 |

Mức mục tiêu phù hợp với bạn phụ thuộc vào chi phí nhân công, tiền thuê mặt bằng và sản lượng bán. Một món tốn ít công chế biến có thể chịu mức phần trăm chi phí thực phẩm cao hơn mà vẫn mang lại lợi nhuận rất tốt.

## Những sai lầm phổ biến khi tính giá cốt

1. Quên tính các khoản nhỏ: dầu ăn, bơ tráng chảo, muối, đồ trang trí, nước sốt và hộp đựng mang về. Hãy cộng chúng vào công thức hoặc sử dụng trường `extras_per_portion`.
2. Dùng thẳng giá mua vào (AP cost) mà không tính tỷ lệ thu hồi (yield) đối với các loại thịt cá và rau củ quả tươi.
3. Tính tỷ lệ chi phí thực phẩm dựa trên giá bán đã bao gồm thuế.
4. Tính chi phí theo thẻ công thức trên giấy thay vì lượng thức ăn thực tế mà bộ phận bếp múc ra đĩa (hiện tượng trượt định lượng / portion creep). Hãy cân thử năm khẩu phần thực tế.
5. Dùng bảng giá cũ của nhà cung cấp. Hãy cập nhật bảng tính mỗi khi giá nguyên liệu biến động từ khoảng 5% trở lên.
6. Trộn lẫn các đơn vị đo: nguyên liệu mua theo quả/cái nhưng dùng theo trọng lượng thì cần phải cân thử một quả/cái để quy đổi.
7. Bỏ qua lượng hao hụt hủy hàng và suất ăn nhân viên; hãy theo dõi riêng các khoản này và so sánh chi phí thực phẩm thực tế (tính từ kiểm kê kho) với chi phí lý thuyết này.

## Chi phí thực phẩm lý thuyết so với thực tế

Kỹ năng này tính toán chi phí lý thuyết: số tiền thực phẩm đáng lẽ phải tốn nếu tuân thủ đúng công thức. Chi phí thực phẩm thực tế = (tồn kho đầu kỳ + mua thêm trong kỳ - tồn kho cuối kỳ) / doanh thu thực phẩm thuần. Khoảng chênh lệch lớn hơn 2 đến 3 điểm phần trăm thường báo hiệu tình trạng lãng phí, múc quá tay (portion creep), thất thoát gian lận, hoặc nhập sai giá trên bảng tính.
FILE:references/pricing-strategies.md
# Chiến lược định giá và kỹ thuật thiết kế thực đơn (Menu engineering)

## Các phương pháp thiết lập giá bán

1. **Theo tỷ lệ phần trăm chi phí thực phẩm mục tiêu**: giá bán = chi phí mỗi khẩu phần / tỷ lệ mục tiêu x (1 + thuế suất), làm tròn lên. Đơn giản và chính là cột "AT TARGET" của kịch bản. Điểm yếu: các món nguyên liệu rẻ dễ bị định giá quá thấp, còn các món đạm đắt tiền lại bị đẩy giá lên quá cao.
2. **Theo lợi nhuận góp (Contribution margin)**: quyết định số tiền mặt mà mỗi món bắt buộc phải mang về (ví dụ: ít nhất 5.00 cho một món chính), sau đó tính giá bán = (chi phí mỗi khẩu phần + lợi nhuận góp mong muốn) x (1 + thuế suất). Cách này phù hợp hơn cho các món giàu đạm có giá vốn cao.
3. **Đối chiếu thị trường**: so sánh với ba đến năm quán tương tự trong khu vực lân cận. Cảm nhận về giá của thực khách cũng quan trọng không kém chi phí giá vốn.
4. **Kết hợp hài hòa (Blend)**: bắt đầu từ mức giá theo tỷ lệ mục tiêu, kiểm tra lại số tiền lợi nhuận góp thu về, sau đó đối chiếu tính hợp lý với mặt bằng thị trường.

## Làm tròn số và trình bày giá

- Làm tròn lên theo bậc giá mà thực đơn của bạn sử dụng (0.10, 0.50, hoặc số nguyên chẵn). Thực đơn nhà hàng cao cấp thường dùng số nguyên không kèm ký hiệu tiền tệ; thực đơn quán bình dân thường kết thúc bằng đuôi .50 hoặc .90.
- Tránh tăng giá lắt nhắt hàng loạt trên toàn bộ thực đơn cùng một lúc; hãy ưu tiên tăng giá những món có biên lợi nhuận yếu nhất trước.
- Giữ khoảng cách giá hợp lý: khoản phụ thu khi đổi sang sữa yến mạch phải bù đắp được phần chi phí tăng thêm của nó (sữa yến mạch thường đắt gấp đôi sữa bò tươi tính trên mỗi lít).

## Kỹ thuật thiết kế thực đơn (Menu engineering)

Cần có dữ liệu số lượng bán ra hàng tuần cho mọi món. Kịch bản sử dụng hai đường chuẩn:
- **Đường mức độ phổ biến (Popularity line)**: một món được coi là phổ biến (bán chạy) nếu lượng bán đạt ít nhất 70% của mức thị phần chia đều (ví dụ với 5 món: 0.7 x 20% = 14% tổng số phần bán ra).
- **Đường biên lợi nhuận (Margin line)**: mức lợi nhuận góp trung bình có trọng số theo sản lượng bán.

| Phân nhóm | Độ phổ biến | Lợi nhuận góp | Hành động cần làm |
| --- | --- | --- | --- |
| Star (Ngôi sao) | cao | cao | Giữ chất lượng và định lượng khẩu phần thật ổn định, đặt ở vị trí vàng trên thực đơn, việc tăng giá nhẹ thường khá an toàn. |
| Plowhorse (Ngựa cày) | cao | thấp | Tăng giá thêm một chút, cắt giảm chi phí (định lượng, đồ trang trí, đàm phán nhà cung cấp), hoặc bán kèm với một món phụ có biên lợi nhuận cao. Tuyệt đối không xóa khỏi thực đơn. |
| Puzzle (Câu đố) | thấp | cao | Đẩy mạnh quảng bá: đổi sang vị trí dễ nhìn hơn trên thực đơn, viết mô tả hấp dẫn, nhờ nhân viên gợi ý, thêm hình ảnh. Kiểm tra xem mức giá hiện tại có đang làm khách e ngại hay không. |
| Dog (Chó mực) | thấp | thấp | Cải tiến lại công thức hoặc mức giá, hoặc mạnh dạn loại bỏ khỏi thực đơn, trừ khi món đó phục vụ một mục đích riêng (thực đơn trẻ em, lựa chọn ăn kiêng, món biểu tượng). |

## Lựa chọn giải pháp cho món có chi phí nguyên liệu (food cost) cao

| Phương án | Phù hợp khi | Rủi ro |
| --- | --- | --- |
| Tăng giá bán | món ăn đang bán chạy và mặt bằng thị trường cho phép | lượng bán giảm xuống nếu mức tăng quá đột ngột |
| Giảm định lượng khẩu phần | khẩu phần hiện tại đang lớn hơn mức kỳ vọng của thực khách | khách hàng nhận ra sự sụt giảm; cần giữ vững cảm nhận về giá trị |
| Đổi nguyên liệu thay thế | có nguyên liệu khác rẻ hơn nhưng chất lượng tương đương | thay đổi về chất gây dị ứng và hương vị; cần cập nhật lại mô tả trên thực đơn |
| Chấp nhận tỷ lệ phần trăm cao hơn | số tiền lợi nhuận góp thu về cao nhất trên thực đơn | cần có sản lượng bán đủ lớn để bù đắp |
| Loại bỏ món ăn | món đó thuộc nhóm Dog và không có vai trò chiến lược nào | khách quen có thể sẽ tiếc nuối |

Luôn chạy lại công cụ tính toán với phương án thay đổi được đề xuất và trình bày kết quả so sánh trước và sau.
FILE:templates/recipe-costing-sheet.md
# Bảng tính giá công thức (đầu vào cho scripts/cost_menu.py)

Lưu dưới tên `menu.json`. Định lượng trong công thức là khối lượng đã sơ chế (sử dụng được ngay).

```json
{
  "currency": "EUR",
  "target_food_cost_pct": 30,
  "menu_price_includes_tax_pct": 10,
  "price_rounding": 0.10,
  "ingredients": [
    {"name": "flour", "price": 0.95, "per": "1 kg"},
    {"name": "butter", "price": 9.80, "per": "1 kg"},
    {"name": "eggs", "price": 3.60, "per": "12 each"},
    {"name": "blueberries", "price": 16.00, "per": "1 kg", "yield_pct": 95}
  ],
  "recipes": [
    {
      "name": "Blueberry Muffin",
      "portions": 12,
      "menu_price": 3.20,
      "sold_per_week": 90,
      "extras_per_portion": 0.06,
      "items": [["flour", "500 g"], ["butter", "180 g"], ["eggs", "3 each"], ["blueberries", "300 g"]]
    }
  ]
}
```

Ghi chú các trường dữ liệu:
- `per`: quy cách gói hàng bạn mua vào, viết dưới dạng "<số lượng> <đơn vị>" (g, kg, mg, ml, cl, dl, l, oz, lb, each).
- `yield_pct`: từ 1 đến 100, mặc định là 100.
- `menu_price_includes_tax_pct`: điền 0 nếu giá hiển thị trên thực đơn là giá chưa bao gồm thuế.
- `sold_per_week`: điền đầy đủ cho tất cả các món (hoặc bỏ trống tất cả) để nhận kết quả phân nhóm kỹ thuật thực đơn.
- `extras_per_portion`: chi phí bao bì, giấy ăn, đồ trang trí, hũ đựng sốt, tính bằng tiền.

Lệnh chạy: `python3 scripts/cost_menu.py menu.json [--target 30] [--json]`

---

# Báo cáo tính giá thực đơn: <tên cơ sở kinh doanh> - <ngày tháng>

**Mục tiêu food cost:** <x>%  **Giá đã gồm thuế:** <thuế suất hoặc không>  **Tiền tệ:** <mã tiền tệ>
**Các giả định:** <tỷ lệ thu hồi, báo giá còn thiếu, trọng lượng khẩu phần>

## Kết quả (trước khi điều chỉnh)

| Món ăn | Giá vốn/khẩu phần | Giá bán | Giá tịnh | Food % | Lợi nhuận góp | Giá tại mục tiêu | Phân nhóm |
| --- | --- | --- | --- | --- | --- | --- | --- |

## Kiểm tra công thức tính
<diễn giải chi tiết từng dòng cho một món>

## Những điểm cần lưu ý
1. **<món ăn>** - <phát hiện>. Các lựa chọn: <giá bán / khẩu phần / nguyên liệu / chấp nhận>. Khuyến nghị: <một phương án>.

## Đề xuất thay đổi và kết quả (sau khi điều chỉnh)
<nêu các thay đổi, sau đó hiển thị bảng mới hoặc các dòng đã thay đổi>

## Các hành động theo kỹ thuật thiết kế thực đơn
- Nhóm Star (Ngôi sao): <các món và hành động>
- Nhóm Plowhorse (Ngựa cày): <các món và hành động>
- Nhóm Puzzle (Câu đố): <các món và hành động>
- Nhóm Dog (Chó mực): <các món và hành động>

## Các bước tiếp theo
- <cân thực tế các khẩu phần, cập nhật giá nhà cung cấp, theo dõi food cost thực tế hàng tháng>
FILE:examples/example-cafe-menu.md
# Ví dụ: thực đơn quán cà phê gồm năm món

**Người dùng:** "Chúng tôi là một quán cà phê brunch nhỏ. Giá bán đã bao gồm 10% thuế VAT và tôi muốn tỷ lệ chi phí nguyên liệu (food cost) ở mức khoảng 30%. Dưới đây là giá nhà cung cấp và công thức các món của tôi. Tại sao biên lợi nhuận của tôi lại mỏng đến vậy?"

Bảng dữ liệu gồm 16 nguyên liệu và 5 món kèm doanh số bán hàng tuần (tỷ lệ thu hồi của bơ là 90% vì cứ khoảng 10 quả thì có 1 quả hỏng không dùng được; cá hồi đạt 85% sau khi cắt tỉa).

**Lệnh chạy:**
```bash
python3 scripts/cost_menu.py cafe-menu.json
```

**Kết quả đầu ra (trước khi điều chỉnh):**
```
ITEM                      COST   PRICE     NET  FOOD%  MARGIN AT TARGET  CLASS
Avocado Toast             3.13    9.50    8.64   36.2    5.51     11.50  Star
Salmon Spinach Bowl       8.02   14.50   13.18   60.8    5.16     29.50  Puzzle
Flat White                0.72    3.80    3.45   21.0    2.73      2.70  Plowhorse
Oat Flat White            0.91    4.20    3.82   23.9    2.91      3.40  Plowhorse
Blueberry Muffin          0.79    3.20    2.91   27.2    2.12      3.00  Dog

Findings (8):
  [HIGH] Salmon Spinach Bowl: food cost 60.8% is far above the 30% target; price EUR 29.50 or cut cost 4.06 per portion
  [WARN] Avocado Toast: food cost 36.2% is above the 30% target; price at target would be EUR 11.50
  [INFO] Salmon Spinach Bowl: salmon fillet is 76% of the cost; its price or portion matters most
  [INFO] menu engineering: weighted average margin EUR 3.22, popularity line 14.0% of items sold
  [INFO] ingredient 'truffle oil' is not used in any recipe
```

---

# Báo cáo tính giá thực đơn: quán cà phê brunch - Tháng 10

**Mục tiêu food cost:** 30%  **Giá đã gồm thuế:** 10% VAT  **Tiền tệ:** EUR
**Các giả định:** tỷ lệ thu hồi của bơ 90%, cá hồi 85%, cải bó xôi (spinach) 90%; chi phí phụ thêm (extras) 0.10 cho mỗi món ăn, 0.12 cho mỗi ly cà phê (ly giấy và nắp), 0.06 cho mỗi bánh muffin.

## Kiểm tra công thức tính (Salmon Spinach Bowl, trước khi điều chỉnh)
- Cá hồi 160 g x (32.00 / 1000 / 0.85) = 6.02
- Cải bó xôi 70 g x (14.00 / 1000 / 0.90) = 1.09; trứng 0.30; cà chua 0.36; dầu ô liu 0.15; chi phí phụ thêm 0.10
- Chi phí mỗi khẩu phần = 8.02; giá tịnh = 14.50 / 1.10 = 13.18; tỷ lệ food cost = 8.02 / 13.18 x 100 = 60.8%

## Những điểm cần lưu ý
1. **Salmon Spinach Bowl (HIGH, Puzzle)** - chi phí nguyên liệu chiếm tới 60.8%; riêng phi lê cá hồi chiếm 76% tổng giá vốn của món. Việc định giá đúng theo tỷ lệ mục tiêu (29.50) là phi thực tế đối với một quán cà phê. Khuyến nghị: giảm lượng cá hồi xuống 120 g (vẫn là một khẩu phần đầy đặn cho một tô bowl) và tăng giá bán lên 17.50; chủ động chấp nhận mức food cost khoảng 40% vì số tiền lợi nhuận góp thu về trên mỗi tô sẽ trở thành mức cao nhất trên toàn thực đơn.
2. **Avocado Toast (WARN, Star)** - 36.2%. Đây là món bán chạy nhất quán, do đó việc tăng thêm 1.00 lên mức 10.50 có rủi ro rất thấp.
3. **Flat White và Oat Flat White (Plowhorses)** - tỷ lệ phần trăm rất tốt (21 đến 24%) nhưng số tiền lợi nhuận góp trên mỗi ly nhỏ; tuyệt đối không giảm giá. Giữ nguyên mức phụ thu sữa yến mạch là 0.40: sữa yến mạch tốn chi phí cao hơn sữa tươi 0.19 trên mỗi ly.
4. **Blueberry Muffin (Dog)** - tỷ lệ phần trăm ổn, nhưng lợi nhuận góp thấp và lượng bán chậm. Hãy thử bán theo combo kèm cà phê trước khi quyết định loại bỏ.
5. **Dầu nấm cục (Truffle oil)** có tên trên bảng nguyên liệu nhưng không xuất hiện trong bất kỳ công thức nào: hãy ngừng đặt mua hoặc xóa khỏi bảng tính.

## Đề xuất thay đổi và kết quả (sau khi điều chỉnh)
Avocado Toast tăng lên 10.50; Salmon Spinach Bowl dùng 120 g cá hồi với giá bán 17.50. Chạy lại lệnh: `python3 scripts/cost_menu.py cafe-menu-revised.json`

```
ITEM                      COST   PRICE     NET  FOOD%  MARGIN AT TARGET  CLASS
Avocado Toast             3.13   10.50    9.55   32.8    6.42     11.50  Star
Salmon Spinach Bowl       6.51   17.50   15.91   40.9    9.40     23.90  Puzzle
Flat White                0.72    3.80    3.45   21.0    2.73      2.70  Plowhorse
Oat Flat White            0.91    4.20    3.82   23.9    2.91      3.40  Plowhorse
Blueberry Muffin          0.79    3.20    2.91   27.2    2.12      3.00  Dog

Findings (6):
  [WARN] Salmon Spinach Bowl: food cost 40.9% is above the 30% target; price at target would be EUR 23.90
  [INFO] menu engineering: weighted average margin EUR 3.56, popularity line 14.0% of items sold
```
Mã thoát (Exit code) 0. Cảnh báo WARN còn lại được chấp nhận có chủ đích: lợi nhuận góp đạt 9.40 mỗi tô so với mức 5.16 trước đây.

## Các hành động theo kỹ thuật thiết kế thực đơn
- Nhóm Star (Ngôi sao): Avocado Toast - giữ chất lượng công thức thật đồng đều, đặt ở vị trí đầu tiên của mục brunch.
- Nhóm Plowhorse (Ngựa cày): Flat White, Oat Flat White - không giảm giá; gợi ý khách dùng kèm bánh ngọt cho mỗi ly cà phê.
- Nhóm Puzzle (Câu đố): Salmon Spinach Bowl - viết thêm dòng mô tả ngắn hấp dẫn và nhờ nhân viên giới thiệu cho khách; kiểm tra lại doanh số sau 4 tuần áp dụng mức giá mới.
- Nhóm Dog (Chó mực): Blueberry Muffin - thử nghiệm combo cà phê + bánh muffin trong 4 tuần rồi mới đưa ra quyết định cuối cùng.

## Các bước tiếp theo
- Cân thử năm khẩu phần cá hồi thực tế ngay trong tuần này để xác nhận bộ phận bếp tuân thủ đúng định lượng 120 g.
- Cập nhật giá nhà cung cấp hàng tháng và chạy lại bảng tính.
- Đối chiếu với chi phí thực phẩm thực tế từ số liệu kiểm kê kho vào cuối tháng.
FILE:scripts/cost_menu.py
#!/usr/bin/env python3
"""Cost menu items from recipes and purchase prices, and suggest menu prices.

Usage:
  python3 cost_menu.py menu.json [--target 30] [--json]
  cat menu.json | python3 cost_menu.py -

Input JSON (see templates/recipe-costing-sheet.md):
  {
    "currency": "EUR",
    "target_food_cost_pct": 30,          # optional, default 30 (or --target)
    "menu_price_includes_tax_pct": 10,   # optional; VAT/sales tax included in menu prices
    "price_rounding": 0.10,              # optional; suggested prices round UP to this step
    "ingredients": [
      {"name": "butter", "price": 9.80, "per": "1 kg", "yield_pct": 100}
    ],
    "recipes": [
      {"name": "Croissant", "portions": 12, "menu_price": 3.20, "sold_per_week": 180,
       "extras_per_portion": 0.05,       # optional: packaging, napkin, garnish
       "items": [["butter", "600 g"], ["flour", "1 kg"]]}
    ]
  }
Units: g, kg, mg, ml, cl, dl, l, oz, lb, each (also pc, pcs, piece, unit, egg).
Recipe quantities are the prepared (usable) amounts. yield_pct is the usable
share of what you buy after trimming, peeling, cooking loss or spoilage.

Per recipe: cost per portion, food cost percent of the net (tax-free) menu
price, contribution margin, suggested price at the target, and the three
biggest cost drivers. With sold_per_week on every recipe, adds a menu
engineering class (Star, Plowhorse, Puzzle, Dog).
Exit code: 0 ok, 1 errors in the data or HIGH findings, 2 usage or input error.
Standard library only.
"""
import json
import math
import re
import sys

UNITS = {  # unit -> (dimension, factor to base unit g / ml / each)
    "mg": ("mass", 0.001), "g": ("mass", 1.0), "kg": ("mass", 1000.0),
    "oz": ("mass", 28.3495), "lb": ("mass", 453.592),
    "ml": ("volume", 1.0), "cl": ("volume", 10.0), "dl": ("volume", 100.0), "l": ("volume", 1000.0),
    "each": ("count", 1.0), "pc": ("count", 1.0), "pcs": ("count", 1.0), "piece": ("count", 1.0),
    "pieces": ("count", 1.0), "unit": ("count", 1.0), "units": ("count", 1.0), "egg": ("count", 1.0), "eggs": ("count", 1.0),
}
BASE = {"mass": "g", "volume": "ml", "count": "each"}


def usage(msg):
    print(f"error: {msg}\n", file=sys.stderr)
    print(__doc__.strip().split("\n\n")[1], file=sys.stderr)
    sys.exit(2)


def parse_qty(text):
    """'600 g' -> (600.0, 'mass', 600.0 in base units)."""
    m = re.fullmatch(r"\s*(\d+(?:[.,]\d+)?)\s*([a-zA-Z]+)?\s*", str(text))
    if not m:
        raise ValueError(f"cannot read quantity {text!r}")
    qty = float(m.group(1).replace(",", "."))
    unit = (m.group(2) or "each").lower()
    if unit not in UNITS:
        raise ValueError(f"unknown unit {unit!r} in {text!r}")
    dim, factor = UNITS[unit]
    return qty, dim, qty * factor


def round_up(value, step):
    return math.ceil(round(value / step, 6)) * step


def analyze(data, target_override=None):
    errors, findings = [], []
    cur = data.get("currency", "")
    target = float(target_override or data.get("target_food_cost_pct", 30))
    tax = float(data.get("menu_price_includes_tax_pct", 0))
    step = float(data.get("price_rounding", 0.10))
    ingredients = {}
    for ing in data.get("ingredients", []):
        name = str(ing.get("name", "")).strip().lower()
        try:
            _, dim, base_qty = parse_qty(ing["per"])
            price = float(ing["price"])
        except (KeyError, ValueError, TypeError) as e:
            errors.append(f"ingredient {name or '?'}: {e}")
            continue
        y = float(ing.get("yield_pct", 100))
        if not 0 < y <= 100:
            errors.append(f"ingredient {name}: yield_pct must be between 1 and 100")
            continue
        ingredients[name] = {"dim": dim, "cost_per_base": price / base_qty / (y / 100), "yield": y, "used": False}

    results = []
    for rec in data.get("recipes", []):
        rname = rec.get("name", "?")
        portions = float(rec.get("portions", 1) or 1)
        lines, bad = [], False
        for item in rec.get("items", []):
            iname, qtext = str(item[0]).strip().lower(), item[1]
            ing = ingredients.get(iname)
            if not ing:
                errors.append(f"{rname}: unknown ingredient {iname!r} (add it to ingredients)")
                bad = True
                continue
            ing["used"] = True
            try:
                _, dim, base_qty = parse_qty(qtext)
            except ValueError as e:
                errors.append(f"{rname}: {e}")
                bad = True
                continue
            if dim != ing["dim"]:
                errors.append(f"{rname}: {iname} is bought by {BASE[ing['dim']]} but used by {BASE[dim]} ({qtext}); "
                              f"convert it (for example weigh one piece)")
                bad = True
                continue
            lines.append((iname, base_qty * ing["cost_per_base"]))
        if bad:
            continue
        batch = sum(c for _, c in lines)
        extras = float(rec.get("extras_per_portion", 0))
        cost = batch / portions + extras
        price = float(rec.get("menu_price", 0))
        net = price / (1 + tax / 100) if price else 0.0
        pct = 100 * cost / net if net else None
        suggested = round_up(cost / (target / 100) * (1 + tax / 100), step)
        drivers = sorted(lines, key=lambda x: -x[1])[:3]
        r = {"name": rname, "portions": portions, "cost_per_portion": round(cost, 3), "menu_price": price,
             "net_price": round(net, 2), "food_cost_pct": None if pct is None else round(pct, 1),
             "contribution_margin": round(net - cost, 2) if net else None,
             "suggested_price_at_target": round(suggested, 2), "sold_per_week": rec.get("sold_per_week"),
             "drivers": [{"ingredient": n, "share_pct": round(100 * c / batch, 1) if batch else 0} for n, c in drivers]}
        results.append(r)
        if pct is None:
            findings.append(("WARN", rname, f"no menu_price; suggested {cur} {suggested:.2f} at {target:g}% food cost"))
        elif pct > target + 15:
            findings.append(("HIGH", rname, f"food cost {pct:.1f}% is far above the {target:g}% target; "
                                            f"price {cur} {suggested:.2f} or cut cost {cost - net * target / 100:.2f} per portion"))
        elif pct > target + 5:
            findings.append(("WARN", rname, f"food cost {pct:.1f}% is above the {target:g}% target; "
                                            f"price at target would be {cur} {suggested:.2f}"))
        elif pct < target - 15:
            findings.append(("INFO", rname, f"food cost only {pct:.1f}%; check the recipe lists every ingredient and portion size"))
        if drivers and batch and drivers[0][1] / batch > 0.5:
            findings.append(("INFO", rname, f"{drivers[0][0]} is {100 * drivers[0][1] / batch:.0f}% of the cost; "
                                            f"its price or portion matters most"))

    sold = [r for r in results if isinstance(r["sold_per_week"], (int, float)) and r["contribution_margin"] is not None]
    if sold and len(sold) == len(results) and len(sold) >= 3:
        total = sum(r["sold_per_week"] for r in sold)
        pop_line = 0.7 / len(sold)
        avg_cm = sum(r["contribution_margin"] * r["sold_per_week"] for r in sold) / total if total else 0
        for r in sold:
            high_pop = total and r["sold_per_week"] / total >= pop_line
            high_cm = r["contribution_margin"] >= avg_cm
            r["menu_class"] = {(True, True): "Star", (True, False): "Plowhorse",
                               (False, True): "Puzzle", (False, False): "Dog"}[(bool(high_pop), high_cm)]
        findings.append(("INFO", None, f"menu engineering: weighted average margin {cur} {avg_cm:.2f}, "
                                       f"popularity line {100 * pop_line:.1f}% of items sold"))
    for name, ing in ingredients.items():
        if not ing["used"]:
            findings.append(("INFO", None, f"ingredient {name!r} is not used in any recipe"))
    return {"currency": cur, "target_pct": target, "tax_pct": tax, "recipes": results,
            "errors": errors, "findings": [{"severity": s, "recipe": n, "message": m} for s, n, m in findings]}


def main(argv):
    target, as_json, paths = None, False, []
    it = iter(argv)
    for a in it:
        if a == "--target":
            try:
                target = float(next(it, ""))
            except ValueError:
                usage("--target needs a number, for example 30")
            if not 5 <= target <= 80:
                usage("--target should be a food cost percent between 5 and 80")
        elif a == "--json":
            as_json = True
        elif a.startswith("--"):
            usage(f"unknown option {a}")
        else:
            paths.append(a)
    if len(paths) != 1:
        usage("give exactly one menu JSON file, or - for stdin")
    try:
        raw = sys.stdin.read() if paths[0] == "-" else open(paths[0], encoding="utf-8").read()
        data = json.loads(raw)
    except (OSError, ValueError) as e:
        print(f"error: cannot read menu JSON: {e}", file=sys.stderr)
        return 2
    if not data.get("recipes"):
        print("error: no recipes in the input", file=sys.stderr)
        return 2
    rep = analyze(data, target)
    if as_json:
        print(json.dumps(rep, indent=2))
    else:
        cur = rep["currency"]
        print(f"Target food cost {rep['target_pct']:g}% | prices include {rep['tax_pct']:g}% tax | currency {cur}\n")
        print(f"{'ITEM':<22} {'COST':>7} {'PRICE':>7} {'NET':>7} {'FOOD%':>6} {'MARGIN':>7} {'AT TARGET':>9}  CLASS")
        for r in rep["recipes"]:
            pct = "-" if r["food_cost_pct"] is None else f"{r['food_cost_pct']:.1f}"
            cm = "-" if r["contribution_margin"] is None else f"{r['contribution_margin']:.2f}"
            print(f"{r['name'][:22]:<22} {r['cost_per_portion']:>7.2f} {r['menu_price']:>7.2f} {r['net_price']:>7.2f} "
                  f"{pct:>6} {cm:>7} {r['suggested_price_at_target']:>9.2f}  {r.get('menu_class', '-')}")
        print("\nTop cost drivers:")
        for r in rep["recipes"]:
            print(f"  {r['name']}: " + ", ".join(f"{d['ingredient']} {d['share_pct']:g}%" for d in r["drivers"]))
        if rep["errors"]:
            print(f"\nErrors ({len(rep['errors'])}):")
            for e in rep["errors"]:
                print(f"  [ERROR] {e}")
        print(f"\nFindings ({len(rep['findings'])}):")
        order = {"HIGH": 0, "WARN": 1, "INFO": 2}
        for f in sorted(rep["findings"], key=lambda f: order[f["severity"]]):
            print(f"  [{f['severity']}] {f['recipe'] + ': ' if f['recipe'] else ''}{f['message']}")
    bad = rep["errors"] or any(f["severity"] == "HIGH" for f in rep["findings"])
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

Bạn là một chuyên gia mua đồ cũ (second-hand) dày dạn kinh nghiệm. Hãy bảo vệ tôi khỏi các vụ lừa đảo, các lỗi hỏng hóc ẩn giấu và việc mua hớ với giá quá đắt, nhưng đừng coi những vết hao mòn tự nhiên thông thường là một vấn đề nghiêm trọng.

Món đồ: 2019 road bike, Shimano 105, size 56
Nội dung tin đăng: Barely used, always stored indoors, new tyres. Moving abroad. Price firm, cash only, meet at the train station.
Giá bán: 450 EUR
Vị trí của tôi: Berlin, Germany
Mức độ kinh nghiệm của tôi: beginner

Hãy trả lời bằng các gạch đầu dòng dễ đọc trên điện thoại, tối đa 700 từ:
1. Kết luận (Verdict): Có vẻ ổn (Looks fine) / Cần thận trọng (Caution) / Khả năng cao là lừa đảo (Likely scam), kèm theo lý do chính.
2. Dấu hiệu cảnh báo đỏ (Red flags): trích dẫn nội dung tin đăng, đánh giá từng dấu hiệu ở mức thấp/trung bình/cao, sau đó liệt kê những thông tin còn thiếu. Tuyệt đối không tự bịa ra dữ kiện.
3. Tối đa 6 câu hỏi có thể sao chép-dán ngay để gửi cho người bán, bao gồm câu hỏi về bằng chứng sở hữu và một câu hỏi mà tôi có thể tự mình kiểm chứng khi gặp trực tiếp.
4. Kiểm tra và thử nghiệm thực tế: các bước kiểm tra giúp phát hiện những lỗi hỏng hóc tốn kém nhất đối với món đồ này, được giải thích phù hợp với mức độ kinh nghiệm của tôi, kèm mô tả rõ dấu hiệu của một món đồ bị lỗi trông như thế nào. Nếu khả năng cao là lừa đảo, hãy thay thế bằng cách hướng dẫn xác minh người bán hoặc khuyên rút lui.
5. Giá cả: khoảng giá hợp lý (nêu rõ là mức ước tính), chi phí sửa chữa dùng làm cơ sở thương lượng, mức giá trả khởi điểm và mức giá tối đa cần rút lui (walk-away price - không bao giờ cao hơn giá người bán rao).
6. Các yếu tố cần hủy giao dịch ngay lập tức (Deal-breakers).
7. Hẹn gặp an toàn, phương thức thanh toán, biên nhận và kiểm tra hàng trộm cắp.

Hãy trả lời cụ thể cho món đồ và tin đăng này. Nếu thiếu các chi tiết quan trọng, hãy nêu rõ các giả định và vẫn trả lời đầy đủ. Chỉ nêu tên các trang web hoặc dịch vụ mà bạn chắc chắn là có tồn tại.

---
name: loan-amortization-planner
description: Xây dựng lịch biểu trả nợ (khấu hao) cho khoản vay và thế chấp có lãi suất cố định, hiển thị rõ bao nhiêu phần trong mỗi kỳ thanh toán được tính vào tiền lãi, đồng thời so sánh các chiến lược tất toán sớm như trả thêm hàng tháng, trả một khoản gộp một lần (lump sum), nâng mức thanh toán cố định cao hơn hoặc rút ngắn kỳ hạn vay, kèm theo số tiền lãi tiết kiệm được, số tháng rút ngắn được, ngày tất toán và ước tính lãi suất thực tế hàng năm (APR) khi có áp dụng phí. Sử dụng khi người dùng hỏi "tôi sẽ phải trả bao nhiêu tiền lãi?", "tôi có nên trả dư nợ trước hạn cho khoản thế chấp không?", "điều gì xảy ra nếu tôi trả thêm 200 mỗi tháng?", hoặc muốn có kế hoạch trả nợ cho khoản vay mua ô tô, vay sinh viên, vay tiêu dùng cá nhân hoặc vay mua nhà. Bao gồm một công cụ tính toán bằng thư viện chuẩn Python đã được kiểm thử.
---

# Trình Lập Kế hoạch Khấu hao Khoản vay (Loan Amortization Planner)

Bạn giúp mọi người hiểu rõ một khoản vay thực sự tốn kém bao nhiêu và làm thế nào để trả hết nợ nhanh hơn theo cách phù hợp với ngân sách của họ. Bạn tính toán các con số một cách chuẩn xác, giải thích chúng bằng ngôn ngữ đời thường dễ hiểu, đặt các phương án thực tế cạnh nhau để so sánh, và chỉ ra những sự đánh đổi (quỹ tiết kiệm khẩn cấp, các khoản nợ khác, quy định phạt trả nợ trước hạn) trước khi bất kỳ ai chuyển thêm tiền cho bên cho vay.

## Các tệp trong kỹ năng này

- `scripts/amortize.py` - tính toán lịch trả nợ hàng tháng cho các khoản vay lãi suất cố định với các tùy chọn trả thêm hàng tháng, trả gộp một lần (lump sums), mức thanh toán cố định, các khoản phí và ước tính APR, bảng tổng hợp theo năm và xuất lịch biểu ra tệp CSV (chỉ dùng thư viện chuẩn Python 3)
- `references/amortization-basics.md` - cách thức hoạt động của khấu hao khoản vay, các công thức tính toán và những thuật ngữ mọi người thường nhầm lẫn (lãi suất danh nghĩa so với APR, kỳ hạn vay so với ngày tất toán thực tế)
- `references/prepayment-decision-guide.md` - khi nào việc trả thêm trước hạn là hợp lý, những điểm cần kiểm tra trong hợp đồng vay và thứ tự ưu tiên tài chính
- `templates/loan-plan.md` - mẫu báo cáo để trả về kết quả
- `examples/example-mortgage-overpayment.md` - một bài toán so sánh hoàn chỉnh ba chiến lược trả thêm trước hạn đối với một khoản vay thế chấp mua nhà

## Quy trình làm việc

### 1. Thu thập thông tin thực tế
Hỏi người dùng, hoặc đưa ra giả định và nêu rõ:
- Số tiền hiện còn nợ (hoặc số tiền dự định vay), lãi suất, thời hạn còn lại và mức thanh toán hàng tháng hiện tại nếu đã biết.
- Lãi suất cố định hay thả nổi, và thời điểm kết thúc giai đoạn ưu đãi lãi suất cố định.
- Các khoản phí: phí thu xếp khoản vay hoặc phí khởi tạo (origination fees), cùng bất kỳ khoản phạt trả nợ trước hạn hoặc hạn mức trả thêm tối đa hàng năm nào.
- Khả năng tài chính của người dùng: số tiền có thể trả thêm mỗi tháng, khoản tiền thưởng dự kiến hoặc khoản tiền có sẵn một lần, cùng quỹ tiết kiệm khẩn cấp và các khoản nợ khác của họ.
- Mục tiêu hướng tới: tổng tiền lãi thấp nhất, sạch nợ trước một cột mốc thời gian nhất định, hay mức đóng hàng tháng nhẹ nhàng nhất.

### 2. Chạy kịch bản cơ sở (baseline)
```bash
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --start 2026-12
python3 scripts/amortize.py --principal 18500 --rate 7.9 --months 48 --fee 400   # car loan with a fee: APR estimate
```
Kiểm tra xem số tiền thanh toán tính ra có khớp với bảng sao kê của bên cho vay trong phạm vi sai số vài xu (cents) hay không. Nếu không khớp, khoản vay có thể áp dụng quy tắc đếm ngày khác, đã cộng gộp phí vào dư nợ gốc, hoặc có kèm phí bảo hiểm trong khoản đóng hàng tháng: hãy hỏi lại người dùng, hoặc sử dụng tham số `--payment` với số tiền thực tế.

### 3. Chạy các kịch bản so sánh
```bash
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --extra 200
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --lump 12:10000 --lump 24:10000
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --payment 2000 --yearly
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 20                # shorter term
python3 scripts/amortize.py ... --schedule plan.csv --json
```
So sánh từ 2 đến 4 phương án mà người dùng thực sự có khả năng chi trả. Đối với mỗi phương án, hãy ghi lại tổng chi hàng tháng, ngày tất toán, tổng tiền lãi phải trả, số tiền lãi tiết kiệm được và số tháng rút ngắn được. Nếu bạn không thể chạy script, hãy sử dụng các công thức trong `references/amortization-basics.md` và lưu ý rằng các con số là ước tính xấp xỉ.

### 4. Kiểm tra quyết định tài chính, không chỉ nhìn vào phép toán
Đối chiếu lần lượt theo `references/prepayment-decision-guide.md`: ưu tiên quỹ dự phòng khẩn cấp trước, trả các khoản nợ có lãi suất cao hơn trước, kiểm tra phí phạt và hạn mức trả nợ trước hạn, lưu ý các tác động về thuế cần kiểm tra theo quy định địa phương, và so sánh với tỷ suất sinh lời sau thuế của phương án thay thế (gửi tiết kiệm hoặc đầu tư). Không bao giờ trình bày như thể việc trả nợ trước hạn lúc nào cũng là lựa chọn đúng đắn tuyệt đối.

### 5. Bàn giao kết quả
Điền vào mẫu `templates/loan-plan.md`: tóm tắt khoản vay trong một dòng, kịch bản cơ sở, bảng so sánh các kịch bản, khuyến nghị kèm theo lý do, những câu hỏi cần trao đổi với bên cho vay và các bước tiếp theo. Tuân theo phong cách trình bày của `examples/example-mortgage-overpayment.md`.

## Quy tắc
- Hiển thị mọi con số kèm theo đơn vị tiền tệ và làm tròn số tiền đến hàng xu (cents) hoặc đơn vị lẻ tương ứng; gắn nhãn rõ ràng các con số ước tính là ước tính.
- Công cụ tính toán giả định lãi suất cố định, thanh toán định kỳ hàng tháng và các khoản trả thêm được trừ thẳng vào dư nợ gốc ngay lập tức trong khi vẫn giữ nguyên mức đóng hàng tháng định kỳ (nhờ đó rút ngắn kỳ hạn vay). Hãy nêu rõ giả định này, đồng thời lưu ý trường hợp lãi suất thả nổi hoặc trường hợp bên cho vay chọn cách tính lại mức đóng hàng tháng thấp hơn thay vì rút ngắn kỳ hạn.
- Không đưa ra lời khuyên đầu tư cá nhân hoặc tư vấn thuế; hãy giải thích sự đánh đổi và hướng dẫn người dùng những điểm cần kiểm tra lại với bên cho vay hoặc cố vấn tài chính được cấp phép.
- Nếu một khoản thanh toán hàng tháng thậm chí không đủ để bù đắp phần tiền lãi phát sinh, hãy cảnh báo thật rõ ràng và dừng lại: dư nợ sẽ ngày càng phình to thêm.
- Giữ cho phần giải thích ngắn gọn và cụ thể: "cứ mỗi 100 trả thêm sẽ giúp tiết kiệm khoảng 120 tiền lãi" hiệu quả hơn nhiều so với cả một đoạn văn lý thuyết dài dòng.
FILE:references/amortization-basics.md
# Kiến thức cơ bản về khấu hao khoản vay (Amortization)

## Cách một khoản vay lãi suất cố định được trả dần cho đến hết

Mỗi tháng, bên cho vay tính lãi dựa trên số dư nợ gốc hiện còn lại. Khoản tiền bạn đóng hàng tháng trước tiên sẽ dùng để trả phần lãi đó; phần tiền còn dư lại mới được trừ vào số dư nợ (tiền gốc). Vì số dư nợ giảm dần, nên phần tiền lãi phải trả sẽ thu nhỏ lại qua từng tháng và phần trả nợ gốc sẽ tăng dần lên, trong khi tổng số tiền đóng mỗi tháng vẫn giữ nguyên không đổi. Những kỳ thanh toán đầu tiên chủ yếu là trả lãi; những kỳ thanh toán về cuối chủ yếu là trả gốc.

## Các công thức tính toán

- Lãi suất hàng tháng: r = lãi suất năm / 12 (ví dụ: 4.5% -> 0.00375).
- Số tiền thanh toán mỗi tháng cho khoản vay P trong n tháng: M = P * r / (1 - (1 + r)^-n). Với r = 0: M = P / n.
- Tiền lãi trong tháng này: dư nợ hiện tại * r. Tiền gốc trả được trong tháng này: M - tiền lãi.
- Tổng tiền lãi phải trả: tổng của tất cả các phần tiền lãi hàng tháng, hoặc xấp xỉ bằng M * n - P.
- Số tháng cần thiết để trả hết nợ với mức đóng hàng tháng M: n = -ln(1 - P * r / M) / ln(1 + r). Nếu P * r >= M thì khoản vay sẽ không bao giờ trả hết được.

Kiểm tra nhanh: Vay 200,000 ở mức lãi suất 6% trong 30 năm -> đóng 1,199.10 mỗi tháng. Vay 300,000 ở mức lãi suất 4.5% trong 30 năm -> đóng 1,520.06 mỗi tháng.

## Tại sao việc trả thêm tiền lại giúp tiết kiệm nhiều đến vậy

Một khoản trả thêm sẽ làm giảm ngay lập tức số dư nợ gốc, nhờ đó mọi tháng tiếp theo sau đó đều chỉ tính lãi trên một số dư nhỏ hơn. Số tiền tiết kiệm được xấp xỉ bằng số tiền trả thêm nhân với mức lãi suất mà khoản tiền đó lẽ ra sẽ phải gánh chịu trong suốt quãng thời gian còn lại của khoản vay. Đó là lý do tại sao số tiền trả thêm ở giai đoạn đầu của khoản vay lại giúp tiết kiệm được nhiều tiền lãi hơn hẳn so với cùng số tiền đó nhưng trả vào giai đoạn cuối.

## Các thuật ngữ mọi người thường nhầm lẫn

| Thuật ngữ | Ý nghĩa |
|---|---|
| Lãi suất danh nghĩa (Nominal rate) | Mức lãi suất hàng năm ghi trong hợp đồng, được dùng để chia ra tính lãi hàng tháng. |
| Lãi suất thực tế hàng năm (APR) | Mức lãi suất phần trăm hàng năm đã bao gồm cả các khoản phí; dùng để so sánh các gói vay với nhau. Một khoản vay có lãi suất danh nghĩa thấp hơn nhưng phí cao thì có thể có APR cao hơn. |
| Kỳ hạn vay (Term) | Khoảng thời gian vay theo kế hoạch ban đầu (ví dụ: 30 năm). |
| Ngày tất toán (Payoff date) | Thời điểm số dư nợ thực sự về bằng 0; sẽ đến sớm hơn nếu có các khoản trả thêm. |
| Rút ngắn kỳ hạn so với giảm số tiền đóng hàng tháng (Reduce term vs reduce payment) | Sau khi bạn trả dư thêm một khoản tiền, một số ngân hàng giữ nguyên mức đóng hàng tháng và rút ngắn kỳ hạn vay (giúp tiết kiệm nhiều tiền lãi hơn), trong khi một số khác lại giữ nguyên kỳ hạn và tính lại mức đóng hàng tháng thấp xuống. Hãy hỏi rõ ngân hàng xem họ áp dụng cách nào. |
| Dư nợ gốc (Principal) | Số tiền gốc hiện vẫn còn nợ, không tính phần lãi sẽ phát sinh trong tương lai. |
| Lịch biểu trả nợ / khấu hao (Amortization schedule) | Bảng chi tiết từng tháng thể hiện số tiền đóng, phần trả lãi, phần trả gốc và dư nợ còn lại. |

## Làm tròn số và những chênh lệch nhỏ

Các tổ chức cho vay thường làm tròn số tiền đến hàng xu (cents) vào mỗi tháng và có thể áp dụng cách tính lãi theo ngày thực tế (số ngày thực tế / 365) thay vì lấy lãi suất năm chia đều cho 12. Do đó, kết quả thực tế có thể chênh lệch vài xu mỗi tháng và vài đơn vị tiền tệ trong tổng số tiền lãi. Kỳ thanh toán cuối cùng thường sẽ điều chỉnh bù trừ toàn bộ phần chênh lệch do làm tròn này.

## Giới hạn của công cụ tính toán lãi suất cố định

- Lãi suất thả nổi hoặc lãi suất tham chiếu (tracker rates): hãy chạy các kịch bản ở mức lãi suất hiện tại và ở mức tăng thêm +1 và +2 điểm phần trăm.
- Giai đoạn chỉ trả lãi (interest-only), khoản thanh toán dồn cục cuối kỳ (balloon payments), thời gian ân hạn tạm dừng trả nợ (payment holidays): cần mô hình hóa riêng biệt hoặc tính thủ công.
- Phí bảo hiểm, tiền ký quỹ (escrow) hoặc phí quản lý tài khoản nằm gộp bên trong khoản đóng hàng tháng không phải là tiền lãi; hãy tách chúng ra trước khi thực hiện so sánh.
FILE:references/prepayment-decision-guide.md
# Tôi có nên trả hết khoản vay sớm hơn không? Hướng dẫn ra quyết định

Việc trả thêm tiền trước hạn cho một khoản vay mang lại một mức "sinh lời" đảm bảo, không rủi ro, đúng bằng mức lãi suất của khoản vay đó. Điều này rất tốt, nhưng không phải lúc nào cũng là cách sử dụng tối ưu nhất đối với khoản tiền nhàn rỗi. Hãy lần lượt xem xét qua các bước dưới đây theo đúng thứ tự.

## 1. An toàn là trên hết
- Quỹ dự phòng khẩn cấp: hãy giữ khoảng 3 đến 6 tháng chi phí sinh hoạt thiết yếu trong tài khoản tiết kiệm dễ rút trước khi tính đến chuyện trả thêm nợ trước hạn. Tiền một khi đã chuyển cho ngân hàng để trả nợ thì rất khó rút ngược trở lại khi cần gấp.
- Thu nhập ổn định: nếu sắp có sự thay đổi công việc, nghỉ thai sản hoặc một khoản chi tiêu lớn sắp tới, hãy ưu tiên tích lũy tiền mặt trước.

## 2. Trả khoản nợ đắt đỏ nhất trước
Xếp hạng các khoản nợ theo lãi suất (phương pháp thác đổ - avalanche method): thẻ tín dụng và thấu chi trước, sau đó đến vay tiêu dùng cá nhân và vay mua ô tô, cuối cùng là vay sinh viên và vay thế chấp mua nhà (mortgage). Trả vượt mức cho khoản nợ có lãi suất cao nhất trước tiên. Nếu vấn đề nằm ở việc duy trì động lực, việc tất toán khoản nợ có dư nợ nhỏ nhất trước (phương pháp quả cầu tuyết - snowball) vẫn có thể chấp nhận được, nhưng hãy nêu rõ chi phí chênh lệch phải trả thêm là bao nhiêu.

## 3. Đọc kỹ hợp đồng
- Phí phạt trả nợ trước hạn hoặc phí tất toán sớm (thường tính theo tỷ lệ phần trăm trên số tiền trả vượt mức, chủ yếu áp dụng trong thời gian ưu đãi lãi suất cố định).
- Hạn mức trả vượt miễn phí hàng năm (ví dụ: được trả trước tối đa 10% dư nợ mỗi năm mà không mất phí).
- Khoản tiền trả vượt mức sẽ làm giảm thời hạn vay hay giảm số tiền phải trả hàng tháng? Bạn có được quyền lựa chọn không?
- Số tiền trả vượt tối thiểu cho mỗi lần và cách thức thực hiện (trực tuyến, qua điện thoại, hoặc bằng văn bản yêu cầu).

## 4. So sánh với các phương án thay thế
- Khoản đóng góp quỹ hưu trí đối ứng từ công ty (employer retirement matching) thường có lợi hơn bất kỳ khoản trả nợ trước hạn nào: hãy nhận tối đa khoản đối ứng này trước.
- So sánh lãi suất khoản vay với mức sinh lời sau thuế và sau phí mà bạn có thể nhận được từ tiền gửi tiết kiệm. Khoản vay thế chấp lãi suất 2% so với tài khoản tiết kiệm lãi suất 4%: gửi tiết kiệm thắng về mặt toán học. Khoản vay mua ô tô lãi suất 7% so với tài khoản tiết kiệm lãi suất 3%: trả nợ trước hạn thắng.
- Đầu tư có thể vượt qua mức lãi suất vay thấp trong dài hạn nhưng đi kèm rủi ro; trong khi lợi ích tiết kiệm lãi từ việc trả nợ trước hạn là chắc chắn 100%.
- Thuế: ở một số quốc gia, tiền lãi vay thế chấp mua nhà được khấu trừ thuế thu nhập, làm giảm mức lãi suất thực tế. Hãy kiểm tra quy định tại địa phương; tuyệt đối không tự suy đoán.

## 5. Chọn chiến lược phù hợp
| Chiến lược | Phù hợp khi |
|---|---|
| Trả thêm một khoản cố định mỗi tháng | Thu nhập ổn định; tạo dựng thói quen; tiết kiệm được nhiều tiền lãi nhất trên cùng một tổng số tiền trả thêm nếu bắt đầu sớm. |
| Trả gộp từng khoản lớn (tiền thưởng, tiền hoàn thuế) | Thu nhập không đều theo tháng; giữ được sự linh hoạt về dòng tiền trong suốt năm. |
| Nâng mức thanh toán cố định hàng tháng cao hơn | Muốn ấn định một ngày thoát nợ rõ ràng. |
| Tái cấp vốn (refinance) sang kỳ hạn ngắn hơn | Có mức lãi suất mới thấp hơn và đủ khả năng chi trả khoản thanh toán hàng tháng cao hơn; cần so sánh kỹ các loại phí. |
| Giữ tiền mặt, trả nợ trước hạn sau | Giai đoạn lãi suất cố định sắp kết thúc (sau đó có thể trả trước mà không bị phạt), hoặc quỹ dự phòng khẩn cấp chưa đủ. |

## 6. Rà soát định kỳ
Tính toán lại các con số mỗi năm một lần, khi lãi suất thay đổi hoặc khi thu nhập thay đổi. Nhắc người dùng rằng các khoản trả thêm tự nguyện luôn có thể tạm dừng bất cứ lúc nào; còn mức thanh toán cố định theo hợp đồng mới thường không thể tự ý giảm xuống.
FILE:templates/loan-plan.md
# Kế hoạch khoản vay: loan_name

**Khoản vay:** balance ở mức lãi suất rate% (fixed_or_variable), còn lại remaining_term, thanh toán payment mỗi tháng, kỳ thanh toán đầu tiên trong kế hoạch này vào start_month
**Phí và quy định:** fees; hạn mức hoặc phí phạt trả nợ trước hạn: prepayment_rules
**Mục tiêu:** goal
**Ngân sách dành cho thanh toán thêm:** extra_budget

## Mốc cơ sở (Baseline)

- Khoản thanh toán hàng tháng: 
- Tổng tiền lãi tính từ hiện tại: 
- Ngày tất toán dự kiến: 
- Cơ cấu kỳ thanh toán đầu tiên: tiền lãi ... / tiền gốc ...

## Các kịch bản so sánh

| Phương án | Chi trả hàng tháng | Ngày tất toán | Tổng tiền lãi | Tiền lãi tiết kiệm được | Số tháng rút ngắn |
|---|---|---|---|---|---|
| Mốc cơ sở (Baseline) | | | | - | - |
| A: | | | | | |
| B: | | | | | |
| C: | | | | | |

## Khuyến nghị

Phương án ... bởi vì:
1. 
2. 
3. 

Những sự đánh đổi cần lưu ý: 

## Danh sách kiểm tra trước khi trả nợ trước hạn

- [ ] Quỹ dự phòng khẩn cấp đủ trang trải ... tháng chi phí
- [ ] Không còn khoản nợ nào khác có lãi suất cao hơn (hoặc khoản nợ đó đã được ưu tiên trả trước)
- [ ] Đã kiểm tra phí phạt / hạn mức trả nợ trước hạn với bên cho vay
- [ ] Đã thiết lập khoản trả vượt để rút ngắn thời hạn vay (hoặc giảm số tiền trả hàng tháng, nếu muốn)

## Câu hỏi dành cho bên cho vay

1. 
2. 

## Các bước tiếp theo

1. 
2. 

*Giả định: lãi suất cố định, thanh toán hàng tháng, các khoản trả thêm được trừ trực tiếp vào dư nợ gốc ngay lập tức. Đây là các con số ước tính, không phải lời khuyên tài chính.*
FILE:examples/example-mortgage-overpayment.md
# Ví dụ: so sánh ba chiến lược trả nợ trước hạn khoản vay thế chấp mua nhà

## Yêu cầu của người dùng

"Chúng tôi còn dư nợ thế chấp mua nhà là 320,000 với lãi suất cố định 4.1% và thời hạn còn lại 25 năm, kỳ thanh toán đầu tiên của kế hoạch này là vào tháng 12 năm 2026. Chúng tôi có thể trả thêm khoảng 300 mỗi tháng, hoặc dùng khoản tiền thưởng 15,000 mỗi năm trong ba năm tới. Một người bạn khuyên chúng tôi nên chuyển hẳn sang mức trả 2,400 một tháng. Phương án nào là tốt nhất? Chúng tôi đã có quỹ tiết kiệm đủ cho 6 tháng chi phí sinh hoạt và không có khoản nợ nào khác. Ngân hàng cho phép trả vượt tối đa 10% dư nợ mỗi năm mà không mất phí."

## Câu lệnh chạy

```bash
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --extra 300
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --lump 12:15000 --lump 24:15000 --lump 36:15000
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --payment 2400
```

Kết quả đầu ra (đã rút gọn):

```
Baseline: 1,706.80 per month, interest 192,038.38, total paid 512,038.38, paid off 2051-11 (300 payments)
Plan (+300.00/month): paid off 2046-02 (231 payments), interest 143,068.39
  Saves 48,969.99 interest and 69 months (5 y 9 m); every 100 of extra saves 70.97
Plan (lump sums 15,000.00 in payment 12, 15,000.00 in payment 24, 15,000.00 in payment 36): paid off 2046-11 (240 payments), interest 133,018.73
  Saves 59,019.65 interest and 60 months (5 y 0 m); every 100 of extra saves 131.15
Plan (fixed payment 2,400.00): paid off 2041-10 (179 payments), interest 107,805.37
  Saves 84,233.01 interest and 121 months (10 y 1 m)
```

## Kế hoạch khoản vay (bản mẫu đã điền, rút gọn)

**Khoản vay:** 320,000.00 ở mức lãi suất cố định 4.1%, còn lại 25 năm, thanh toán 1,706.80 mỗi tháng, kỳ thanh toán đầu tiên vào tháng 12 năm 2026
**Phí và quy định:** trả vượt mức tối đa 10% dư nợ mỗi năm được miễn phí
**Mục tiêu:** trả ít tiền lãi hơn mà không làm mất đi sự linh hoạt tài chính

| Phương án | Chi trả hàng tháng | Ngày tất toán | Tổng tiền lãi | Tiền lãi tiết kiệm được | Số tháng rút ngắn |
|---|---|---|---|---|---|
| Mốc cơ sở (Baseline) | 1,706.80 | 2051-11 | 192,038.38 | - | - |
| A: +300 mỗi tháng | 2,006.80 | 2046-02 | 143,068.39 | 48,969.99 | 69 |
| B: Thưởng 15,000 từ năm 1 đến năm 3 | 1,706.80 + tổng cộng 45,000 | 2046-11 | 133,018.73 | 59,019.65 | 60 |
| C: Cố định 2,400 mỗi tháng | 2,400.00 | 2041-10 | 107,805.37 | 84,233.01 | 121 |

**Khuyến nghị:** Chọn Phương án B, kết hợp thêm Phương án A nếu ngân sách cho phép. Các khoản tiền thưởng được đóng vào giai đoạn đầu của khoản vay, nên cứ mỗi 100 trả vượt sẽ tiết kiệm được khoảng 131 tiền lãi, cao gấp gần hai lần hiệu quả của kế hoạch trả thêm hàng tháng (khoảng 71 trên mỗi 100, vì phần lớn số tiền đó được trả rải rác vào những năm về sau). Phương án này không đòi hỏi thay đổi ngân sách chi tiêu hàng tháng, và mỗi khoản 15,000 đều nằm gọn trong hạn mức miễn phí 10% hàng năm (32,000 trong năm thứ nhất). Phương án C tiết kiệm được nhiều lãi nhất vì nó bơm thêm tổng cộng khoảng 124,000 trong suốt 15 năm, nhưng lại làm tăng mức chi cố định hàng tháng thêm 693; chỉ nên áp dụng nếu mức chi này hoàn toàn thoải mái với bạn, và hãy thiết lập nó dưới dạng khoản trả thêm tự nguyện định kỳ thay vì sửa mức thanh toán cứng trong hợp đồng để có thể tạm dừng khi cần.

**Sự đánh đổi:** số tiền đã trả vượt vào khoản vay thế chấp rất khó rút ra lại; hãy giữ nguyên quỹ dự phòng khẩn cấp 6 tháng không đụng tới. Nếu tài khoản tiết kiệm của bạn trả lãi cao hơn 4.1% sau thuế, việc gửi tiết kiệm có thể thắng việc trả nợ trước hạn về mặt tính toán; hãy kiểm tra mức lãi suất thực tế và các quy định thuế tại địa phương.

**Câu hỏi dành cho bên cho vay:**
1. Các khoản trả vượt mức sẽ làm rút ngắn thời hạn vay và giữ nguyên số tiền trả hàng tháng (như giả định ở trên), hay sẽ tính toán lại để giảm số tiền trả hàng tháng?
2. Hạn mức miễn phí 10% được làm mới theo năm dương lịch hay theo năm hợp đồng vay?

*Giả định: lãi suất cố định trong toàn bộ thời hạn, thanh toán hàng tháng, các khoản trả vượt được trừ trực tiếp vào dư nợ gốc ngay lập tức. Đây là số liệu ước tính, không phải lời khuyên tài chính.*
FILE:scripts/amortize.py
#!/usr/bin/env python3
"""Fixed-rate loan amortization with extra payments and scenario comparison.

Usage:
  python3 amortize.py --principal 250000 --rate 4.2 --years 30 [options]
  python3 amortize.py --principal 18000 --rate 7.9 --months 60 --extra 150

Options:
  --principal N      amount borrowed (required)
  --rate PCT         nominal annual interest rate in percent, e.g. 4.2 (required; 0 allowed)
  --years N | --months N   term (one of them is required)
  --start YYYY-MM    month of the first payment (default: next month)
  --extra N          extra amount added to every monthly payment
  --extra-from N     payment number where --extra starts (default 1)
  --lump N:AMOUNT    one-off extra payment in payment number N (repeatable)
  --payment N        pay this fixed monthly amount instead of the computed one
  --fee N            one-off upfront fees, used for the cost and APR estimate
  --schedule FILE    write the full monthly schedule as CSV
  --yearly           print a year-by-year table
  --json             print the result as JSON

Extra payments are assumed to reduce principal immediately with no prepayment
penalty and the same monthly payment (term shortens). Rates are nominal annual,
compounded monthly (rate / 12 per month). Money is rounded to cents each month.
Exit codes: 0 ok, 2 usage or input error. Python 3 standard library only.
"""
import argparse
import csv
import datetime as dt
import json
import sys


def monthly_payment(principal, annual_rate, n):
    r = annual_rate / 100 / 12
    if r == 0:
        return principal / n
    return principal * r / (1 - (1 + r) ** -n)


def add_months(ym, k):
    y, m = ym
    m0 = m - 1 + k
    return (y + m0 // 12, m0 % 12 + 1)


def schedule(principal, annual_rate, n, payment=None, extra=0.0, extra_from=1, lumps=None):
    r = annual_rate / 100 / 12
    base = round(payment if payment else monthly_payment(principal, annual_rate, n), 2)
    lumps = lumps or {}
    bal = round(principal, 2)
    rows = []
    k = 0
    while bal > 0.005:
        k += 1
        if k > 1200:
            raise ValueError("the loan is not paid off within 100 years; the payment is too small for the interest")
        interest = round(bal * r, 2)
        if base + (extra if k >= extra_from else 0) <= interest and not lumps.get(k):
            raise ValueError(f"payment {base:.2f} does not cover the monthly interest {interest:.2f}; the balance would grow")
        sched = min(base, bal + interest)
        if payment is None and k == n:
            sched = bal + interest  # last scheduled payment absorbs the rounding difference
        ext = min(extra if k >= extra_from else 0.0, max(bal + interest - sched, 0))
        lump = min(lumps.get(k, 0.0), max(bal + interest - sched - ext, 0))
        principal_paid = round(sched + ext + lump - interest, 2)
        bal = round(bal - principal_paid, 2)
        rows.append({"n": k, "payment": round(sched, 2), "extra": round(ext + lump, 2), "interest": interest,
                     "principal": principal_paid, "balance": max(bal, 0.0)})
    return base, rows


def summarize(rows):
    return {"months": len(rows), "total_interest": round(sum(x["interest"] for x in rows), 2),
            "total_paid": round(sum(x["payment"] + x["extra"] for x in rows), 2),
            "total_extra": round(sum(x["extra"] for x in rows), 2)}


def apr_estimate(principal, fee, payment, n):
    """Annual rate that makes the payments worth principal - fee (bisection)."""
    target = principal - fee
    lo, hi = 0.0, 1.0
    for _ in range(100):
        mid = (lo + hi) / 2
        r = mid / 12
        pv = payment * n if r == 0 else payment * (1 - (1 + r) ** -n) / r
        lo, hi = (mid, hi) if pv > target else (lo, mid)
    return round(lo * 100, 3)


def fmt_ym(ym):
    return f"{ym[0]:04d}-{ym[1]:02d}"


def main(argv):
    p = argparse.ArgumentParser(add_help=True, description="Loan amortization with extra payments")
    p.add_argument("--principal", type=float, required=True)
    p.add_argument("--rate", type=float, required=True)
    g = p.add_mutually_exclusive_group(required=True)
    g.add_argument("--years", type=float)
    g.add_argument("--months", type=int)
    p.add_argument("--start")
    p.add_argument("--extra", type=float, default=0.0)
    p.add_argument("--extra-from", type=int, default=1)
    p.add_argument("--lump", action="append", default=[])
    p.add_argument("--payment", type=float)
    p.add_argument("--fee", type=float, default=0.0)
    p.add_argument("--schedule")
    p.add_argument("--yearly", action="store_true")
    p.add_argument("--json", action="store_true")
    try:
        a = p.parse_args(argv)
    except SystemExit as e:
        return 0 if e.code == 0 else 2
    try:
        n = a.months if a.months else round(a.years * 12)
        if a.principal <= 0 or n <= 0 or a.rate < 0 or a.extra < 0 or a.fee < 0:
            raise ValueError("principal and term must be positive; rate, extra, and fee cannot be negative")
        if a.rate > 100:
            raise ValueError("rate is in percent per year, e.g. 4.2 for 4.2%")
        lumps = {}
        for item in a.lump:
            num, _, amt = item.partition(":")
            try:
                if not num.isdigit():
                    raise ValueError
                value = float(amt)
            except ValueError:
                raise ValueError(f"--lump must look like 24:5000 (payment number:amount), got {item!r}") from None
            lumps[int(num)] = lumps.get(int(num), 0.0) + value
        if a.start:
            try:
                y, m = a.start.split("-")
                start = (int(y), int(m))
            except ValueError:
                raise ValueError(f"--start must look like 2026-11, got {a.start!r}") from None
            if not 1 <= start[1] <= 12:
                raise ValueError("--start month must be 01 to 12")
        else:
            t = dt.date.today()
            start = add_months((t.year, t.month), 1)
        base_pay, base_rows = schedule(a.principal, a.rate, n, payment=None)
        scenario = bool(a.extra or lumps or a.payment)
        pay, rows = schedule(a.principal, a.rate, n, payment=a.payment, extra=a.extra,
                             extra_from=a.extra_from, lumps=lumps) if scenario else (base_pay, base_rows)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    base_sum, plan_sum = summarize(base_rows), summarize(rows)
    result = {
        "inputs": {"principal": a.principal, "annual_rate_pct": a.rate, "term_months": n, "first_payment": fmt_ym(start),
                   "extra_monthly": a.extra, "extra_from_payment": a.extra_from, "lumps": lumps, "fixed_payment": a.payment, "fees": a.fee},
        "baseline": {"monthly_payment": base_pay, **base_sum, "payoff": fmt_ym(add_months(start, base_sum["months"] - 1))},
    }
    if a.fee:
        result["baseline"]["apr_estimate_pct"] = apr_estimate(a.principal, a.fee, base_pay, n)
        result["baseline"]["total_cost_incl_fees"] = round(base_sum["total_interest"] + a.fee, 2)
    if scenario:
        result["plan"] = {"monthly_payment": pay, **plan_sum, "payoff": fmt_ym(add_months(start, plan_sum["months"] - 1)),
                          "months_saved": base_sum["months"] - plan_sum["months"],
                          "interest_saved": round(base_sum["total_interest"] - plan_sum["total_interest"], 2)}
        if plan_sum["total_extra"]:
            result["plan"]["interest_saved_per_100_extra"] = round(100 * result["plan"]["interest_saved"] / plan_sum["total_extra"], 2)
    yearly = []
    for i in range(0, len(rows), 12):
        chunk = rows[i:i + 12]
        yearly.append({"year": i // 12 + 1, "paid": round(sum(x["payment"] + x["extra"] for x in chunk), 2),
                       "interest": round(sum(x["interest"] for x in chunk), 2),
                       "principal": round(sum(x["principal"] for x in chunk), 2), "end_balance": chunk[-1]["balance"]})
    result["yearly"] = yearly
    first = base_rows[0]
    result["baseline"]["first_payment_split"] = {"interest": first["interest"], "principal": first["principal"]}

    if a.schedule:
        try:
            with open(a.schedule, "w", newline="", encoding="utf-8") as f:
                w = csv.writer(f)
                w.writerow(["n", "month", "payment", "extra", "interest", "principal", "balance"])
                for x in rows:
                    w.writerow([x["n"], fmt_ym(add_months(start, x["n"] - 1)), f"{x['payment']:.2f}", f"{x['extra']:.2f}",
                                f"{x['interest']:.2f}", f"{x['principal']:.2f}", f"{x['balance']:.2f}"])
        except OSError as e:
            print(f"error: cannot write schedule {a.schedule}: {e.strerror}", file=sys.stderr)
            return 2
    if a.json:
        print(json.dumps(result, indent=2))
        return 0
    b = result["baseline"]
    print(f"Loan {a.principal:,.2f} at {a.rate}% for {n} months, first payment {fmt_ym(start)}")
    print(f"Baseline: {b['monthly_payment']:,.2f} per month, interest {b['total_interest']:,.2f}, "
          f"total paid {b['total_paid']:,.2f}, paid off {b['payoff']} ({b['months']} payments)")
    if a.fee:
        print(f"  With fees {a.fee:,.2f}: total cost of borrowing {b['total_cost_incl_fees']:,.2f}, APR about {b['apr_estimate_pct']}%")
    print(f"  First payment: {first['interest']:,.2f} interest, {first['principal']:,.2f} principal")
    if scenario:
        pl = result["plan"]
        what = []
        if a.payment:
            what.append(f"fixed payment {a.payment:,.2f}")
        if a.extra:
            what.append(f"+{a.extra:,.2f}/month" + (f" from payment {a.extra_from}" if a.extra_from > 1 else ""))
        if lumps:
            what.append("lump sums " + ", ".join(f"{v:,.2f} in payment {k}" for k, v in sorted(lumps.items())))
        print(f"Plan ({'; '.join(what)}): paid off {pl['payoff']} ({pl['months']} payments), "
              f"interest {pl['total_interest']:,.2f}")
        ms = pl["months_saved"]
        if ms >= 0 and pl["interest_saved"] >= 0:
            print(f"  Saves {pl['interest_saved']:,.2f} interest and {ms} months ({ms // 12} y {ms % 12} m)"
                  + (f"; every 100 of extra saves {pl['interest_saved_per_100_extra']:,.2f}" if pl.get("interest_saved_per_100_extra") else ""))
        else:
            print(f"  WARNING: this plan costs {-pl['interest_saved']:,.2f} MORE interest and takes {-ms} months longer than the baseline")
    if a.yearly:
        print(f"\nYear-by-year ({'plan' if scenario else 'baseline'}):")
        print(f"{'Year':>4} {'Paid':>12} {'Interest':>12} {'Principal':>12} {'Balance':>12}")
        for y in yearly:
            print(f"{y['year']:>4} {y['paid']:>12,.2f} {y['interest']:>12,.2f} {y['principal']:>12,.2f} {y['end_balance']:>12,.2f}")
    if a.schedule:
        print(f"\nSchedule written to {a.schedule} ({len(rows)} rows)")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: subscription-spending-auditor
description: Kiểm toán các gói đăng ký định kỳ (phát trực tuyến, ứng dụng, phòng tập gym, lưu trữ đám mây, tin tức) từ một tệp CSV đơn giản: chi phí thực tế hàng tháng và hàng năm theo một loại tiền tệ duy nhất, phần chi phí của bạn trong các gói gia đình, các khoản gia hạn và chuyển đổi dùng thử trong 30 ngày tới, các dịch vụ không sử dụng, các dịch vụ trùng lặp trong cùng một danh mục, các đợt tăng giá và các gói theo năm giúp tiết kiệm tiền. Kết thúc bằng danh sách hành động hủy/giữ/hạ cấp. Bao gồm một trình kiểm toán Python dùng thư viện chuẩn với tùy chọn --self-test.
---

# Trình Kiểm Toán Chi Tiêu Đăng Ký Định Kỳ

Bạn giúp mọi người nhìn rõ chi phí thực sự của các gói đăng ký định kỳ và quyết định nên giữ lại dịch vụ nào. Bạn chuyển các dòng sao kê ngân hàng, biên lai kho ứng dụng hoặc một danh sách sơ bộ thành một bảng duy nhất, quy đổi mọi khoản phí sang cùng một loại tiền tệ cũng như số tiền hàng tháng và hàng năm, đồng thời chỉ ra những điểm dễ dàng tối ưu: các dịch vụ không ai dùng đến, ba dịch vụ xem video trong khi chỉ cần một là đủ, các gói dùng thử sắp chuyển thành gói trả phí, những đợt tăng giá âm thầm, và các gói trả theo năm rẻ hơn nếu đằng nào cũng giữ lại dịch vụ đó. Người dùng là người ra quyết định; bạn giúp làm rõ các sự đánh đổi.

## Các tệp trong kỹ năng này

- `scripts/sub_audit.py` - đọc tệp CSV danh sách gói đăng ký và in ra tổng chi phí, phần chi phí của bạn trong các gói dùng chung, tổng chi phí theo danh mục, các khoản phí sắp tới và các cờ cảnh báo (TRIAL, RENEWS_YEARLY, UNUSED, OVERLAP, PRICE_UP, ANNUAL_SAVES) (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/cost-normalization.md` - cách quy đổi các chu kỳ, tiền tệ, gói dùng chung, gói dùng thử và thay đổi giá, kèm theo công thức tính
- `references/cancellation-playbook.md` - cách hủy, tạm dừng, hạ cấp hoặc thương lượng giá, và cách tránh bị gia hạn bất ngờ
- `templates/subscription-review.md` - bản đánh giá gói gọn trong một trang bao gồm các quyết định và lời nhắc
- `examples/subscriptions.csv` - 12 gói đăng ký mẫu bằng đồng EUR và USD với các chu kỳ hàng tuần, hàng tháng, hàng quý và hàng năm, một gói gia đình dùng chung, một gói dùng thử, các dịch vụ không sử dụng và các đợt tăng giá

## Quy trình làm việc

### 1. Lập danh sách
Yêu cầu người dùng rà soát sao kê ngân hàng và thẻ trong 12 tháng qua, các gói đăng ký trên App Store và Google Play, các khoản thanh toán tự động qua PayPal và biên lai trong email (tìm kiếm các từ khóa "renewal", "subscription", "receipt", "trial"). Đưa từng mục vào định dạng CSV giống như `examples/subscriptions.csv`. Các cột bắt buộc: name, amount, cycle. Các cột hữu ích: currency, next_renewal, category, last_used (ước tính trung thực là được), users (số người dùng chung gói), trial_end và paid_after_trial, previous_amount, annual_price.

### 2. Chạy trình kiểm toán
```
python3 scripts/sub_audit.py examples/subscriptions.csv --currency EUR --rate USD=0.92 --today 2026-10-20
python3 scripts/sub_audit.py subs.csv --currency USD --rate EUR=1.08 --rate GBP=1.27 --days 45 --unused-days 60
python3 scripts/sub_audit.py subs.csv --json > audit.json
python3 scripts/sub_audit.py --self-test
```
Tỷ giá được tính theo quy tắc "1 đơn vị tiền tệ đó = X đơn vị tiền tệ báo cáo"; hãy sử dụng tỷ giá trên sao kê thẻ của người dùng. Mã thoát (exit code) bằng 2 có nghĩa là dữ liệu đầu vào không hợp lệ (chu kỳ không xác định, thiếu tỷ giá, ngày tháng sai định dạng, số tiền âm).

### 3. Duyệt qua danh sách hành động
Thứ tự ưu tiên chú ý: TRIAL (hạn chót gần nhất), RENEWS_YEARLY (sắp phát sinh một khoản phí lớn), UNUSED, OVERLAP, PRICE_UP, ANNUAL_SAVES. Đối với mỗi mục, hãy đặt một câu hỏi: "Hôm nay bạn có sẵn sàng đăng ký mới dịch vụ này với mức giá này không?" Đề xuất hủy, tạm dừng, hạ cấp, chia sẻ gói, hoặc chuyển sang gói năm (chỉ áp dụng cho các dịch vụ mà họ chắc chắn sẽ duy trì trong 12 tháng).

### 4. Hành động an toàn
Sử dụng `references/cancellation-playbook.md`. Hủy thông qua trang tài khoản chính thức hoặc kho ứng dụng, chụp màn hình xác nhận và đặt lời nhắc lịch trước 3 ngày khi kết thúc dùng thử cũng như khi gia hạn hàng năm.

### 5. Tóm tắt
Điền vào `templates/subscription-review.md`: tổng chi phí hàng tháng và hàng năm trước và sau khi điều chỉnh, các quyết định đã đưa ra và ngày nhắc nhở.

## Kết quả ví dụ
Đối với `examples/subscriptions.csv` với tỷ giá USD=0.92 vào ngày 2026-10-20: 136.65 EUR/tháng (1,639.80 EUR/năm), phần chi phí của người dùng là 112.66 EUR/tháng, 699.49 EUR/năm nằm ở bốn dịch vụ không sử dụng, một gói dùng thử DesignPro sẽ chuyển đổi vào ngày 2026-10-25 thành 22.99 EUR/tháng, một khoản gia hạn CloudVault trị giá 99.99 EUR vào ngày 2026-11-05, ba dịch vụ video trùng lặp, ba đợt tăng giá trị giá 108 EUR/năm, và 237.87 EUR các khoản phí sẽ phát sinh trong 30 ngày tới.

## Quy tắc

- Không bao giờ hỏi số thẻ, thông tin đăng nhập ngân hàng hoặc mật khẩu; chỉ cần số tiền và ngày tháng là đủ.
- Không tự ý hủy bất kỳ dịch vụ nào hoặc liên hệ với nhà cung cấp thay cho người dùng trừ khi họ yêu cầu; thay vào đó hãy soạn sẵn nội dung tin nhắn cho họ.
- Giữ thái độ khách quan, không phán xét: một số gói đăng ký hoàn toàn xứng đáng với chi phí bỏ ra. Hãy trình bày chi phí và để người dùng tự lựa chọn.
- Các gói dùng thử được tính là 0 trong tổng chi phí hiện tại; luôn hiển thị mức phí sẽ phát sinh sau khi chuyển đổi sang gói trả phí.
FILE:references/cost-normalization.md
# Chuẩn Hóa Chi Phí

## Số lần thu phí mỗi tháng theo chu kỳ
| Chu kỳ | Số lần thu phí mỗi tháng | Chi phí hàng năm cho mức phí 10.00 |
|---|---|---|
| weekly | 4.348125 (365.25 / 12 / 7) | 521.78 |
| biweekly | 2.1740625 | 260.89 |
| monthly | 1 | 120.00 |
| quarterly | 1/3 | 40.00 |
| semiannual | 1/6 | 20.00 |
| yearly | 1/12 | 10.00 |
| every N days | 30.436875 / N | |

chi phí hàng tháng = mức phí x tỷ giá x số lần thu phí mỗi tháng; chi phí hàng năm = chi phí hàng tháng x 12. Việc làm tròn đến hàng xu chỉ thực hiện ở bước cuối cùng để tổng số không bị lệch.

## Tiền tệ
- Sử dụng một loại tiền tệ báo cáo duy nhất và một tỷ giá cho mỗi ngoại tệ, ví dụ: `--rate USD=0.92` (1 USD = 0.92 EUR).
- Nguồn tốt nhất: lấy số tiền đã quy đổi trên sao kê thẻ chia cho số tiền gốc. Con số này đã bao gồm biên độ tỷ giá ngoại hối (FX margin) của thẻ.
- Đề cập riêng các khoản phí giao dịch ngoại tệ nếu thẻ có thu thêm (thường từ 1-3%).

## Gói dùng chung
- `users` = số người cùng chia sẻ gói. Phần của bạn = chi phí / users.
- Hiển thị cả toàn bộ chi phí (số tiền thẻ phải thanh toán) và phần của bạn (số tiền thực tế bạn chịu sau khi những người khác hoàn trả lại). Nếu những người khác thực tế không trả tiền, hãy dùng users = 1.

## Gói dùng thử
- Một gói dùng thử có amount bằng 0, kèm theo `trial_end` và `paid_after_trial`. Các khoản phí phát sinh vào hoặc sau ngày `trial_end` sẽ sử dụng số tiền trả phí trong danh sách các khoản phí sắp tới.
- Tổng chi phí hiển thị chi phí ngày hôm nay (bằng 0) để người dùng thấy điều gì sẽ thay đổi nếu họ không làm gì cả: cờ TRIAL sẽ cho biết mức giá hàng tháng và hàng năm sau khi chuyển đổi.

## Thay đổi giá
- `previous_amount` = mức giá trước đợt tăng giá gần nhất. Tác động hàng năm = (mức mới - mức cũ) x tỷ giá x số lần thu phí mỗi tháng x 12.
- Các nhà cung cấp thường thông báo tăng giá qua email trước 30 ngày; hãy tìm kiếm cụm từ "price change" và "new price".

## Gói năm so với gói tháng
- Gói trả theo năm chỉ giúp tiết kiệm tiền nếu đằng nào dịch vụ đó cũng được duy trì trong suốt 12 tháng. Khoản tiết kiệm = chi phí hàng tháng x 12 - giá gói năm.
- Các gói trả theo năm thường không được hoàn tiền sau một khoảng thời gian ngắn ban đầu; chỉ nên chuyển sang gói năm đối với các dịch vụ được sử dụng hàng tuần.

## Ngày gia hạn
- Nếu `next_renewal` nằm trong quá khứ, ngày này sẽ được cộng dồn theo chu kỳ cho đến khi trùng với ngày hôm nay hoặc một ngày trong tương lai.
- Các ngày cuối tháng sẽ được giới hạn theo số ngày thực tế của tháng: một gói gia hạn vào ngày 31 sẽ gia hạn vào ngày 28 (hoặc 29) tháng 2, sau đó vào ngày 28 hoặc 31 tùy thuộc vào nhà cung cấp; hãy kiểm tra biên lai.
FILE:references/cancellation-playbook.md
# Cẩm Nang Hủy và Hạ Cấp Dịch Vụ

## Nơi thực hiện hủy
| Thanh toán qua | Nơi thực hiện hủy |
|---|---|
| Apple App Store | Settings > tên của bạn > Subscriptions |
| Google Play | Play Store > hồ sơ > Payments & subscriptions > Subscriptions |
| PayPal | Settings > Payments > Manage automatic payments (dừng thanh toán, đồng thời hãy hủy cả bên phía nhà cung cấp) |
| Trực tiếp với dịch vụ | Trang tài khoản hoặc thanh toán trên website; một số dịch vụ yêu cầu nhắn tin hỗ trợ hoặc gọi điện thoại |
| Nhà mạng di động hoặc gói truyền hình | Tài khoản nhà mạng hoặc tổng đài hỗ trợ |

Việc xóa ứng dụng không làm hủy gói đăng ký của ứng dụng đó.

## Các bước thực hiện
1. Kiểm tra ngày gia hạn và xem việc hủy sẽ chấm dứt quyền truy cập ngay lập tức hay vào cuối kỳ thanh toán (thường là cuối kỳ).
2. Xuất mọi dữ liệu bạn muốn giữ lại (ảnh, danh sách phát, ghi chú, lịch sử tập luyện).
3. Hủy qua kênh chính thức nêu trên, không hủy qua các đường dẫn trong những email lạ.
4. Lưu lại bằng chứng: email xác nhận hoặc ảnh chụp màn hình có kèm ngày tháng.
5. Theo dõi kỳ sao kê tiếp theo; nếu vẫn bị trừ tiền sau khi đã hủy, hãy khiếu nại với nhà cung cấp trước, sau đó mới làm việc với bên phát hành thẻ.

## Các lựa chọn thay thế cho việc hủy
- **Tạm dừng (Pause)** (phòng gym, gói nguyên liệu nấu ăn, một số dịch vụ phát trực tuyến) vào những tháng đi du lịch hoặc bận rộn.
- **Hạ cấp (Downgrade)** xuống gói có quảng cáo, gói một màn hình hoặc gói dung lượng lưu trữ nhỏ hơn.
- **Luân phiên (Rotate)** các dịch vụ phát trực tuyến: chỉ giữ một dịch vụ tại một thời điểm và đổi sang dịch vụ khác theo từng tháng để xem các chương trình bạn muốn.
- **Chia sẻ (Share)** gói gia đình với các thành viên trong hộ gia đình, trong phạm vi điều khoản của nhà cung cấp.
- **Yêu cầu (Ask)** ưu đãi giữ chân khách hàng: nhiều dịch vụ sẽ đưa ra mức giảm giá khi bạn bắt đầu thao tác hủy. Hãy xác định trước mức giá tối đa bạn chấp nhận trả trước khi thương lượng.

## Gói dùng thử
- Đặt lời nhắc trước ngày `trial_end` từ 2-3 ngày; nhiều gói dùng thử cho phép hủy ngay sau khi đăng ký mà vẫn giữ nguyên thời gian dùng thử còn lại.
- Sử dụng thẻ ảo có giới hạn hạn mức hoặc thẻ chỉ thanh toán cho một đơn vị chấp nhận thẻ đối với các gói dùng thử nếu ngân hàng có hỗ trợ.

## Mẫu tin nhắn (chat hỗ trợ hoặc email)
> Xin chào, vui lòng hủy gói đăng ký <service> của tôi trên tài khoản <email> có hiệu lực vào cuối kỳ thanh toán hiện tại, và xác nhận qua email rằng sẽ không có khoản phí nào phát sinh thêm. Xin cảm ơn.

## Những thói quen giúp kiểm soát chi phí
- Rà soát lại các gói đăng ký mỗi quý bằng kỹ năng này.
- Duy trì một lịch duy nhất ghi lại tất cả các ngày gia hạn hàng năm.
- Trước khi đăng ký mới, hãy tự hỏi: mình có dùng dịch vụ này ít nhất mỗi tuần một lần không?
FILE:templates/subscription-review.md
# Đánh Giá Gói Đăng Ký - <name> - <date>

**Tiền tệ báo cáo:** <EUR>  **Tỷ giá:** <1 USD = 0.92 EUR (sao kê thẻ)>
**Trước khi điều chỉnh:** <monthly> /tháng = <yearly> /năm (phần của bạn <monthly> /tháng)
**Sau khi quyết định:** <monthly> /tháng = <yearly> /năm  **Tiết kiệm mỗi năm:** <amount>

## Các quyết định
| Gói đăng ký | Chi phí mỗi năm | Cờ cảnh báo | Quyết định | Hoàn thành |
|---|---|---|---|---|
| | | | giữ / hủy / tạm dừng / hạ cấp / chuyển sang gói năm | [ ] |

## Hạn chót và lời nhắc
| Ngày | Nội dung | Đã đặt lời nhắc |
|---|---|---|
| | hết hạn dùng thử | [ ] |
| | gia hạn hàng năm | [ ] |

## Các khoản phí trong 30 ngày tới
- <date> <name> <amount>

## Ghi chú
- Gói dùng chung: <ai hoàn trả lại khoản nào>
- Các đợt tăng giá ghi nhận được: <dịch vụ giá cũ -> giá mới>
- Lần đánh giá tiếp theo: <ngày, khoảng 3 tháng kể từ bây giờ>
FILE:examples/subscriptions.csv
name,amount,currency,cycle,next_renewal,category,last_used,users,trial_end,previous_amount,annual_price,paid_after_trial
StreamFlix Premium,17.99,EUR,monthly,2026-10-27,Video streaming,2026-10-18,2,,15.99,,
CineBox,8.99,EUR,monthly,2026-11-03,Video streaming,2026-08-02,1,,,89.90,
AnimeNow,6.49,USD,monthly,2026-10-22,Video streaming,2026-07-15,1,,,,
TuneWave Family,19.99,EUR,monthly,2026-11-10,Music,2026-10-19,4,,16.99,,
CloudVault 2 TB,99.99,EUR,yearly,2026-11-05,Cloud storage,2026-10-19,1,,,,
PhotoCloud 200 GB,2.99,EUR,monthly,2026-11-01,Cloud storage,2026-10-10,1,,,29.99,
FitPulse Gym,39.00,EUR,monthly,2026-11-01,Fitness,2026-09-04,1,,35.00,,
Yoga Daily App,59.99,USD,yearly,2027-03-14,Fitness,2026-10-12,1,,,,
NewsLine Digital,4.99,EUR,weekly,2026-10-23,News,2026-10-19,1,,,,
PasswordSafe,36.00,USD,yearly,2027-01-20,Software,2026-10-19,1,,,,
DesignPro Trial,0.00,USD,monthly,2026-10-25,Design,2026-10-02,1,2026-10-25,,,24.99
LangLeap Plus,12.99,EUR,quarterly,2026-12-01,Learning,2026-06-30,1,,,,
FILE:scripts/sub_audit.py
#!/usr/bin/env python3
"""Subscription spending auditor (Python 3 standard library only).

Input CSV columns (header names are case-insensitive; only name, amount, cycle are required):
  name, amount, currency, cycle, next_renewal, category, last_used, users, trial_end,
  previous_amount, annual_price, paid_after_trial
cycle: weekly, biweekly, monthly, quarterly, semiannual, yearly/annual, or "every N days|weeks|months|years"
       (also short forms like 2w, 3m, 1y).
users: how many people share the plan; your share = amount / users (default 1).
trial_end + paid_after_trial: a free trial (amount 0) that converts to paid_after_trial on trial_end.

Reports, all converted to one currency with explicit rates (--rate USD=0.92):
  monthly and yearly cost per item and in total, by category, your share of shared plans,
  renewals in the next --days days (past dates are rolled forward by the cycle),
  flags: UNUSED (last_used older than --unused-days), OVERLAP (several items in one category),
  TRIAL (trial ends within --days; amount after trial if given), PRICE_UP (amount > previous_amount),
  ANNUAL_SAVES (annual_price cheaper than 12 x monthly), RENEWS_YEARLY (a yearly charge within --days).
Usage:
  python3 sub_audit.py subscriptions.csv --currency EUR --rate USD=0.92 --today 2026-10-20
  python3 sub_audit.py subscriptions.csv --json
  python3 sub_audit.py --self-test
Exit code: 0 OK, 2 bad input.
"""
import argparse
import calendar
import csv
import datetime as dt
import json
import re
import sys
from decimal import Decimal, ROUND_HALF_UP

NAMED = {"weekly": (1, "w"), "biweekly": (2, "w"), "fortnightly": (2, "w"), "monthly": (1, "m"),
         "bimonthly": (2, "m"), "quarterly": (3, "m"), "semiannual": (6, "m"), "semiannually": (6, "m"),
         "half-yearly": (6, "m"), "yearly": (12, "m"), "annual": (12, "m"), "annually": (12, "m")}
UNIT = {"d": "d", "day": "d", "days": "d", "w": "w", "week": "w", "weeks": "w", "m": "m", "month": "m",
        "months": "m", "y": "y", "year": "y", "years": "y"}
PER_MONTH = {"d": Decimal("30.436875"), "w": Decimal("4.348125"), "m": Decimal(1), "y": Decimal(1) / 12}
D2 = Decimal("0.01")


class AuditError(ValueError):
    pass


def parse_cycle(s):
    s = (s or "").strip().lower()
    if s in NAMED:
        n, u = NAMED[s]
        return n, u
    m = re.fullmatch(r"(?:every\s+)?(\d+)\s*([a-z]+)", s)
    if m and m.group(2) in UNIT:
        n, u = int(m.group(1)), UNIT[m.group(2)]
        if n <= 0:
            raise AuditError(f"cycle must be positive: {s!r}")
        if u == "y":
            return n * 12, "m"
        return n, u
    raise AuditError(f"unknown cycle {s!r} (use weekly, monthly, quarterly, yearly or 'every 2 months')")


def monthly_factor(n, u):
    """How many charges per month for a cycle of n units."""
    return PER_MONTH[u] / n


def add_cycle(d, n, u):
    if u == "d":
        return d + dt.timedelta(days=n)
    if u == "w":
        return d + dt.timedelta(weeks=n)
    m = d.month - 1 + n
    y, m = d.year + m // 12, m % 12 + 1
    return dt.date(y, m, min(d.day, calendar.monthrange(y, m)[1]))


def parse_date(s, field, name):
    s = (s or "").strip()
    if not s:
        return None
    try:
        return dt.date.fromisoformat(s)
    except ValueError:
        raise AuditError(f"{name}: bad {field} date {s!r} (use YYYY-MM-DD)")


def money(s, field, name, required=False):
    s = (s or "").strip().replace(",", "") if (s or "").count(",") and "." in (s or "") else (s or "").strip().replace(",", ".")
    if not s:
        if required:
            raise AuditError(f"{name}: {field} is required")
        return None
    try:
        v = Decimal(s)
    except Exception:
        raise AuditError(f"{name}: bad {field} {s!r}")
    if v < 0:
        raise AuditError(f"{name}: {field} cannot be negative")
    return v


def q(v):
    return v.quantize(D2, rounding=ROUND_HALF_UP)


def load(lines):
    rd = csv.DictReader(lines)
    if not rd.fieldnames:
        raise AuditError("empty CSV")
    rows = []
    for r in rd:
        r = {(k or "").strip().lower(): (v or "").strip() for k, v in r.items()}
        if not any(r.values()):
            continue
        if not r.get("name"):
            raise AuditError("every row needs a name")
        rows.append(r)
    if not rows:
        raise AuditError("no subscriptions found")
    return rows


def audit(rows, currency="EUR", rates=None, today=None, days=30, unused_days=45):
    rates = {k.upper(): Decimal(str(v)) for k, v in (rates or {}).items()}
    rates[currency.upper()] = Decimal(1)
    today = today or dt.date.today()
    horizon = today + dt.timedelta(days=days)
    items, flags, renewals, raw = [], [], [], {}
    for r in rows:
        name = r["name"]
        cur = (r.get("currency") or currency).upper()
        if cur not in rates:
            raise AuditError(f"{name}: no rate for {cur}; pass --rate {cur}=<value in {currency}>")
        rate = rates[cur]
        n, u = parse_cycle(r.get("cycle"))
        amount = money(r.get("amount"), "amount", name, required=True)
        after_trial = money(r.get("paid_after_trial"), "paid_after_trial", name)
        trial_end = parse_date(r.get("trial_end"), "trial_end", name)
        users = int(r.get("users") or 1)
        if users < 1:
            raise AuditError(f"{name}: users must be at least 1")
        charge = amount * rate
        f = monthly_factor(n, u)
        monthly = charge * f
        item = {"name": name, "category": r.get("category") or "Other", "currency": cur, "amount": float(amount),
                "cycle": r.get("cycle"), "monthly": q(monthly), "yearly": q(monthly * 12), "users": users,
                "your_monthly": q(monthly / users), "your_yearly": q(monthly * 12 / users)}
        raw[name] = (monthly, monthly / users)
        items.append(item)
        nxt = parse_date(r.get("next_renewal"), "next_renewal", name)
        if nxt:
            while nxt < today:
                nxt = add_cycle(nxt, n, u)
            item["next_renewal"] = nxt.isoformat()
            d = nxt
            while d <= horizon:
                due = charge
                if trial_end and d >= trial_end and after_trial is not None:
                    due = after_trial * rate
                renewals.append({"date": d.isoformat(), "name": name, "amount": q(due)})
                d = add_cycle(d, n, u)
            if (n, u) in ((12, "m"),) or (u == "m" and n >= 12):
                if nxt <= horizon:
                    flags.append({"name": name, "flag": "RENEWS_YEARLY",
                                  "detail": f"{q(charge)} {currency} charge on {nxt.isoformat()}; decide before then"})
        last = parse_date(r.get("last_used"), "last_used", name)
        if last and (today - last).days > unused_days:
            flags.append({"name": name, "flag": "UNUSED",
                          "detail": f"last used {last.isoformat()} ({(today - last).days} days ago); costs {q(monthly * 12)} {currency}/year"})
        if trial_end and today <= trial_end <= horizon:
            extra = (f"; then {q(after_trial * rate)} {currency} per charge ({q(after_trial * rate * f * 12)} {currency}/year)"
                     if after_trial is not None else "")
            flags.append({"name": name, "flag": "TRIAL",
                          "detail": f"trial ends {trial_end.isoformat()} ({(trial_end - today).days} days){extra}; cancel or keep on purpose"})
        prev = money(r.get("previous_amount"), "previous_amount", name)
        if prev and amount > prev:
            pct = (amount - prev) / prev * 100
            flags.append({"name": name, "flag": "PRICE_UP",
                          "detail": f"{prev} -> {amount} {cur} (+{q(pct)}%), +{q((amount - prev) * rate * f * 12)} {currency}/year"})
        annual = money(r.get("annual_price"), "annual_price", name)
        if annual is not None and not (u == "m" and n == 12):
            save = monthly * 12 - annual * rate
            if save > 0:
                flags.append({"name": name, "flag": "ANNUAL_SAVES",
                              "detail": f"annual plan {q(annual * rate)} {currency} vs {q(monthly * 12)} {currency} paid {r.get('cycle')}: saves {q(save)} {currency}/year if you keep it 12 months"})
    cats = {}
    for it in items:
        c = cats.setdefault(it["category"], {"count": 0, "monthly": Decimal(0), "names": []})
        c["count"] += 1
        c["monthly"] += raw[it["name"]][0]
        c["names"].append(it["name"])
    for cname, c in sorted(cats.items()):
        if c["count"] > 1:
            flags.append({"name": ", ".join(c["names"]), "flag": "OVERLAP",
                          "detail": f"{c['count']} subscriptions in {cname} ({q(c['monthly'])} {currency}/month); keep the one you use most"})
    order = {"TRIAL": 0, "RENEWS_YEARLY": 1, "UNUSED": 2, "OVERLAP": 3, "PRICE_UP": 4, "ANNUAL_SAVES": 5}
    flags.sort(key=lambda x: (order[x["flag"]], x["name"]))
    renewals.sort(key=lambda x: (x["date"], x["name"]))
    unused_names = {f["name"] for f in flags if f["flag"] == "UNUSED"}
    total_m = sum((raw[it["name"]][0] for it in items), Decimal(0))
    your_m = sum((raw[it["name"]][1] for it in items), Decimal(0))
    return {
        "currency": currency, "today": today.isoformat(), "days": days, "rates": {k: str(v) for k, v in rates.items()},
        "count": len(items), "monthly_total": q(total_m), "yearly_total": q(total_m * 12),
        "your_monthly_total": q(your_m), "your_yearly_total": q(your_m * 12),
        "unused_yearly": q(sum((raw[it["name"]][0] * 12 for it in items if it["name"] in unused_names), Decimal(0))),
        "next_days_total": q(sum((x["amount"] for x in renewals), Decimal(0))),
        "by_category": {k: {"count": v["count"], "monthly": q(v["monthly"])} for k, v in sorted(cats.items(), key=lambda kv: -kv[1]["monthly"])},
        "items": sorted(items, key=lambda it: -it["monthly"]), "renewals": renewals, "flags": flags,
    }


def to_markdown(r):
    c = r["currency"]
    out = ["# Subscription audit", "",
           f"**As of:** {r['today']}  **Subscriptions:** {r['count']}  **Currency:** {c}  **Rates:** "
           + ", ".join(f"1 {k} = {v} {c}" for k, v in r["rates"].items() if k != c.upper()),
           f"**Total:** {r['monthly_total']} {c}/month = {r['yearly_total']} {c}/year  "
           f"**Your share:** {r['your_monthly_total']} {c}/month = {r['your_yearly_total']} {c}/year",
           f"**Unused (yearly cost):** {r['unused_yearly']} {c}  **Charges in next {r['days']} days:** {r['next_days_total']} {c}",
           "", "## Action list", ""]
    out += [f"- **{f['flag']}** {f['name']}: {f['detail']}" for f in r["flags"]] or ["- Nothing to act on."]
    out += ["", "## All subscriptions (most expensive first)", "",
            "| Name | Category | Charge | Cycle | Per month | Per year | Users | Your year | Next renewal |",
            "|---|---|---|---|---|---|---|---|---|"]
    for it in r["items"]:
        out.append(f"| {it['name']} | {it['category']} | {it['amount']:.2f} {it['currency']} | {it['cycle']} | {it['monthly']} | "
                   f"{it['yearly']} | {it['users']} | {it['your_yearly']} | {it.get('next_renewal', '')} |")
    out += ["", "## By category", "", "| Category | Count | Per month |", "|---|---|---|"]
    out += [f"| {k} | {v['count']} | {v['monthly']} |" for k, v in r["by_category"].items()]
    out += ["", f"## Charges in the next {r['days']} days", ""]
    out += [f"- {x['date']} {x['name']}: {x['amount']} {c}" for x in r["renewals"]] or ["- none"]
    return "\n".join(out)


def self_test():
    cases = []

    def ok(name, cond):
        cases.append((name, bool(cond)))

    T = dt.date(2026, 10, 20)
    hdr = "name,amount,currency,cycle,next_renewal,category,last_used,users,trial_end,previous_amount,annual_price,paid_after_trial"

    def run(*lines, **kw):
        return audit(load([hdr, *lines]), today=T, **kw)

    ok("named cycles", parse_cycle("Quarterly") == (3, "m") and parse_cycle("annual") == (12, "m"))
    ok("every N units", parse_cycle("every 2 weeks") == (2, "w") and parse_cycle("1y") == (12, "m"))
    ok("month end clamps", add_cycle(dt.date(2026, 1, 31), 1, "m") == dt.date(2026, 2, 28))
    ok("leap year clamp", add_cycle(dt.date(2027, 2, 28), 12, "m") == dt.date(2028, 2, 28) and add_cycle(dt.date(2028, 1, 31), 1, "m") == dt.date(2028, 2, 29))
    r = run("A,10,EUR,monthly,,X,,,,,,")
    ok("monthly 10 = 120/year", r["yearly_total"] == Decimal("120.00"))
    r = run("A,120,EUR,yearly,,X,,,,,,")
    ok("yearly 120 = 10/month", r["monthly_total"] == Decimal("10.00"))
    r = run("A,5,EUR,weekly,,X,,,,,,")
    ok("weekly 5 = 260.89/year", r["yearly_total"] == Decimal("260.89") and r["items"][0]["monthly"] == Decimal("21.74"))
    r = run("A,1,EUR,monthly,,X,,3,,,,", "B,1,EUR,monthly,,X,,3,,,,", "C,1,EUR,monthly,,X,,3,,,,")
    ok("totals use unrounded shares", r["your_monthly_total"] == Decimal("1.00"))
    r = run("A,10,USD,monthly,,X,,,,,,", rates={"USD": "0.9"})
    ok("currency rate applied", r["monthly_total"] == Decimal("9.00"))
    try:
        run("A,10,GBP,monthly,,X,,,,,,")
        ok("missing rate rejected", False)
    except AuditError:
        ok("missing rate rejected", True)
    r = run("Fam,20,EUR,monthly,,Music,,4,,,,")
    ok("shared plan your share", r["your_monthly_total"] == Decimal("5.00") and r["monthly_total"] == Decimal("20.00"))
    r = run("Old,10,EUR,monthly,,X,2026-07-01,,,,,")
    ok("unused flagged", any(f["flag"] == "UNUSED" for f in r["flags"]) and r["unused_yearly"] == Decimal("120.00"))
    r = run("Fresh,10,EUR,monthly,,X,2026-10-01,,,,,")
    ok("recent use not flagged", not r["flags"])
    r = run("A,10,EUR,monthly,,Video,,,,,,", "B,8,EUR,monthly,,Video,,,,,,")
    ok("overlap flagged", [f["flag"] for f in r["flags"]] == ["OVERLAP"])
    r = run("T,0,EUR,monthly,2026-10-25,Software,,,2026-10-25,,,24.99")
    ok("trial flagged with paid price", r["flags"][0]["flag"] == "TRIAL" and "24.99" in r["flags"][0]["detail"])
    ok("trial charge counted in renewals", r["renewals"][0]["amount"] == Decimal("24.99"))
    r = run("P,12,EUR,monthly,,X,,,,10,,")
    ok("price increase flagged", r["flags"][0]["flag"] == "PRICE_UP" and "+20.00%" in r["flags"][0]["detail"] and "+24.00" in r["flags"][0]["detail"])
    r = run("M,10,EUR,monthly,,X,,,,,99,")
    ok("annual saving flagged", r["flags"][0]["flag"] == "ANNUAL_SAVES" and "saves 21.00" in r["flags"][0]["detail"])
    r = run("M,10,EUR,monthly,,X,,,,,130,")
    ok("no saving when annual is pricier", not r["flags"])
    r = run("Y,50,EUR,yearly,2026-11-01,X,,,,,,")
    ok("yearly renewal soon flagged", r["flags"][0]["flag"] == "RENEWS_YEARLY")
    r = run("W,1,EUR,weekly,2026-10-21,X,,,,,,")
    ok("weekly renewals listed in window", len(r["renewals"]) == 5 and r["next_days_total"] == Decimal("5.00"))
    r = run("Past,10,EUR,monthly,2026-08-15,X,,,,,,")
    ok("rolled forward to the future", r["items"][0]["next_renewal"] == "2026-11-15")
    for line, label in [("A,-3,EUR,monthly,,X,,,,,,", "negative amount rejected"),
                        ("A,3,EUR,sometimes,,X,,,,,,", "unknown cycle rejected"),
                        ("A,3,EUR,monthly,20-10-2026,X,,,,,,", "bad date rejected"),
                        ("A,3,EUR,monthly,,X,,0,,,,", "zero users rejected")]:
        try:
            run(line)
            ok(label, False)
        except AuditError:
            ok(label, True)
    ok("markdown has action list", "## Action list" in to_markdown(run("A,10,EUR,monthly,,X,,,,,,")))
    passed = sum(c for _, c in cases)
    for name, c in cases:
        print(("PASS " if c else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def default(o):
    if isinstance(o, Decimal):
        return float(o)
    raise TypeError(type(o))


def main(argv=None):
    ap = argparse.ArgumentParser(description="Audit recurring subscriptions: true yearly cost, unused, overlapping, trials and renewals.")
    ap.add_argument("file", nargs="?", help="subscriptions CSV ('-' for stdin)")
    ap.add_argument("--currency", default="EUR", help="report currency (default EUR)")
    ap.add_argument("--rate", action="append", default=[], metavar="CUR=VALUE",
                    help="1 CUR = VALUE report-currency units, e.g. USD=0.92 (repeatable)")
    ap.add_argument("--today", help="evaluation date YYYY-MM-DD (default: today)")
    ap.add_argument("--days", type=int, default=30, help="look-ahead for renewals and trials (default 30)")
    ap.add_argument("--unused-days", type=int, default=45, help="flag items not used for this many days (default 45)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("subscriptions CSV required (or --self-test)")
    try:
        rates = {}
        for x in a.rate:
            k, _, v = x.partition("=")
            if not v:
                raise AuditError(f"bad --rate {x!r}, use CUR=VALUE")
            rates[k.strip().upper()] = Decimal(v.strip())
        lines = sys.stdin.read().splitlines() if a.file == "-" else open(a.file, encoding="utf-8").read().splitlines()
        today = dt.date.fromisoformat(a.today) if a.today else None
        r = audit(load(lines), a.currency.upper(), rates, today, a.days, a.unused_days)
    except (OSError, AuditError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(r, indent=2, default=default, ensure_ascii=False) if a.json else to_markdown(r))
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: csv-diff-and-reconciliation-checker
description: So sánh hai bản xuất CSV của cùng các bản ghi (cũ và mới, hệ thống thanh toán và sổ cái, nguồn và kho dữ liệu) theo khóa sau khi chuẩn hóa tiêu đề, dấu phân cách, định dạng tiền tệ, số âm kế toán, ngày tháng và chữ hoa/thường. Báo cáo các khóa được thêm, bị xóa và trùng lặp, lệch định dạng khóa, giá trị thay đổi theo từng cột kèm ngưỡng dung sai, các trường hợp có khả năng đổi khóa và bảng cầu nối tổng kiểm soát, sau đó xuất báo cáo đối chiếu. Bao gồm công cụ kiểm tra bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Công cụ Kiểm tra Đối chiếu và So sánh Khác biệt CSV

Bạn giúp các chuyên viên phân tích, đội ngũ tài chính và kỹ sư dữ liệu trả lời câu hỏi "hai tệp này có khớp nhau không, và nếu không thì chính xác là tại sao?". Bạn đối sánh các dòng theo khóa nghiệp vụ, bỏ qua những khác biệt chỉ nằm ở mặt định dạng, và chuyển các khác biệt thực sự thành một danh sách ngắn gọn các nguyên nhân kèm theo số tiền mà mỗi nguyên nhân giải thích được, để các con số tổng khớp nhau đến từng xu.

## Các tệp trong kỹ năng này

- `scripts/csv_recon.py` - đối sánh hai tệp CSV theo khóa (đơn hoặc phức hợp), chuẩn hóa giá trị, liệt kê các khác biệt về lược đồ (schema), khóa trùng lặp và khóa trống, các dòng được thêm, bị xóa và thay đổi, lệch định dạng khóa và các trường hợp có khả năng đổi khóa, đồng thời xây dựng bảng cầu nối tổng kiểm soát (chỉ sử dụng thư viện chuẩn Python 3)
- `references/matching-and-normalization.md` - cách chọn khóa, chuẩn hóa tiêu đề và giá trị, định dạng số và ngày tháng, ngưỡng dung sai, cùng ý nghĩa của từng mã phát hiện
- `references/reconciliation-playbook.md` - các nguyên nhân gây lệch phổ biến (chênh lệch thời điểm, trùng lặp, quy ước dấu, làm tròn, bộ lọc, bảng mã ký tự) và cách chứng minh từng nguyên nhân
- `templates/reconciliation-report.md` - mẫu báo cáo để bàn giao lại
- `examples/billing-export-sept.csv` - hóa đơn tháng Chín từ hệ thống thanh toán (14 dòng, phân cách bằng dấu phẩy)
- `examples/ledger-export-sept.csv` - dữ liệu cùng tháng từ sổ cái chung (15 dòng, dấu chấm phẩy, số tiền dạng $1,200.00, ngày tháng kiểu Mỹ, có các cột bị đổi tên và cột dư thêm)

## Quy trình làm việc

### 1. Tìm hiểu hai tệp dữ liệu
Hãy hỏi xem mỗi tệp là gì, hệ thống và bộ lọc nào đã tạo ra nó (khoảng thời gian, trạng thái, pháp nhân, loại tiền tệ), bên nào là nguồn dữ liệu chuẩn (source of truth), khóa đối sánh là gì, và những khác biệt nào là quan trọng (số tiền chính xác đến từng xu, trạng thái, ngày tháng). Hãy hỏi số lượng dòng và các con số tổng mà người dùng đang kỳ vọng sẵn. Xem qua những dòng đầu tiên của cả hai tệp trước khi chạy bất kỳ công cụ nào.

### 2. Chạy công cụ kiểm tra
```
python3 scripts/csv_recon.py examples/billing-export-sept.csv examples/ledger-export-sept.csv --key invoice_id --map customer=customer_name --tol amount=0.01 --sum amount --ignore-case --dates invoice_date
python3 scripts/csv_recon.py orders_old.csv orders_new.csv --key order_id,line_no --ignore updated_at --out-csv diff.csv
python3 scripts/csv_recon.py a.csv b.csv --key id --json
python3 scripts/csv_recon.py --self-test
```
Các tiêu đề chỉ khác nhau về chữ hoa/thường hoặc khoảng trắng sẽ tự động khớp với nhau; các cột bị đổi tên cần dùng tùy chọn `--map old=new`. Mã thoát (Exit) 0 có nghĩa là hai tệp khớp nhau hoàn toàn, 1 nghĩa là có sự khác biệt, 2 nghĩa là đầu vào không hợp lệ (thiếu tệp hoặc thiếu cột khóa).

### 3. Giải thích mọi điểm khác biệt
Xử lý lần lượt từng phát hiện từ trên xuống (xem `references/reconciliation-playbook.md`): kiểm tra các khóa trùng lặp và khóa trống trước tiên (vì chúng làm sai lệch mọi thứ khác), tiếp đến là các dòng được thêm vào và bị xóa đi (do thời điểm ghi nhận, bộ lọc, đổi khóa), sau đó là các giá trị bị thay đổi được nhóm theo cột và theo quy luật (cùng mức chênh lệch, đảo dấu, đảo vị trí chữ số, làm tròn). Sử dụng công thức cầu nối: tổng cũ + thêm mới - đã xóa + thay đổi - trùng lặp = tổng mới, không để sót khoản nào không giải thích được. Kiểm tra thủ công một vài dòng mẫu trên cả hai hệ thống nguồn.

### 4. Bàn giao kết quả
Điền đầy đủ vào `templates/reconciliation-report.md`: phạm vi và dữ liệu đầu vào, kết quả đối chiếu, số liệu thống kê tóm tắt, bảng cầu nối, từng khoản lệch kèm nguyên nhân, số tiền, người phụ trách và cách khắc phục, cũng như những gì cần thay đổi để tháng sau có thể đối chiếu tự động (khóa ổn định, dùng chung bộ lọc, thống nhất định dạng xuất dữ liệu). Đính kèm kết quả đầu ra từ `--out-csv` cho những người trực tiếp sửa dữ liệu từng dòng.

## Ví dụ kết quả
Hệ thống thanh toán so với sổ cái trong tháng Chín: 14 so với 15 dòng, 13 dòng khớp khóa (INV-1009 khớp với `inv-1009` dưới dạng KEY_FORMAT_DRIFT), 11 dòng không thay đổi giá trị. Các khoản lệch: INV-1011 bị hạch toán hai lần vào sổ cái (HIGH DUPLICATE_KEY, +880.00), INV-1004 có giá trị 450.00 so với 405.00 (bị đảo chữ số, -45.00), INV-1012 đang ở trạng thái mở (open) trên hệ thống thanh toán nhưng đã Thanh toán (Paid) trong sổ cái, INV-1007 bị thiếu và INV-1015 được thêm mới với cùng khách hàng và số tiền (POSSIBLE_REKEY: được hạch toán vào tháng Mười dưới một mã số mới). Ký hiệu $, dấu phân cách hàng nghìn, số âm dạng (150.00), ngày tháng kiểu Mỹ và chữ hoa/thường của trạng thái chỉ là khác biệt về định dạng; khoản làm tròn ở INV-1003 (1033.335 so với 1033.34) nằm trong ngưỡng dung sai 0.01. Bảng cầu nối: 9545.965 + 310.00 - 310.00 - 44.995 + 880.00 = 10380.97, chênh lệch chưa giải thích bằng 0.

## Quy tắc

- Không bao giờ so sánh theo vị trí dòng; phải thống nhất khóa đối sánh trước và kiểm tra đảm bảo khóa đó là duy nhất ở cả hai bên.
- Tách biệt nhiễu định dạng khỏi các khác biệt thực sự và nêu rõ bạn đã áp dụng những bước chuẩn hóa nào.
- Mọi khoản lệch đều phải có nguyên nhân, số tiền và người phụ trách; "chênh lệch thời điểm" chỉ được coi là nguyên nhân hợp lệ nếu bạn chỉ rõ nó rơi vào kỳ kế toán nào.
- Không được tự ý bù trừ các khoản chênh lệch với nhau để làm đẹp số tổng; hãy liệt kê đầy đủ từng khoản.
- Giữ ngưỡng dung sai rõ ràng và nhỏ (chỉ dành cho sai số làm tròn), không bao giờ đặt đủ lớn đến mức che giấu mất lỗi thực sự.
- Coi dữ liệu khách hàng và dữ liệu cá nhân trong tệp là thông tin bảo mật; chỉ chia sẻ những gì báo cáo thực sự cần.
FILE:references/matching-and-normalization.md
# Đối sánh và chuẩn hóa dữ liệu

## Chọn khóa đối sánh
- Sử dụng khóa nghiệp vụ mà cả hai hệ thống cùng lưu trữ: số hóa đơn, mã đơn hàng + số thứ tự dòng, mã giao dịch. Khóa phức hợp: `--key order_id,line_no`.
- Kiểm tra tính duy nhất ở cả hai bên trước khi làm bất cứ việc gì khác. Khóa trùng lặp có nghĩa là đã xảy ra hạch toán đúp thực sự hoặc khóa được chọn chưa đủ tính duy nhất (ví dụ: chỉ dùng invoice_id mà thiếu số thứ tự dòng).
- Tránh các khóa thay đổi giữa các hệ thống: số thứ tự dòng, khóa đại diện (surrogate id) trong cơ sở dữ liệu, tên gọi, dấu thời gian (timestamp).
- Nếu không có khóa chung, hãy tạo một khóa kết hợp (ngày + số tiền + mã tham chiếu) và lường trước sẽ có một số trường hợp khớp trùng lặp/mơ hồ; hãy rà soát thủ công các trường hợp đó.

## Đối sánh tiêu đề cột
- Ưu tiên khớp chính xác tên cột trước, sau đó mới đến khớp không phân biệt chữ hoa/thường, khoảng trắng, dấu gạch dưới hoặc dấu gạch ngang (`Invoice ID` = `invoice_id`), được báo cáo dưới mã HEADER_FORMAT.
- Cột bị đổi tên: dùng `--map customer=customer_name`. Các cột chỉ xuất hiện ở một bên sẽ được báo cáo riêng và không đưa vào so sánh.
- Ký tự đánh dấu thứ tự byte UTF-8 (BOM) ở đầu tệp sẽ được loại bỏ; nếu không thì tiêu đề cột đầu tiên sẽ không thể khớp được.

## Dấu phân cách và bảng mã ký tự (encoding)
- Tự động nhận diện dấu phẩy, dấu chấm phẩy, ký tự tab và dấu gạch đứng (pipe). Các bản xuất Excel kiểu châu Âu thường dùng `;` kèm dấu `,` làm dấu phân cách thập phân; công cụ kiểm tra này yêu cầu dấu thập phân là `.`, vì vậy hãy chuyển đổi chúng trước (hoặc xuất lại tệp với dấu `.`).
- Đọc tệp theo bảng mã UTF-8. Nếu bạn thấy `é` thay vì `é`, tệp đó đang dùng bảng mã Windows-1252: hãy chuyển đổi bằng lệnh `iconv -f cp1252 -t utf-8`.

## Chuẩn hóa giá trị (áp dụng cho mọi ô được đem ra so sánh)
| Giá trị thô | Được xử lý thành |
|---|---|
| khoảng trắng ở đầu/cuối, nhiều khoảng trắng liên tiếp ở giữa | cắt bỏ khoảng trắng thừa ở hai đầu, gộp thành một khoảng trắng đơn |
| `1,234.50`, `$1,234.50`, `1234.5`, `1234.50 USD` | số 1234.5 |
| `(150.00)`, `150.00-`, `-$150.00` | số -150 |
| `12.5%` | số 12.5 (không phải 0.125) |
| để trống, `null`, `None`, `N/A`, `NA`, `-` | để trống |
| `Paid` so với `paid` | khác nhau, trừ khi dùng tùy chọn `--ignore-case` |
| `09/01/2026`, `2026/09/01`, `01.09.2026` | 2026-09-01 đối với các cột trong `--dates` (mặc định tháng đứng trước kiểu Mỹ trừ khi có `--dayfirst`) |

Các con số được so sánh dưới dạng số thập phân chính xác (decimal) chứ không phải số thực dấu phẩy động (float), do đó lỗi kiểu `0.1 + 0.2` sẽ không xảy ra. Các chữ số 0 đứng đầu trong những mã trông giống số (`00123` so với `123`) sẽ được coi là bằng nhau khi so sánh dưới dạng số; nếu điều đó không đúng với một cột mã định danh, hãy thêm cột đó vào `--ignore` và so sánh riêng.

## Ngưỡng dung sai
- Dùng `--tol amount=0.01` cho từng cột riêng lẻ, hoặc `--tol 0.01` cho mọi cột số.
- Sử dụng đơn vị nhỏ nhất của loại tiền tệ cho các chênh lệch do làm tròn; không bao giờ dùng ngưỡng dung sai để che giấu một lỗi đã biết.
- Các giá trị nằm trong ngưỡng dung sai được tính là FORMAT_ONLY và vẫn xuất hiện trong bảng cầu nối dưới dạng các khoản thay đổi.

## Các mã phát hiện (Finding codes)
| Mã | Mức độ nghiêm trọng | Ý nghĩa |
|---|---|---|
| DUPLICATE_KEY | HIGH | cùng một khóa xuất hiện nhiều hơn một lần ở một bên; chỉ dòng đầu tiên được đưa vào so sánh |
| MISSING_KEY | HIGH | các dòng có khóa bị bỏ trống; không thể đối sánh các dòng này |
| TOTAL_UNEXPLAINED | HIGH | bảng cầu nối không khớp tổng (do có ô không phải dạng số, hoặc có khóa trống) |
| COLUMN_ONLY_IN_OLD / NEW | MEDIUM | khác biệt về lược đồ (schema); hãy ánh xạ cột nếu nó đã bị đổi tên |
| ROWS_ADDED / ROWS_REMOVED | MEDIUM | các khóa chỉ xuất hiện ở một bên |
| VALUE_CHANGED | MEDIUM | theo từng cột, các dòng có giá trị sau chuẩn hóa khác nhau |
| RAGGED_ROWS | MEDIUM | các dòng có số ô nhiều hơn hoặc ít hơn dòng tiêu đề (lỗi dấu ngoặc kép, dấu phân cách nằm bên trong dữ liệu) |
| NON_NUMERIC | MEDIUM | các ô trong cột `--sum` không phải là số |
| HEADER_FORMAT | LOW | các cột chỉ khớp sau khi bỏ qua chữ hoa/thường và khoảng trắng |
| KEY_FORMAT_DRIFT | LOW | các khóa bằng nhau sau khi bỏ qua chữ hoa/thường, khoảng trắng, dấu phân cách và chữ số 0 đứng đầu; được so sánh như cùng một dòng |
| POSSIBLE_REKEY | LOW | một dòng bị xóa và một dòng được thêm mới có cùng các giá trị ở những cột không phải khóa và không phải ngày tháng |
| FORMAT_ONLY, DELIMITER, TOTAL_DIFF | INFO | thông tin ngữ cảnh: bằng nhau sau khi chuẩn hóa, khác dấu phân cách, tổng số tiền thay đổi |

## Bảng cầu nối tổng kiểm soát (Control-total bridge)
```
Tổng OLD
+ số tiền của các dòng chỉ có trong NEW
- số tiền của các dòng chỉ có trong OLD
+ (NEW - OLD) trên các dòng đã khớp khóa
- các dòng trùng lặp dư ra hoặc có khóa trống trong OLD
+ các dòng trùng lặp dư ra hoặc có khóa trống trong NEW
= Tổng NEW            (phần chưa giải thích phải bằng 0)
```
FILE:references/reconciliation-playbook.md
# Sổ tay đối chiếu: nguyên nhân gây lệch và cách chứng minh

Thực hiện theo đúng thứ tự này: các khóa trùng lặp và khóa trống, tiếp đến là các dòng chỉ xuất hiện ở một bên, sau đó là các giá trị bị thay đổi, cuối cùng là số tổng.

## Khóa trùng lặp (Duplicates)
- **Hạch toán đúp (Double posting)** (cùng khóa, cùng giá trị xuất hiện hai lần): do cơ chế tự động thử lại (retry), chạy lệnh nhập dữ liệu (import) hai lần, hoặc nhập tay lại. Cách chứng minh: các dòng giống hệt nhau, thường có cùng dấu thời gian tạo hoặc cùng mã lô (batch id). Cách khắc phục: đảo (reverse) một bút toán hạch toán; bổ sung khóa chống trùng lặp (idempotency key) vào quy trình nhập dữ liệu.
- **Khóa không duy nhất (Non-unique key)** (cùng khóa, khác giá trị): khóa hiện tại cần kết hợp thêm một cột khác (số thứ tự dòng, loại tiền tệ, pháp nhân). Hãy chạy lại công cụ với khóa phức hợp.

## Các dòng chỉ xuất hiện ở một bên
- **Chênh lệch thời điểm / cắt kỳ (Timing / cut-off)**: bản ghi tồn tại trên cả hai hệ thống nhưng nằm ở hai kỳ kế toán khác nhau (hóa đơn ghi ngày 30/9, nhưng hạch toán ngày 1/10). Cách chứng minh: tìm thấy bản ghi đó trong tệp xuất dữ liệu của kỳ kế tiếp hoặc kỳ trước đó. Dấu hiệu điển hình: mã POSSIBLE_REKEY kèm theo ngày tháng nằm ngay sát ranh giới chuyển giao kỳ.
- **Khác bộ lọc (Different filters)**: một bản xuất đã loại trừ các bản nháp (drafts), bản ghi đã hủy (voids), tài khoản thử nghiệm, số tiền bằng 0, hoặc khác pháp nhân hay loại tiền tệ. Cách chứng minh: so sánh câu truy vấn xuất dữ liệu hoặc thiết lập báo cáo; đếm số lượng các trạng thái đã bị loại trừ.
- **Bản ghi bị đổi khóa (Re-keyed records)**: xuất hóa đơn điều chỉnh giảm (credit note) rồi phát hành lại, mã id được di chuyển sang hệ thống mới, thay đổi tiền tố (INV- so với IN-). Cách chứng minh: cùng khách hàng, số tiền và ngày tháng nhưng mang một khóa mới.
- **Lỗi đồng bộ (Failed sync)**: bản ghi chưa bao giờ được chuyển tới hệ thống đích. Cách chứng minh: kiểm tra nhật ký tích hợp (integration logs), hàng đợi lỗi (error queue), thời điểm đồng bộ thành công gần nhất.
- **Định dạng khóa (Key format)**: khác biệt chữ hoa/thường, khoảng trắng, chữ số 0 đứng đầu, dấu phân cách (KEY_FORMAT_DRIFT). Cách khắc phục: sửa ngay tại hệ thống nguồn; chuẩn hóa khóa khi xuất dữ liệu.

## Các giá trị bị thay đổi
| Quy luật | Nguyên nhân có khả năng cao |
|---|---|
| chênh lệch là bội số của 9 (450 -> 405, 1,234 -> 1,324) | bị đảo vị trí chữ số khi nhập liệu thủ công |
| đảo dấu chính xác | quy ước nợ/có (debit/credit), hóa đơn điều chỉnh giảm được lưu dưới dạng số dương kèm theo một cột phân loại |
| chênh lệch đúng bằng thuế suất hoặc tỷ lệ phí x số tiền | một bên là số tiền trước thuế/phí (gross), bên kia là số tiền thực nhận (net) |
| chênh lệch từ 0.01 đến 0.05 | làm tròn theo từng dòng so với làm tròn trên số tổng; làm tròn lên (half-up) so với làm tròn kiểu ngân hàng (banker's rounding) |
| số tiền / tỷ giá | quy đổi ngoại tệ, áp dụng tỷ giá của ngày khác |
| ngày tháng lệch nhau một ngày | khác múi giờ (UTC so với giờ địa phương) trên các dấu thời gian gần nửa đêm |
| khác trạng thái | độ trễ đồng bộ, hoặc hai hệ thống sử dụng máy trạng thái (state machine) khác nhau (paid so với settled) |
| văn bản chỉ khác nhau ở dấu trọng âm hoặc ký tự lạ | lệch bảng mã ký tự (UTF-8 so với Windows-1252) |

## Số tổng (Totals)
- Đảm bảo bảng cầu nối cân bằng về 0 trước khi lập báo cáo. Khoản chênh lệch chưa giải thích khác 0 có nghĩa là đang có khóa trống, ô dữ liệu không phải dạng số hoặc một cột đang trộn lẫn nhiều loại tiền tệ.
- Báo cáo số tổng riêng theo từng loại tiền tệ; không bao giờ cộng gộp USD và EUR với nhau.
- Đối chiếu số tổng với báo cáo gốc của chính hệ thống đó (bảng cân đối thử, báo cáo chi trả), chứ không chỉ đối chiếu với tệp xuất ra.

## Chứng minh nguyên nhân
Đối với mỗi khoản lệch: chỉ rõ (các) dòng dữ liệu ở cả hai bên, nguyên nhân, số tiền và bằng chứng cụ thể (dòng nhật ký hệ thống, thiết lập xuất dữ liệu, dòng dữ liệu xuất hiện ở kỳ tiếp theo). Đánh dấu hướng xử lý cho từng khoản: sửa tại nguồn A, sửa tại nguồn B, chênh lệch thời điểm (sẽ tự hết ở kỳ sau), hoặc chênh lệch được chấp nhận.

## Ngăn ngừa sai lệch cho tháng tiếp theo
- Áp dụng cùng bộ lọc và cùng định nghĩa kỳ dữ liệu (múi giờ, mốc ngày kết thúc bao gồm cả ngày cuối) trên cả hai bản xuất.
- Duy trì khóa ổn định, duy nhất xuyên suốt từ đầu đến cuối; không đổi khóa thủ công.
- Xuất số tiền dưới dạng số thuần túy dùng dấu thập phân `.` và tách riêng một cột tiền tệ; xuất ngày tháng theo chuẩn ISO 8601.
- Chạy công cụ kiểm tra định kỳ theo lịch và bật cảnh báo khi có phát hiện mức HIGH hoặc khi có số tổng chưa giải thích được.
FILE:templates/reconciliation-report.md
# Báo cáo đối chiếu: <Nguồn OLD> so với <Nguồn NEW>, <kỳ đối chiếu>

**Dữ liệu đầu vào:** <billing-export-sept.csv (14 dòng, xuất ngày 2026-10-02 bởi ...)>, <ledger-export-sept.csv (15 dòng)>
**Khóa:** <invoice_id>   **Các cột so sánh:** <customer, amount, currency, status, invoice_date>
**Chuẩn hóa:** <loại bỏ ký hiệu $ và dấu phân cách hàng nghìn, (x) = -x, bỏ qua chữ hoa/thường ở cột status, ngày tháng kiểu Mỹ được đọc thành chuẩn ngày tháng, ngưỡng dung sai cột amount là 0.01>
**Kết quả:** <KHỚP HOÀN TOÀN / PHÁT HIỆN KHÁC BIỆT: 4 khoản lệch, chênh lệch ròng +835.005, chưa giải thích 0>

## Tóm tắt
| Số dòng OLD | Số dòng NEW | Đã khớp | Không đổi | Thay đổi | Thêm mới | Đã xóa | Trùng lặp |
|---|---|---|---|---|---|---|---|
| <14> | <15> | <13> | <11> | <2> | <1> | <1> | <1> |

## Bảng cầu nối tổng kiểm soát (<amount>, <USD>)
| Bước | Số tiền |
|---|---|
| Tổng OLD | <9,545.97> |
| + các dòng chỉ có trong NEW | <310.00> |
| - các dòng chỉ có trong OLD | <310.00> |
| + thay đổi trên các dòng đã khớp | <-45.00> |
| + trùng lặp trong NEW | <880.00> |
| = Tổng NEW | <10,380.97> |
| Chưa giải thích | <0.00> |

## Chi tiết các khoản lệch (Breaks)
| # | (Các) khóa | Loại | OLD | NEW | Số tiền | Nguyên nhân (bằng chứng) | Người phụ trách | Hành động xử lý |
|---|---|---|---|---|---|---|---|---|
| 1 | <INV-1011> | <Trùng lặp> | <880.00 x1> | <880.00 x2> | <+880.00> | <hạch toán hai lần do cơ chế thử lại khi nhập dữ liệu (lô 7731)> | <Đội GL> | <đảo bút toán hạch toán thứ hai> |

## Các khác biệt chỉ về mặt định dạng (không cần xử lý)
- <định dạng số tiền, chữ hoa/thường của trạng thái, định dạng ngày tháng, tên tiêu đề cột>

## Khuyến nghị
- <áp dụng cùng bộ lọc và định nghĩa kỳ dữ liệu trên cả hai bản xuất>
- <bổ sung khóa chống trùng lặp (idempotency key) vào quy trình nhập dữ liệu sổ cái>

## Tài liệu đính kèm
- <diff.csv từ tùy chọn --out-csv (status, key, column, old, new, delta)>
FILE:examples/billing-export-sept.csv
invoice_id,customer,amount,currency,status,invoice_date
INV-1001,Northwind Traders,1200.00,USD,paid,2026-09-01
INV-1002,Blue Harbor Cafe,89.90,USD,paid,2026-09-02
INV-1003,Atlas Fitness,1033.335,USD,paid,2026-09-03
INV-1004,Greenleaf Dental,450.00,USD,paid,2026-09-05
INV-1005,Orbit Labs,2500.00,USD,paid,2026-09-08
INV-1006,Maple & Co,74.50,USD,refunded,2026-09-09
INV-1007,Copperline Studio,310.00,USD,paid,2026-09-11
INV-1008,Riverbend School,640.00,USD,paid,2026-09-12
INV-1009,Juniper Vet Clinic,195.00,USD,paid,2026-09-15
INV-1010,Northwind Traders,1200.00,USD,paid,2026-09-18
INV-1011,Summit Roofing,880.00,USD,paid,2026-09-22
INV-1012,Blue Harbor Cafe,89.90,USD,open,2026-09-25
INV-1013,Orbit Labs,-150.00,USD,credit,2026-09-26
INV-1014,Atlas Fitness,1033.33,USD,paid,2026-09-30
FILE:examples/ledger-export-sept.csv
Invoice ID;customer_name;Amount;Currency;Status;Invoice Date;gl_account
INV-1001;Northwind Traders;$1,200.00;USD;Paid;09/01/2026;4000
INV-1002;Blue Harbor Cafe;$89.90;USD;Paid;09/02/2026;4000
INV-1003;Atlas Fitness;$1,033.34;USD;Paid;09/03/2026;4000
INV-1004;Greenleaf Dental;$405.00;USD;Paid;09/05/2026;4000
INV-1005;Orbit Labs;$2,500.00;USD;Paid;09/08/2026;4000
INV-1006;Maple & Co;$74.50;USD;Refunded;09/09/2026;4000
INV-1008;Riverbend School;$640.00;USD;Paid;09/12/2026;4000
inv-1009;Juniper Vet Clinic;$195.00;USD;Paid;09/15/2026;4000
INV-1010;Northwind Traders;$1,200.00;USD;Paid;09/18/2026;4000
INV-1011;Summit Roofing;$880.00;USD;Paid;09/22/2026;4000
INV-1011;Summit Roofing;$880.00;USD;Paid;09/22/2026;4000
INV-1012;Blue Harbor Cafe;$89.90;USD;Paid;09/25/2026;4000
INV-1013;Orbit Labs;($150.00);USD;Credit;09/26/2026;4090
INV-1014;Atlas Fitness;$1,033.33;USD;Paid;09/30/2026;4000
INV-1015;Copperline Studio;$310.00;USD;Paid;10/01/2026;4000
FILE:scripts/csv_recon.py
#!/usr/bin/env python3
"""CSV diff and reconciliation checker (Python 3 standard library only).

Compares two CSV exports of the same records (old vs new, system A vs system B) by a
key, after normalizing the noise that makes naive diffs useless: spaces, header case,
thousands separators, currency signs, accounting negatives "(12.50)", number
formatting, optional text case and date formats. Reports schema differences, missing
or duplicate keys, added and removed rows, changed values per column (with numeric
tolerances), keys that only differ by format (case, leading zeros, spaces) and a
control-total bridge for amount columns: old total + added - removed + changes = new.

Usage:
  python3 csv_recon.py OLD.csv NEW.csv --key id [--key2 line] [--map old_col=new_col]
        [--ignore col,col] [--tol amount=0.01] [--sum amount] [--ignore-case]
        [--dates col,col] [--dayfirst] [--limit 20] [--out-csv diff.csv] [--json]
  python3 csv_recon.py --self-test
Exit codes: 0 = files reconcile (no differences after normalization and tolerance),
1 = differences found, 2 = bad input (missing file, missing key column).
"""
import argparse, csv, datetime, io, json, re, sys
from decimal import Decimal, InvalidOperation

SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
NUM_RE = re.compile(r"^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$")
DATE_FORMATS = ["%Y-%m-%d", "%Y/%m/%d", "%Y%m%d", "%d.%m.%Y", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S"]


class InputError(Exception):
    pass


def norm_header(h):
    return re.sub(r"[\s_\-]+", "_", h.strip().lstrip("\ufeff").lower())


def read_csv(text, name):
    text = text.lstrip("\ufeff")
    if not text.strip():
        raise InputError(f"{name} is empty")
    sample = text[:4096]
    try:
        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t|")
    except csv.Error:
        dialect = csv.excel
    rows = list(csv.reader(io.StringIO(text), dialect))
    rows = [r for r in rows if any(c.strip() for c in r)]
    header = [h.strip() for h in rows[0]]
    body = []
    for i, r in enumerate(rows[1:], 2):
        if len(r) != len(header):
            body.append((i, dict(zip(header, r + [""] * (len(header) - len(r)))), len(r)))
        else:
            body.append((i, dict(zip(header, r)), len(r)))
    return header, body, getattr(dialect, "delimiter", ",")


def parse_number(s):
    """Return Decimal for '1,234.50', '$1,234.50', '(12.00)', '-5', '12.5%' (as 12.5), else None."""
    t = s.strip().replace("\u00a0", "").replace(" ", "")
    if not t:
        return None
    neg = False
    if t.startswith("(") and t.endswith(")"):
        neg, t = True, t[1:-1]
    if t.endswith("-") and NUM_RE.match(t[:-1].lstrip("$")):
        neg, t = True, t[:-1]
    t = re.sub(r"^([+-]?)(USD|EUR|GBP|[$\u20ac\u00a3])", r"\1", t)
    t = re.sub(r"(USD|EUR|GBP|[$\u20ac\u00a3])$", "", t)
    t = t.rstrip("%")
    if re.match(r"^[+-]?\d{1,3}(,\d{3})+(\.\d+)?$", t):
        t = t.replace(",", "")
    if not NUM_RE.match(t):
        return None
    try:
        d = Decimal(t)
    except InvalidOperation:
        return None
    return -d if neg else d


def parse_date(s, dayfirst):
    t = s.strip()
    fmts = DATE_FORMATS + (["%d/%m/%Y"] if dayfirst else ["%m/%d/%Y"])
    for f in fmts:
        try:
            return datetime.datetime.strptime(t, f).date().isoformat() if "%H" not in f else datetime.datetime.strptime(t, f).isoformat()
        except ValueError:
            pass
    return None


def normalize(value, col, opts):
    v = value.strip()
    if col in opts["dates"]:
        d = parse_date(v, opts["dayfirst"])
        if d:
            return ("date", d)
    n = parse_number(v)
    if n is not None:
        return ("num", n)
    if v.lower() in ("", "null", "none", "n/a", "na", "-"):
        return ("empty", "")
    v = re.sub(r"\s+", " ", v)
    return ("text", v.lower() if opts["ignore_case"] else v)


def same(a, b, col, opts):
    if a[0] == "num" and b[0] == "num":
        tol = opts["tol"].get(col, opts["tol"].get("*", Decimal(0)))
        return abs(a[1] - b[1]) <= tol
    return a == b


def key_variant(k):
    """Format-insensitive form of a key: case, spaces, separators and leading zeros."""
    t = re.sub(r"[\s\-_./]", "", k.lower())
    return re.sub(r"(?<!\d)0+(?=\d)", "", t)


def reconcile(old_text, new_text, keys, opts):
    oh, ob, odelim = read_csv(old_text, "OLD")
    nh, nb, ndelim = read_csv(new_text, "NEW")
    findings = []

    def add(sev, code, detail, count=1):
        findings.append({"severity": sev, "code": code, "detail": detail, "count": count})

    # column matching: explicit map, then exact, then normalized header
    cmap, fuzzy = {}, []
    n_by_norm = {norm_header(h): h for h in nh}
    for h in oh:
        if h in opts["map"]:
            target = opts["map"][h]
            if target not in nh:
                raise InputError(f"--map target column '{target}' not in NEW")
            cmap[h] = target
        elif h in nh:
            cmap[h] = h
        elif norm_header(h) in n_by_norm:
            cmap[h] = n_by_norm[norm_header(h)]
            fuzzy.append(f"{h} = {cmap[h]}")
    if fuzzy:
        add("LOW", "HEADER_FORMAT", f"{len(fuzzy)} column(s) matched by case/spacing only: " + "; ".join(fuzzy), len(fuzzy))
    only_old = [h for h in oh if h not in cmap]
    only_new = [h for h in nh if h not in cmap.values()]
    for h in only_old:
        add("MEDIUM", "COLUMN_ONLY_IN_OLD", f"'{h}' has no match in NEW (use --map {h}=<new name> if it was renamed)")
    for h in only_new:
        add("MEDIUM", "COLUMN_ONLY_IN_NEW", f"'{h}' has no match in OLD")
    for k in keys:
        if k not in oh:
            raise InputError(f"key column '{k}' not in OLD header {oh}")
        if cmap.get(k) not in nh:
            raise InputError(f"key column '{k}' has no match in NEW header {nh}")
    if odelim != ndelim:
        add("INFO", "DELIMITER", f"OLD uses '{odelim}', NEW uses '{ndelim}'")

    def index(body, side, colnames):
        idx, dups, blanks, ragged = {}, {}, 0, 0
        for line, row, ncells in body:
            if ncells != (len(oh) if side == "OLD" else len(nh)):
                ragged += 1
            kv = tuple(row.get(c, "").strip() for c in colnames)
            if not all(kv):
                blanks += 1
                continue
            if kv in idx:
                dups.setdefault(kv, [idx[kv][0]]).append(line)
            else:
                idx[kv] = (line, row)
        return idx, dups, blanks, ragged

    oidx, odups, oblank, orag = index(ob, "OLD", keys)
    nidx, ndups, nblank, nrag = index(nb, "NEW", [cmap[k] for k in keys])
    for side, dups in (("OLD", odups), ("NEW", ndups)):
        for kv, lines in dups.items():
            add("HIGH", "DUPLICATE_KEY", f"{side} key {'/'.join(kv)} on lines {', '.join(map(str, lines))} (only the first is compared)")
    for side, n in (("OLD", oblank), ("NEW", nblank)):
        if n:
            add("HIGH", "MISSING_KEY", f"{side} has {n} row(s) with a blank key (not compared)", n)
    for side, n in (("OLD", orag), ("NEW", nrag)):
        if n:
            add("MEDIUM", "RAGGED_ROWS", f"{side} has {n} row(s) with a different number of cells than the header", n)

    removed = [k for k in oidx if k not in nidx]
    added = [k for k in nidx if k not in oidx]
    # keys that only differ by format
    drift = []
    add_by_variant = {}
    for k in added:
        add_by_variant.setdefault(tuple(key_variant(x) for x in k), k)
    for k in list(removed):
        v = tuple(key_variant(x) for x in k)
        if v in add_by_variant:
            nk = add_by_variant.pop(v)
            drift.append((k, nk))
            removed.remove(k); added.remove(nk)
    for ok, nk in drift:
        add("LOW", "KEY_FORMAT_DRIFT", f"OLD key {'/'.join(ok)} = NEW key {'/'.join(nk)} after ignoring case, spaces, separators and leading zeros (compared as one row)")
    if removed:
        add("MEDIUM", "ROWS_REMOVED", f"{len(removed)} key(s) in OLD only: " + ", ".join('/'.join(k) for k in removed[:opts['limit']]), len(removed))
    if added:
        add("MEDIUM", "ROWS_ADDED", f"{len(added)} key(s) in NEW only: " + ", ".join('/'.join(k) for k in added[:opts['limit']]), len(added))

    compare_cols = [h for h in oh if h in cmap and h not in keys and h not in opts["ignore"]]
    pairs = [(k, k) for k in oidx if k in nidx] + drift
    changes, per_col, unchanged, fmt_only = [], {c: 0 for c in compare_cols}, 0, {c: 0 for c in compare_cols}
    for ok, nk in pairs:
        orow, nrow = oidx[ok][1], nidx[nk][1]
        row_changed = False
        for c in compare_cols:
            a_raw, b_raw = orow.get(c, ""), nrow.get(cmap[c], "")
            a, b = normalize(a_raw, c, opts), normalize(b_raw, c, opts)
            if same(a, b, c, opts):
                if a_raw.strip() != b_raw.strip():
                    fmt_only[c] += 1
                continue
            row_changed = True
            per_col[c] += 1
            delta = (b[1] - a[1]) if a[0] == "num" and b[0] == "num" else None
            changes.append({"key": "/".join(ok), "column": c, "old": a_raw, "new": b_raw,
                            "delta": str(delta) if delta is not None else ""})
        unchanged += not row_changed
    # removed and added rows that look like the same record under a new key or period
    nondate = [c for c in compare_cols if c not in opts["dates"]]
    used = set()
    for rk in removed:
        orow = oidx[rk][1]
        for ak in added:
            if ak in used or not nondate:
                continue
            nrow = nidx[ak][1]
            hits = sum(same(normalize(orow.get(c, ""), c, opts), normalize(nrow.get(cmap[c], ""), c, opts), c, opts) for c in nondate)
            if hits == len(nondate):
                used.add(ak)
                add("LOW", "POSSIBLE_REKEY", f"removed {'/'.join(rk)} and added {'/'.join(ak)} have the same values in {', '.join(nondate)} (re-keyed, re-posted or moved to another period?)")
                break
    for c, n in per_col.items():
        if n:
            add("MEDIUM", "VALUE_CHANGED", f"'{c}' differs in {n} row(s)", n)
    for c, n in fmt_only.items():
        if n:
            add("INFO", "FORMAT_ONLY", f"'{c}' equal after normalization in {n} row(s) (formatting, case or within tolerance)", n)

    bridges = []
    for col in opts["sum"]:
        if col not in oh or cmap.get(col) not in nh:
            raise InputError(f"--sum column '{col}' missing in OLD or NEW")
        def total(body, c):
            t, bad = Decimal(0), 0
            for _, row, _ in body:
                n = parse_number(row.get(c, ""))
                if n is None:
                    bad += bool(row.get(c, "").strip())
                else:
                    t += n
            return t, bad
        ot, obad = total(ob, col)
        nt, nbad = total(nb, cmap[col])
        def val(row, c):
            return parse_number(row.get(c, "")) or Decimal(0)
        s_add = sum((val(nidx[k][1], cmap[col]) for k in added), Decimal(0))
        s_rem = sum((val(oidx[k][1], col) for k in removed), Decimal(0))
        s_chg = sum((val(nidx[nk][1], cmap[col]) - val(oidx[ok][1], col) for ok, nk in pairs), Decimal(0))
        s_dup_o = sum((val(r, col) for _, r, _ in ob), Decimal(0)) - sum((val(r, col) for _, r in oidx.values()), Decimal(0))
        s_dup_n = sum((val(r, cmap[col]) for _, r, _ in nb), Decimal(0)) - sum((val(r, cmap[col]) for _, r in nidx.values()), Decimal(0))
        explained = ot + s_add - s_rem + s_chg - s_dup_o + s_dup_n
        unexplained = nt - explained
        bridges.append({"column": col, "old_total": str(ot), "added": str(s_add), "removed": str(s_rem),
                        "changed": str(s_chg), "duplicates_old": str(s_dup_o), "duplicates_new": str(s_dup_n),
                        "new_total": str(nt), "unexplained": str(unexplained), "non_numeric_old": obad, "non_numeric_new": nbad})
        if nt != ot:
            add("INFO", "TOTAL_DIFF", f"'{col}' total {ot} -> {nt} (diff {nt - ot}); see bridge")
        if unexplained != 0:
            add("HIGH", "TOTAL_UNEXPLAINED", f"'{col}' bridge leaves {unexplained} unexplained (blank keys or non-numeric cells?)")
        if obad or nbad:
            add("MEDIUM", "NON_NUMERIC", f"'{col}' has {obad} non-numeric cell(s) in OLD and {nbad} in NEW (left out of totals)", obad + nbad)

    findings.sort(key=lambda f: (SEV_ORDER[f["severity"]], f["code"]))
    summary = {"old_rows": len(ob), "new_rows": len(nb), "matched": len(pairs), "unchanged": unchanged,
               "changed_rows": len(pairs) - unchanged, "added": len(added), "removed": len(removed),
               "compared_columns": compare_cols, "column_map": {k: v for k, v in cmap.items() if k != v}}
    differs = any(f["severity"] in ("HIGH", "MEDIUM") for f in findings)
    return {"summary": summary, "findings": findings, "changes": changes, "bridges": bridges,
            "added_keys": ["/".join(k) for k in added], "removed_keys": ["/".join(k) for k in removed],
            "reconciles": not differs}


def render_md(res, old_name, new_name, limit):
    s = res["summary"]
    out = [f"# CSV reconciliation: {old_name} vs {new_name}", "",
           f"**Result:** {'RECONCILES' if res['reconciles'] else 'DIFFERENCES FOUND'}", "",
           "| Rows OLD | Rows NEW | Matched | Unchanged | Changed | Added | Removed |", "|---|---|---|---|---|---|---|",
           f"| {s['old_rows']} | {s['new_rows']} | {s['matched']} | {s['unchanged']} | {s['changed_rows']} | {s['added']} | {s['removed']} |", ""]
    if s["column_map"]:
        out.append("Column map: " + ", ".join(f"{k} -> {v}" for k, v in s["column_map"].items()))
        out.append("")
    out += ["## Findings", ""]
    if res["findings"]:
        out += ["| Severity | Code | Detail |", "|---|---|---|"]
        out += [f"| {f['severity']} | {f['code']} | {f['detail']} |" for f in res["findings"]]
    else:
        out.append("No findings.")
    if res["changes"]:
        out += ["", f"## Changed values (first {min(limit, len(res['changes']))} of {len(res['changes'])})", "",
                "| Key | Column | OLD | NEW | Delta |", "|---|---|---|---|---|"]
        out += [f"| {c['key']} | {c['column']} | {c['old']} | {c['new']} | {c['delta']} |" for c in res["changes"][:limit]]
    for b in res["bridges"]:
        out += ["", f"## Control total bridge: {b['column']}", "", "| Step | Amount |", "|---|---|",
                f"| OLD total | {b['old_total']} |", f"| + rows added | {b['added']} |", f"| - rows removed | {b['removed']} |",
                f"| + changes on matched rows | {b['changed']} |", f"| - duplicate/blank-key rows in OLD | {b['duplicates_old']} |",
                f"| + duplicate/blank-key rows in NEW | {b['duplicates_new']} |", f"| = NEW total | {b['new_total']} |",
                f"| Unexplained | {b['unexplained']} |"]
    return "\n".join(out)


def parse_args(argv):
    ap = argparse.ArgumentParser(description="CSV diff and reconciliation checker (stdlib only)")
    ap.add_argument("old", nargs="?"); ap.add_argument("new", nargs="?")
    ap.add_argument("--key", help="key column(s) in OLD, comma-separated")
    ap.add_argument("--map", action="append", default=[], help="old_col=new_col (repeatable)")
    ap.add_argument("--ignore", default="", help="columns to skip, comma-separated")
    ap.add_argument("--tol", action="append", default=[], help="col=0.01 or 0.01 for all numeric columns")
    ap.add_argument("--sum", default="", help="amount columns for the control-total bridge")
    ap.add_argument("--ignore-case", action="store_true")
    ap.add_argument("--dates", default="", help="date columns to compare as dates")
    ap.add_argument("--dayfirst", action="store_true", help="read 03/04/2026 as 3 April")
    ap.add_argument("--limit", type=int, default=20)
    ap.add_argument("--out-csv"); ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    return ap, ap.parse_args(argv)


def build_opts(a):
    tol = {}
    for t in a.tol:
        if "=" in t:
            c, v = t.split("=", 1); tol[c.strip()] = Decimal(v)
        else:
            tol["*"] = Decimal(t)
    mp = {}
    for m in a.map:
        if "=" not in m:
            raise InputError(f"--map needs old=new, got '{m}'")
        o, n = m.split("=", 1); mp[o.strip()] = n.strip()
    split = lambda s: [x.strip() for x in s.split(",") if x.strip()]
    return {"tol": tol, "map": mp, "ignore": set(split(a.ignore)), "sum": split(a.sum),
            "ignore_case": a.ignore_case, "dates": set(split(a.dates)), "dayfirst": a.dayfirst, "limit": a.limit}


# ---------------------------------------------------------------- self-test
def self_test():
    D = Decimal
    O = "id,customer,amount,status,date\nA1,Ann,100.00,paid,2026-09-01\nA2,Bob,50,open,2026-09-02\nA3,Cy,10,paid,2026-09-03\n"
    def run(old, new, keys=("id",), **kw):
        opts = {"tol": {}, "map": {}, "ignore": set(), "sum": [], "ignore_case": False, "dates": set(), "dayfirst": False, "limit": 20}
        opts.update(kw)
        return reconcile(old, new, list(keys), opts)
    codes = lambda r: [f["code"] for f in r["findings"]]
    cases = [
        ("number 1,234.50", lambda: parse_number("1,234.50") == D("1234.50")),
        ("currency $1,234.50", lambda: parse_number("$1,234.50") == D("1234.50")),
        ("accounting (12.00)", lambda: parse_number("(12.00)") == D("-12.00")),
        ("trailing minus 5-", lambda: parse_number("5-") == D("-5")),
        ("percent 12.5%", lambda: parse_number("12.5%") == D("12.5")),
        ("text is not a number", lambda: parse_number("INV-12") is None and parse_number("1,23") is None),
        ("EUR suffix", lambda: parse_number("99.90 EUR") == D("99.90")),
        ("date formats", lambda: parse_date("2026-09-01", False) == parse_date("09/01/2026", False) == parse_date("01.09.2026", False)),
        ("dayfirst", lambda: parse_date("03/04/2026", True) == "2026-04-03"),
        ("key variant", lambda: key_variant("INV-0012") == key_variant("inv12")),
        ("identical files reconcile", lambda: run(O, O)["reconciles"] and codes(run(O, O)) == []),
        ("semicolon + formatting only", lambda: run(O, O.replace(",", ";").replace("100.00", "100").replace("50;", "50.0;"))["reconciles"]),
        ("added and removed", lambda: (lambda r: r["summary"]["added"] == 1 and r["summary"]["removed"] == 1)(
            run(O, O.replace("A3,Cy", "A4,Cy")))),
        ("value change counted", lambda: (lambda r: r["summary"]["changed_rows"] == 1 and "VALUE_CHANGED" in codes(r))(
            run(O, O.replace("50,open", "55,open")))),
        ("tolerance hides rounding", lambda: run(O, O.replace("100.00", "100.004"), tol={"amount": D("0.01")})["reconciles"]),
        ("tolerance does not hide real diff", lambda: not run(O, O.replace("100.00", "100.02"), tol={"amount": D("0.01")})["reconciles"]),
        ("ignore case", lambda: run(O, O.replace("paid", "PAID"), ignore_case=True)["reconciles"] and not run(O, O.replace("paid", "PAID"))["reconciles"]),
        ("dates compared as dates", lambda: run(O, O.replace("2026-09-01", "09/01/2026"), dates={"date"})["reconciles"]),
        ("duplicate key HIGH", lambda: "DUPLICATE_KEY" in codes(run(O, O + "A2,Bob,50,open,2026-09-02\n"))),
        ("blank key HIGH", lambda: "MISSING_KEY" in codes(run(O, O + ",Zed,5,open,2026-09-09\n"))),
        ("column only in new", lambda: "COLUMN_ONLY_IN_NEW" in codes(run(O, O.replace("date\n", "date,region\n", 1)))),
        ("header case matched", lambda: (lambda r: "HEADER_FORMAT" in codes(r) and r["reconciles"])(run(O, O.replace("customer", "Customer")))),
        ("rename via map", lambda: run(O, O.replace("customer", "client"), map={"customer": "client"})["reconciles"]),
        ("key format drift", lambda: (lambda r: "KEY_FORMAT_DRIFT" in codes(r) and r["summary"]["added"] == 0)(run(O, O.replace("A3,", "a03,")))),
        ("possible rekey", lambda: "POSSIBLE_REKEY" in codes(run(O, O.replace("A3,Cy,10,paid,2026-09-03", "A9,Cy,10,paid,2026-10-01"), dates={"date"}))),
        ("ragged rows", lambda: "RAGGED_ROWS" in codes(run(O, O + "A5,Dee,5\n"))),
        ("sign before currency", lambda: parse_number("-$5.00") == parse_number("$-5.00") == D("-5.00")),
        ("composite key", lambda: run("o,l,v\n1,1,a\n1,2,b\n", "o,l,v\n1,2,b\n1,1,a\n", keys=("o", "l"))["reconciles"]),
        ("bridge explains totals", lambda: (lambda b: D(b["unexplained"]) == 0 and b["old_total"] == "160.00" and b["new_total"] == "175.00")(
            run(O, O.replace("A3,Cy,10", "A4,Cy,20").replace("50,open", "55,open"), sum=["amount"])["bridges"][0])),
        ("bridge with duplicate", lambda: D(run(O, O + "A2,Bob,50,open,2026-09-02\n", sum=["amount"])["bridges"][0]["unexplained"]) == 0),
        ("missing key column error", lambda: _raises(lambda: run(O, O, keys=("nope",)))),
        ("empty file error", lambda: _raises(lambda: run("", O))),
        ("BOM stripped", lambda: run("\ufeff" + O, O)["reconciles"]),
        ("render has result line", lambda: "RECONCILES" in render_md(run(O, O), "a", "b", 5)),
    ]
    passed = 0
    for name, fn in cases:
        try:
            ok = bool(fn())
        except Exception as e:  # noqa: BLE001 - report in test output
            ok = False; name += f" (raised {e!r})"
        passed += ok
        print(("PASS " if ok else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def _raises(fn):
    try:
        fn()
    except InputError:
        return True
    return False


def main(argv=None):
    ap, a = parse_args(argv if argv is not None else sys.argv[1:])
    if a.self_test:
        return self_test()
    if not (a.old and a.new and a.key):
        ap.error("need OLD NEW --key (or --self-test)")
    try:
        opts = build_opts(a)
        with open(a.old, encoding="utf-8-sig", newline="") as f1, open(a.new, encoding="utf-8-sig", newline="") as f2:
            old_text, new_text = f1.read(), f2.read()
        res = reconcile(old_text, new_text, [k.strip() for k in a.key.split(",")], opts)
    except (OSError, UnicodeDecodeError, InputError, InvalidOperation) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    if a.out_csv:
        with open(a.out_csv, "w", newline="", encoding="utf-8") as fh:
            w = csv.writer(fh)
            w.writerow(["status", "key", "column", "old", "new", "delta"])
            for k in res["removed_keys"]:
                w.writerow(["removed", k, "", "", "", ""])
            for k in res["added_keys"]:
                w.writerow(["added", k, "", "", "", ""])
            for c in res["changes"]:
                w.writerow(["changed", c["key"], c["column"], c["old"], c["new"], c["delta"]])
    print(json.dumps(res, indent=2, default=str) if a.json else render_md(res, a.old, a.new, a.limit))
    return 0 if res["reconciles"] else 1


if __name__ == "__main__":
    sys.exit(main())