Files

admin ce795b26e2 Prepare to version 1.5 use spec-kit

2025-11-30 13:58:46 +07:00

11 KiB

Raw Blame History

FullStackJS Development Guidelines

🧠 General Philosophy

Unified best practices for NestJS Backend, NextJS Frontend, and Bootstrap-based UI/UX development in TypeScript environments.
Focus on clarity, maintainability, consistency, and accessibility across the entire stack.

⚙️ TypeScript General Guidelines

Basic Principles

Use English for all code and documentation.
Explicitly type all variables, parameters, and return values.
Avoid any; create custom types or interfaces.
Use JSDoc for public classes and methods.
Export only one main symbol per file.
Avoid blank lines within functions.

Naming Conventions

Entity	Convention	Example
Classes	PascalCase	`UserService`
Variables & Functions	camelCase	`getUserInfo`
Files & Folders	kebab-case	`user-service.ts`
Environment Variables	UPPERCASE	`DATABASE_URL`
Booleans	Verb + Noun	`isActive`, `canDelete`, `hasPermission`

Use full words — no abbreviations — except for standard ones (API, URL, req, res, err, ctx).

🧩 Functions

Write short, single-purpose functions (<20 lines).
Use early returns to reduce nesting.
Use map, filter, reduce instead of loops when suitable.
Prefer arrow functions for short logic, named functions otherwise.
Use default parameters over null checks.
Group multiple parameters into a single object (RO-RO pattern).
Return typed objects, not primitives.
Maintain a single abstraction level per function.

🧱 Data Handling

Encapsulate data in composite types.
Use immutability with readonly and as const.
Perform validations in classes or DTOs, not within business functions.
Always validate data using typed DTOs.

🧰 Classes

Follow SOLID principles.
Prefer composition over inheritance.
Define interfaces for contracts.
Keep classes focused and small (<200 lines, <10 methods, <10 properties).

🚨 Error Handling

Use exceptions for unexpected errors.
Catch only to fix or add context; otherwise, use global error handlers.
Always provide meaningful error messages.

🧪 Testing (General)

Use the Arrange–Act–Assert pattern.
Use descriptive test variable names (inputData, expectedOutput).
Write unit tests for all public methods.
Mock external dependencies.
Add acceptance tests per module using Given–When–Then.

🏗️ Backend (NestJS)

Principles

Modular architecture:
- One module per domain.
- Controller → Service → Model structure.
DTOs validated with class-validator.
Use MikroORM or equivalent for persistence.
Encapsulate reusable code in a common module (@app/common):
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.

Core Functionalities

Global filters for exception handling.
Middlewares for request handling.
Guards for permissions and RBAC.
Interceptors for response transformation and logging.

Testing

Use Jest for testing.
Test each controller and service.
Add admin/test endpoint as a smoke test.

🖥️ Frontend (NextJS / React)

Developer Profile

Senior-level TypeScript + React/NextJS engineer.
Expert in TailwindCSS, Shadcn/UI, and Radix for UI development.

Code Implementation Guidelines

Use early returns for clarity.
Always style with TailwindCSS classes.
Prefer class: conditional syntax over ternary operators.
Use const arrow functions for components and handlers.
Event handlers start with handle... (e.g., handleClick, handleSubmit).
Include accessibility attributes:
tabIndex="0", aria-label, onKeyDown, etc.
Ensure all code is complete, tested, and DRY.
Always import required modules explicitly.

UI/UX with React

Use semantic HTML.
Apply responsive Tailwind classes.
Maintain visual hierarchy with typography and spacing.
Use Shadcn components for consistent UI.
Keep components small and focused.

🎨 UI/UX (Bootstrap Integration)

Key Principles

Use Bootstrap 5+ for responsive design and consistent UI.
Focus on maintainability, readability, and accessibility.
Use clear and descriptive class names.

Bootstrap Usage

Structure layout with container, row, col.
Use built-in components (buttons, modals, alerts, etc.) instead of custom CSS.
Apply utility classes for quick styling (spacing, colors, text, etc.).
Ensure ARIA compliance and semantic markup.

Form Validation & Errors

Use Bootstrap’s built-in validation states.
Show errors with alert components.
Include labels, placeholders, and feedback messages.

Dependencies

Bootstrap (latest CSS + JS)
Optionally jQuery (for legacy interactive components)

Bootstrap-Specific Guidelines

Customize Bootstrap via Sass variables and mixins.
Use responsive visibility utilities.
Avoid overriding Bootstrap; extend it.
Follow official documentation for examples.

Performance Optimization

Include only necessary Bootstrap modules.
Use CDN for assets and caching.
Optimize images and assets for mobile.

Key Conventions

Follow Bootstrap’s naming and structure.
Prioritize responsiveness and accessibility.
Keep the file structure organized and modular.

