First commit

2026-02-19 17:54:50 +03:30
commit 4b0749b0d7
16 changed files with 616 additions and 0 deletions
@@ -0,0 +1,74 @@
+---
+alwaysApply: false
+---
+# Backend API Architecture & Postman
+
+## 1. URL / Routing Architecture
+
+- **Root (config/urls.py):** API mounts under `api/<app-prefix>/` via `include()`.
+  - Example: `path("api/auth/", include("auth.urls"))`, `path("api/sensor-hub/", include("sensor_hub.urls"))`.
+  - App prefix: kebab-case (e.g. `sensor-hub`).
+
+- **App URLs (each app’s urls.py):** Only endpoint definitions with `path()`.
+  - Same view can be used for several paths; distinguish by path or `kwargs` (e.g. `kwargs={"action": "active"}`).
+  - Order matters: more specific paths first (e.g. `active/`, `deactive/`), then path-param routes (e.g. `<uuid:uuid>/`), then base `""` for list.
+  - Example pattern:
+    - `path("active/", View.as_view(), kwargs={"action": "active"})`
+    - `path("deactive/", View.as_view(), kwargs={"action": "deactive"})`
+    - `path("<uuid:uuid>/", View.as_view(), name="...-detail")`
+    - `path("", View.as_view(), name="...-list")`
+
+- **Views:** One `APIView` per resource (or per flow, e.g. auth). Dispatch by HTTP method and optionally by `request.path` or `kwargs` (e.g. `uuid`, `action`). No business logic in views; orchestration only.
+
+---
+
+## 2. Postman Collection Layout
+
+- **Placement:** One collection per app: `<app_name>/postman/<collection_name>.json` (e.g. `sensor_hub/postman/sensor_hub.json`, `auth/postman/postman.json`).
+
+- **Structure:**
+  - `info`: `name`, `schema` (v2.1.0), optional `description`.
+  - `item`: array of requests (one per endpoint variant/method).
+  - `variable`: at least `baseUrl` (e.g. `http://localhost:8000`); add `token`, `uuid` etc. when needed.
+
+- **Request style:**
+  - One base URL per resource; multiple requests for different methods or path params (e.g. list vs `{{uuid}}/`).
+  - URL: `{{baseUrl}}/api/<app-prefix>/...` (e.g. `{{baseUrl}}/api/sensor-hub/`, `{{baseUrl}}/api/sensor-hub/{{uuid}}/`).
+  - Auth: where required, header `Authorization: Bearer {{token}}`.
+  - No random/dynamic values in body or response examples.
+
+---
+
+## 3. Postman Request Generator (when I give you routes)
+
+Your task is to take the API routes I provide and convert them into a valid Postman collection JSON (as above).
+
+ROUTE STYLE:
+- When routes are defined as a single URL with different HTTP methods, generate one base URL and multiple requests (one per method/variant). Use the same URL for all; use path params (e.g. `<uuid>/`) or query for GET detail vs list when applicable.
+
+RULES:
+
+1. For each route (or each method/variant on the same URL), generate:
+   - Name: A descriptive, concise name for the request based on the route and HTTP method.
+   - Method: The HTTP method (GET, POST, PUT, DELETE, etc.).
+   - URL: The route URL.
+   - Body: If the endpoint accepts input, provide a JSON body example with appropriate keys; otherwise, leave it empty.
+   - Response: Provide a sample JSON response in the following format:
+     - If the endpoint returns no data:
+       {
+         "status": "success"
+       }
+     - If the endpoint returns data:
+       {
+         "status": "success",
+         "data": {}
+       }
+   - All responses must use HTTP status 200.
+2. Do NOT generate random or dynamic values in the body or response.
+3. Output must be a valid Postman collection JSON structure:
+   - Include "info" with collection name.
+   - Include "item" array with all requests.
+4. Keep the JSON fully compatible with Postman import.
+5. Do NOT include explanations outside the JSON.
+
+Wait for me to provide the route definitions.
@@ -0,0 +1,96 @@
+---
+alwaysApply: true
+---
+
+## 2. Django App (Module) Naming
+
+| Item   | Convention | Example                    |
+|--------|------------|----------------------------|
+| App name | snake_case, **بدون** پسوند `_api` | `account`, `auth`, `sensor_hub` |
+
+- نام اپ‌ها را با `_api` تمام **نکنید**. مثلاً به‌جای `account_api` از `account` استفاده کنید.
+- برای ماژول‌های فقط API، همان نام دامنه کافی است (مثلاً `auth`، `account`).
+
+---
+
+## 3. Model and Database Field Naming
+
+| Item              | Convention              | Example                                      |
+|-------------------|-------------------------|----------------------------------------------|
+| Model             | PascalCase              | `UserProfile`                                |
+| Fields            | snake_case              | `first_name`, `email_address`                |
+| Boolean           | `is_` / `has_` + name   | `is_active`, `has_paid`                      |
+| Date/Time         | `created_at` / `updated_at` | `created_at`, `updated_at`               |
+| ForeignKey / M2M  | snake_case, often model name | `author = ForeignKey(UserProfile)`     |
+| Choices / Enum    | UPPER_SNAKE_CASE values | `role = CharField(choices=(("ADMIN","Admin"), ("USER","User")))` |
+
+---
+
+## 4. DRF Conventions
+
+- **Serializer:** Validation + data transformation. Use PascalCase names.
+- **Service layer:** All business logic lives here.
+- **View:** Orchestration only — call services and return responses. No business logic in views.
+- **URLs:** Define endpoints only. Use kebab-case for URL paths.
+
+---
+
+## 5. API Response Format
+
+همه پاسخ‌های API باید فیلد `code` را برگردانند؛ مقدار آن برابر **HTTP status code** درخواست است (مثلاً 200، 201، 400، 404).
+
+| فیلد  | توضیح                                  |
+|-------|----------------------------------------|
+| `code` | کد وضعیت HTTP (مثلاً 200، 404، 500)   |
+| `msg`  | پیام (مثلاً "success" برای 2xx)       |
+| `data` | دادهٔ برگشتی (اختیاری)                |
+
+مثال:
+```json
+{"code": 200, "msg": "success", "data": {...}}
+```
+
+---
+
+## 6. Simple Example: How the Layers Connect (users app)
+
+```python
+# models.py
+class UserProfile(models.Model):
+    first_name = models.CharField(max_length=50)
+    last_name = models.CharField(max_length=50)
+    email_address = models.EmailField(unique=True)
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+
+# serializers.py
+class UserCreateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = UserProfile
+        fields = ["first_name", "last_name", "email_address"]
+
+
+# services.py
+def create_user(first_name, last_name, email_address):
+    return UserProfile.objects.create(
+        first_name=first_name,
+        last_name=last_name,
+        email_address=email_address,
+    )
+
+
+# views.py
+class UserCreateAPIView(APIView):
+    def post(self, request):
+        serializer = UserCreateSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        user = create_user(**serializer.validated_data)
+        return Response({"code": 201, "msg": "success", "data": {"id": user.id}}, status=201)
+```
+
+- All names follow the conventions above.
+- Business logic is in `services.py`.
+- Serializer only validates and serializes.
+- View only orchestrates (calls service, returns response).
@@ -0,0 +1,72 @@
+---
+alwaysApply: false
+---
+You are a Django API code generator.
+
+Your task is to generate a complete and runnable Django project based on the routes I provide.
+
+ROUTE STYLE:
+- Routes may be defined as a single URL with different HTTP methods (e.g. one path, GET for list, GET with query for detail, PUT/PATCH for update, DELETE for delete, POST for action). Use one view class that implements get, post, put, patch, delete as needed. Use query parameters (e.g. sensor_id) to distinguish list vs detail when both use GET.
+
+STRICT RULES:
+
+- Use Django only.
+- Do NOT use Django REST Framework unless I explicitly request it.
+- Do NOT connect to any database.
+- Do NOT create any Models.
+- Do NOT generate random or dynamic data.
+- Input parameters must be accepted (body, query params, path params).
+- HOWEVER, absolutely NO processing, validation, transformation, or logic may be applied to them.
+- Do NOT use input values inside the response.
+- No conditional logic.
+- No business logic.
+- No validation.
+- All endpoints must always return static JSON responses only.
+- ALL responses must return HTTP status code 200 only.
+- No other status codes are allowed.
+- No explanations outside the code.
+- Return complete runnable code including project structure (views.py, urls.py, settings if needed, etc.).
+
+--------------------------------------------------
+RESPONSE FORMAT (STRICTLY ENFORCED)
+
+If the endpoint does NOT require returning data:
+
+{
+  "status": "success"
+}
+
+If the endpoint requires returning data:
+
+{
+  "status": "success",
+  "data": {}
+}
+
+Mandatory rules:
+- The "status" field MUST always be exactly "success".
+- If "data" is present, it MUST be exactly an empty object {}.
+- If data is not required, DO NOT include the "data" field.
+- No additional fields are allowed.
+--------------------------------------------------
+
+COMMENTING REQUIREMENTS (VERY IMPORTANT):
+
+Each endpoint MUST include professional, multi-line docstring documentation.
+
+The documentation MUST include:
+
+1. Clear description of the endpoint purpose.
+2. Complete description of ALL input parameters:
+   - Parameter name
+   - Data type
+   - Location (body / query / path)
+   - Description of its intended purpose
+3. Full description of the response structure:
+   - status field
+   - data field (if applicable)
+4. Explicit statement that no processing or validation is performed on inputs.
+
+Use clean, professional API documentation style.
+Do not write anything outside the code.
+Wait for my route definitions.