Upload 9 files

prompts.py

@@ -109,6 +109,23 @@ Trả về JSON THUẦN TÚY, không có markdown fence, không có chú thích:
   "memory_summary": "nội dung memory có cấu trúc như trên"
 }"""
 
+DOC_QA_COMPACT_PROMPT = """Bạn là bộ nhớ dài hạn riêng cho chế độ QA tài liệu của Team Chat.
+
+Mục tiêu:
+- Giữ các kết luận ổn định đã được xác nhận từ tài liệu.
+- Giữ document/section/node quan trọng, thuật ngữ đặc thù, giả định còn dang dở và câu hỏi tiếp theo.
+- Không lưu lời chào, lặp ý, hoặc chi tiết không ảnh hưởng đến câu trả lời sau.
+
+Quy tắc:
+- Chỉ giữ thông tin thật sự có ích cho các lượt QA sau.
+- Nếu có xung đột, ưu tiên bằng chứng mới hơn và ghi rõ phần chưa chắc chắn.
+- Không bịa thêm dữ kiện ngoài tài liệu và câu trả lời hiện tại.
+
+Đầu ra JSON thuần:
+{
+  "memory_summary": "..."
+}"""
+
 VOICE_COMPACT_PROMPT = """Bạn là chuyên gia compact cho hội thoại giọng nói (voice chat) của Nomus AI.
 
 Mục tiêu:
@@ -153,17 +170,24 @@ Mục tiêu:
 - Ưu tiên đọc đúng các tin nhắn user đã chọn thay vì đọc toàn bộ lịch sử.
 - Có thể phân tích bug, blocker, requirement, kế hoạch, task và trạng thái dự án.
 - Có thể đọc document theo cấu trúc cây (hierarchical index) và điều hướng theo từng nhánh.
+- Có khả năng trả lời câu hỏi dựa trên tài liệu (document-grounded QA) giống phong cách NotebookLM: bám bằng chứng, trích dẫn rõ nguồn, không bịa.
 - Khi đủ dữ liệu, hãy đề xuất hoặc thực thi action phù hợp thay vì chỉ trả lời chung chung.
 
 Các action được hỗ trợ:
 - create_issue: tạo issue mới cho project.
 - update_issue: cập nhật issue hiện có theo issue_id hoặc issue_anchor_id.
 - create_task: tạo task lịch khi có mốc thời gian cụ thể.
+- Khi tạo issue/task, luôn cố gắng gắn chúng vào một node requirement phù hợp.
 
 Quy tắc quan trọng:
 - Nếu không có @bot và require_bot_mention=true: không tạo action, chỉ nhắc user gọi bằng @bot.
 - Khi có selected_messages thì chỉ dùng selected_messages làm nguồn chat chính.
 - Nếu có documents_index, hãy điều hướng cây theo từng bước để chọn section phù hợp với câu hỏi.
+- Khi câu hỏi thiên về giải thích/tóm tắt/so sánh nội dung tài liệu: ưu tiên trả lời dựa trên documents_sections + document_grounded_answer và để actions = [].
+- Khi tạo work item, ưu tiên dùng requirement_node_reference làm node cha, và nêu rõ node_path trong reply.
+- Khi ở chế độ QA docs, ưu tiên bám vào document_grounded_answer, citations và doc_qa_memory; không quên ngữ cảnh tài liệu đã được xác nhận ở các lượt trước.
+- Nếu thiếu node requirement hợp lệ cho action, hãy hỏi user chọn node thay vì tự đoán.
+- Khi thiếu bằng chứng từ tài liệu, nói rõ phần nào chưa có dữ liệu thay vì suy đoán.
 - Nếu thiếu dữ liệu quan trọng, hỏi đúng 1-2 câu ngắn để chốt, không tự bịa.
 - Nếu user chỉ muốn tư vấn hoặc thảo luận, không cần action thì không tạo tool.
 - Nếu user yêu cầu làm luôn và đủ thông tin, có thể trả về nhiều action trong một lượt.
@@ -177,10 +201,19 @@ Schema mong muốn:
   "reply": "nội dung trả lời ngắn gọn cho user",
   "needs_confirmation": false,
   "missing_fields": ["..."],
