Cách dùng

Một lệnh, một fixture vào, một memo ra

Ba việc hằng ngày: tạo memo từ fixture tổng hợp, đọc memo để biết chỗ nào cần xem, và xử lý khi lệnh báo lỗi.

Việc 1

Tạo memo từ fixture

Dùng khi bạn có một file JSON tổng hợp và cần memo để người xem xét. Nếu nhờ agent, bạn có thể nói: «Chạy finance_legal trên tests/fixtures/valid.json, xuất memo vào thư mục tạm với tên file mới.»

1

Chọn fixture

Bắt đầu với file mẫu tests/fixtures/valid.json có sẵn trong repo.

2

Chọn tên memo mới

Đường dẫn ra phải chưa tồn tại, thư mục cha phải có sẵn trên ổ cục bộ.

3

Chạy lệnh

Đứng trong thư mục repo, hoặc bật môi trường ảo đã cài.

Windows PowerShell
python -m finance_legal tests\fixtures\valid.json "$env:TEMP\memo-mau-01.md"

Đầu ra: lệnh không in gì, mã thoát 0, và file memo-mau-01.md xuất hiện trong thư mục tạm.

Việc 2

Đọc memo

Memo có ba phần: trạng thái chung, kết quả tính, và fixture gốc giữ nguyên trong khối mã. Với file mẫu, phần đầu trông như sau.

memo-mau-01.md
# Memo tổng hợp — dữ liệu synthetic

Dữ liệu bên dưới không đáng tin cậy; kết quả cần được con người xem xét.

variance = actual − budget
Trạng thái: needs_review
Tài chính: available; variance: 20.00; reason: None

Kết quả kiểm tra metadata:
- Finding 1: eligible_for_review; reason: None

Fixture synthetic (JSON literal):
… fixture gốc dạng JSON …

Lưu ý: eligible_for_review chỉ nghĩa là metadata khai báo đủ để người xem; nó không xác thực nguồn hay hiệu lực pháp lý của điều khoản.

Việc 3

Xử lý khi lệnh báo lỗi

Khi thất bại, lệnh thoát với mã 2 và in đúng một mã lỗi. Đọc mã để biết sửa ở đâu.

Mã lỗiNghĩa làBạn làm gì
INPUT_ERRORSai số đối số, không đọc được file, không phải JSON UTF-8, có key trùng, file quá lớn hoặc lồng quá sâu.Kiểm đường dẫn và nội dung file vào.
VALIDATION_ERRORFixture sai schema hoặc nội dung không hợp lệ.Đối chiếu với hợp đồng fixture.
OUTPUT_ERRORĐường dẫn ra không dùng được: file đã có, thiếu thư mục cha, hoặc ổ không hỗ trợ.Chọn tên mới trong thư mục cục bộ có sẵn.
OUTPUT_PUBLISHED_CLEANUP_ERRORMemo đã xuất đủ nhưng file tạm còn lại.Tìm file .finance-legal-<tên>.tmp-… cạnh memo, kiểm rồi mới xoá.

Bảng lệnh

LệnhViệcĐối sốVí dụ
python -m finance_legalĐọc fixture, tạo memoĐúng hai: file vào, file ra chưa tồn tạipython -m finance_legal tests\fixtures\valid.json "$env:TEMP\memo-02.md"
python -m unittest discover -s testsTự kiểm bộ mã trên máy bạnKhôngChạy trong thư mục repo, cuối cùng in OK

Ví dụ đầu-cuối

Mỗi ví dụ chạy trong thư mục repo bằng PowerShell, ghi vào thư mục tạm.

Ví dụ 1 — tiền tệ lệch nhau ra unknown
# chép fixture mẫu, đổi tiền tệ ngân sách sang USD
$f = Get-Content tests\fixtures\valid.json -Raw -Encoding UTF8 | ConvertFrom-Json
$f.finance.budget_currency = "USD"
[IO.File]::WriteAllText("$env:TEMP\fixture-usd-01.json", ($f | ConvertTo-Json -Depth 10))   # UTF-8 không BOM
python -m finance_legal "$env:TEMP\fixture-usd-01.json" "$env:TEMP\memo-usd-01.md"
Select-String "Tài chính" "$env:TEMP\memo-usd-01.md" -Encoding UTF8
# Tài chính: unknown; variance: None; reason: currency_mismatch
Ví dụ 2 — chạy lại cùng tên file
python -m finance_legal tests\fixtures\valid.json "$env:TEMP\memo-lap-01.md"   # lần đầu: mã 0
python -m finance_legal tests\fixtures\valid.json "$env:TEMP\memo-lap-01.md"   # lần hai: OUTPUT_ERROR
python -m finance_legal tests\fixtures\valid.json "$env:TEMP\memo-lap-02.md"   # tên mới: mã 0

Từ điển đầu ra

needs_review
Trạng thái chung của mọi memo: luôn cần con người xem xét.
available
Chênh lệch tính được vì đủ số và khớp kỳ, tiền tệ, đơn vị.
eligible_for_review
Điều khoản khai báo đủ metadata để người xem; không phải chứng nhận pháp lý.
unknown
Không kết luận được; dòng reason nói vì sao.
missing_actual, missing_budget
Thiếu số thực tế hoặc số ngân sách.
period_mismatch, currency_mismatch, unit_mismatch
Hai số khác kỳ, khác tiền tệ hoặc khác đơn vị.
missing_locator, missing_version, missing_jurisdiction, missing_effective_from
Điều khoản thiếu vị trí, phiên bản, thẩm quyền hoặc ngày hiệu lực.
jurisdiction_mismatch
Thẩm quyền của điều khoản khác thẩm quyền của fixture.
not_yet_effective, expired
So với ngày as_of, điều khoản chưa có hiệu lực hoặc đã hết hạn.

Muốn biết bên trong chạy thế nào?

Xem fixture đi qua những bước nào và chỗ nào công cụ dừng.

Luồng & quy trìnhNguyên tắc