AzuTear
94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
# Atlas Desk Conventions
|
|
|
|
## Naming
|
|
|
|
- Use support-domain language: request, assignment, note, queue, audit event.
|
|
- Use `Async` suffix for asynchronous backend methods.
|
|
- Name Vue components by feature and purpose, such as `RequestDetailPanel`.
|
|
- Name authorization policies by action, such as `CanAssignRequest`.
|
|
|
|
## File Organization
|
|
|
|
- Keep backend files under their owning module.
|
|
- Keep Vue components below 250 lines when practical.
|
|
- Co-locate component tests with feature components.
|
|
- Keep generated API types in `frontend/src/shared/api/generated`.
|
|
|
|
## Folder Organization
|
|
|
|
| Folder | Rule |
|
|
| --- | --- |
|
|
| `backend/src/Requests` | Owns request workflow commands, queries, and domain rules. |
|
|
| `backend/src/Shared` | Contains cross-cutting primitives only. |
|
|
| `frontend/src/features/requests` | Owns request screens and feature-specific components. |
|
|
| `frontend/src/shared` | Contains reusable UI primitives and API utilities. |
|
|
|
|
## Dependency Injection
|
|
|
|
- Register backend services by module.
|
|
- Inject clocks, email clients, database contexts, and external gateways.
|
|
- Do not inject primitive configuration values directly into domain classes.
|
|
|
|
## Logging
|
|
|
|
- Use structured logs with `requestId` and `userId` where available.
|
|
- Log workflow transitions at information level.
|
|
- Log authorization denials at warning level only when they indicate suspicious behavior.
|
|
- Do not log customer message bodies.
|
|
|
|
## Validation
|
|
|
|
- Validate API DTO shape at the API boundary.
|
|
- Validate workflow invariants inside request commands.
|
|
- Validate authorization before loading sensitive detail views.
|
|
|
|
## Error Handling
|
|
|
|
- Use stable problem codes for client-visible API errors.
|
|
- Return validation errors as field-level responses.
|
|
- Include correlation IDs in error responses.
|
|
- Do not expose stack traces outside local development.
|
|
|
|
## DTO Rules
|
|
|
|
- API DTOs are separate from persistence entities.
|
|
- Request detail DTOs must not include internal audit metadata unless the user has manager or auditor access.
|
|
- Public API changes require a changelog entry.
|
|
|
|
## Repository Rules
|
|
|
|
- Keep queries explicit, such as `FindOpenRequestsForQueue`.
|
|
- Do not add generic repository abstractions over the database context.
|
|
- Write operations that can be retried must be idempotent or transactionally protected.
|
|
|
|
## Service Rules
|
|
|
|
- Application services coordinate commands and queries.
|
|
- Domain services contain request workflow rules only when the rule spans entities.
|
|
- External email delivery is behind an interface.
|
|
|
|
## Testing
|
|
|
|
- Unit test request state transitions.
|
|
- Integration test authorization and database persistence.
|
|
- End-to-end test create, assign, comment, and close workflows.
|
|
- Add regression tests for production defects.
|
|
|
|
## Git Workflow
|
|
|
|
- Branch names use `feature/`, `fix/`, `refactor/`, `docs/`, or `hotfix/`.
|
|
- Squash merge pull requests into `main`.
|
|
- Commit messages use imperative summaries.
|
|
|
|
## Pull Requests
|
|
|
|
- Include summary, validation, risk, and screenshots for UI changes.
|
|
- Include migration notes when database schema changes.
|
|
- Keep unrelated refactors in separate pull requests.
|
|
|
|
## Code Reviews
|
|
|
|
- Block on correctness, security, data integrity, missing validation, or unclear ownership.
|
|
- Prefer suggestions for style issues that are not covered by tooling.
|
|
- Ask for ADR updates when a decision changes system structure.
|