Agregar documentacion completa del proyecto

- README.md actualizado con descripcion detallada del sistema - DOCUMENTATION.md con documentacion tecnica exhaustiva Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-18 04:58:02 +00:00
parent 143cd77cee
commit 2b5735d78d
2 changed files with 976 additions and 20 deletions
--- a/README.md
+++ b/README.md
@@ -1,30 +1,375 @@
-# React + TypeScript + Vite
+# Water Project - Sistema de Gestion de Recursos Hidricos (GRH)

-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Sistema de gestion y monitoreo de infraestructura hidrica desarrollado con React, TypeScript y Vite.

-Currently, two official plugins are available:
+## Descripcion General

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+El **Sistema de Gestion de Recursos Hidricos (GRH)** es una aplicacion web frontend disenada para el monitoreo, administracion y control de infraestructura de toma de agua. Permite gestionar medidores, concentradores, proyectos, usuarios y roles a traves de una interfaz moderna y responsiva.

-## Expanding the ESLint configuration
+### Caracteristicas Principales

-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+- **Dashboard interactivo** con KPIs, alertas e historial de actividades
+- **Gestion de Medidores (Tomas de Agua)** - CRUD completo con filtros por proyecto
+- **Gestion de Concentradores** - Configuracion de gateways LoRa/LoRaWAN
+- **Gestion de Proyectos** - Administracion de proyectos de infraestructura
+- **Gestion de Usuarios y Roles** - Control de acceso al sistema
+- **Tema claro/oscuro** - Personalizacion de la interfaz
+- **Diseno responsive** - Compatible con desktop, tablet y movil

- Configure the top-level `parserOptions` property like this:
+---

