import { tags } from "typia";

import { AutoBeOpenApi } from "../openapi/AutoBeOpenApi";
import { AutoBeAgentHistoryBase } from "./AutoBeHistoryBase";
import { AutoBeInterfaceAuthorization } from "./contents";
import { AutoBeProcessAggregateCollection } from "./contents/AutoBeProcessAggregateCollection";

/**
 * History record generated when the Interface agent completes RESTful API
 * design based on the previous requirements analysis report and database
 * design.
 *
 * The Interface agent constructs data of type {@link AutoBeOpenApi.IDocument}
 * through AI function calling, validates it, and stores it in the document
 * property. This is then converted to a formal OpenAPI document, and NestJS API
 * controllers, DTOs, and e2e test code are generated through the sophisticated
 * multi-stage transformation pipeline.
 *
 * The Interface agent operates on the same vibe coding principles as other
 * agents, ensuring that API designs are syntactically perfect and semantically
 * aligned with business requirements before any code generation occurs.
 *
 * @author Samchon
 */
export interface AutoBeInterfaceHistory extends AutoBeAgentHistoryBase<"interface"> {
  /**
   * The constructed OpenAPI document containing the complete API specification.
   *
   * Contains the validated {@link AutoBeOpenApi.IDocument} AST structure that
   * defines all API endpoints, operations, schemas, and business logic. This
   * document serves as the source of truth for API generation and ensures
   * perfect alignment between database schemas and API interfaces.
   *
   * The document includes comprehensive business logic integration, type safety
   * bridges with database schemas, and security pattern validation to ensure
   * enterprise-grade API specifications.
   */
  document: AutoBeOpenApi.IDocument;

  /**
   * JWT-based authentication and authorization operations generated for each
   * user role.
   *
   * Contains role-specific authentication API operations including essential
   * flows (join, login, validate, changePassword, refresh) plus additional
   * operations based on database schema capabilities like email verification
   * and password reset. These operations are generated by analyzing the
   * database schema to determine which authentication features are supported
   * for each role.
   */
  authorizations: AutoBeInterfaceAuthorization[];

  /**
   * Instructions for the Interface agent redefined by AI from user's utterance.
   *
   * Contains AI-generated specific guidance for the API design phase,
   * interpreted and refined from the user's original request. These
   * instructions direct the Interface agent on how to approach RESTful API
   * design, which endpoints to expose, operation patterns to follow, and
   * security requirements to implement based on the business context.
   */
  instruction: string;

  /**
   * Array of schema type names that are referenced but not yet implemented in
   * components.schemas.
   *
   * When this array is not empty, it indicates critical missing type
   * definitions that will cause cascading failures throughout the entire
   * compilation pipeline:
   *
   * - Interface compilation will fail due to unresolved type references
   * - Test code generation will fail due to missing DTO types
   * - Realize agent cannot implement endpoints without proper type definitions
   * - TypeScript compilation will ultimately fail with "Cannot find name" errors
   *
   * This represents a fundamental incompleteness in the OpenAPI specification
   * that must be resolved before any subsequent development phases can proceed.
   * The Interface agent will attempt to automatically generate these missing
   * schemas through the complement process.
   */
  missed: string[];

  aggregates: AutoBeProcessAggregateCollection<"interface">;

  /**
   * Iteration number of the requirements analysis report this API design was
   * performed for.
   *
   * Indicates which version of the requirements analysis this API design
   * reflects. If this value is lower than {@link AutoBeAnalyzeHistory.step}, it
   * means the API design has not yet been updated to reflect the latest
   * requirements and may need to be regenerated.
   *
   * A value of 0 indicates the initial API design, while higher values
   * represent subsequent revisions based on updated requirements or database
   * schema changes.
   */
  step: number;

  /**
   * ISO 8601 timestamp indicating when the API design process was completed.
   *
   * Marks the exact moment when the Interface agent finished the complete
   * transformation pipeline from AST construction through OpenAPI validation to
   * NestJS code generation. This timestamp is crucial for tracking the
   * development timeline and determining the currency of the API design
   * relative to other development artifacts.
   */
  completed_at: string & tags.Format<"date-time">;
}