table structure docs are made

common/src/proto/komp_ac.table_structure.rs

@@ -1,27 +1,46 @@
 // This file is @generated by prost-build.
+/// Request identifying the profile (schema) and table to inspect.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableStructureRequest {
-    /// e.g., "default"
+    /// Required. Profile (PostgreSQL schema) name. Must exist in `schemas`.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
-    /// e.g., "2025_adresar6"
+    /// Required. Table name within the profile. Must exist in `table_definitions`
+    /// for the given profile. The physical table is then introspected via
+    /// information_schema.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
 }
+/// Response with the ordered list of columns (by ordinal position).
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct 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.
     #[prost(message, repeated, tag = "1")]
     pub columns: ::prost::alloc::vec::Vec<TableColumn>,
 }
+/// One physical column entry as reported by information_schema.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TableColumn {
+    /// Column name exactly as defined in PostgreSQL.
     #[prost(string, tag = "1")]
     pub name: ::prost::alloc::string::String,
-    /// 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)"
     #[prost(string, tag = "2")]
     pub data_type: ::prost::alloc::string::String,
+    /// True if information_schema reports the column as nullable.
     #[prost(bool, tag = "3")]
     pub is_nullable: bool,
+    /// True if the column is part of the table's PRIMARY KEY.
+    /// Typically true for the "id" column created by the system.
     #[prost(bool, tag = "4")]
     pub is_primary_key: bool,
 }
@@ -36,6 +55,14 @@ pub mod table_structure_service_client {
     )]
     use tonic::codegen::*;
     use tonic::codegen::http::Uri;
+    /// 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.
     #[derive(Debug, Clone)]
     pub struct TableStructureServiceClient<T> {
         inner: tonic::client::Grpc<T>,
@@ -116,6 +143,16 @@ pub mod table_structure_service_client {
             self.inner = self.inner.max_encoding_message_size(limit);
             self
         }
+        /// 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)
         pub async fn get_table_structure(
             &mut self,
             request: impl tonic::IntoRequest<super::GetTableStructureRequest>,
@@ -160,6 +197,16 @@ pub mod table_structure_service_server {
     /// Generated trait containing gRPC methods that should be implemented for use with TableStructureServiceServer.
     #[async_trait]
     pub trait TableStructureService: std::marker::Send + std::marker::Sync + 'static {
+        /// 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)
         async fn get_table_structure(
             &self,
             request: tonic::Request<super::GetTableStructureRequest>,
@@ -168,6 +215,14 @@ pub mod table_structure_service_server {
             tonic::Status,
         >;
     }
+    /// 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.
     #[derive(Debug)]
     pub struct TableStructureServiceServer<T> {
         inner: Arc<T>,