-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-  },
+## Stack Tecnologico
+
+### Frontend
+| Tecnologia | Version | Proposito |
+|------------|---------|-----------|
+| React | 18.2.0 | Framework UI |
+| TypeScript | 5.2.2 | Type safety |
+| Vite | 5.2.0 | Build tool y dev server |
+| Tailwind CSS | 4.1.18 | Estilos utility-first |
+| Material-UI | 7.3.6 | Componentes UI |
+| Recharts | 3.6.0 | Visualizacion de datos |
+| Lucide React | 0.559.0 | Iconos SVG |
+
+### Herramientas de Desarrollo
+- **ESLint** - Linting de codigo
+- **TypeScript ESLint** - Analisis estatico
+
+---
+
+## Instalacion
+
+### Prerrequisitos
+
+- Node.js >= 18.x
+- npm >= 9.x o yarn >= 1.22
+
+### Pasos de Instalacion
+
+1. **Clonar el repositorio**
+```bash
+git clone <url-del-repositorio>
+cd water-project
+```
+
+2. **Instalar dependencias**
+```bash
+npm install
+```
+
+3. **Configurar variables de entorno**
+```bash
+cp .env.example .env
+```
+
+Editar el archivo `.env`:
+```env
+VITE_API_BASE_URL=https://tu-api-url.com
+VITE_API_TOKEN=tu-token-de-api
+```
+
+4. **Iniciar servidor de desarrollo**
+```bash
+npm run dev
+```
+
+La aplicacion estara disponible en `http://localhost:5173`
+
+---
+
+## Scripts Disponibles
+
+| Comando | Descripcion |
+|---------|-------------|
+| `npm run dev` | Inicia el servidor de desarrollo |
+| `npm run build` | Compila TypeScript y genera build de produccion |
+| `npm run preview` | Previsualiza el build de produccion |
+| `npm run lint` | Ejecuta ESLint en el codigo |
+
+---
+
+## Estructura del Proyecto
+
+```
+water-project/
+├── public/                          # Assets estaticos
+│   └── grhWatermark.jpg
+│
+├── src/
+│   ├── api/                        # Capa de comunicacion con API
+│   │   ├── me.ts                   # Endpoints de perfil
+│   │   ├── meters.ts               # CRUD de medidores
+│   │   ├── concentrators.ts        # CRUD de concentradores
+│   │   └── projects.ts             # CRUD de proyectos
+│   │
+│   ├── components/
+│   │   ├── layout/                 # Componentes de layout
+│   │   │   ├── Sidebar.tsx         # Menu lateral
+│   │   │   ├── TopMenu.tsx         # Barra superior
+│   │   │   └── common/             # Componentes reutilizables
+│   │   │       ├── ProfileModal.tsx
+│   │   │       ├── ConfirmModal.tsx
+│   │   │       └── Watermark.tsx
+│   │   └── SettingsModals.tsx
+│   │
+│   ├── pages/                      # Paginas principales
+│   │   ├── Home.tsx                # Dashboard
+│   │   ├── LoginPage.tsx           # Login
+│   │   ├── UsersPage.tsx           # Gestion de usuarios
+│   │   ├── RolesPage.tsx           # Gestion de roles
+│   │   ├── projects/
+│   │   │   └── ProjectsPage.tsx
+│   │   ├── meters/                 # Modulo de medidores
+│   │   │   ├── MeterPage.tsx
+│   │   │   ├── useMeters.ts        # Hook personalizado
+│   │   │   ├── MetersTable.tsx
+│   │   │   ├── MetersModal.tsx
+│   │   │   └── MetersSidebar.tsx
+│   │   └── concentrators/          # Modulo de concentradores
+│   │       ├── ConcentratorsPage.tsx
+│   │       ├── useConcentrators.ts
+│   │       ├── ConcentratorsTable.tsx
+│   │       ├── ConcentratorsModal.tsx
+│   │       └── ConcentratorsSidebar.tsx
+│   │
+│   ├── assets/
+│   │   └── images/
+│   │
+│   ├── App.tsx                     # Componente raiz
+│   ├── main.tsx                    # Punto de entrada
+│   └── index.css                   # Estilos globales
+│
+├── index.html
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── .env.example
+```
+
+---
+
+## Modulos Funcionales
+
+### 1. Dashboard (Home)
+
+El dashboard principal ofrece:
+- Selector de organismos operadores (CESPT TIJUANA, TECATE, MEXICALI)
+- Grafico de barras: "Numero de Medidores por Proyecto"
+- Tarjetas de acceso rapido: Tomas, Alertas, Mantenimiento, Reportes
+- Historial reciente de actividades
+- Panel de ultimas alertas
+
+### 2. Gestion de Medidores
+
+Modulo completo para administrar medidores/tomas de agua:
+
+**Funcionalidades:**
+- Listado con busqueda y filtros
+- Filtrado por proyecto
+- Tipos de toma: GENERAL, LORA, LORAWAN, GRANDES
+- CRUD completo (Crear, Leer, Actualizar, Eliminar)
+
+**Campos principales:**
+- Area, Numero de cuenta, Usuario, Direccion
+- Serial del medidor, Nombre, Estado
+- Tipo de protocolo, Particion DMA
+- Configuracion de dispositivo (Device EUI, AppKey, etc.)
+
+### 3. Gestion de Concentradores
+
+Administracion de concentradores y gateways:
+
+**Funcionalidades:**
+- Listado con filtros por proyecto
+- Configuracion de Gateway (ID, EUI, Nombre)
+- Seleccion de ubicacion de antena (Indoor/Outdoor)
+- CRUD completo
+
+### 4. Gestion de Proyectos
+
+Administracion de proyectos de infraestructura:
+- Tabla con busqueda integrada
+- Estados: ACTIVE/INACTIVE
+- Informacion de operador y tiempos
+
+### 5. Gestion de Usuarios
+
+Control de usuarios del sistema:
+- Listado de usuarios
+- Asignacion de roles
+- Estados: ACTIVE/INACTIVE
+
+### 6. Gestion de Roles
+
+Administracion de roles de acceso:
+- Roles predefinidos: SUPER_ADMIN, USER
+- Descripcion de permisos
+
+---
+
+## API y Comunicacion
+
+### Configuracion
+
+La aplicacion se conecta a una API REST externa. Configurar en `.env`:
+
+```env
+VITE_API_BASE_URL=https://tu-api.com
+VITE_API_TOKEN=tu-token
+```
+
+### Endpoints Principales
+
+| Recurso | Endpoint Base |
+|---------|---------------|
+| Medidores | `/api/v3/data/.../m4hzpnopjkppaav/records` |
+| Concentradores | `/api/v3/data/.../mheif1vdgnyt8x2/records` |
+| Proyectos | `/api/v3/data/.../m9882vn3xb31e29/records` |
+
+### Estructura de Respuesta
+
+```typescript
+interface ApiResponse<T> {
+  records: Array<{
+    id: string;
+    fields: T;
+  }>;
+  next?: string;
+  prev?: string;
 }
 ```

- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+---
+
+## Modelos de Datos
+
+### Meter (Medidor)
+
+```typescript
+interface Meter {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  areaName: string;
+  accountNumber: string | null;
+  userName: string | null;
+  userAddress: string | null;
+  meterSerialNumber: string;
+  meterName: string;
+  meterStatus: string;
+  protocolType: string;
+  priceNo: string | null;
+  priceName: string | null;
+  dmaPartition: string | null;
+  supplyTypes: string;
+  deviceId: string;
+  deviceName: string;
+  deviceType: string;
+  usageAnalysisType: string;
+  installedTime: string;
+}
+```
+
+### Concentrator
+
+```typescript
+interface Concentrator {
+  id: string;
+  "Area Name": string;
+  "Device S/N": string;
+  "Device Name": string;
+  "Device Time": string;
+  "Device Status": string;
+  "Operator": string;
+  "Installed Time": string;
+  "Communication Time": string;
+  "Instruction Manual": string;
+}
+```
+
+### Project
+
+```typescript
+interface Project {
+  id: string;
+  areaName: string;
+  deviceSN: string;
+  deviceName: string;
+  deviceType: string;
+  deviceStatus: "ACTIVE" | "INACTIVE";
+  operator: string;
+  installedTime: string;
+  communicationTime: string;
+}
+```
+
+---
+
+## Autenticacion
+
+### Flujo de Login
+
+1. Usuario ingresa credenciales
+2. Validacion del checkbox "No soy un robot"
+3. Token almacenado en `localStorage` (`grh_auth`)
+4. Redireccion al Dashboard
+
+### Almacenamiento
+
+```javascript
+// localStorage keys
+grh_auth: { token: string, ts: number }
+water_project_settings_v1: { theme: string, compactMode: boolean }
+```
+
+---
+
+## Configuracion de Temas
+
+El sistema soporta tres modos de tema:
+- **Sistema** - Detecta preferencia del OS
+- **Claro** - Tema light
+- **Oscuro** - Tema dark
+
+Configuracion persistida en `localStorage` bajo `water_project_settings_v1`.
+
+---
+
+## Despliegue
+
+### Build de Produccion
+
+```bash
+npm run build
+```
+
+Los archivos compilados se generan en la carpeta `dist/`.
+
+### Configuracion de Vite
+
+El servidor de desarrollo esta configurado para:
+- Puerto: 5173
+- Host: habilitado para acceso remoto
+- Hosts permitidos: localhost, 127.0.0.1, dominios personalizados
+
+---
+
+## Contribucion
+
+1. Fork del repositorio
+2. Crear rama feature (`git checkout -b feature/nueva-funcionalidad`)
+3. Commit de cambios (`git commit -m 'Agregar nueva funcionalidad'`)
+4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
+5. Crear Pull Request
+
+---
+
+## Licencia
+
+Este proyecto es privado y pertenece a GRH - Gestion de Recursos Hidricos.
+
+---
+
+## Contacto
+
+Para soporte o consultas sobre el sistema, contactar al equipo de desarrollo.