🔗 Full Stack Integration Guidelines

Aspect	Backend (NestJS)	Frontend (NextJS)	UI Layer (Bootstrap/Tailwind)
API	REST / GraphQL Controllers	API hooks via fetch/axios	Components consuming data
Validation	`class-validator` DTOs	`zod` / form-level validation	Bootstrap validation feedback
Auth	Guards, JWT	NextAuth / cookies	Auth UI states
Errors	Global filters	Toasts / modals	Alerts / feedback
Testing	Jest (unit/e2e)	Vitest / Playwright	Visual regression
Styles	Scoped modules	Tailwind / Shadcn	Bootstrap utilities
Accessibility	Guards + filters	ARIA attributes	Semantic HTML

✅ Final Notes

Use a shared types package (@types/shared) for consistent interfaces.
Document your modules and APIs.
Run lint, type-check, and tests before commit.
Use Prettier + ESLint for consistent formatting.
Prefer clarity over cleverness — readable code wins.

🗂️ DMS-Specific Conventions (Document Management System)

This section extends the general FullStackJS guidelines for projects similar to np‑dms.work, focusing on document approval workflows (RFA, Drawing, Contract, Revision, Transmittal, Report).

🧱 Backend Domain Modules

Use modular domain structure per document type:

src/
 ├─ modules/
 │   ├─ rfas/
 │   ├─ drawings/
 │   ├─ contracts/
 │   ├─ transmittals/
 │   ├─ audit-log/
 │   ├─ users/
 │   └─ common/

Naming Convention

Entity	Example
Table	`rfa_revisions`, `drawing_contracts`
DTO	`CreateRfaDto`, `UpdateContractDto`
Controller	`rfas.controller.ts`
Service	`rfas.service.ts`

🧩 RBAC & Permission Control

Use decorators to enforce access rights:

@RequirePermission('rfa.update')
@Put(':id')
updateRFA(@Param('id') id: string) {
  return this.rfaService.update(id);
}

Roles

Admin: Full access to all modules.
Editor: Modify data within assigned modules.
Viewer: Read‑only access.

Permissions

rfa.create, rfa.update, rfa.delete, rfa.view
drawing.upload, drawing.map, drawing.view
contract.assign, contract.view

Seed mapping between roles and permissions via seeder scripts.

🧾 AuditLog Standard

Log all CRUD and mapping operations:

Field	Description
`actor_id`	user performing the action
`module_name`	e.g. `rfa`, `drawing`
`action`	`create`, `update`, `delete`, `map`
`target_id`	primary id of the record
`timestamp`	UTC timestamp
`description`	contextual note

Example implementation:

await this.auditLogService.log({
  actorId: user.id,
  moduleName: 'rfa',
  action: 'update',
  targetId: rfa.id,
  description: `Updated revision ${rev}`,
});

📂 File Handling

File Upload Standard

Upload path: /storage/{year}/{month}/
File naming: {drawing_code}_{revision}_{timestamp}.pdf
Allowed types: pdf, dwg, docx, xlsx, zip
Max size: 50 MB
Store outside webroot.
Serve via secure endpoint /files/:id/download.

Access Control

Each file download must verify user permission (hasPermission('drawing.view')).

📊 Reporting & Exports

Report	Description
Report A	RFA → Drawings → All Drawing Revisions
Report B	RFA Revision Timeline vs Drawing Revision
Dashboard KPI	RFAs, Drawings, Revisions, Transmittals summary

Export Rules

Export formats: CSV, Excel, PDF.
Provide print view.
Include source entity link (e.g., /rfas/:id).

🧮 Frontend: DataTable & Form Patterns

DataTable (Server‑Side)

Endpoint: /api/{module}?page=1&pageSize=20
Must support: pagination, sorting, search, filters.
Always display latest revision inline (for RFA/Drawing).

Form Standards

Dependent dropdowns:
- Contract → Subcategory
- RFA → Related Drawing
File upload: preview + validation.
Submit via API with toast feedback.

🧭 Dashboard & Activity Feed

Dashboard Cards

Show latest RFA, Drawing, Transmittal, KPI summary.
Include quick links to modules.

Activity Feed

Display recent AuditLog actions (10 latest).

// Example response
[
  { user: 'admin', action: 'Updated RFA 023-Rev02', time: '2025‑11‑04T09:30Z' }
]

✅ Integration Summary

🧩 Recommended Enhancements

✅ Add deleted_at for soft delete + restore.
✅ Fulltext search + date filters.
✅ Background job for RFA deadline reminders.
✅ Optimize DB with indexes on rfa_id, drawing_id, contract_id.
✅ Periodic cleanup for unused file uploads.

11 KiB Raw Blame History Unescape Escape