Cấu trúc thư mục chuẩn cho dự án script NX Open: lib, scripts, tests, config và README

Script rải rác trong máy mỗi người là nguồn rắc rối khi công ty lớn lên. Một cấu trúc thư mục thống nhất giúp dễ tìm, dễ test, dễ triển khai và dễ giao việc bảo trì cho người khác.

Cấu trúc thư mục chuẩn cho dự án script NX…

Các bước thực hiện

1. Tách thư viện và script. lib chứa hàm dùng chung, scripts chỉ là điểm vào mỏng.
2. Tách cấu hình. config chứa file JSON; không viết cứng trong code.
3. Có thư mục test. tests chạy được ngoài NX cho phần logic.
4. Có tài liệu. README hướng dẫn cài đặt và chạy; CHANGELOG ghi thay đổi.
5. Quản lý phiên bản. Dùng Git, gắn tag cho mỗi bản phát hành.

Cấu trúc thư mục đề xuất

nxlab-tools/
├── README.md                  # cài đặt, cách chạy, liên hệ
├── CHANGELOG.md               # lịch sử thay đổi theo phiên bản
├── VERSION                    # một dòng: 1.3.0
├── config/
│   ├── mac_dinh.json          # giá trị mặc định cho mọi người
│   └── cong_ty.json           # quy tắc riêng của công ty (đặt tên, vật liệu)
├── lib/
│   ├── __init__.py
│   ├── nxlab_core.py          # logger, đọc cấu hình, kiểm tra part
│   ├── hinh_hoc.py            # hàm toán hình học thuần (test được ngoài NX)
│   └── xuat_file.py           # bọc API xuất STEP, PDF, DXF
├── scripts/                   # điểm vào: mỗi file là một nút lệnh
│   ├── kiem_tra_chi_tiet.py
│   ├── xuat_step.py
│   └── dong_goi_giao_hang.py
├── tests/
│   ├── test_hinh_hoc.py       # unittest cho phần thuần Python
│   └── test_trong_nx.py       # chạy trong NX bằng part mẫu
├── mau/                       # part mẫu dùng cho test hồi quy
└── NXCustom/
    └── startup/nxlab.men      # menu NX Lab

Giải thích code

• Quy tắc quan trọng nhất: mọi logic nằm trong lib, scripts chỉ đọc cấu hình, gọi hàm và báo kết quả.
• File VERSION là nguồn duy nhất cho số phiên bản; script đọc nó để hiện trong menu Trợ giúp.
• Part mẫu trong mau/ là dữ liệu kiểm thử cố định, đảm bảo kết quả đối chiếu được giữa các lần chạy.

Lỗi thường gặp

• Đừng bỏ file cấu hình có mật khẩu hay đường dẫn riêng tư vào kho Git chung.
• Đặt tên module trùng thư viện chuẩn (ví dụ random.py, json.py) trong lib sẽ che mất thư viện thật.

Code mang tính tham khảo, viết cho NX 12 trở lên (Python journal). Tên menu và một số lớp có thể khác theo phiên bản NX; hãy chạy thử trên bản sao của chi tiết trước khi dùng cho dữ liệu thật.