---
name: describe-entity
description: Xem chi tiết một hồ sơ theo entity_code — metadata, danh sách files, trạng thái index. Dùng khi user hỏi sâu về một record cụ thể.
---

# Describe Entity

## Khi nào dùng

- "Cho tôi chi tiết hồ sơ IB2600250575-00"
- "Hồ sơ X có bao nhiêu file?"
- "Trạng thái index của IB...-00 ?"
- "Gói này đóng thầu khi nào, ai là chủ đầu tư?"
- "File chính của hồ sơ này tên gì?"

## Workflow

1. Cần `entity_code` chính xác (mã eGP dạng `IB<digits>-<version>`, vd. `IB2600250575-00`).
   Nếu user nói mơ hồ ("hồ sơ A", "cái gói thầu hôm qua"):
   - Hỏi lại để clarify, hoặc
   - Dùng `list_entities` để tìm trước rồi xác nhận với user.
2. Gọi `describe_entity(entity_code="<mã>")`.
3. Xử lý lỗi:
   - Tool raise `entity_not_found` → thông báo user "Không tìm thấy hồ sơ <mã>", gợi ý dùng `list_entities` để xem danh sách.
4. Nếu OK: trả lời gồm:
   - **Metadata** (entity giờ giàu trường — surface cái nào liên quan câu hỏi):
     `entity_type`, `index_status`, `title` (tên gói), `investor_name` (chủ đầu tư),
     `status_code`, `public_date` (ngày đăng), `version_no` (phiên bản/sửa đổi),
     `bid_open_date` / `bid_close_date` (mở/đóng thầu — giờ VN), `created_at`/`updated_at`.
   - **Bảng files**: mỗi row có `id` (cần cho `fetch-raw-file`), `file_name`, `file_type`, `size`,
     `convert_status`, `index_status`.

## Ví dụ

**User:** "Chi tiết hồ sơ IB2600250575-00"

**Agent:**

```
→ describe_entity(entity_code="IB2600250575-00")
← {entity: {entity_type: "tbmt", title: "...", investor_name: "...",
            bid_close_date: "2026-06-12T09:00:00", version_no: "00", ...},
   files: [{id: 10, file_name: "main.pdf", file_type: "pdf", ...}, ...]}
```

**Reply:** metadata (tên gói, chủ đầu tư, đóng thầu, phiên bản) + bảng files với cột `id` để tham chiếu khi cần download.

## Đóng/mở thầu & phiên bản

- `bid_close_date`/`bid_open_date` là ISO **giờ VN (UTC+7, không có tz suffix)** → tính đang mở / sắp đóng / đã đóng theo giờ VN, không theo giờ máy chủ.
- `version_no` > `"00"` ⇒ hồ sơ đã có sửa đổi/gia hạn (notice được đăng lại). Khi user hỏi "có sửa đổi không", dùng trường này thay vì đoán.

## Anti-patterns

- ❌ Đừng đoán entity_code — phải hỏi nếu user mơ hồ.
- ❌ Đừng bịa mã kiểu `TBMT-2026-001` — mã thật là `IB<digits>-<version>`.
- ❌ Đừng tóm tắt nội dung file dựa vào file_name — đó là việc của `search_procurement_docs`.
- ❌ Đừng giấu `id` của file — agent/user cần `id` để tải file gốc qua `fetch_raw_file_url`.
- ❌ Đừng kết luận đóng/mở thầu bằng giờ máy chủ — luôn tính theo giờ VN.