Specpin bởi Lam Ngoc Khuong

Specpin gắn đặc tả nghiệp vụ (quy tắc, mô tả, tiêu chí chấp nhận) trực tiếp lên các phần tử của một giao diện web đang chạy, rồi hiển thị chúng ngay trong trình duyệt khi bạn rê chuột hoặc duyệt trang.

Specpin KHÔNG phải công cụ sinh code từ đặc tả: nó không tạo ra mã ứng dụng nào. Đây là một lớp tri thức ghim tài liệu sống, được quản lý phiên bản bằng Git, lên chính giao diện bạn đang có. Đặc tả nằm dưới dạng JSON trong thư mục .specs/ của repo và được phục vụ cho tiện ích bởi một sidecar Go cục bộ nhỏ qua localhost có xác thực token. Không có gì rời khỏi máy của bạn.

Tính năng:

• Ghim đặc tả lên phần tử sống: đối sánh vân tay đa tín hiệu bền bỉ (test-id, aria, selector, xpath, văn bản, vị trí) để đặc tả vẫn khớp sau khi refactor, giới hạn theo trang bằng URL glob.

• Độ tin cậy đối sánh và tình trạng trang: xem mỗi đặc tả khớp thế nào (anchor chính xác hay selector), rà soát các match dễ vỡ, và thêm thuộc tính data-spec-id để khớp chính xác.

• Ba chế độ hiển thị: tooltip, sidebar, và modal kéo thả được. Chuyển đổi bằng một cú nhấp hoặc Alt+Shift+M.

• Bắt thủ công (Manual capture): nhấp vào một phần tử và soạn đặc tả ngay tại chỗ, không cần rời trang. Bật/tắt chế độ bắt bằng Alt+Shift+C.

• Dự án cục bộ có thể ghi: chỉnh sửa, bắt, tạo mới, xóa và xuất đặc tả theo nhóm dạng zip, kể cả khi không có sidecar đang chạy.

• Kết nối nhiều dự án: một tiện ích phục vụ nhiều dự án cùng lúc, định tuyến tới từng trang theo origin, kèm bật/tắt riêng cho từng dự án và nhãn nguồn (sidecar hay cục bộ).

• Chế độ hướng dẫn (Guide mode): tour onboarding dựa trên đặc tả với hai phạm vi (nhóm, commit vào repo; cá nhân, theo từng origin), kèm lớp phủ spotlight và popover neo.

• Bề mặt sidebar: mở Specpin trong sidebar của Firefox với chi tiết đặc tả nội tuyến và tự động làm mới trực tiếp.

• Tìm kiếm đặc tả: lọc phía client theo tiêu đề, tệp, thẻ và mô tả.

• Nội dung đặc tả đa ngôn ngữ: chuỗi theo locale với công tắc đổi ngôn ngữ trong trình duyệt và trình soạn theo tab cho từng locale.

• Đặc tả định dạng Markdown: mô tả và quy tắc nghiệp vụ hỗ trợ một tập con Markdown an toàn (đậm, nghiêng, mã nội tuyến, liên kết, danh sách), soạn qua thanh công cụ và hiển thị trên mọi bề mặt.

• Chủ đề do người dùng chọn: Theo hệ thống / Sáng / Tối, với design token hai chủ đề.

• Giao diện ba ngôn ngữ (EN + VI + JA), độc lập với ngôn ngữ nội dung đặc tả.

An toàn theo mặc định: sidecar mặc định lắng nghe 127.0.0.1 (remote là tùy chọn qua reverse proxy HTTPS của riêng bạn), dùng xác thực bearer-token, chỉ chấp nhận CORS từ origin của tiện ích, và chống path traversal khi ghi. Mã nguồn mở. Không thu thập dữ liệu, không theo dõi, không dùng mã từ xa.