openapi: 3.0.3
info:
  title: VIETAL — Agent API
  version: "1.1"
  description: |
    API cho AI Agent làm việc từ xa trên hệ thống quản trị dự án VIETAL.
    Xác thực: Bearer token (`vtk_...`) do quản trị viên cấp tại /project/agents.
    Giới hạn: 120 request/phút/token; tệp ≤ 25 MB.
  contact:
    name: VIETAL project management
    url: https://dv.badt.vn/project
servers:
  - url: https://dv.badt.vn/project/api/v1
    description: Production (Internet)
security:
  - bearerAuth: []
tags:
  - name: bootstrap
  - name: docs
  - name: documents
  - name: tasks
  - name: requests
  - name: resources
  - name: evidence
  - name: indicators
  - name: logs
paths:
  /ping:
    get:
      tags: [bootstrap]
      summary: Kiểm tra token
      responses:
        "200": { description: OK }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /workspace:
    get:
      tags: [bootstrap]
      summary: Gói khởi động cho agent
      parameters:
        - { name: project, in: query, schema: { type: string }, example: VIETAL-2026 }
      responses:
        "200":
          description: Việc được giao, yêu cầu, job, nguồn lực, quy trình
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  workspace: { $ref: "#/components/schemas/Workspace" }
  /projects:
    get:
      tags: [bootstrap]
      summary: Danh sách dự án
      responses: { "200": { description: OK } }
  /projects/{code}/summary:
    get:
      tags: [bootstrap]
      summary: KPI + mốc của dự án
      parameters:
        - { name: code, in: path, required: true, schema: { type: string } }
      responses: { "200": { description: OK } }
  /tasks:
    get:
      tags: [tasks]
      summary: Danh sách công việc
      parameters:
        - { name: project, in: query, required: true, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [backlog, todo, doing, review, done, blocked] } }
        - { name: type, in: query, schema: { type: string, enum: [task, milestone] } }
        - { name: limit, in: query, schema: { type: integer, default: 100 } }
      responses: { "200": { description: OK } }
  /tasks/{id}/context:
    get:
      tags: [tasks]
      summary: Ngữ cảnh đầy đủ của một việc
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: task + indicators + evidence + events + logs }
        "404": { description: Không tìm thấy việc }
  /tasks/{id}/claim:
    post:
      tags: [tasks]
      summary: Giữ việc (lease) — 409 nếu agent khác đang giữ
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl_minutes: { type: integer, default: 120, minimum: 15, maximum: 1440 }
                note: { type: string }
      responses:
        "200": { description: "Trả claim_token + expires_at" }
        "409": { description: already_claimed }
  /tasks/{id}/release:
    post:
      tags: [tasks]
      summary: Trả việc
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { "200": { description: OK }, "409": { description: not_owner } }
  /tasks/{id}/progress:
    post:
      tags: [tasks]
      summary: Cập nhật tiến độ/trạng thái
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [backlog, todo, doing, review, done, blocked] }
                progress: { type: integer, minimum: 0, maximum: 100 }
                message: { type: string }
      responses: { "200": { description: OK } }
  /tasks/{id}/deliverable:
    post:
      tags: [tasks]
      summary: Nộp kết quả (JSON markdown hoặc multipart file)
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                content: { type: string, description: Markdown }
                summary: { type: string }
                kind: { type: string, enum: [report, minutes, artifact, document, image, other] }
          multipart/form-data:
            schema:
              type: object
              properties:
                title: { type: string }
                kind: { type: string }
                summary: { type: string }
                file: { type: string, format: binary }
      responses:
        "200": { description: "evidence_id + task.status=review" }
        "422": { description: missing_content / upload_failed }
  /tasks/{id}:
    get:
      summary: Chi tiết một công việc (thuộc tính, việc con, tài chính, minh chứng)
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { '200': { description: OK } }
    post:
      summary: Cập nhật thuộc tính công việc
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [backlog, todo, doing, review, done, blocked] }
                progress: { type: integer, minimum: 0, maximum: 100 }
                due_date: { type: string, format: date }
                start_date: { type: string, format: date }
                location: { type: string }
                deliverables: { type: string }
                note: { type: string, description: "ghi chú nối thêm vào mô tả" }
                est_cost: { type: number }
      responses: { '200': { description: OK } }
  /tasks/{id}/cost:
    post:
      summary: Ghi khoản chi/thu/cam kết gắn với công việc
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount: { type: number }
                currency: { type: string, enum: [EUR, VND, USD] }
                kind: { type: string, enum: [income, expense, commitment] }
                date: { type: string, format: date }
                description: { type: string }
                category: { type: string }
                ref_no: { type: string }
      responses: { '200': { description: OK } }
  /events:
    post:
      summary: Thêm sự kiện (cuộc họp, tập huấn, báo cáo)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                date: { type: string, format: date }
                time: { type: string, description: "HH:MM" }
                kind: { type: string, enum: [meeting, training, report, other] }
                location: { type: string }
                participants: { type: string }
                notes: { type: string }
                project: { type: string }
      responses: { '200': { description: OK } }
  /requests/{id}/answer:
    post:
      summary: Trả lời một yêu cầu
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [answer]
              properties:
                answer: { type: string }
                status: { type: string, enum: [answered, closed] }
      responses: { '200': { description: OK } }
  /intake:
    post:
      summary: Phân tích văn bản thô (apply=false chỉ trả kế hoạch, không ghi)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string }
                project: { type: string }
                apply: { type: boolean, default: false }
                force: { type: boolean, description: "bỏ qua kiểm tra dán trùng" }
      responses:
        '200': { description: "intake{id,status,model,preview{changes,warnings},applied,skipped,duplicate}" }
        '202': { description: "Đã xếp hàng (apply=false, chế độ cũ)" }
    get:
      summary: Danh sách bản tiếp nhận gần đây
      responses: { '200': { description: OK } }
  /intake/{id}:
    get:
      summary: Chi tiết một bản tiếp nhận (analysis, preview, snapshot, warnings)
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { '200': { description: OK } }
  /intake/{id}/apply:
    post:
      summary: Duyệt ghi kế hoạch đã phân tích
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { '200': { description: OK } }
  /intake/{id}/revert:
    post:
      summary: Hoàn tác một lần ghi tiếp nhận
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { '200': { description: OK } }
  /requests:
    get:
      tags: [requests]
      summary: Yêu cầu dành cho agent
      parameters:
        - { name: status, in: query, schema: { type: string, default: open } }
        - { name: project, in: query, schema: { type: string } }
        - { name: direction, in: query, schema: { type: string, enum: [to_agent, from_agent], default: to_agent } }
      responses: { "200": { description: OK } }
    post:
      tags: [requests]
      summary: Agent hỏi / báo vướng mắc / đề xuất
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                body: { type: string }
                kind: { type: string, enum: [question, blocker, request, review] }
                priority: { type: string, enum: [low, normal, high] }
                project: { type: string }
                task_id: { type: integer }
      responses: { "200": { description: request_id } }
  /requests/{id}/accept:
    post:
      tags: [requests]
      summary: Nhận một yêu cầu chung
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { "200": { description: accepted }, "409": { description: assigned_other } }
  /resources:
    get:
      tags: [resources]
      summary: Danh mục nguồn lực (LLM/OCR/ASR/TTS) + token dịch vụ nếu scope=write
      responses: { "200": { description: OK } }
  /resources/{code}/check:
    post:
      tags: [resources]
      summary: Kiểm tra sức khoẻ một nguồn lực
      parameters:
        - { name: code, in: path, required: true, schema: { type: string } }
      responses: { "200": { description: "health: {ok, code, ms}" } }
  /docs:
    get:
      tags: [docs]
      summary: Danh mục tài liệu kỹ thuật (slug + URL công khai)
      responses: { "200": { description: OK } }
  /docs/{slug}:
    get:
      tags: [docs]
      summary: Nội dung một tài liệu kỹ thuật (markdown)
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string }, example: agent-claude }
      responses: { "200": { description: OK }, "404": { description: doc_not_found } }
  /documents:
    get:
      tags: [documents]
      summary: Tìm tài liệu dự án (minh chứng) theo từ khoá
      parameters:
        - { name: project, in: query, schema: { type: string } }
        - { name: q, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 20 } }
      responses: { "200": { description: OK } }
  /documents/{id}:
    get:
      tags: [documents]
      summary: Nội dung text đã bóc của tài liệu (PDF/DOCX/ảnh)
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { name: refresh, in: query, schema: { type: boolean }, description: bóc lại (cần scope write) }
      responses:
        "200": { description: "{method, cached, chars, text}" }
        "404": { description: evidence_not_found }
  /documents/{id}/extract:
    post:
      tags: [documents]
      summary: Bóc lại nội dung tài liệu
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses: { "200": { description: "{method, chars, text}" } }
  /evidence/{id}/file:
    get:
      tags: [evidence]
      summary: Tải tệp nguồn
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: Tệp nhị phân }
        "404": { description: evidence_not_found }
  /evidence:
    post:
      tags: [evidence]
      summary: Tải minh chứng (multipart hoặc base64)
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                project: { type: string }
                kind: { type: string }
                title: { type: string }
                file: { type: string, format: binary }
          application/json:
            schema:
              type: object
              properties:
                project: { type: string }
                kind: { type: string }
                title: { type: string }
                filename: { type: string }
                content_base64: { type: string }
      responses: { "200": { description: evidence_id } }
  /indicators:
    get:
      tags: [indicators]
      summary: Danh sách chỉ số + giá trị hiện tại
      parameters:
        - { name: project, in: query, required: true, schema: { type: string } }
      responses: { "200": { description: OK } }
  /indicators/{code}:
    post:
      tags: [indicators]
      summary: Ghi giá trị chỉ số
      parameters:
        - { name: code, in: path, required: true, schema: { type: string }, example: "6.1.2" }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [value]
              properties:
                value: { type: number }
                note: { type: string }
      responses: { "200": { description: OK } }
  /logs:
    post:
      tags: [logs]
      summary: Ghi nhật ký xử lý
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project, message]
              properties:
                project: { type: string }
                action: { type: string }
                message: { type: string }
                task_id: { type: integer }
                payload: { type: object }
      responses: { "200": { description: OK } }
  /reports:
    post:
      tags: [logs]
      summary: Nộp báo cáo (lưu thành minh chứng .md)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project, content]
              properties:
                project: { type: string }
                title: { type: string }
                content: { type: string }
                kind: { type: string }
                task_id: { type: integer }
      responses: { "200": { description: evidence_id } }
  /jobs:
    get:
      tags: [tasks]
      summary: Việc trong hàng đợi
      parameters:
        - { name: status, in: query, schema: { type: string, default: queued } }
      responses: { "200": { description: OK } }
    post:
      tags: [tasks]
      summary: Agent đề xuất việc mới
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                instruction: { type: string }
                project: { type: string }
      responses: { "200": { description: job_id } }
  /jobs/{id}:
    post:
      tags: [tasks]
      summary: Báo trạng thái/kết quả job
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [queued, running, done, failed, cancelled] }
                result: { type: string }
                tokens_in: { type: integer }
                tokens_out: { type: integer }
      responses: { "200": { description: OK } }
  /heartbeat:
    post:
      tags: [bootstrap]
      summary: Duy trì trạng thái agent (mỗi 5 phút)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [active, paused, offline] }
                note: { type: string }
      responses: { "200": { description: OK } }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: vtk_<48 hex>
  responses:
    Unauthorized:
      description: missing_token / invalid_token / expired / revoked
  schemas:
    Workspace:
      type: object
      properties:
        agent_id: { type: integer }
        project: { type: object }
        stats: { type: object }
        tasks: { type: array, items: { type: object } }
        requests: { type: array, items: { type: object } }
        jobs: { type: array, items: { type: object } }
        resources: { type: array, items: { type: object } }
        protocol: { type: object }
