GitLab Time Tracker FTL

Extension giúp ghi nhận hoạt động làm việc trong editor (file đang mở, nhánh Git, v.v.) và gửi định kỳ lên Time Tracker API của dự án GitLab Time Tracker FTL — phục vụ pipeline time tracking và đồng bộ GitLab sau này. Dữ liệu được gửi qua HTTPS kèm API Key của bạn.

Trước khi bắt đầu

Bạn cần có tài khoản dùng web app Time Tracker và tạo API Key trong trang Cài đặt (mỗi môi trường dev/prod một key khác nhau — dùng đúng key với đúng URL backend).
URL backend phải trùng origin với trang web bạn đăng nhập (ví dụ môi trường dev thường là host dev, không dùng localhost nếu bạn chỉ làm việc trên bản deployed).

Cài đặt

Cách 1 — Trong IDE: mở Extensions (Ctrl+Shift+X / Cmd+Shift+X), tìm GitLab Time Tracker FTL, nhấn Install.

Cách 2 — Dòng lệnh (CLI của IDE đã có trong PATH, ví dụ code, cursor, …):

<code|cursor|codium|...> --install-extension timetracker-ftl.timetracker-vscode-extension

(Thay code|cursor|... bằng lệnh tương ứng với IDE bạn đang dùng.)

Hướng dẫn sử dụng (từng bước)

1. Cấu hình địa chỉ API (`timetracker.apiUrl`)

File → Preferences → Settings (hoặc Ctrl+, / Cmd+,).
Tìm Time Tracker hoặc nhập timetracker.apiUrl.
Nhập chỉ phần origin của backend, ví dụ https://timetracker-dev.ftl.vn hoặc http://localhost:4000.
- Không thêm /api ở cuối. Extension sẽ tự nối đường dẫn API; nếu bạn nhập nhầm đuôi /api, extension có thể tự chỉnh để tránh lỗi 404.

2. API Key (`timetracker.apiKey`)

Copy API Key từ web app (Cài đặt → API Key).
Trong IDE: Ctrl+Shift+P / Cmd+Shift+P → chọn Time Tracking: Set API Key → dán key → Enter.

Key được lưu trong cấu hình của extension; chỉ nhập lại khi đổi môi trường hoặc tạo key mới.

3. Kiểm tra kết nối (khuyến nghị)

Command Palette → Time Tracking: Test API Connection.

Kiểm tra xem máy của bạn tới được server không (HTTP GET /api/health, không cần API key — chỉ để ping URL đúng).
Nếu lỗi: kiểm tra VPN/firewall, URL có đúng https/port, và backend có đang chạy.

4. Bật gửi dữ liệu

Time Tracking: Toggle — bật/tắt gửi ping định kỳ lên backend.

Khi tracking đang chạy, thanh trạng thái (status bar, góc dưới) hiển thị dạng Time Tracking: Active — nhấn vào có thể bật/tắt nhanh như Toggle.

Lưu ý: Theo mặc định có thể phải bật Toggle sau khi cài đặt và nhập đủ URL + API key — mặc không gửi gì để tránh nhầm môi trường.

5. Chu kỳ ping (`timetracker.pingInterval`)

Trong Settings, chỉnh chu kỳ (giây) trong khoảng 30–600:

Giá trị nhỏ → cập nhật thường xuyên hơn, nhiều request hơn.
Giá trị lớn → ít ping hơn, độ chi tiết theo thời gian thưa hơn.

Đổi chỉ có hiệu lực theo nhịp chu kỳ tiếp theo (không nhất thiết cần reload window).

6. Xem log khi có sự cố

Time Tracking: Show Log hoặc View → Output → chọn kênh Time Tracker.

Bạn sẽ thấy log ping (thành công/thất bại), trạng thái idle, và thông báo lỗi mạng hoặc 401 (thiếu/sai API key).

Cấu hình chi tiết (Settings)

Cài đặt	Ý nghĩa
`timetracker.apiUrl`	Origin của Time Tracker API (không có `/api` cuối). VD: `http://localhost:4000`, hoặc host dev/prod bạn đang dùng.
`timetracker.apiKey`	API key cá nhân tạo trên web app; dùng kèm header khi extension gửi activity.
`timetracker.enabled`	Bật/tắt tracking; đồng bộ với lệnh Toggle và (tùy bản IDE) có thể phản chiếu lên UI.
`timetracker.pingInterval`	Khoảng giữa các lần gửi dữ liệu (giây), từ 30 đến 600.

Có thể chỉnh trực tiếp trong Settings UI hoặc trong settings.json (chuỗi key timetracker.*).

Lệnh (Command Palette — `Ctrl+Shift+P`)

Lệnh	Việc làm
Time Tracking: Toggle	Bật/tắt gửi ping định kỳ hoạt động hiện tại lên API.
Time Tracking: Set API Key	Nhập và lưu API key vào cấu hình.
Time Tracking: Show Log	Mở kênh Output Time Tracker để đọc log.
Time Tracking: Test API Connection	Gọi `GET /api/health` để kiểm tra URL và server có phản hồi không.

Mẹo ngắn

Dev và prod có API URL + API key khác nhau: đổi workspace hoặc profile Settings nếu bạn làm song song hai môi trường.
Lỗi 401: thường là thiếu key, key hết hạn bị revoke, hoặc key không thuộc đúng môi trường và URL đang nhập.

GitLab Time Tracker FTL