documentação do sistema

2026-05-05 16:12:52 -03:00
parent bbb5d68af1
commit 4652fea8fc
41 changed files with 1919 additions and 0 deletions
--- a/.context/docs/README.md
+++ b/.context/docs/README.md
@@ -0,0 +1,42 @@
+# Documentation Index
+
+Welcome to the repository knowledge base. Start with the project overview, then dive into specific guides as needed.
+
+## Core Guides
+- [Project Overview](./project-overview.md)
+- [Architecture Notes](./architecture.md)
+- [Development Workflow](./development-workflow.md)
+- [Testing Strategy](./testing-strategy.md)
+- [Glossary & Domain Concepts](./glossary.md)
+- [Security & Compliance Notes](./security.md)
+- [Tooling & Productivity Guide](./tooling.md)
+
+## Repository Snapshot
+- `angular.json/`
+- `browserslist/`
+- `docker-compose.yml/`
+- `Dockerfile/`
+- `e2e/`
+- `k8s/`
+- `karma.conf.js/`
+- `kendo-ui-license.txt/`
+- `nginx.conf/`
+- `package-lock.json/`
+- `package.json/`
+- `README.md/`
+- `src/` — TypeScript source files and CLI entrypoints.
+- `tsconfig.app.json/`
+- `tsconfig.json/`
+- `tsconfig.spec.json/`
+- `tslint.json/`
+
+## Document Map
+| Guide | File | Primary Inputs |
+| --- | --- | --- |
+| Project Overview | `project-overview.md` | Roadmap, README, stakeholder notes |
+| Architecture Notes | `architecture.md` | ADRs, service boundaries, dependency graphs |
+| Development Workflow | `development-workflow.md` | Branching rules, CI config, contributing guide |
+| Testing Strategy | `testing-strategy.md` | Test configs, CI gates, known flaky suites |
+| Glossary & Domain Concepts | `glossary.md` | Business terminology, user personas, domain rules |
+| Security & Compliance Notes | `security.md` | Auth model, secrets management, compliance requirements |
+| Tooling & Productivity Guide | `tooling.md` | CLI scripts, IDE configs, automation workflows |
--- a/.context/docs/architecture.md
+++ b/.context/docs/architecture.md
@@ -0,0 +1,61 @@
+---
+type: doc
+name: architecture
+description: System architecture, layers, patterns, and design decisions
+category: architecture
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Architecture Notes
+
+## System Architecture Overview
+The system is a modular frontend web application built using Angular. It follows a modular monolith architecture where features are grouped into specific modules such as `Sales`, `Partners`, `Financial`, and `CRM`. The application heavily relies on Redux-pattern state management (likely NgRx) to manage global state such as shopping carts, customer sales, and application data flow. Data is fetched via Angular services which communicate with a backend REST API.
+
+## Architectural Layers
+- **Components**: UI elements and pages organized by feature domain (`src/app/sales/`, `src/app/partners/`, `src/app/crm/`).
+- **Services**: Business logic and API communication layer (`src/app/services/`, `src/app/shared/services/`).
+- **Store / State Management**: Reducers, actions, and models handling complex state management (`src/app/sales/store/`).
+- **Models**: TypeScript interfaces and classes defining data structures (`src/app/models/`).
+- **Shared Utils**: Common messages, loading indicators, and validators (`src/app/shared/`).
+
+> See [`codebase-map.json`](./codebase-map.json) for complete symbol counts and dependency graphs.
+
+## Detected Design Patterns
+| Pattern | Confidence | Locations | Description |
+|---------|------------|-----------|-------------|
+| Module | 100% | `src/app/*.module.ts` | Angular feature modules for separation of concerns |
+| Redux / Store | 95% | `src/app/sales/store/` | State management using Actions, Reducers, and Store |
+| Dependency Injection | 100% | `src/app/services/` | Angular DI for injecting services into components |
+| Observable / Reactive | 90% | Services & Store | Heavy use of RxJS Observables for async data flows |
+
+## Entry Points
+- [AppModule](file:///d:/desenvolvimento/Simplifique/vendaweb/Vendaweb-portal/src/app/app.module.ts)
+- [AppComponent](file:///d:/desenvolvimento/Simplifique/vendaweb/Vendaweb-portal/src/app/app.component.ts)
+
+## Public API
+| Symbol | Type | Location |
+|--------|------|----------|
+| `AppModule` | Class | `src/app/app.module.ts` |
+| `SalesModule` | Class | `src/app/sales/sales.module.ts` |
+| `PartnersModule` | Class | `src/app/partners/partners.module.ts` |
+| `ShoppingReducer` | Function | `src/app/sales/store/reducers/shopping.reducer.ts` |
+
+## Internal System Boundaries
+The application is clearly separated into bounded contexts:
+- **Sales**: Core module handling product listings, shopping carts, checkout, and ordering.
+- **Partners**: Module for managing partner ranges, reports, and payments.
+- **CRM**: Module handling customer data, editing, and listing.
+- **Admin/Auth**: Authentication and user permission management.
+
+## Top Directories Snapshot
+- `src/app/sales/` (~50+ files)
+- `src/app/models/` (~40+ files)
+- `src/app/shared/` (~30+ files)
+- `src/app/partners/` (~20+ files)
+- `src/app/components/` (~10+ files)
+
+## Related Resources
+- [Project Overview](./project-overview.md)
+- [Data Flow](./data-flow.md)
--- a/.context/docs/codebase-map.json
+++ b/.context/docs/codebase-map.json
--- a/.context/docs/development-workflow.md
+++ b/.context/docs/development-workflow.md
@@ -0,0 +1,40 @@
+---
+type: doc
+name: development-workflow
+description: Day-to-day engineering processes, branching, and contribution guidelines
+category: workflow
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Development Workflow
+
+## Day-to-Day Process
+This Angular repository requires developers to implement features within their respective feature modules (e.g., `Sales`, `Partners`, `CRM`). Developers should ensure that all new services, components, and state management changes are properly typed using the `src/app/models` directory.
+
+## Branching & Releases
+We follow a standard Git workflow:
+- `main` / `master`: The stable production branch.
+- `develop`: The primary integration branch.
+- Feature branches: Created from `develop` using a standard naming convention like `feat/feature-name` or `bugfix/issue-description`.
+Commits should follow Conventional Commits (e.g., `feat(sales): add discount module`).
+
+## Local Development
+- Install dependencies: `npm install`
+- Run local development server: `npm start` or `npm run dev` (uses Angular CLI `ng serve`)
+- Run tests: `npm test`
+- Build for production: `npm run build`
+
+## Code Review Expectations
+- Ensure Angular best practices are followed (e.g., Unsubscribing from Observables, using `OnPush` change detection where applicable).
+- Avoid mutating state directly in components; use the Store actions.
+- Keep components small and focused, extracting complex business logic into Services.
+- All new features should include proper TypeScript models.
+
+## Onboarding Tasks
+New developers should begin by reading the `Project Overview` and familiarizing themselves with the `Sales` module, as it is the core of the application.
+
+## Cross-References
+- [Testing Strategy](./testing-strategy.md)
+- [Tooling](./tooling.md)
--- a/.context/docs/glossary.md
+++ b/.context/docs/glossary.md
@@ -0,0 +1,45 @@
+---
+type: doc
+name: glossary
+description: Project terminology, type definitions, domain entities, and business rules
+category: glossary
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Glossary & Domain Concepts
+
+## Glossary
+- **PreOrder (Pré-venda)**: An order created by a seller that has not yet been billed.
+- **Cart (Carrinho)**: A temporary collection of products a customer intends to purchase.
+- **Checkout**: The process of finalizing an order, choosing payment methods and installments.
+- **Seller (Vendedor)**: The user using the application to sell products to customers.
+- **Partner (Parceiro)**: A B2B entity that works with the company, has specific commission and range logic.
+- **Tintométrico**: A specific feature related to color mixing, usually for paint products.
+
+## Type Definitions
+- `Customer` (src/app/models/customer.model.ts)
+- `Product` (src/app/models/product.model.ts)
+- `Order` (src/app/models/order.model.ts)
+- `PreOrder` (src/app/models/pre-order.model.ts)
+- `CartModel` (src/app/models/cart.model.ts)
+- `SaleProduct` (src/app/models/sale-product.model.ts)
+
+## Enumerations
+- `ShoppingActionTypes` (src/app/sales/store/actions/shopping.action.ts)
+- `CustomerSaleActionTypes` (src/app/sales/store/actions/customer-sale.action.ts)
+
+## Core Terms
+- **State/Store**: Refers to the application's global Redux state (NgRx) which holds the current customer, cart contents, and authentication status.
+- **CRM**: Customer Relationship Management section where sellers can view, create, or edit customer profiles.
+
+## Personas / Actors
+- **Seller (Vendedor)**: Wants to quickly look up products, add them to a cart, apply discounts, and checkout on behalf of a customer.
+- **Admin**: Configures permissions, views high-level dashboard KPIs.
+- **Partner (Parceiro)**: Checks commissions, extracts, and ranges.
+
+## Domain Rules & Invariants
+- A cart must be associated with a customer before checkout.
+- Discounts are governed by specific authorization roles.
+- The `Tintométrico` module calculates specific prices based on color compositions.
--- a/.context/docs/project-overview.md
+++ b/.context/docs/project-overview.md
@@ -0,0 +1,49 @@
+---
+type: doc
+name: project-overview
+description: High-level overview of the project, its purpose, and key components
+category: overview
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Project Overview
+This project is an Angular-based B2B/B2C Sales Portal (VendaWeb). It empowers sellers to manage customers, browse product catalogs, assemble carts, and process orders, while also offering CRM, Partner Management, and administrative capabilities.
+
+> **Detailed Analysis**: For complete symbol counts, architecture layers, and dependency graphs, see [`codebase-map.json`](./codebase-map.json).
+
+## Quick Facts
+- **Root**: `/`
+- **Languages**: TypeScript, HTML, SCSS
+- **Framework**: Angular
+- **State Management**: NgRx (Redux pattern)
+
+## Entry Points
+- [AppModule](file:///d:/desenvolvimento/Simplifique/vendaweb/Vendaweb-portal/src/app/app.module.ts)
+- [main.ts](file:///d:/desenvolvimento/Simplifique/vendaweb/Vendaweb-portal/src/main.ts)
+
+## Key Exports
+- `AppModule`
+- `SalesModule`
+- `PartnersModule`
+
+## File Structure & Code Organization
+- `src/app/sales/` — Core point-of-sale functionality (cart, products, checkout).
+- `src/app/crm/` — Customer management interfaces.
+- `src/app/partners/` — Partner reporting, commissions, and management.
+- `src/app/financial/` — Financial operations and checkout.
+- `src/app/models/` — TypeScript interfaces representing business entities.
+- `src/app/shared/` — Reusable UI components, interceptors, and services.
+- `src/app/auth/` — Authentication and login flows.
+
+## Technology Stack Summary
+- **Frontend**: Angular
+- **State**: NgRx Store
+- **Styling**: SCSS, Kendo UI (`kendo-ui-license.txt` indicates Kendo usage)
+- **Tooling**: Angular CLI, TypeScript, npm
+
+## Getting Started Checklist
+1. Install dependencies with `npm install`.
+2. Run the application locally with `npm run start` or `ng serve`.
+3. Navigate to `http://localhost:4200` to view the app.
--- a/.context/docs/qa/README.md
+++ b/.context/docs/qa/README.md
@@ -0,0 +1,23 @@
+# Q&A Index
+
+Project type: **web-app**
+
+Generated: 2026-04-29T20:15:44.291Z
+
+## Getting-started
+
+- [How do I set up and run this project?](./getting-started.md)
+
+## Architecture
+
+- [How is the codebase organized?](./project-structure.md)
+
+## Features
+
+- [How does authentication work?](./authentication.md)
+- [How is data stored and accessed?](./database.md)
+- [What API endpoints are available?](./api-endpoints.md)
+
+## Operations
+
+- [How do I deploy this project?](./deployment.md)
--- a/.context/docs/qa/api-endpoints.md
+++ b/.context/docs/qa/api-endpoints.md
@@ -0,0 +1,11 @@
+---
+slug: api-endpoints
+category: features
+generatedAt: 2026-04-29T20:15:39.516Z
+---
+
+# What API endpoints are available?
+
+## API Endpoints
+
+### Detected API Files
--- a/.context/docs/qa/authentication.md
+++ b/.context/docs/qa/authentication.md
@@ -0,0 +1,23 @@
+---
+slug: authentication
+category: features
+generatedAt: 2026-04-29T20:15:39.516Z
+relevantFiles:
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\guards\auth.guard.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\auth\auth-login\auth-login.component.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\auth\auth.module.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\auth\services\auth.service.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\shared\messages\auth-user\auth-user.component.ts
+---
+
+# How does authentication work?
+
+## Authentication
+
+### Implementation Details
+
+- Auth-related symbol: AuthGuard
+- Auth-related symbol: AuthLoginComponent
+- Auth-related symbol: AuthModule
+- Auth-related symbol: AuthService
+- Auth-related symbol: AuthUserComponent
--- a/.context/docs/qa/database.md
+++ b/.context/docs/qa/database.md
@@ -0,0 +1,22 @@
+---
+slug: database
+category: features
+generatedAt: 2026-04-29T20:15:39.516Z
+relevantFiles:
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\sales\store\models\action.model.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\models\cart-itens.model.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\models\cart.model.ts
+  - C:\Users\luis.estevao\AppData\Local\Programs\Antigravity\src\app\sales\components\create-customer-modal\create-customer-modal.component.ts
+---
+
+# How is data stored and accessed?
+
+## Database
+
+### Implementation Details
+
+- Database-related symbol: ActionModel
+- Database-related symbol: CartItensModel
+- Database-related symbol: CartModel
+- Database-related symbol: JsonModel
+- Data layer detected in architecture
--- a/.context/docs/qa/deployment.md
+++ b/.context/docs/qa/deployment.md
@@ -0,0 +1,21 @@
+---
+slug: deployment
+category: operations
+generatedAt: 2026-04-29T20:15:44.246Z
+relevantFiles:
+  - docker-compose.yml
+  - Dockerfile
+---
+
+# How do I deploy this project?
+
+## Deployment
+
+### Docker
+
+This project includes Docker configuration.
+
+```bash
+docker build -t app .
+docker run -p 3000:3000 app
+```
--- a/.context/docs/qa/getting-started.md
+++ b/.context/docs/qa/getting-started.md
@@ -0,0 +1,32 @@
+---
+slug: getting-started
+category: getting-started
+generatedAt: 2026-04-29T20:11:48.572Z
+---
+
+# How do I set up and run this project?
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (LTS version recommended)
+- npm
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd Vendaweb-portal
+
+# Install dependencies
+npm install
+```
+
+### Running
+
+```bash
+# See package.json for available scripts
+npm run <script-name>
+```
--- a/.context/docs/qa/project-structure.md
+++ b/.context/docs/qa/project-structure.md
@@ -0,0 +1,15 @@
+---
+slug: project-structure
+category: architecture
+generatedAt: 2026-04-29T20:15:39.515Z
+---
+
+# How is the codebase organized?
+
+## Project Structure
+
+```
+e2e/
+k8s/
+src/
+```
--- a/.context/docs/security.md
+++ b/.context/docs/security.md
@@ -0,0 +1,25 @@
+---
+type: doc
+name: security
+description: Security policies, authentication, secrets management, and compliance requirements
+category: security
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Security & Compliance Notes
+
+## Authentication & Authorization
+The application uses JWT (JSON Web Tokens) for authentication. 
+- The `AuthModule` handles user login (`AuthLoginComponent`).
+- An `AuthGuard` is implemented to protect specific routes, ensuring that unauthenticated users are redirected to the login page.
+- Role-based access control (RBAC) is implemented via `PermissionUser` components and specific guards.
+
+## Secrets & Sensitive Data
+- Environment variables (`src/environments/`) contain API endpoints.
+- Avoid hardcoding tokens or sensitive keys directly into the source code.
+- JWT tokens are stored in `localStorage` or `sessionStorage` and attached to outgoing requests via an HttpInterceptor.
+
+## Cross-References
+- [Architecture](./architecture.md)
--- a/.context/docs/testing-strategy.md
+++ b/.context/docs/testing-strategy.md
@@ -0,0 +1,25 @@
+---
+type: doc
+name: testing-strategy
+description: Test frameworks, patterns, coverage requirements, and quality gates
+category: testing
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Testing Strategy
+
+## Test Types
+- **Unit**: Jasmine and Karma, files named `*.spec.ts`.
+- **E2E**: Protractor (`e2e/` folder), files named `*.e2e-spec.ts`.
+
+## Running Tests
+- All tests: `npm run test` or `ng test`
+- E2E tests: `npm run e2e` or `ng e2e`
+- Watch mode: `npm run test -- --watch`
+
+## Quality Gates
+- Components should have accompanying `.spec.ts` files ensuring fundamental rendering and interactions.
+- NgRx reducers and effects must be covered by unit tests.
+- TypeScript strict typing helps catch compile-time issues before tests even run.
--- a/.context/docs/tooling.md
+++ b/.context/docs/tooling.md
@@ -0,0 +1,33 @@
+---
+type: doc
+name: tooling
+description: Scripts, IDE settings, automation, and developer productivity tips
+category: tooling
+generated: 2026-04-29
+status: active
+scaffoldVersion: "2.0.0"
+---
+
+# Tooling & Productivity Guide
+
+## Required Tooling
+- **Node.js**: The JavaScript runtime.
+- **npm**: Package manager.
+- **Angular CLI**: Install globally via `npm install -g @angular/cli`.
+
+## Recommended Automation
+- Formatting: Prettier/ESLint integration should be configured.
+- Scaffolding: Use Angular CLI to generate boilerplate.
+  - Generate component: `ng g c component-name`
+  - Generate service: `ng g s service-name`
+
+## IDE / Editor Setup
+- **VS Code** is highly recommended.
+- **Extensions**:
+  - Angular Language Service
+  - ESLint
+  - Prettier
+  - NgRx Snippets
+
+## Productivity Tips
+- Utilize the Redux DevTools extension in your browser to debug NgRx state changes in real-time.