203 lines
7.4 KiB
Markdown
Executable File
203 lines
7.4 KiB
Markdown
Executable File
# Annunk Development Rules
|
|
|
|
## Project Overview
|
|
|
|
Annunk is a multi-user web application for sending learning insights and training content via AI (OpenRouter.ai, OpenAI, StepFun, llama.cpp, QwenCloud), Telegram bot, and dashboard. Built with Laravel 13 + PHP 8.3 + MariaDB.
|
|
|
|
## Code Standards
|
|
|
|
- All PHP code **must** follow **PSR-12** coding standards
|
|
- All PHP source files **must** include technical comments in **English** using the **PHPDoc** standard (`@param`, `@return`, `@throws`, `@property`, etc.)
|
|
- Use **meaningful** variable and function names (self-documenting code)
|
|
- Keep methods **small and focused** (max 50 lines per method)
|
|
- Use **dependency injection** instead of facades when possible
|
|
- Use **type hints** for all function parameters and return types
|
|
- Declare **strict types** (`declare(strict_types=1)`) in all PHP files
|
|
|
|
## Architecture
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
app/
|
|
├── Console/Commands/ # Artisan commands (SendScheduledInsights)
|
|
├── Http/
|
|
│ ├── Controllers/
|
|
│ │ ├── Admin/ # Admin user controllers (Subject, Insight, Telegram, Billing)
|
|
│ │ ├── Auth/ # Authentication controllers (login/register with MathCaptcha)
|
|
│ │ └── SuperAdmin/ # SuperAdmin controllers (User, System, Billing)
|
|
│ ├── Middleware/ # SetLocale, EnsureUserConsent
|
|
│ └── Validation/ # MathCaptchaRule
|
|
├── Models/ # User, Subject, Insight, UserSubject, TelegramUser, TokenUsage, UserConsent, SubscriptionPlan, UserSubscription, Invoice, UserNotification
|
|
├── Services/ # AIService (multi-provider), TelegramService, MarkdownService
|
|
└── Providers/ # AppServiceProvider
|
|
```
|
|
|
|
### Naming Conventions
|
|
|
|
- **Controllers**: `SingularPascalCaseController`
|
|
- **Models**: `SingularPascalCase`
|
|
- **Migrations**: `YYYY_MM_DD_HHMMSS_descriptive_name`
|
|
- **Services**: `DescriptivePascalCaseService`
|
|
- **Middleware**: `DescriptivePascalCase`
|
|
- **Validation Rules**: `DescriptivePascalCaseRule`
|
|
- **Routes**: kebab-case for URLs
|
|
- **Blade Views**: kebab-case for directories and files
|
|
|
|
## Database
|
|
|
|
- All migrations **must** be reversible
|
|
- Use **foreign key constraints** with `cascadeOnDelete()`
|
|
- **Index** frequently queried columns
|
|
- Use **transactions** for multi-step operations
|
|
- All tables **must** have `created_at` and `updated_at` timestamps
|
|
|
|
## Security
|
|
|
|
- All user input **must** be validated and sanitized
|
|
- **CSRF protection** on all forms
|
|
- **Math Captcha** on all public forms (login, register)
|
|
- New users **must** be approved by SuperAdmin
|
|
- Use **role-based access** (Spatie Laravel Permission)
|
|
- Admin users cannot see the AI model name
|
|
|
|
## Roles & Permissions
|
|
|
|
### Roles
|
|
- **SuperAdmin**: Full system control, user management, system subjects, billing, plans
|
|
- **Admin**: Regular user with access to subjects, insights, Telegram, billing
|
|
|
|
### Route Protection
|
|
- `role:admin|superadmin` - Admin routes
|
|
- `role:superadmin` - SuperAdmin routes
|
|
|
|
## Multilingual
|
|
|
|
- Supported locales: `pt_BR` (Português Brasil), `en` (English), `es` (Español)
|
|
- All UI text **must** use Laravel's `__()` helper or `@lang()` directive
|
|
- Translation files in `lang/{locale}/` directory
|
|
- User can switch language via Alpine.js dropdown in navbar
|
|
- Selected locale stored in session and user profile
|
|
|
|
## Frontend
|
|
|
|
- **Tailwind CSS** (v4) for all styling
|
|
- **Blade** templates with `@extends` and `@section`/`@yield`
|
|
- **Fully responsive** (mobile-first)
|
|
- **Alpine.js** for interactive components (dropdowns, modals)
|
|
- **ApexCharts** for charts and statistics
|
|
- **Math Captcha** on all public forms (MIT-licensed, no external libraries)
|
|
- All icons via inline SVG (MIT-licensed)
|
|
|
|
## AI Integration (Multi-Provider)
|
|
|
|
### Supported Providers
|
|
| Provider | Base URL | Config Key |
|
|
|----------|----------|------------|
|
|
| OpenRouter.ai | `https://openrouter.ai/api/v1/` | `OPENROUTER_API_KEY` |
|
|
| OpenAI | `https://api.openai.com/v1/` | `OPENAI_API_KEY` |
|
|
| StepFun | `https://api.stepfun.ai/step_plan/v1/` | `STEPFUN_API_KEY` |
|
|
| llama.cpp (Local) | `http://localhost:8080/v1/` | `LLAMACPP_BASE_URL` |
|
|
| QwenCloud | `https://api.qwencloud.com/v1/` | `QWEN_API_KEY` |
|
|
|
|
### Rules
|
|
- All AI-generated content **must** be logged with token usage
|
|
- Track `input_tokens` and `output_tokens` for each request
|
|
- Store AI responses in the `insights` table
|
|
- Implement **rate limiting** to control costs
|
|
- Configurable provider via `AI_DEFAULT_PROVIDER` env variable
|
|
- Include subject context and language preference in all prompts
|
|
- Implement **fallback** for AI service failures
|
|
- Log all AI API errors for debugging
|
|
|
|
### Content Guidelines
|
|
|
|
- AI-generated insights must be relevant to the selected subject
|
|
- Include subject context in all AI prompts
|
|
- Set appropriate temperature and max_tokens parameters
|
|
- Implement fallback for AI service failures
|
|
- Log all AI API errors for debugging
|
|
|
|
### Cost Management
|
|
|
|
- Monitor token consumption per user
|
|
- Set daily/monthly token limits if needed
|
|
- Alert on unusual token usage patterns
|
|
- Cache common AI responses when appropriate
|
|
- Use free models when possible to reduce costs
|
|
|
|
### Privacy
|
|
|
|
- Do not send sensitive user data to AI APIs
|
|
- Anonymize user information in prompts
|
|
- Review AI outputs before sending to users
|
|
- Implement content filtering if needed
|
|
|
|
### Prompt Engineering
|
|
|
|
- Use clear and specific prompts
|
|
- Include context about the subject and user preferences
|
|
- Set appropriate response formats
|
|
- Test prompts regularly for quality
|
|
- Document prompt templates
|
|
|
|
## Telegram Integration
|
|
|
|
- Each user configures their **own Telegram bot** (bot_token, chat_id)
|
|
- Users can enable/disable Telegram delivery per subject via `delivery_channels`
|
|
- Test button to verify bot connection
|
|
- Insights sent to Telegram when `telegram` channel is enabled
|
|
|
|
## Billing & Subscriptions
|
|
|
|
- SuperAdmin creates/manages subscription plans (name, price, duration, token limit)
|
|
- Users subscribe to plans (creates pending invoice)
|
|
- SuperAdmin approves payments (generates PDF invoice, notifies user)
|
|
- Users can view invoices and download PDFs
|
|
- Dashboard notifications for payment status, expiring subscriptions
|
|
|
|
## Testing
|
|
|
|
- Write tests for all new features using **PHPUnit**
|
|
- Maintain minimum **80% code coverage**
|
|
- Test **edge cases** and error conditions
|
|
- Use **descriptive test method names**
|
|
|
|
## Git
|
|
|
|
- Write **clear commit messages** in English
|
|
- Keep commits **atomic** and focused
|
|
- **Never** commit secrets, credentials, or `.env` files
|
|
|
|
## License
|
|
|
|
- Annunk is **Proprietary** - owned by Syspanel (syspanel.com.br)
|
|
- All libraries, extensions, and icons used must be **MIT-licensed**
|
|
- Math Captcha implementation is MIT-licensed (no external libraries)
|
|
|
|
## Environment
|
|
|
|
- System URL: `http://localhost:16790`
|
|
- SuperAdmin: `marcocosta@gmx.com` / `superadmin123456`
|
|
- Test user: `teste@annunki.com` / `teste123`
|
|
- System location: `/home/marco/Dockers/dockerank2/app`
|
|
|
|
## Tech Stack
|
|
|
|
| Technology | Version | Purpose |
|
|
|-----------|---------|---------|
|
|
| Laravel | 13 | PHP Framework |
|
|
| PHP | 8.3 | Runtime |
|
|
| MariaDB | Latest | Database |
|
|
| Tailwind CSS | 4 | CSS Framework |
|
|
| Blade | - | Templating Engine |
|
|
| Spatie Laravel Permission | 8 | RBAC |
|
|
| Spatie Laravel PDF | 2 | PDF Generation |
|
|
| Laravel Mail | - | Email Notifications |
|
|
| Laravel Reverb | 1 | Real-time Events |
|
|
| ApexCharts | Latest | Charts |
|
|
| OpenRouter.ai | - | AI API (default) |
|
|
| OpenAI API | - | AI API (optional) |
|
|
| Nutgram | Latest | Telegram Bot |
|
|
| Alpine.js | 3 | JavaScript Framework |
|