sa-lessons/modules/module7/sections/05-technical-documentation.md

# Техническая документация

## Навигация
- [🏠 Главная страница курса](../../../README.md)
- [📚 Модуль 7](../README.md)

---

## Документация API

### 1. OpenAPI Specification
```yaml
openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0
  description: API for managing orders

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        status:
          type: string
          enum: [CREATED, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        totalAmount:
          type: number
          format: decimal
        createdAt:
          type: string
          format: date-time
```

### 2. API Documentation Tools
- **Swagger UI** — интерактивная документация
- **ReDoc** — альтернативный интерфейс
- **Postman** — коллекции и тесты

## Документация базы данных

### 1. Entity Relationship Diagrams
```plantuml
@startuml
title Order Database Schema

entity "users" {
    * id : UUID
    --
    * username : VARCHAR(50)
    * email : VARCHAR(100)
    * password_hash : VARCHAR(255)
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

entity "orders" {
    * id : UUID
    --
    * user_id : UUID
    * status : VARCHAR(20)
    * total_amount : DECIMAL(10,2)
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

entity "order_items" {
    * id : UUID
    --
    * order_id : UUID
    * product_id : UUID
    * quantity : INTEGER
    * unit_price : DECIMAL(10,2)
}

entity "products" {
    * id : UUID
    --
    * name : VARCHAR(100)
    * description : TEXT
    * price : DECIMAL(10,2)
    * stock_quantity : INTEGER
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

users ||--o{ orders : "places"
orders ||--o{ order_items : "contains"
products ||--o{ order_items : "referenced in"

@enduml
```

### 2. Data Dictionary
```markdown
# Data Dictionary

## Table: users

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY | Unique identifier for user |
| username | VARCHAR(50) | NOT NULL, UNIQUE | User's login name |
| email | VARCHAR(100) | NOT NULL, UNIQUE | User's email address |
| password_hash | VARCHAR(255) | NOT NULL | Hashed password |
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record update timestamp |

## Table: orders

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY | Unique identifier for order |
| user_id | UUID | NOT NULL, FOREIGN KEY | Reference to users.id |
| status | VARCHAR(20) | NOT NULL | Order status (CREATED, CONFIRMED, etc.) |
| total_amount | DECIMAL(10,2) | NOT NULL | Total order amount |
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record update timestamp |
```

## Заключение

Техническая документация является основой для понимания и поддержки системы:

1. **API документация** — OpenAPI спецификации и интерактивные инструменты
2. **Документация БД** — ER диаграммы и словари данных
3. **Структурированность** — четкая организация и стандартизация
4. **Актуальность** — регулярное обновление и синхронизация с кодом

Правильная техническая документация значительно упрощает разработку, тестирование и поддержку системы.