table structure docs are made

common/proto/table_structure.proto

@@ -1,25 +1,70 @@
-// proto/table_structure.proto
+// common/proto/table_structure.proto
 syntax = "proto3";
 package komp_ac.table_structure;
 
 import "common.proto";
 
-message GetTableStructureRequest {
-  string profile_name = 1; // e.g., "default"
-  string table_name = 2;   // e.g., "2025_adresar6"
+// Introspects the physical PostgreSQL table for a given logical table
+// (defined in table_definitions) and returns its column structure.
+// The server validates that:
+// - The profile (schema) exists in `schemas`
+// - The table is defined for that profile in `table_definitions`
+// It then queries information_schema for the physical table and returns
+// normalized column metadata. If the physical table is missing despite
+// a definition, the response may contain an empty `columns` list.
+service TableStructureService {
+  // Return the physical column list (name, normalized data_type,
+  // nullability, primary key flag) for a table in a profile.
+  //
+  // Behavior:
+  // - NOT_FOUND if profile doesn't exist in `schemas`
+  // - NOT_FOUND if table not defined for that profile in `table_definitions`
+  // - Queries information_schema.columns ordered by ordinal position
+  // - Normalizes data_type text (details under TableColumn.data_type)
+  // - Returns an empty list if the table is validated but has no visible
+  //   columns in information_schema (e.g., physical table missing)
+  rpc GetTableStructure(GetTableStructureRequest)
+      returns (TableStructureResponse);
 }
 
+// Request identifying the profile (schema) and table to inspect.
+message GetTableStructureRequest {
+  // Required. Profile (PostgreSQL schema) name. Must exist in `schemas`.
+  string profile_name = 1;
+
+  // Required. Table name within the profile. Must exist in `table_definitions`
+  // for the given profile. The physical table is then introspected via
+  // information_schema.
+  string table_name = 2;
+}
+
+// Response with the ordered list of columns (by ordinal position).
 message TableStructureResponse {
+  // Columns of the physical table, including system columns (id, deleted,
+  // created_at), user-defined columns, and any foreign-key columns such as
+  // "<linked_table>_id". May be empty if the physical table is missing.
   repeated TableColumn columns = 1;
 }
 
+// One physical column entry as reported by information_schema.
 message TableColumn {
+  // Column name exactly as defined in PostgreSQL.
   string name = 1;
-  string data_type = 2; // e.g., "TEXT", "BIGINT", "VARCHAR(255)", "TIMESTAMPTZ"
+
+  // Normalized data type string derived from information_schema:
+  // - VARCHAR(n) when udt_name='varchar' with character_maximum_length
+  // - CHAR(n) when udt_name='bpchar' with character_maximum_length
+  // - NUMERIC(p,s) when udt_name='numeric' with precision and scale
+  // - NUMERIC(p) when udt_name='numeric' with precision only
+  // - <TYPE>[] for array types (udt_name starting with '_', e.g., INT[] )
+  // - Otherwise UPPER(udt_name), e.g., TEXT, BIGINT, TIMESTAMPTZ
+  // Examples: "TEXT", "BIGINT", "VARCHAR(255)", "TIMESTAMPTZ", "NUMERIC(14,4)"
+  string data_type = 2;
+
+  // True if information_schema reports the column as nullable.
   bool is_nullable = 3;
+
+  // True if the column is part of the table's PRIMARY KEY.
+  // Typically true for the "id" column created by the system.
   bool is_primary_key = 4;
 }
-
-service TableStructureService {
-  rpc GetTableStructure (GetTableStructureRequest) returns (TableStructureResponse);
-}