+  "citations": [{"document_id": "...", "section_id": "..."}],
   "actions": [
     {
       "type": "create_issue|update_issue|create_task",
       "payload": {
+        "requirement_node_id": "...",
+        "requirement_node_title": "...",
+        "requirement_node_path": "...",
+        "requirement_node_path_titles": ["..."],
+        "requirement_node_path_ids": ["..."],
+        "requirement_node_depth": 0,
+        "requirement_document_id": "...",
+        "requirement_document_name": "...",
         "...": "..."
       }
     }

routes_team_chat.py

@@ -8,8 +8,13 @@ from core import TEAM_AGENT_MODEL, projects_collection, team_chat_collection, te
 from prompts import TEAM_AGENT_SYSTEM_PROMPT
 from schemas import TeamChatRequest
 from services import (
+    build_document_grounded_answer,
+    build_requirement_node_options_from_documents,
+    compact_team_doc_qa_memory,
     create_issue_for_project,
     create_task_from_agent,
+    get_team_doc_qa_memory,
+    resolve_requirement_node_reference_from_documents,
     get_selected_team_messages,
     get_team_agent_context,
     get_team_chat_context,
@@ -21,6 +26,7 @@ from services import (
     run_team_agent_with_nvidia,
     save_team_chat_message,
     save_team_document,
+    store_uploaded_image,
     unique_ids,
     update_issue_from_agent,
 )
@@ -28,6 +34,23 @@ from services import (
 router = APIRouter()
 
 
+def _looks_like_action_request(message: str) -> bool:
+    text = (message or "").lower()
+    action_patterns = [
+        r"\btạo\b",
+        r"\bcreate\b",
+        r"\bcập nhật\b",
+        r"\bupdate\b",
+        r"\bassign\b",
+        r"\bgiao\b",
+        r"\bthực thi\b",
+        r"\blàm luôn\b",
+        r"\bissue\b",
+        r"\btask\b",
+    ]
+    return any(re.search(pattern, text) for pattern in action_patterns)
+
+
 def _extract_json_payload(raw_text: str) -> Optional[Dict[str, Any]]:
     if not raw_text:
         return None
@@ -103,6 +126,29 @@ def _execute_agent_action(action: Dict[str, Any], user_id: str, req: TeamChatReq
     raise HTTPException(status_code=400, detail=f"Unsupported action: {action_type}")
 
 
+def _merge_requirement_node_reference(payload: Dict[str, Any], node_ref: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(node_ref, dict) or not node_ref:
+        return payload
+
+    merged = dict(payload)
+    merged.setdefault("requirement_node_id", node_ref.get("node_id") or node_ref.get("section_id"))
+    merged.setdefault("requirement_node_title", node_ref.get("node_title") or node_ref.get("section_title"))
+    merged.setdefault("requirement_node_path", node_ref.get("node_path"))
+    merged.setdefault("requirement_node_path_titles", node_ref.get("node_path_titles", []))
+    merged.setdefault("requirement_node_path_ids", node_ref.get("node_path_ids", []))
+    merged.setdefault("requirement_node_depth", node_ref.get("node_depth"))
+    merged.setdefault("requirement_document_id", node_ref.get("document_id"))
+    merged.setdefault("requirement_document_name", node_ref.get("document_name"))
+    return merged
+
+
+def _has_requirement_node_payload(payload: Dict[str, Any]) -> bool:
+    return any(
+        str(payload.get(field_name) or "").strip()
+        for field_name in ("requirement_node_id", "requirement_node_title", "requirement_node_path")
+    )
+
+
 def _assert_team_project_access(user: Dict[str, Any], team_id: str, project_id: Optional[str]) -> Optional[Dict[str, Any]]:
     team = teams_collection.find_one({"id": team_id}, {"_id": 0})
     if not team or user["id"] not in unique_ids([team.get("owner_id", "")], team.get("member_ids", [])):
@@ -173,12 +219,54 @@ async def upload_team_document(
     }
 
 
+@router.post("/teams/{team_id}/chat/images")
+async def upload_team_chat_images(
+    team_id: str,
+    files: List[UploadFile] = File(...),
+    project_id: Optional[str] = Form(None),
+    x_session_token: Optional[str] = Header(None, alias="X-Session-Token"),
+):
+    user = require_session_user(x_session_token)
+    _assert_team_project_access(user, team_id, project_id)
+
+    if not files:
+        raise HTTPException(status_code=400, detail="No image files provided")
+
+    scope_id = team_id if not project_id else f"{team_id}__{project_id}"
+    assets: List[Dict[str, Any]] = []
+    for file in files:
+        raw_bytes = await file.read()
+        if not raw_bytes:
+            continue
+        asset = store_uploaded_image(
+            raw_bytes=raw_bytes,
+            original_name=file.filename or "image",
+            scope="team",
+            scope_id=scope_id,
+        )
+        assets.append(asset)
+
+    if not assets:
+        raise HTTPException(status_code=400, detail="All uploaded files were empty")
+
+    return {
+        "assets": assets,
+        "urls": [asset["url"] for asset in assets],
+    }
+
+
 @router.post("/teams/chat")
 async def team_chat(req: TeamChatRequest, x_session_token: Optional[str] = Header(None, alias="X-Session-Token")):
     user = require_session_user(x_session_token)
     project = _assert_team_project_access(user, req.team_id, req.project_id)
 
-    user_msg = save_team_chat_message(req.team_id, "user", req.message, req.project_id)
+    user_msg = save_team_chat_message(
+        req.team_id,
+        "user",
+        req.message,
+        req.project_id,
+        attachment_urls=req.attachment_urls,
+    )
 
     has_bot_mention = "@bot" in (req.message or "")
     if req.require_bot_mention and not has_bot_mention:
@@ -212,7 +300,16 @@ async def team_chat(req: TeamChatRequest, x_session_token: Optional[str] = Heade
     base_messages = selected_messages or fallback_messages
 
     team_docs = get_team_documents_by_ids(req.team_id, req.document_ids, req.project_id)
-    doc_context = retrieve_document_context_with_tree(req.message, team_docs)
+    doc_context = retrieve_document_context_with_tree(
+        req.message,
+        team_docs,
+        selected_messages=base_messages,
+    )
+    preferred_requirement_node_reference = resolve_requirement_node_reference_from_documents(
+        team_docs,
+        req.preferred_requirement_node_id,
+    )
+    qa_memory = get_team_doc_qa_memory(req.team_id, req.project_id)
 
     doc_indexes = []
     for doc in team_docs:
@@ -244,16 +341,20 @@ OUTPUT REQUIREMENTS:
 - Trường actions là danh sách action có thể thực thi.
 - Nếu thiếu thông tin, đặt actions = [] và missing_fields ghi rõ thiếu gì.
 - Nếu user chưa cho phép tự động hóa, needs_confirmation = true khi có action cần làm.
+- Nếu câu hỏi thiên về tra cứu tài liệu, ưu tiên trả lời dựa trên documents_sections/document_grounded_answer và có thể để actions = [].
+- Nếu doc_qa_only=true thì bắt buộc actions = [] và chỉ tập trung trả lời theo tài liệu.
+- Nếu thiếu requirement node hợp lệ cho create_issue hoặc create_task, hãy để missing_fields có requirement_node_id thay vì tự đoán.
 
 ACTION PAYLOAD GỢI Ý:
-- create_issue: title, description, severity, status, assignee_id|assignee_email|assignee_name, tags, requirement_text, attachment_urls
-- update_issue: issue_id, title, description, severity, status, assignee_id|assignee_email|assignee_name, tags, attachment_urls, requirement_text
-- create_task: title, description, start_time, end_time, priority, tags, reminder
+- create_issue: title, description, severity, status, assignee_id|assignee_email|assignee_name, tags, requirement_text, attachment_urls, requirement_node_id, requirement_node_title, requirement_node_path, requirement_node_path_titles, requirement_node_path_ids, requirement_node_depth, requirement_document_id, requirement_document_name
+- update_issue: issue_id, title, description, severity, status, assignee_id|assignee_email|assignee_name, tags, attachment_urls, requirement_text, requirement_node_id, requirement_node_title, requirement_node_path, requirement_node_path_titles, requirement_node_path_ids, requirement_node_depth, requirement_document_id, requirement_document_name
+- create_task: title, description, start_time, end_time, priority, tags, reminder, requirement_node_id, requirement_node_title, requirement_node_path, requirement_node_path_titles, requirement_node_path_ids, requirement_node_depth, requirement_document_id, requirement_document_name
 
 LƯU Ý CONTEXT:
 - selected_messages là nguồn hội thoại chính, ưu tiên tuyệt đối.
 - Nếu selected_messages rỗng thì mới dùng fallback_messages gần nhất.
 - documents_index là cây tài liệu; documents_sections là các section đã drill-down và lấy nguyên văn.
+- document_grounded_answer là bản nháp trả lời đã bám evidence; có thể tái sử dụng và tinh chỉnh.
 
 OUTPUT SHAPE:
 {
@@ -265,6 +366,42 @@ OUTPUT SHAPE:
 }
 """
 
+    doc_context_for_answer = dict(doc_context)
+    doc_sections = list(doc_context.get("sections", []))
+    if preferred_requirement_node_reference:
+        preferred_node_id = str(preferred_requirement_node_reference.get("node_id") or "").strip()
+        preferred_section_id = str(preferred_requirement_node_reference.get("node_id") or "").strip()
+        preferred_match = None
+        for section in doc_sections:
+            section_id = str(section.get("section_id") or "").strip()
+            if section_id == preferred_section_id or section_id == preferred_node_id:
+                preferred_match = section
+                break
+        if preferred_match:
+            doc_sections = [preferred_match] + [section for section in doc_sections if section is not preferred_match]
+            doc_context_for_answer["sections"] = doc_sections
+            doc_context_for_answer["citations"] = [
+                citation for citation in doc_context.get("citations", []) if str(citation.get("section_id") or "").strip() != preferred_section_id
+            ]
+            doc_context_for_answer["citations"].insert(0, {
+                "document_id": preferred_match.get("document_id"),
+                "document_name": preferred_match.get("document_name"),
+                "section_id": preferred_match.get("section_id"),
+                "section_title": preferred_match.get("section_title"),
+                "section_path": preferred_match.get("section_path"),
+                "section_path_titles": preferred_match.get("section_path_titles", []),
+                "section_path_ids": preferred_match.get("section_path_ids", []),
+                "source": "preferred_node",
+            })
+
+    document_grounded = build_document_grounded_answer(
+        query=req.message,
+        selected_messages=base_messages,
+        doc_context=doc_context_for_answer,
+        qa_memory=qa_memory,
+    )
+    requirement_node_reference = preferred_requirement_node_reference or document_grounded.get("requirement_node_reference") or doc_context.get("requirement_node_reference") or {}
+
     prompt_context = {
         "current_user": {"id": user["id"], "name": user.get("name"), "email": user.get("email")},
         "team_id": req.team_id,
@@ -276,8 +413,17 @@ OUTPUT SHAPE:
         "documents_index": doc_indexes,
         "documents_sections": doc_context.get("sections", []),
         "documents_citations": doc_context.get("citations", []),
+        "documents_retrieval_meta": doc_context.get("retrieval_meta", {}),
+        "document_grounded_answer": document_grounded.get("answer", ""),
+        "document_grounded_citations": document_grounded.get("citations", []),
+        "document_grounded_confidence": document_grounded.get("confidence", "medium"),
+        "doc_qa_memory": qa_memory,
+        "requirement_node_reference": requirement_node_reference,
+        "preferred_requirement_node_reference": preferred_requirement_node_reference,
         "new_message": req.message,
+        "new_message_attachments": req.attachment_urls,
         "allow_auto_tool_call": req.allow_auto_tool_call,
+        "doc_qa_only": req.doc_qa_only,
         "current_time": get_vn_now().isoformat(),
         "agent_context": get_team_agent_context(req.team_id, req.project_id, req.issue_anchor_id, window=2),
     }
@@ -295,12 +441,81 @@ OUTPUT SHAPE:
     missing_fields = parsed.get("missing_fields") if isinstance(parsed.get("missing_fields"), list) else []
     needs_confirmation = bool(parsed.get("needs_confirmation"))
 
+    # Doc QA mode: for non-action prompts, prioritize grounded answer from document evidence.
+    should_force_doc_qa = req.doc_qa_only or not _looks_like_action_request(req.message)
+    if document_grounded.get("answer") and should_force_doc_qa:
+        reply_text = str(document_grounded.get("answer") or reply_text).strip()
+        actions = []
+        missing_fields = []
+        needs_confirmation = False
+
+    if should_force_doc_qa:
+        try:
+            qa_memory_result = await compact_team_doc_qa_memory(
+                req.team_id,
+                req.project_id,
+                req.message,
+                str(document_grounded.get("answer") or ""),
+                doc_context_for_answer,
+                base_messages,
+                citations=document_grounded.get("citations", []),
+            )
+            qa_memory = str(qa_memory_result.get("memory_summary") or qa_memory or "").strip()
+        except Exception:
+            pass
+
+    grounded_confidence = str(document_grounded.get("confidence") or "medium").strip().lower()
+    grounded_needs_clarification = bool(document_grounded.get("needs_clarification"))
+    if should_force_doc_qa and (grounded_confidence == "low" or grounded_needs_clarification):
+        followup = str(document_grounded.get("clarifying_question") or "").strip()
+        if followup:
+            reply_text = f"{reply_text}\n\n{followup}".strip()
+        actions = []
+        missing_fields = []
+        needs_confirmation = False
+
+    if req.doc_qa_only:
+        actions = []
+        missing_fields = []
+        needs_confirmation = False
+
     tool_results: List[Dict[str, Any]] = []
     execution_errors: List[str] = []
+    node_selection_options = build_requirement_node_options_from_documents(team_docs, limit=8)
+    node_confirmation_required = False
+    if actions:
+        for action in actions:
+            if action.get("type") not in {"create_issue", "create_task"}:
+                continue
+            merged_preview = _merge_requirement_node_reference(
+                dict(action.get("payload") or {}),
+                requirement_node_reference if isinstance(requirement_node_reference, dict) else {},
+            )
+            if not _has_requirement_node_payload(merged_preview):
+                node_confirmation_required = True
+                needs_confirmation = True
+                missing_fields = list({*missing_fields, "requirement_node_id"})
+                break
     if req.allow_auto_tool_call and actions:
         for action in actions:
             try:
-                tool_results.append(_execute_agent_action(action, user["id"], req))
+                enriched_action = dict(action)
+                enriched_action["payload"] = _merge_requirement_node_reference(
+                    dict(action.get("payload") or {}),
+                    requirement_node_reference if isinstance(requirement_node_reference, dict) else {},
+                )
+                if action.get("type") in {"create_issue", "create_task"} and node_confirmation_required and not _has_requirement_node_payload(enriched_action["payload"]):
+                    needs_confirmation = True
+                    tool_results.append(
+                        {
+                            "type": action.get("type"),
+                            "status": "needs_confirmation",
+                            "error": "missing_requirement_node",
+                            "node_selection_options": node_selection_options,
+                        }
+                    )
+                    continue
+                tool_results.append(_execute_agent_action(enriched_action, user["id"], req))
             except HTTPException as exc:
                 action_type = str(action.get("type") or "unknown")
                 execution_errors.append(f"{action_type}: {exc.detail}")
@@ -314,6 +529,35 @@ OUTPUT SHAPE:
     if needs_confirmation and not assistant_text.endswith("?"):
         assistant_text = f"{assistant_text} Bạn có muốn mình tự xử lý luôn không?".strip()
 
+    if not actions and isinstance(document_grounded.get("citations"), list) and document_grounded.get("citations"):
+        section_lookup: Dict[str, Dict[str, str]] = {}
+        for sec in doc_context.get("sections", []):
+            sec_id = str(sec.get("section_id") or "").strip()
+            if not sec_id:
+                continue
+            section_lookup[sec_id] = {
+                "document_name": str(sec.get("document_name") or "Tài liệu"),
+                "section_title": str(sec.get("section_title") or sec_id),
+            }
+
+        source_refs: List[str] = []
+        for item in document_grounded.get("citations", [])[:3]:
+            section_id = str(item.get("section_id") or "").strip()
+            if not section_id:
+                continue
+            lookup = section_lookup.get(section_id)
+            if lookup:
+                source_refs.append(f"{lookup['document_name']} > {lookup['section_title']}")
+            else:
+                source_refs.append(f"Section {section_id}")
+        if source_refs:
+            assistant_text = f"{assistant_text}\n\nNguồn tham chiếu: {', '.join(source_refs)}"
+
+    if requirement_node_reference and not actions:
+        node_display = str(requirement_node_reference.get("node_display") or "").strip()
+        if node_display:
+            assistant_text = f"{assistant_text}\n\nNode đề xuất: {node_display}".strip()
+
     if tool_results:
         summary_bits = []
         for item in tool_results:
@@ -327,9 +571,16 @@ OUTPUT SHAPE:
                 summary_bits.append(f"đã tạo task {item['task'].get('title', '')}".strip())
         if summary_bits:
             assistant_text = f"{assistant_text}\n\nKết quả: {', '.join(summary_bits)}."
+        if requirement_node_reference:
+            node_display = str(requirement_node_reference.get("node_display") or "").strip()
+            if node_display:
+                assistant_text = f"{assistant_text}\nNode: {node_display}".strip()
     if execution_errors:
         assistant_text = f"{assistant_text}\n\nMột số action chưa xử lý được: {', '.join(execution_errors)}."
 
+    if needs_confirmation and node_selection_options:
+        assistant_text = f"{assistant_text}\n\nMình cần bạn chọn requirement node trước khi tạo issue/task.".strip()
+
     assistant_doc = save_team_chat_message(req.team_id, "assistant", assistant_text, req.project_id)
 
     return {
@@ -344,6 +595,15 @@ OUTPUT SHAPE:
         "selected_message_count": len(selected_messages),
         "document_section_count": len(doc_context.get("sections", [])),
         "document_citations": doc_context.get("citations", []),
+        "document_retrieval_meta": doc_context.get("retrieval_meta", {}),
+        "document_grounded": document_grounded,
+        "document_grounded_confidence": document_grounded.get("confidence", "medium"),
+        "document_grounded_confidence_score": document_grounded.get("confidence_score", 0.0),
+        "requirement_node_reference": requirement_node_reference,
+        "node_selection_required": bool(node_confirmation_required),
+        "node_selection_options": node_selection_options if node_confirmation_required else [],
+        "node_selection_reason": "missing_requirement_node" if node_confirmation_required else None,
+        "doc_qa_only": req.doc_qa_only,
         "used_bot_mention": has_bot_mention,
         "agent_model": TEAM_AGENT_MODEL,
         "timestamp": get_vn_now().isoformat(),

routes_workspace.py

@@ -209,6 +209,14 @@ async def create_project_issue(project_id: str, req: IssueCreateRequest, x_sessi
         "assignee_id": req.assignee_id,
         "tags": req.tags,
         "requirement_text": req.requirement_text,
+        "requirement_node_id": req.requirement_node_id,
+        "requirement_node_title": req.requirement_node_title,
+        "requirement_node_path": req.requirement_node_path,
+        "requirement_node_path_titles": req.requirement_node_path_titles,
+        "requirement_node_path_ids": req.requirement_node_path_ids,
+        "requirement_node_depth": req.requirement_node_depth,
+        "requirement_document_id": req.requirement_document_id,
+        "requirement_document_name": req.requirement_document_name,
         "attachment_urls": req.attachment_urls,
         "reporter_id": user["id"],
         "created_at": get_vn_now().isoformat(),
@@ -229,10 +237,14 @@ async def update_project_issue(issue_id: str, req: IssueUpdateRequest, x_session
         raise HTTPException(status_code=404, detail="Project not found")
 
     update_data: Dict[str, Any] = {"updated_at": get_vn_now().isoformat()}
-    for field_name in ["title", "description", "severity", "status", "assignee_id", "tags", "attachment_urls"]:
+    for field_name in ["title", "description", "severity", "status", "assignee_id", "tags", "attachment_urls", "requirement_node_id", "requirement_node_title", "requirement_node_path", "requirement_node_depth", "requirement_document_id", "requirement_document_name"]:
         value = getattr(req, field_name)
         if value is not None:
             update_data[field_name] = value if not isinstance(value, str) else value.strip()
+    if req.requirement_node_path_titles is not None:
+        update_data["requirement_node_path_titles"] = req.requirement_node_path_titles
+    if req.requirement_node_path_ids is not None:
+        update_data["requirement_node_path_ids"] = req.requirement_node_path_ids
     issues_collection.update_one({"id": issue_id}, {"$set": update_data})
     return {"message": "Issue updated"}
 

schemas.py

@@ -16,6 +16,14 @@ class ManualTaskRequest(BaseModel):
     priority: str = "medium"
     tags: List[str] = []
     reminder: Optional[str] = None
+    requirement_node_id: Optional[str] = None
+    requirement_node_title: Optional[str] = None
+    requirement_node_path: Optional[str] = None
+    requirement_node_path_titles: List[str] = Field(default_factory=list)
+    requirement_node_path_ids: List[str] = Field(default_factory=list)
+    requirement_node_depth: Optional[int] = None
+    requirement_document_id: Optional[str] = None
+    requirement_document_name: Optional[str] = None
 
 
 class TTSRequest(BaseModel):
@@ -67,6 +75,14 @@ class IssueCreateRequest(BaseModel):
     assignee_id: Optional[str] = None
     tags: List[str] = Field(default_factory=list)
     requirement_text: Optional[str] = None
+    requirement_node_id: Optional[str] = None
+    requirement_node_title: Optional[str] = None
+    requirement_node_path: Optional[str] = None
+    requirement_node_path_titles: List[str] = Field(default_factory=list)
+    requirement_node_path_ids: List[str] = Field(default_factory=list)
+    requirement_node_depth: Optional[int] = None
+    requirement_document_id: Optional[str] = None
+    requirement_document_name: Optional[str] = None
     attachment_urls: List[str] = Field(default_factory=list)
 
 
@@ -78,6 +94,14 @@ class IssueUpdateRequest(BaseModel):
     assignee_id: Optional[str] = None
     tags: Optional[List[str]] = None
     attachment_urls: Optional[List[str]] = None
+    requirement_node_id: Optional[str] = None
+    requirement_node_title: Optional[str] = None
+    requirement_node_path: Optional[str] = None
+    requirement_node_path_titles: Optional[List[str]] = None
+    requirement_node_path_ids: Optional[List[str]] = None
+    requirement_node_depth: Optional[int] = None
+    requirement_document_id: Optional[str] = None
+    requirement_document_name: Optional[str] = None
 
 
 class ProjectSuggestRequest(BaseModel):
@@ -90,8 +114,11 @@ class TeamChatRequest(BaseModel):
     message: str
     issue_anchor_id: Optional[str] = None
     allow_auto_tool_call: bool = False
+    doc_qa_only: bool = False
+    preferred_requirement_node_id: Optional[str] = None
     selected_message_ids: List[str] = Field(default_factory=list)
     document_ids: List[str] = Field(default_factory=list)
+    attachment_urls: List[str] = Field(default_factory=list)
     require_bot_mention: bool = True
 
 
@@ -102,6 +129,14 @@ class TeamChatToolCreateIssue(BaseModel):
     status: str = "open"
     assignee_id: Optional[str] = None
     tags: List[str] = Field(default_factory=list)
+    requirement_node_id: Optional[str] = None
+    requirement_node_title: Optional[str] = None
+    requirement_node_path: Optional[str] = None
+    requirement_node_path_titles: List[str] = Field(default_factory=list)
+    requirement_node_path_ids: List[str] = Field(default_factory=list)
+    requirement_node_depth: Optional[int] = None
+    requirement_document_id: Optional[str] = None
+    requirement_document_name: Optional[str] = None
 
 
 class TeamChatToolCreateTask(BaseModel):
@@ -112,3 +147,11 @@ class TeamChatToolCreateTask(BaseModel):
     priority: str = "medium"
     tags: List[str] = Field(default_factory=list)
     reminder: Optional[str] = None
+    requirement_node_id: Optional[str] = None
+    requirement_node_title: Optional[str] = None
+    requirement_node_path: Optional[str] = None
+    requirement_node_path_titles: List[str] = Field(default_factory=list)
+    requirement_node_path_ids: List[str] = Field(default_factory=list)
+    requirement_node_depth: Optional[int] = None
+    requirement_document_id: Optional[str] = None
+    requirement_document_name: Optional[str] = None

services.py

@@ -1,8 +1,10 @@
 import asyncio
+from collections import Counter
 import hashlib
 import hmac
 import io
 import json
+import math
 import os
 import re
 import secrets
@@ -55,7 +57,7 @@ from core import (
     UPLOAD_DIR,
     WHISPER_MODEL_NAME,
 )
-from prompts import TTS_REWRITE_PROMPT
+from prompts import DOC_QA_COMPACT_PROMPT, TTS_REWRITE_PROMPT
 
 VN_TZ = ZoneInfo("Asia/Ho_Chi_Minh")
 
@@ -209,6 +211,89 @@ def get_memory() -> str:
     return mem["content"] if mem else ""
 
 
+def _team_doc_qa_memory_scope_key(team_id: str, project_id: Optional[str]) -> str:
+    return f"{team_id}::{project_id or 'global'}"
+
+
+def get_team_doc_qa_memory(team_id: str, project_id: Optional[str]) -> str:
+    scope_key = _team_doc_qa_memory_scope_key(team_id, project_id)
+    mem = memory_collection.find_one({"type": "team_doc_qa_memory", "scope_key": scope_key}, {"_id": 0})
+    return str(mem.get("content") or "") if mem else ""
+
+
+def _save_team_doc_qa_memory(team_id: str, project_id: Optional[str], content: str) -> None:
+    scope_key = _team_doc_qa_memory_scope_key(team_id, project_id)
+    memory_collection.update_one(
+        {"type": "team_doc_qa_memory", "scope_key": scope_key},
+        {
+            "$set": {
+                "type": "team_doc_qa_memory",
+                "scope_key": scope_key,
+                "team_id": team_id,
+                "project_id": project_id,
+                "content": content,
+                "updated_at": get_vn_now().isoformat(),
+            }
+        },
+        upsert=True,
+    )
+
+
+async def compact_team_doc_qa_memory(
+    team_id: str,
+    project_id: Optional[str],
+    query: str,
+    answer: str,
+    doc_context: Dict[str, Any],
+    selected_messages: List[Dict[str, Any]],
+    citations: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    current_memory = get_team_doc_qa_memory(team_id, project_id)
+    sections = doc_context.get("sections") if isinstance(doc_context, dict) else []
+    payload = {
+        "team_id": team_id,
+        "project_id": project_id,
+        "current_memory": current_memory,
+        "query": query,
+        "answer": answer,
+        "selected_messages": selected_messages[-4:] if isinstance(selected_messages, list) else [],
+        "citations": citations[:6] if isinstance(citations, list) else [],
+        "evidence_sections": [
+            {
+                "document_id": section.get("document_id"),
+                "document_name": section.get("document_name"),
+                "section_id": section.get("section_id"),
+                "section_title": section.get("section_title"),
+                "section_path": section.get("section_path"),
+                "section_content": _clip_text(str(section.get("section_content") or ""), 420),
+                "section_summary": _clip_text(str(section.get("section_summary") or ""), 240),
+            }
+            for section in sections[:6]
+        ],
+    }
+
+    def run_compact() -> str:
+        return _nvidia_chat_completion(
+            system_prompt=DOC_QA_COMPACT_PROMPT,
+            user_prompt=json.dumps(payload, ensure_ascii=False),
+            model=TEAM_AGENT_MODEL,
+            temperature=0.0,
+            max_tokens=800,
+        )
+
+    result_text = await asyncio.to_thread(run_compact)
+    result_json = _extract_json_object(result_text)
+    memory_summary = str(result_json.get("memory_summary") or "").strip()
+    if not memory_summary:
+        memory_summary = current_memory
+    if memory_summary:
+        _save_team_doc_qa_memory(team_id, project_id, memory_summary)
+    return {
+        "memory_summary": memory_summary,
+        "raw": result_json,
+    }
+
+
 async def compact_chat_with_prompt(system_prompt: str, min_messages: int = 6) -> Dict[str, Any]:
     messages = get_daily_chat()
     if len(messages) < min_messages:
@@ -585,6 +670,7 @@ def build_document_tree(text: str) -> Dict[str, Any]:
             "level": level,
             "title": title.strip() or f"Section {node_counter}",
             "summary": "",
+            "contextual_summary": "",
             "scope": "",
             "content": "",
             "children": [],
@@ -619,6 +705,7 @@ def build_document_tree(text: str) -> Dict[str, Any]:
         paragraphs = [part.strip() for part in node["content"].split("\n") if part.strip()]
         summary = paragraphs[0] if paragraphs else f"Mục {node['title']}"
         node["summary"] = summary[:280]
+        node["contextual_summary"] = node["summary"]
         node["scope"] = f"Dùng để trả lời câu hỏi liên quan tới: {node['title']}"
         node["content"] = node["content"].strip()
 
@@ -629,6 +716,94 @@ def build_document_tree(text: str) -> Dict[str, Any]:
     }
 
 
+def _contextualize_document_tree(file_name: str, text: str, tree: Dict[str, Any]) -> Dict[str, Any]:
+    nodes = tree.get("nodes") or []
+    target_nodes = [node for node in nodes if node.get("id") and node.get("id") != tree.get("root_id")]
+    if not target_nodes:
+        return {
+            "global_summary": f"Tài liệu {file_name}",
+            "context_coverage": 0,
+            "context_source": "fallback",
+        }
+
+    compact_nodes = [
+        {
+            "id": str(node.get("id") or ""),
+            "title": str(node.get("title") or ""),
+            "summary": _clip_text(str(node.get("summary") or ""), 180),
+            "content_snippet": _clip_text(str(node.get("content") or ""), 180),
+        }
+        for node in target_nodes[:80]
+    ]
+
+    global_context = ""
+    contextual_map: Dict[str, str] = {}
+
+    try:
+        payload = {
+            "file_name": file_name,
+            "document_snippet": _clip_text(text, 1600),
+            "nodes": compact_nodes,
+            "instruction": (
+                "Sinh context retrieval cho từng node để tăng độ chính xác tìm kiếm. "
+                "Mỗi context 1 câu ngắn, có thực thể/chủ đề cụ thể, không bịa thêm dữ kiện."
+            ),
+        }
+        response = _nvidia_chat_completion(
+            system_prompt=(
+                "Trả về JSON thuần: "
+                "{\"global_summary\":\"...\",\"nodes\":[{\"id\":\"sec_x\",\"context\":\"...\"}]}."
+            ),
+            user_prompt=json.dumps(payload, ensure_ascii=False),
+            model=TEAM_AGENT_MODEL,
+            temperature=0.0,
+            max_tokens=1000,
+        )
+        parsed = _extract_json_object(response)
+        global_context = str(parsed.get("global_summary") or "").strip()
+        node_items = parsed.get("nodes") if isinstance(parsed.get("nodes"), list) else []
+        for item in node_items:
+            if not isinstance(item, dict):
+                continue
+            node_id = str(item.get("id") or "").strip()
+            context = str(item.get("context") or "").strip()
+            if node_id and context:
+                contextual_map[node_id] = _clip_text(context, 260)
+    except Exception:
+        global_context = ""
+
+    if not global_context:
+        first_lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
+        global_context = _clip_text(" ".join(first_lines[:3]) or f"Tài liệu {file_name}", 260)
+
+    applied = 0
+    for node in target_nodes:
+        node_id = str(node.get("id") or "")
+        node_context = contextual_map.get(node_id)
+        if not node_context:
+            node_context = _clip_text(
+                f"{global_context}. Mục {node.get('title')}: {node.get('summary') or 'Nội dung liên quan'}",
+                260,
+            )
+        else:
+            applied += 1
+        node["contextual_summary"] = node_context
+
+    root_id = tree.get("root_id")
+    for node in nodes:
+        if node.get("id") == root_id:
+            node["summary"] = _clip_text(global_context, 280)
+            node["contextual_summary"] = node["summary"]
+            node["scope"] = "Tóm tắt toàn bộ tài liệu cho truy vấn tổng quan"
+            break
+
+    return {
+        "global_summary": global_context,
+        "context_coverage": round(applied / max(1, len(target_nodes)), 4),
+        "context_source": "llm_contextualizer" if contextual_map else "fallback",
+    }
+
+
 def save_team_document(
     team_id: str,
     project_id: Optional[str],
@@ -639,6 +814,7 @@ def save_team_document(
 ) -> Dict[str, Any]:
     text = _safe_decode_text(raw_bytes, file_name)
     tree = build_document_tree(text)
+    contextual_meta = _contextualize_document_tree(file_name=file_name, text=text, tree=tree)
     doc = {
         "id": str(uuid.uuid4()),
         "team_id": team_id,
@@ -648,6 +824,8 @@ def save_team_document(
         "uploader_id": uploader_id,
         "tree": tree,
         "text": text,
+        "contextual_global_summary": contextual_meta.get("global_summary", ""),
+        "contextual_meta": contextual_meta,
         "created_at": get_vn_now().isoformat(),
         "updated_at": get_vn_now().isoformat(),
     }
@@ -673,9 +851,33 @@ def list_team_documents(team_id: str, project_id: Optional[str] = None) -> List[
                 "created_at": 1,
                 "updated_at": 1,
                 "tree.total_nodes": 1,
+                "tree.nodes.id": 1,
+                "tree.nodes.parent_id": 1,
+                "tree.nodes.level": 1,
+                "tree.nodes.title": 1,
+                "tree.nodes.summary": 1,
+                "tree.nodes.contextual_summary": 1,
             },
         ).sort("updated_at", -1)
     )
+    for doc in docs:
+        tree = doc.get("tree") or {}
+        nodes = tree.get("nodes") or []
+        doc["node_catalog"] = [
+            {
+                "id": node.get("id"),
+                "parent_id": node.get("parent_id"),
+                "level": node.get("level"),
+                "title": node.get("title"),
+                "summary": node.get("summary"),
+                "contextual_summary": node.get("contextual_summary"),
+                "path": _build_node_path(tree, str(node.get("id") or "")).get("node_path", ""),
+                "path_titles": _build_node_path(tree, str(node.get("id") or "")).get("node_path_titles", []),
+                "path_ids": _build_node_path(tree, str(node.get("id") or "")).get("node_path_ids", []),
+            }
+            for node in nodes
+            if node.get("id")
+        ]
     return docs
 
 
@@ -691,6 +893,42 @@ def get_team_documents_by_ids(team_id: str, doc_ids: List[str], project_id: Opti
     return ordered
 
 
+def build_requirement_node_options_from_documents(documents: List[Dict[str, Any]], limit: int = 8) -> List[Dict[str, Any]]:
+    options: List[Dict[str, Any]] = []
+    seen_ids: set[str] = set()
+
+    for doc in documents:
+        tree = doc.get("tree") or {}
+        for node in tree.get("nodes") or []:
+            node_id = str(node.get("id") or "").strip()
+            if not node_id or node_id in seen_ids:
+                continue
+
+            path = _build_node_path(tree, node_id)
+            node_title = str(node.get("title") or "").strip()
+            node_path = str(path.get("node_path") or "").strip()
+            if not node_title and not node_path:
+                continue
+
+            options.append(
+                {
+                    "node_id": node_id,
+                    "node_title": node_title or node_id,
+                    "node_path": node_path or node_title or node_id,
+                    "node_path_titles": path.get("node_path_titles", []),
+                    "node_path_ids": path.get("node_path_ids", []),
+                    "node_depth": path.get("node_depth", 0),
+                    "document_id": doc.get("id"),
+                    "document_name": doc.get("name"),
+                }
+            )
+            seen_ids.add(node_id)
+            if len(options) >= limit:
+                return options
+
+    return options
+
+
 def _nvidia_chat_completion(system_prompt: str, user_prompt: str, model: Optional[str] = None, temperature: float = 0.1, max_tokens: int = 1200) -> str:
     if not NVIDIA_KEY:
         raise HTTPException(status_code=500, detail="Missing NVIDIA_KEY for team agent")
@@ -746,12 +984,447 @@ def _extract_json_object(text: str) -> Dict[str, Any]:
     return {}
 
 
-def retrieve_document_context_with_tree(query: str, documents: List[Dict[str, Any]]) -> Dict[str, Any]:
+def _normalize_search_text(text: str) -> str:
+    lowered = (text or "").lower()
+    return re.sub(r"[^\w\s]", " ", lowered, flags=re.UNICODE)
+
+
+def _tokenize_search_text(text: str) -> List[str]:
+    normalized = _normalize_search_text(text)
+    return [token for token in normalized.split() if token]
+
+
+def _clip_text(text: str, max_len: int = 420) -> str:
+    content = (text or "").strip()
+    if len(content) <= max_len:
+        return content
+    return f"{content[: max_len - 3].rstrip()}..."
+
+
+def _build_node_path(tree: Dict[str, Any], node_id: str) -> Dict[str, Any]:
+    nodes = tree.get("nodes") or []
+    by_id = {str(node.get("id") or ""): node for node in nodes if node.get("id")}
+    root_id = str(tree.get("root_id") or "root")
+    current_id = str(node_id or "").strip()
+    path_nodes: List[Dict[str, Any]] = []
+
+    while current_id and current_id in by_id:
+        node = by_id[current_id]
+        path_nodes.append(node)
+        parent_id = str(node.get("parent_id") or "").strip()
+        if not parent_id or parent_id == current_id:
+            break
+        current_id = parent_id
+
+    path_nodes.reverse()
+    filtered_nodes = [
+        node
+        for node in path_nodes
+        if str(node.get("id") or "").strip() != root_id and str(node.get("title") or "").strip() != "Document Root"
+    ]
+    titles = [str(node.get("title") or "").strip() for node in filtered_nodes if str(node.get("title") or "").strip()]
+    ids = [str(node.get("id") or "").strip() for node in filtered_nodes if str(node.get("id") or "").strip()]
+    return {
+        "node_path_titles": titles,
+        "node_path_ids": ids,
+        "node_path": " > ".join(titles),
+        "node_depth": max(0, len(titles) - 1),
+        "node_title": titles[-1] if titles else "",
+        "parent_node_title": titles[-2] if len(titles) > 1 else "",
+    }
+
+
+def _format_requirement_node(node_ref: Dict[str, Any]) -> str:
+    node_path = str(node_ref.get("node_path") or "").strip()
+    node_title = str(node_ref.get("node_title") or "").strip()
+    document_name = str(node_ref.get("document_name") or "").strip()
+    if node_path and document_name:
+        return f"{document_name} > {node_path}"
+    if node_path:
+        return node_path
+    return node_title or document_name or ""
+
+
+def _build_requirement_node_reference(sections: List[Dict[str, Any]]) -> Dict[str, Any]:
+    if not sections:
+        return {}
+    top = sections[0]
+    reference = {
+        "document_id": top.get("document_id"),
+        "document_name": top.get("document_name"),
+        "section_id": top.get("section_id"),
+        "section_title": top.get("section_title"),
+        "node_id": top.get("section_id"),
+        "node_title": top.get("section_title"),
+        "node_path": top.get("section_path"),
+        "node_path_titles": top.get("section_path_titles", []),
+        "node_path_ids": top.get("section_path_ids", []),
+        "node_depth": top.get("section_depth", 0),
+        "retrieval_source": top.get("retrieval_source"),
+        "retrieval_score": top.get("retrieval_score"),
+    }
+    reference["node_display"] = _format_requirement_node(reference)
+    return reference
+
+
+def resolve_requirement_node_reference_from_documents(documents: List[Dict[str, Any]], preferred_node_id: Optional[str]) -> Dict[str, Any]:
+    target_id = str(preferred_node_id or "").strip()
+    if not target_id:
+        return {}
+
+    for doc in documents:
+        tree = doc.get("tree") or {}
+        nodes = tree.get("nodes") or []
+        by_id = {str(node.get("id") or ""): node for node in nodes if node.get("id")}
+        if target_id not in by_id:
+            continue
+        node = by_id[target_id]
+        path = _build_node_path(tree, target_id)
+        return {
+            "document_id": doc.get("id"),
+            "document_name": doc.get("name"),
+            "node_id": target_id,
+            "node_title": node.get("title"),
+            "node_path": path.get("node_path", ""),
+            "node_path_titles": path.get("node_path_titles", []),
+            "node_path_ids": path.get("node_path_ids", []),
+            "node_depth": path.get("node_depth", 0),
+            "node_display": _format_requirement_node({
+                "document_name": doc.get("name"),
+                "node_path": path.get("node_path", ""),
+                "node_title": node.get("title"),
+            }),
+            "source": "preferred_node",
+        }
+
+    return {}
+
+
+def _node_to_search_blob(node: Dict[str, Any]) -> str:
+    fields = [
+        str(node.get("title") or ""),
+        str(node.get("summary") or ""),
+        str(node.get("scope") or ""),
+        str(node.get("contextual_summary") or ""),
+        str(node.get("content") or ""),
+    ]
+    return "\n".join(field for field in fields if field)
+
+
+def _prepare_bm25f_corpus(documents: List[Dict[str, Any]]) -> Dict[str, Any]:
+    field_names = ["title", "summary", "contextual_summary", "content"]
+    rows: List[Dict[str, Any]] = []
+
+    for doc in documents:
+        tree = doc.get("tree") or {}
+        for node in tree.get("nodes") or []:
+            node_id = str(node.get("id") or "").strip()
+            if not node_id:
+                continue
+
+            field_tokens: Dict[str, List[str]] = {}
+            for field in field_names:
+                field_tokens[field] = _tokenize_search_text(str(node.get(field) or ""))
+
+            rows.append(
+                {
+                    "document_id": doc.get("id"),
+                    "document_name": doc.get("name"),
+                    "node": node,
+                    "field_tokens": field_tokens,
+                }
+            )
+
+    total_docs = max(1, len(rows))
+    avg_field_len: Dict[str, float] = {}
+    doc_freq: Dict[str, Dict[str, int]] = {field: {} for field in field_names}
+
+    for field in field_names:
+        lengths = [len(row["field_tokens"][field]) for row in rows]
+        avg_field_len[field] = (sum(lengths) / len(lengths)) if lengths else 1.0
+        for row in rows:
+            unique_terms = set(row["field_tokens"][field])
+            for term in unique_terms:
+                doc_freq[field][term] = doc_freq[field].get(term, 0) + 1
+
+    return {
+        "rows": rows,
+        "field_names": field_names,
+        "avg_field_len": avg_field_len,
+        "doc_freq": doc_freq,
+        "total_docs": total_docs,
+    }
+
+
+def _bm25f_score_row(query_tokens: List[str], row: Dict[str, Any], corpus: Dict[str, Any]) -> float:
+    if not query_tokens:
+        return 0.0
+
+    field_weights = {
+        "title": 2.2,
+        "summary": 1.4,
+        "contextual_summary": 1.8,
+        "content": 1.0,
+    }
+    k1 = 1.5
+    b = 0.75
+
+    total_docs = int(corpus.get("total_docs", 1))
+    avg_field_len = corpus.get("avg_field_len", {})
+    doc_freq = corpus.get("doc_freq", {})
+
+    score = 0.0
+    for term in query_tokens:
+        term_score = 0.0
+        max_df = 0
+        for field in ["title", "summary", "contextual_summary", "content"]:
+            tokens = row["field_tokens"][field]
+            tf = tokens.count(term)
+            if tf <= 0:
+                continue
+
+            field_len = len(tokens)
+            avg_len = max(1e-6, float(avg_field_len.get(field, 1.0)))
+            norm = (1 - b) + b * (field_len / avg_len)
+            tf_norm = (tf * (k1 + 1)) / (tf + (k1 * norm))
+            term_score += field_weights[field] * tf_norm
+
+            df_field = int(doc_freq.get(field, {}).get(term, 0))
+            max_df = max(max_df, df_field)
+
+        if term_score <= 0:
+            continue
+
+        idf = math.log(1 + (total_docs - max_df + 0.5) / (max_df + 0.5)) if max_df > 0 else 0.0
+        score += term_score * idf
+
+    return score
+
+
+def _collect_bm25f_candidates(query: str, documents: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    query_tokens = _tokenize_search_text(query)
+    if not query_tokens:
+        return []
+
+    corpus = _prepare_bm25f_corpus(documents)
+    rows = corpus.get("rows", [])
+
+    candidates: List[Dict[str, Any]] = []
+    for row in rows:
+        score = _bm25f_score_row(query_tokens, row, corpus)
+        if score <= 0:
+            continue
+        candidates.append(
+            {
+                "document_id": row.get("document_id"),
+                "document_name": row.get("document_name"),
+                "node": row.get("node") or {},
+                "score": score,
+            }
+        )
+
+    candidates.sort(key=lambda item: float(item.get("score", 0.0)), reverse=True)
+    return candidates[:60]
+
+
+def _generate_hyde_variant(query: str, selected_messages: Optional[List[Dict[str, Any]]] = None) -> str:
+    payload = {
+        "query": query,
+        "selected_messages": (selected_messages or [])[-6:],
+        "instruction": (
+            "Sinh một đoạn giả định ngắn (2-4 câu) mô tả câu trả lời lý tưởng để phục vụ retrieval. "
+            "Giữ keyword/thuật ngữ kỹ thuật quan trọng, không thêm lan man."
+        ),
+    }
+    text = _nvidia_chat_completion(
+        system_prompt=(
+            "Bạn là bộ tạo HyDE query cho retrieval. "
+            "Trả về văn bản thuần duy nhất, không markdown, không JSON."
+        ),
+        user_prompt=json.dumps(payload, ensure_ascii=False),
+        model=TEAM_AGENT_MODEL,
+        temperature=0.0,
+        max_tokens=220,
+    )
+    return _clip_text(text.strip(), 500)
+
+
+def _expand_query_variants(
+    query: str,
+    max_variants: int = 5,
+    selected_messages: Optional[List[Dict[str, Any]]] = None,
+    use_hyde: bool = True,
+) -> Dict[str, Any]:
+    base = (query or "").strip()
+    if not base:
+        return {"variants": [], "hyde_variant": ""}
+
+    variants: List[str] = [base]
+    hyde_variant = ""
+    try:
+        payload = {
+            "query": base,
+            "instruction": (
+                "Sinh tối đa 3 truy vấn thay thế để tăng recall tài liệu kỹ thuật. "
+                "Giữ nguyên ý nghĩa, thêm biến thể keyword/chuẩn thuật ngữ."
+            ),
+        }
+        response = _nvidia_chat_completion(
+            system_prompt=(
+                "Trả về JSON thuần: {\"variants\":[\"...\"]}. "
+                "Không thêm giải thích."
+            ),
+            user_prompt=json.dumps(payload, ensure_ascii=False),
+            model=TEAM_AGENT_MODEL,
+            temperature=0.0,
+            max_tokens=220,
+        )
+        parsed = _extract_json_object(response)
+        llm_variants = parsed.get("variants") if isinstance(parsed.get("variants"), list) else []
+        for item in llm_variants:
+            text = str(item or "").strip()
+            if text and text.lower() not in {v.lower() for v in variants}:
+                variants.append(text)
+            if len(variants) >= max_variants:
+                break
+    except Exception:
+        pass
+
+    # Deterministic backup variant using token dedupe.
+    tokens = _tokenize_search_text(base)
+    if tokens:
+        keyword_variant = " ".join(sorted(set(tokens), key=tokens.index))
+        if keyword_variant and keyword_variant.lower() not in {v.lower() for v in variants}:
+            variants.append(keyword_variant)
+
+    if use_hyde and len(variants) < max_variants:
+        try:
+            hyde_variant = _generate_hyde_variant(base, selected_messages=selected_messages)
+            if hyde_variant and hyde_variant.lower() not in {v.lower() for v in variants}:
+                variants.append(hyde_variant)
+        except Exception:
+            hyde_variant = ""
+
+    return {"variants": variants[:max_variants], "hyde_variant": hyde_variant}
+
+
+def _collect_multi_query_candidates(
+    query: str,
+    documents: List[Dict[str, Any]],
+    selected_messages: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    variant_payload = _expand_query_variants(
+        query,
+        max_variants=5,
+        selected_messages=selected_messages,
+        use_hyde=True,
+    )
+    variants = variant_payload.get("variants", []) if isinstance(variant_payload, dict) else []
+    if not variants:
+        return {"variants": [query], "candidates": [], "hyde_variant": ""}
+
+    k = 60.0
+    merged: Dict[str, Dict[str, Any]] = {}
+
+    for variant in variants:
+        candidates = _collect_bm25f_candidates(variant, documents)
+        for rank, item in enumerate(candidates):
+            node = item.get("node") or {}
+            doc_id = str(item.get("document_id") or "")
+            node_id = str(node.get("id") or "")
+            if not doc_id or not node_id:
+                continue
+            key = f"{doc_id}::{node_id}"
+            rrf = 1.0 / (k + rank + 1)
+            score = float(item.get("score", 0.0))
+
+            if key not in merged:
+                merged[key] = {
+                    "document_id": item.get("document_id"),
+                    "document_name": item.get("document_name"),
+                    "node": node,
+                    "score": 0.0,
+                    "max_lexical": 0.0,
+                    "query_hits": [],
+                }
+
+            merged[key]["score"] += rrf
+            merged[key]["max_lexical"] = max(float(merged[key]["max_lexical"]), score)
+            if variant not in merged[key]["query_hits"]:
+                merged[key]["query_hits"].append(variant)
+
+    fused = list(merged.values())
+    for item in fused:
+        item["score"] = float(item.get("score", 0.0)) + float(item.get("max_lexical", 0.0)) * 0.45
+
+    fused.sort(key=lambda item: float(item.get("score", 0.0)), reverse=True)
+    return {
+        "variants": variants,
+        "candidates": fused[:50],
+        "hyde_variant": variant_payload.get("hyde_variant", "") if isinstance(variant_payload, dict) else "",
+    }
+
+
+def _llm_rerank_document_candidates(query: str, candidates: List[Dict[str, Any]], top_k: int = 8) -> List[str]:
+    if not candidates:
+        return []
+
+    payload = {
+        "query": query,
+        "candidates": [
+            {
+                "id": str(item["node"].get("id") or ""),
+                "document_id": item.get("document_id"),
+                "document_name": item.get("document_name"),
+                "title": item["node"].get("title"),
+                "summary": item["node"].get("summary"),
+                "snippet": _clip_text(item["node"].get("content", ""), 220),
+                "lexical_score": round(float(item.get("score", 0.0)), 4),
+            }
+            for item in candidates[:18]
+        ],
+        "top_k": max(1, min(top_k, 10)),
+    }
+
+    rerank_text = _nvidia_chat_completion(
+        system_prompt=(
+            "Bạn là bộ xếp hạng bằng chứng tài liệu. "
+            "Trả về JSON thuần: {\"selected_ids\": [\"node_id\"], \"reason\": \"...\"}. "
+            "Chọn các node liên quan nhất để trả lời câu hỏi."
+        ),
+        user_prompt=json.dumps(payload, ensure_ascii=False),
+        model=TEAM_AGENT_MODEL,
+        temperature=0.0,
+        max_tokens=260,
+    )
+    rerank_json = _extract_json_object(rerank_text)
+    selected_ids_raw = rerank_json.get("selected_ids")
+    if isinstance(selected_ids_raw, list):
+        selected_ids = [str(item).strip() for item in selected_ids_raw if str(item).strip()]
+        if selected_ids:
+            return selected_ids[:top_k]
+
+    return [
+        str(item["node"].get("id"))
+        for item in candidates[:top_k]
+        if item["node"].get("id")
+    ]
+
+
+def retrieve_document_context_with_tree(
+    query: str,
+    documents: List[Dict[str, Any]],
+    selected_messages: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
     if not documents:
         return {"sections": [], "citations": []}
 
     picked_sections: List[Dict[str, Any]] = []
     citations: List[Dict[str, Any]] = []
+    seen_node_ids: set[str] = set()
+
+    # Layer 1: tree navigation keeps hierarchical intent and ensures at least one anchor per doc.
+    tree_picks: List[Dict[str, Any]] = []
 
     for doc in documents:
         tree = doc.get("tree") or {}
@@ -810,27 +1483,251 @@ def retrieve_document_context_with_tree(query: str, documents: List[Dict[str, An
         if not selected_node:
             continue
 
-        section_text = selected_node.get("content", "")
-        picked_sections.append(
+        selected_node_id = str(selected_node.get("id") or "").strip()
+        node_path = _build_node_path(tree, selected_node_id)
+        path_titles = node_path.get("node_path_titles", [])
+        path_ids = node_path.get("node_path_ids", [])
+
+        tree_picks.append(
             {
                 "document_id": doc.get("id"),
                 "document_name": doc.get("name"),
-                "section_id": selected_node.get("id"),
-                "section_title": selected_node.get("title"),
+                "node": selected_node,
+                "score": 1.0,
+                "source": "tree_nav",
+            }
+        )
+
+    # Layer 2: multi-query lexical retrieval broadens recall.
+    fused_results = _collect_multi_query_candidates(query, documents, selected_messages=selected_messages)
+    lexical_candidates = fused_results.get("candidates", []) if isinstance(fused_results, dict) else []
+    query_variants = fused_results.get("variants", [query]) if isinstance(fused_results, dict) else [query]
+    hyde_variant = fused_results.get("hyde_variant", "") if isinstance(fused_results, dict) else ""
+
+    # Layer 3: LLM reranking improves precision on top lexical candidates.
+    reranked_ids = set(_llm_rerank_document_candidates(query, lexical_candidates, top_k=8))
+
+    merged_candidates: List[Dict[str, Any]] = []
+    merged_candidates.extend(tree_picks)
+    for item in lexical_candidates:
+        node_id = str(item["node"].get("id") or "")
+        if not node_id:
+            continue
+        score = float(item.get("score", 0.0))
+        if node_id in reranked_ids:
+            score += 1.0
+        merged_candidates.append(
+            {
+                "document_id": item.get("document_id"),
+                "document_name": item.get("document_name"),
+                "node": item.get("node") or {},
+                "score": score,
+                "source": "hybrid_rerank" if node_id in reranked_ids else "lexical",
+            }
+        )
+
+    merged_candidates.sort(key=lambda item: float(item.get("score", 0.0)), reverse=True)
+
+    for item in merged_candidates:
+        node = item.get("node") or {}
+        section_id = str(node.get("id") or "").strip()
+        if not section_id or section_id in seen_node_ids:
+            continue
+
+        seen_node_ids.add(section_id)
+        section_text = str(node.get("content") or "")
+        picked_sections.append(
+            {
+                "document_id": item.get("document_id"),
+                "document_name": item.get("document_name"),
+                "section_id": section_id,
+                "section_title": node.get("title"),
                 "section_content": section_text,
-                "section_summary": selected_node.get("summary", ""),
+                "section_summary": node.get("summary", ""),
+                "section_context": node.get("contextual_summary", ""),
+                "section_path": node_path.get("node_path", ""),
+                "section_path_titles": path_titles,
+                "section_path_ids": path_ids,
+                "section_depth": node_path.get("node_depth", 0),
+                "retrieval_score": round(float(item.get("score", 0.0)), 4),
+                "retrieval_source": item.get("source"),
+                "query_hit_count": len(item.get("query_hits", [])) if isinstance(item.get("query_hits"), list) else 0,
             }
         )
         citations.append(
             {
-                "document_id": doc.get("id"),
-                "document_name": doc.get("name"),
-                "section_id": selected_node.get("id"),
-                "section_title": selected_node.get("title"),
+                "document_id": item.get("document_id"),
+                "document_name": item.get("document_name"),
+                "section_id": section_id,
+                "section_title": node.get("title"),
+                "section_path": node_path.get("node_path", ""),
+                "section_path_titles": path_titles,
+                "section_path_ids": path_ids,
+                "source": item.get("source"),
             }
         )
+        if len(picked_sections) >= 10:
+            break
 
-    return {"sections": picked_sections, "citations": citations}
+    return {
+        "sections": picked_sections,
+        "citations": citations,
+        "retrieval_meta": {
+            "tree_pick_count": len(tree_picks),
+            "lexical_candidate_count": len(lexical_candidates),
+            "rerank_pick_count": len(reranked_ids),
+            "query_variants": query_variants,
+            "hyde_used": bool(hyde_variant),
+        },
+        "requirement_node_reference": _build_requirement_node_reference(picked_sections),
+    }
+
+
+def _evaluate_grounding_confidence(
+    answer: str,
+    citations: List[Dict[str, Any]],
+    sections: List[Dict[str, Any]],
+    retrieval_meta: Dict[str, Any],
+    llm_confidence: str,
+) -> Dict[str, Any]:
+    section_ids = {
+        str(section.get("section_id") or "").strip()
+        for section in sections
+        if str(section.get("section_id") or "").strip()
+    }
+    citation_match = 0
+    for item in citations:
+        if not isinstance(item, dict):
+            continue
+        section_id = str(item.get("section_id") or "").strip()
+        if section_id and section_id in section_ids:
+            citation_match += 1
+
+    llm_map = {"low": 0.35, "medium": 0.65, "high": 0.9}
+    llm_score = llm_map.get(llm_confidence, 0.6)
+    cited_ratio = citation_match / max(1, len(citations) if citations else 1)
+    retrieval_strength = min(float(retrieval_meta.get("rerank_pick_count", 0)) / 6.0, 1.0)
+    section_strength = min(len(sections) / 8.0, 1.0)
+    answer_len_strength = min(len((answer or "").split()) / 80.0, 1.0)
+
+    score = (
+        llm_score * 0.40
+        + cited_ratio * 0.25
+        + retrieval_strength * 0.20
+        + section_strength * 0.10
+        + answer_len_strength * 0.05
+    )
+    score = max(0.0, min(score, 1.0))
+
+    if score >= 0.78:
+        label = "high"
+    elif score >= 0.56:
+        label = "medium"
+    else:
+        label = "low"
+
+    return {
+        "confidence": label,
+        "confidence_score": round(score, 4),
+        "needs_clarification": label == "low",
+    }
+
+
+def build_document_grounded_answer(
+    query: str,
+    selected_messages: List[Dict[str, Any]],
+    doc_context: Dict[str, Any],
+    qa_memory: Optional[str] = None,
+) -> Dict[str, Any]:
+    sections = doc_context.get("sections") if isinstance(doc_context, dict) else []
+    citations = doc_context.get("citations") if isinstance(doc_context, dict) else []
+    retrieval_meta = doc_context.get("retrieval_meta") if isinstance(doc_context, dict) else {}
+    if not isinstance(sections, list) or not sections:
+        return {
+            "answer": "",
+            "citations": [],
+            "confidence": "low",
+            "confidence_score": 0.0,
+            "needs_clarification": True,
+            "clarifying_question": "Bạn có thể chọn thêm tài liệu hoặc section liên quan để mình trả lời chính xác hơn không?",
+        }
+
+    payload = {
+        "query": query,
+        "qa_memory": (qa_memory or "").strip(),
+        "selected_messages": selected_messages[-8:] if isinstance(selected_messages, list) else [],
+        "evidence_sections": [
+            {
+                "document_id": section.get("document_id"),
+                "document_name": section.get("document_name"),
+                "section_id": section.get("section_id"),
+                "section_title": section.get("section_title"),
+                "section_path": section.get("section_path"),
+                "summary": _clip_text(str(section.get("section_summary") or ""), 280),
+                "context": _clip_text(str(section.get("section_context") or ""), 240),
+                "content": _clip_text(str(section.get("section_content") or ""), 520),
+            }
+            for section in sections[:8]
+        ],
+        "citations": citations[:8] if isinstance(citations, list) else [],
+    }
+
+    answer_text = _nvidia_chat_completion(
+        system_prompt=(
+            "Bạn là trợ lý phân tích tài liệu dạng NotebookLM-style cho team chat. "
+            "Nhiệm vụ: trả lời trực tiếp câu hỏi user dựa trên evidence đã cho, không bịa, không suy diễn vượt dữ liệu. "
+            "Nếu có qa_memory thì dùng như ngữ cảnh ổn định cho các lượt QA tiếp theo, nhưng không được vượt quá evidence hiện có. "
+            "Trả về JSON thuần: {\"answer\":\"...\",\"citations\":[{\"document_id\":\"...\",\"section_id\":\"...\"}],\"confidence\":\"high|medium|low\"}."
+        ),
+        user_prompt=json.dumps(payload, ensure_ascii=False),
+        model=TEAM_AGENT_MODEL,
+        temperature=0.1,
+        max_tokens=700,
+    )
+    answer_json = _extract_json_object(answer_text)
+    answer = str(answer_json.get("answer") or "").strip()
+    out_citations = answer_json.get("citations") if isinstance(answer_json.get("citations"), list) else []
+    confidence = str(answer_json.get("confidence") or "medium").strip().lower()
+    if confidence not in {"high", "medium", "low"}:
+        confidence = "medium"
+
+    if not answer:
+        top = sections[0]
+        fallback_title = str(top.get("section_title") or "nội dung liên quan").strip()
+        fallback_doc = str(top.get("document_name") or "tài liệu").strip()
+        answer = f"Theo {fallback_doc}, phần '{fallback_title}' là dữ liệu liên quan nhất với câu hỏi hiện tại."
+        out_citations = [
+            {
+                "document_id": top.get("document_id"),
+                "section_id": top.get("section_id"),
+            }
+        ]
+        confidence = "low"
+
+    eval_result = _evaluate_grounding_confidence(
+        answer=answer,
+        citations=out_citations,
+        sections=sections,
+        retrieval_meta=retrieval_meta if isinstance(retrieval_meta, dict) else {},
+        llm_confidence=confidence,
+    )
+
+    clarifying_question = ""
+    if eval_result.get("needs_clarification"):
+        clarifying_question = (
+            "Mình chưa đủ chắc chắn vì bằng chứng tài liệu còn yếu. "
+            "Bạn muốn mình bám vào tài liệu nào hoặc section nào cụ thể hơn?"
+        )
+
+    return {
+        "answer": answer,
+        "citations": out_citations,
+        "confidence": eval_result.get("confidence", confidence),
+        "confidence_score": eval_result.get("confidence_score", 0.0),
+        "needs_clarification": bool(eval_result.get("needs_clarification")),
+        "clarifying_question": clarifying_question,
+        "requirement_node_reference": _build_requirement_node_reference(sections),
+    }
 
 
 def run_team_agent_with_nvidia(system_prompt: str, payload: Dict[str, Any]) -> str:
@@ -843,13 +1740,20 @@ def run_team_agent_with_nvidia(system_prompt: str, payload: Dict[str, Any]) -> s
     )
 
 
-def save_team_chat_message(team_id: str, role: str, content: str, project_id: Optional[str] = None) -> Dict[str, Any]:
+def save_team_chat_message(
+    team_id: str,
+    role: str,
+    content: str,
+    project_id: Optional[str] = None,
+    attachment_urls: Optional[List[str]] = None,
+) -> Dict[str, Any]:
     doc = {
         "id": str(uuid.uuid4()),
         "team_id": team_id,
         "project_id": project_id,
         "role": role,
         "content": content,
+        "attachment_urls": attachment_urls or [],
         "timestamp": get_vn_now().isoformat(),
     }
     team_chat_collection.insert_one(doc)
@@ -871,6 +1775,14 @@ def create_issue_for_project(project_id: str, reporter_id: str, payload: Dict[st
         "assignee_id": assignee["id"] if assignee else payload.get("assignee_id"),
         "tags": tags,
         "requirement_text": payload.get("requirement_text"),
+        "requirement_node_id": payload.get("requirement_node_id"),
+        "requirement_node_title": payload.get("requirement_node_title"),
+        "requirement_node_path": payload.get("requirement_node_path"),
+        "requirement_node_path_titles": payload.get("requirement_node_path_titles", []),
+        "requirement_node_path_ids": payload.get("requirement_node_path_ids", []),
+        "requirement_node_depth": payload.get("requirement_node_depth"),
+        "requirement_document_id": payload.get("requirement_document_id"),
+        "requirement_document_name": payload.get("requirement_document_name"),
         "attachment_urls": payload.get("attachment_urls", []),
         "reporter_id": reporter_id,
         "created_at": get_vn_now().isoformat(),
@@ -893,6 +1805,14 @@ def create_task_from_agent(payload: Dict[str, Any]) -> Dict[str, Any]:
         "priority": payload.get("priority", "medium"),
         "tags": tags,
         "reminder": payload.get("reminder") or payload.get("start_time"),
+        "requirement_node_id": payload.get("requirement_node_id"),
+        "requirement_node_title": payload.get("requirement_node_title"),
+        "requirement_node_path": payload.get("requirement_node_path"),
+        "requirement_node_path_titles": payload.get("requirement_node_path_titles", []),
+        "requirement_node_path_ids": payload.get("requirement_node_path_ids", []),
+        "requirement_node_depth": payload.get("requirement_node_depth"),
+        "requirement_document_id": payload.get("requirement_document_id"),
+        "requirement_document_name": payload.get("requirement_document_name"),
     }
     tasks_collection.insert_one(task)
     return task
@@ -904,7 +1824,7 @@ def update_issue_from_agent(issue_id: str, payload: Dict[str, Any]) -> Dict[str,
         raise HTTPException(status_code=404, detail="Issue not found")
 
     update_data: Dict[str, Any] = {"updated_at": get_vn_now().isoformat()}
-    field_names = ["title", "description", "severity", "status", "tags", "attachment_urls", "requirement_text"]
+    field_names = ["title", "description", "severity", "status", "tags", "attachment_urls", "requirement_text", "requirement_node_id", "requirement_node_title", "requirement_node_path", "requirement_document_id", "requirement_document_name"]
     for field_name in field_names:
         value = payload.get(field_name)
         if value is None:
@@ -914,6 +1834,13 @@ def update_issue_from_agent(issue_id: str, payload: Dict[str, Any]) -> Dict[str,
         else:
             update_data[field_name] = value
 
+    if "requirement_node_path_titles" in payload and payload["requirement_node_path_titles"] is not None:
+        update_data["requirement_node_path_titles"] = payload["requirement_node_path_titles"]
+    if "requirement_node_path_ids" in payload and payload["requirement_node_path_ids"] is not None:
+        update_data["requirement_node_path_ids"] = payload["requirement_node_path_ids"]
+    if "requirement_node_depth" in payload and payload["requirement_node_depth"] is not None:
+        update_data["requirement_node_depth"] = payload["requirement_node_depth"]
+
     assignee = resolve_user_reference(payload)
     if assignee:
         update_data["assignee_id"] = assignee["id"]