{
  "openapi": "3.0.3",
  "info": {
    "title": "Zalo Client Memory CRM API",
    "description": "API backend cho CRM cá nhân biến tin nhắn Zalo thành Khách hàng, Yêu cầu, Task có ảnh chứng cứ, Lịch hẹn và Insight AI. Hỗ trợ Web App, Electron App và Chrome Extension.",
    "version": "0.1.0",
    "contact": {
      "name": "Zalo Client Memory Support"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "Máy chủ hiện tại (Local / Staging / Production)"
    }
  ],
  "components": {
    "securitySchemes": {
      "SessionAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "cm_session",
        "description": "Cookie phiên làm việc sau khi đăng nhập thành công"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Token",
        "description": "API Token cố định cấu hình qua biến môi trường API_TOKEN"
      }
    },
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["Mới", "Đang tìm hiểu", "Có nhu cầu rõ", "Đang tư vấn", "Đã mua", "Đang thực hiện", "Hoàn thành", "Chăm sóc lại"]
          },
          "temperature": {
            "type": "string",
            "enum": ["Băng", "Lạnh", "Ấm", "Nóng", "Chốt"]
          },
          "leadScore": { "type": "integer", "minimum": 0, "maximum": 100 },
          "phone": { "type": "string" },
          "owner": { "type": "string" },
          "nextFollowUpAt": { "type": "string", "format": "date-time" },
          "estimatedBudget": { "type": "number" },
          "productType": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Requirement": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "customerId": { "type": "string" },
          "customerName": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "quote": { "type": "string" },
          "category": { "type": "string" },
          "priority": { "type": "string", "enum": ["Thấp", "Trung bình", "Cao", "Khẩn cấp"] },
          "status": { "type": "string" },
          "sourceUrl": { "type": "string" },
          "focusUrl": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "customerId": { "type": "string" },
          "customerName": { "type": "string" },
          "requirementId": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string", "enum": ["todo", "doing", "done", "cancelled"] },
          "priority": { "type": "string", "enum": ["Thấp", "Trung bình", "Cao", "Khẩn cấp"] },
          "dueAt": { "type": "string", "format": "date-time" },
          "imagePaths": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Mảng đường dẫn tối đa 5 ảnh đính kèm (chứng cứ xác thực)"
          },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Insight": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "content": { "type": "string" },
          "type": { "type": "string" },
          "confidence": { "type": "string", "enum": ["Cao", "Trung bình", "Thấp"] },
          "feedback": { "type": "string", "enum": ["Đúng", "Sai", "Cần xác minh", null] }
        }
      },
      "CaptureRequest": {
        "type": "object",
        "required": ["customerName"],
        "properties": {
          "customerName": { "type": "string" },
          "customerPhone": { "type": "string" },
          "quote": { "type": "string" },
          "requirement": { "type": "string" },
          "taskTitle": { "type": "string" },
          "dueAt": { "type": "string", "format": "date-time" },
          "category": { "type": "string" },
          "priority": { "type": "string" },
          "sourceUrl": { "type": "string" },
          "focusUrl": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Kiểm tra sức khỏe hệ thống",
        "tags": ["Hệ thống"],
        "responses": {
          "200": { "description": "Hệ thống hoạt động bình thường" },
          "503": { "description": "Bộ lưu trữ hoặc hệ thống lỗi" }
        }
      }
    },
    "/api/auth/status": {
      "get": {
        "summary": "Lấy trạng thái cấu hình xác thực",
        "tags": ["Xác thực"],
        "responses": {
          "200": { "description": "Thông tin chế độ xác thực và phiên hiện tại" }
        }
      }
    },
    "/api/login": {
      "post": {
        "summary": "Đăng nhập bằng mật khẩu",
        "tags": ["Xác thực"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Đăng nhập thành công, trả về cookie phiên" },
          "401": { "description": "Sai mật khẩu" }
        }
      }
    },
    "/api/logout": {
      "post": {
        "summary": "Đăng xuất và hủy phiên",
        "tags": ["Xác thực"],
        "responses": {
          "200": { "description": "Đã đăng xuất" }
        }
      }
    },
    "/api/capture": {
      "post": {
        "summary": "Ghi nhận nhanh tin nhắn từ Zalo (Capture API)",
        "tags": ["Thu thập Zalo"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CaptureRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Đã tạo/liên kết khách hàng, yêu cầu, task và insight" }
        }
      }
    },
    "/api/customers": {
      "get": {
        "summary": "Lấy danh sách khách hàng (hỗ trợ phân trang & lọc)",
        "tags": ["Khách hàng (CRM)"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Từ khóa tìm kiếm" },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "temperature", "in": "query", "schema": { "type": "string" } },
          { "name": "owner", "in": "query", "schema": { "type": "string" } },
          { "name": "followUp", "in": "query", "schema": { "type": "string", "enum": ["overdue", "today", "upcoming", "none"] } }
        ],
        "responses": {
          "200": { "description": "Danh sách khách hàng phân trang" }
        }
      }
    },
    "/api/customers/{id}/summary": {
      "get": {
        "summary": "Lấy hồ sơ Customer 360",
        "tags": ["Khách hàng (CRM)"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Tổng quan thông tin, lịch sử yêu cầu, task, timeline" },
          "404": { "description": "Không tìm thấy khách hàng" }
        }
      }
    },
    "/api/customers/{id}": {
      "patch": {
        "summary": "Cập nhật thông tin khách hàng (Trạng thái, Nhiệt độ, SLA)",
        "tags": ["Khách hàng (CRM)"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": { "type": "string" },
                  "temperature": { "type": "string" },
                  "owner": { "type": "string" },
                  "nextFollowUpAt": { "type": "string", "format": "date-time" },
                  "estimatedBudget": { "type": "number" },
                  "productType": { "type": "string" },
                  "tags": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Cập nhật thành công" }
        }
      }
    },
    "/api/requirements": {
      "get": {
        "summary": "Lấy danh sách yêu cầu khách hàng",
        "tags": ["Yêu cầu & Nhu cầu"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "priority", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Danh sách yêu cầu phân trang" }
        }
      }
    },
    "/api/requirements/{id}": {
      "patch": {
        "summary": "Cập nhật yêu cầu",
        "tags": ["Yêu cầu & Nhu cầu"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Cập nhật thành công" }
        }
      }
    },
    "/api/tasks": {
      "get": {
        "summary": "Lấy danh sách công việc (Task)",
        "tags": ["Công việc & Thực thi"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "due", "in": "query", "schema": { "type": "string", "enum": ["overdue", "today", "upcoming"] } }
        ],
        "responses": {
          "200": { "description": "Danh sách task phân trang" }
        }
      },
      "post": {
        "summary": "Tạo task mới (hỗ trợ đính kèm tối đa 5 ảnh base64/file)",
        "tags": ["Công việc & Thực thi"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": { "type": "string" },
                  "customerId": { "type": "string" },
                  "requirementId": { "type": "string" },
                  "priority": { "type": "string" },
                  "dueAt": { "type": "string", "format": "date-time" },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "data": { "type": "string", "description": "Base64 chuỗi ảnh" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tạo task thành công" }
        }
      }
    },
    "/api/tasks/{id}": {
      "patch": {
        "summary": "Cập nhật trạng thái / thông tin task",
        "tags": ["Công việc & Thực thi"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Cập nhật thành công" }
        }
      }
    },
    "/api/tasks/{id}/images": {
      "post": {
        "summary": "Thêm ảnh đính kèm vào task đã có (tối đa 5 ảnh/task)",
        "tags": ["Công việc & Thực thi"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Thêm ảnh thành công" }
        }
      }
    },
    "/api/tasks/{id}/images/{filename}": {
      "delete": {
        "summary": "Xóa 1 ảnh đính kèm của task",
        "tags": ["Công việc & Thực thi"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Đã xóa ảnh thành công" }
        }
      }
    },
    "/api/insights": {
      "get": {
        "summary": "Lấy danh sách Insight AI & Đề xuất",
        "tags": ["Insight AI & Marketing"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Danh sách insight" }
        }
      }
    },
    "/api/marketing": {
      "get": {
        "summary": "Báo cáo phễu chuyển đổi, Lead Score, Content Board và Sales Playbook",
        "tags": ["Insight AI & Marketing"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7 } }
        ],
        "responses": {
          "200": { "description": "Báo cáo phân tích marketing toàn diện" }
        }
      }
    },
    "/api/calendar.ics": {
      "get": {
        "summary": "Xuất file lịch chuẩn iCalendar (.ics kèm VALARM nhắc việc)",
        "tags": ["Lịch & Nhắc nhở"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Nội dung file text/calendar" }
        }
      }
    },
    "/api/backup": {
      "get": {
        "summary": "Tải về bản sao lưu ZIP (bao gồm dữ liệu và toàn bộ ảnh task)",
        "tags": ["Sao lưu & Dữ liệu"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Tập tin .zip sao lưu" }
        }
      }
    },
    "/api/export.csv": {
      "get": {
        "summary": "Xuất toàn bộ khách hàng và trạng thái ra CSV",
        "tags": ["Sao lưu & Dữ liệu"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "File text/csv" }
        }
      }
    },
    "/api/integrations/telegram/status": {
      "get": {
        "summary": "Kiểm tra cấu hình bot Telegram",
        "tags": ["Tích hợp bên thứ ba"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Trạng thái kết nối bot Telegram" }
        }
      }
    },
    "/api/integrations/telegram/test": {
      "post": {
        "summary": "Gửi tin nhắn thử nghiệm qua Telegram",
        "tags": ["Tích hợp bên thứ ba"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Tin nhắn đã được gửi" }
        }
      }
    },
    "/api/integrations/google-calendar/status": {
      "get": {
        "summary": "Trạng thái đồng bộ Google Calendar",
        "tags": ["Tích hợp bên thứ ba"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Trạng thái cấu hình và token" }
        }
      }
    },
    "/api/integrations/google-sheets/status": {
      "get": {
        "summary": "Trạng thái kết nối Google Sheets",
        "tags": ["Tích hợp bên thứ ba"],
        "security": [{ "SessionAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Trạng thái Google Sheets" }
        }
      }
    }
  }
}