Hướng dẫn dữ liệu tổng hợp ngoại tuyến

Chỉ sử dụng dữ liệu tổng hợp. CLI đọc một giá trị JSON UTF-8 qua stdin, tối đa 65.536 byte, rồi xuất memo qua stdout; chương trình không truy cập URL hay mạng. JSON bị từ chối nếu có key trùng, nội dung thừa sau JSON ngoài khoảng trắng, UTF-8 sai, lồng quá sâu, trường lạ, tham chiếu sai hoặc số không hợp lệ. ID chỉ gồm chữ ASCII, số, dấu gạch ngang hoặc gạch dưới, tối đa 40 ký tự. Mỗi danh sách evidence và comparables có tối đa 20 phần tử.

Hai mẫu đầy đủ là tests/fixtures/apartment.json và tests/fixtures/house.json. Các trường cấp cao nhất gồm version (số nguyên 1), case, evidence, comparables, và rental (object hoặc null); fixture thể hiện các trường bắt buộc. Ngày theo YYYY-MM-DD. Loại tài sản gồm apartment và residential_house; cơ sở diện tích hợp lệ là net_usable hoặc saleable cho căn hộ, land, gross_floor hoặc net_usable cho nhà ở. Loại giá là asking_sale hoặc reported_transaction. Tiền và diện tích là chuỗi số thập phân không âm, tối đa 15 chữ số nguyên và 2 chữ số thập phân; giá và diện tích của comp cùng giá mua phải dương. vacancy_rate là chuỗi thập phân từ 0 đến 1, tối đa 4 chữ số thập phân. Không dùng dấu phẩy, số mũ, dấu cộng hoặc số 0 thừa ở đầu.

Một comp chỉ được chọn khi cùng loại tài sản, cơ sở diện tích, loại giá và có ngày không sau as_of của case. Cần ít nhất ba dòng được chọn với ba evidence ID khác nhau để hiển thị min/median/max; ID khác nhau không chứng minh nguồn độc lập, kết quả chỉ mô tả mẫu được nhập. reported_transaction là giao dịch do người nhập báo cáo, chưa được xác minh độc lập; asking_sale là giá rao, không phải giao dịch.

rental là null khi thiếu thông tin, hoặc object đầy đủ. Doanh thu thuê tiềm năng năm bằng tiền thuê tháng × 12; thất thu bằng doanh thu tiềm năng × tỷ lệ trống; NOI bằng doanh thu tiềm năng trừ thất thu và chi phí vận hành năm; cap_rate bằng NOI chia giá mua. cap_rate là tỷ lệ: 0.0480 tương đương 4,8%, không phải số 4,8 được xuất trực tiếp. Người nhập cung cấp số liệu và giả định; chương trình không tự suy nợ, chi phí đầu tư, thuế, giá bán hoặc tình trạng pháp lý.

Text tự do được trung hòa để hiển thị theo CommonMark/GFM; người chạy chịu trách nhiệm giữ input gốc. Tình trạng pháp lý luôn là unknown. Cùng input cho cùng đầu ra: thành công mã 0, dữ liệu sai mã 2 (invalid_input trên stderr), lỗi stream mã 1 (io_error trên stderr). Khi ghi stdout lỗi, một phần memo có thể đã được xuất.

Có thể lưu fixture và memo tổng hợp trong một thư mục làm việc riêng, ngoài repo. Chương trình không tự mở hay ghi vào thư mục này; người chạy tự quyết định nguồn stdin, nơi chuyển hướng stdout và quyền riêng tư.

Để chạy test khi máy đã có pytest và pytest-cov, đặt PYTHONPATH trỏ tới thư mục src của repo và chạy python -m pytest -q --cov=agent_real_estate --cov-report=term-missing --cov-fail-under=80. Runtime chỉ dùng thư viện chuẩn Python; test và đóng gói cần công cụ phát triển đã có. Hướng dẫn này không thay cho bằng chứng test hoặc build thực tế. Hướng dẫn viết cho Windows; các phiên bản Python 3.11+ và hệ điều hành khác chưa được xác nhận đầy đủ.