blockmine 1.24.0 → 1.25.0

package/.claude/skills/backend-dev-guidelines/resources/complete-examples.md

@@ -1,638 +0,0 @@
-# Complete Examples - Full Working Code
-
-Real-world examples showing complete implementation patterns.
-
-## Table of Contents
-
-- [Complete Controller Example](#complete-controller-example)
-- [Complete Service with DI](#complete-service-with-di)
-- [Complete Route File](#complete-route-file)
-- [Complete Repository](#complete-repository)
-- [Refactoring Example: Bad to Good](#refactoring-example-bad-to-good)
-- [End-to-End Feature Example](#end-to-end-feature-example)
-
----
-
-## Complete Controller Example
-
-### UserController (Following All Best Practices)
-
-```typescript
-// controllers/UserController.ts
-import { Request, Response } from 'express';
-import { BaseController } from './BaseController';
-import { UserService } from '../services/userService';
-import { createUserSchema, updateUserSchema } from '../validators/userSchemas';
-import { z } from 'zod';
-
-export class UserController extends BaseController {
-    private userService: UserService;
-
-    constructor() {
-        super();
-        this.userService = new UserService();
-    }
-
-    async getUser(req: Request, res: Response): Promise<void> {
-        try {
-            this.addBreadcrumb('Fetching user', 'user_controller', {
-                userId: req.params.id,
-            });
-
-            const user = await this.withTransaction(
-                'user.get',
-                'db.query',
-                () => this.userService.findById(req.params.id)
-            );
-
-            if (!user) {
-                return this.handleError(
-                    new Error('User not found'),
-                    res,
-                    'getUser',
-                    404
-                );
-            }
-
-            this.handleSuccess(res, user);
-        } catch (error) {
-            this.handleError(error, res, 'getUser');
-        }
-    }
-
-    async listUsers(req: Request, res: Response): Promise<void> {
-        try {
-            const users = await this.userService.getAll();
-            this.handleSuccess(res, users);
-        } catch (error) {
-            this.handleError(error, res, 'listUsers');
-        }
-    }
-
-    async createUser(req: Request, res: Response): Promise<void> {
-        try {
-            // Validate input with Zod
-            const validated = createUserSchema.parse(req.body);
-
-            // Track performance
-            const user = await this.withTransaction(
-                'user.create',
-                'db.mutation',
-                () => this.userService.create(validated)
-            );
-
-            this.handleSuccess(res, user, 'User created successfully', 201);
-        } catch (error) {
-            if (error instanceof z.ZodError) {
-                return this.handleError(error, res, 'createUser', 400);
-            }
-            this.handleError(error, res, 'createUser');
-        }
-    }
-
-    async updateUser(req: Request, res: Response): Promise<void> {
-        try {
-            const validated = updateUserSchema.parse(req.body);
-
-            const user = await this.userService.update(
-                req.params.id,
-                validated
-            );
-
-            this.handleSuccess(res, user, 'User updated');
-        } catch (error) {
-            if (error instanceof z.ZodError) {
-                return this.handleError(error, res, 'updateUser', 400);
-            }
-            this.handleError(error, res, 'updateUser');
-        }
-    }
-
-    async deleteUser(req: Request, res: Response): Promise<void> {
-        try {
-            await this.userService.delete(req.params.id);
-            this.handleSuccess(res, null, 'User deleted', 204);
-        } catch (error) {
-            this.handleError(error, res, 'deleteUser');
-        }
-    }
-}
-```
-
----
-
-## Complete Service with DI
-
-### UserService
-
-```typescript
-// services/userService.ts
-import { UserRepository } from '../repositories/UserRepository';
-import { ConflictError, NotFoundError, ValidationError } from '../types/errors';
-import type { CreateUserDTO, UpdateUserDTO, User } from '../types/user.types';
-
-export class UserService {
-    private userRepository: UserRepository;
-
-    constructor(userRepository?: UserRepository) {
-        this.userRepository = userRepository || new UserRepository();
-    }
-
-    async findById(id: string): Promise<User | null> {
-        return await this.userRepository.findById(id);
-    }
-
-    async getAll(): Promise<User[]> {
-        return await this.userRepository.findActive();
-    }
-
-    async create(data: CreateUserDTO): Promise<User> {
-        // Business rule: validate age
-        if (data.age < 18) {
-            throw new ValidationError('User must be 18 or older');
-        }
-
-        // Business rule: check email uniqueness
-        const existing = await this.userRepository.findByEmail(data.email);
-        if (existing) {
-            throw new ConflictError('Email already in use');
-        }
-
-        // Create user with profile
-        return await this.userRepository.create({
-            email: data.email,
-            profile: {
-                create: {
-                    firstName: data.firstName,
-                    lastName: data.lastName,
-                    age: data.age,
-                },
-            },
-        });
-    }
-
-    async update(id: string, data: UpdateUserDTO): Promise<User> {
-        // Check exists
-        const existing = await this.userRepository.findById(id);
-        if (!existing) {
-            throw new NotFoundError('User not found');
-        }
-
-        // Business rule: email uniqueness if changing
-        if (data.email && data.email !== existing.email) {
-            const emailTaken = await this.userRepository.findByEmail(data.email);
-            if (emailTaken) {
-                throw new ConflictError('Email already in use');
-            }
-        }
-
-        return await this.userRepository.update(id, data);
-    }
-
-    async delete(id: string): Promise<void> {
-        const existing = await this.userRepository.findById(id);
-        if (!existing) {
-            throw new NotFoundError('User not found');
-        }
-
-        await this.userRepository.delete(id);
-    }
-}
-```
-
----
-
-## Complete Route File
-
-### userRoutes.ts
-
-```typescript
-// routes/userRoutes.ts
-import { Router } from 'express';
-import { UserController } from '../controllers/UserController';
-import { SSOMiddlewareClient } from '../middleware/SSOMiddleware';
-import { auditMiddleware } from '../middleware/auditMiddleware';
-
-const router = Router();
-const controller = new UserController();
-
-// GET /users - List all users
-router.get('/',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.listUsers(req, res)
-);
-
-// GET /users/:id - Get single user
-router.get('/:id',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.getUser(req, res)
-);
-
-// POST /users - Create user
-router.post('/',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.createUser(req, res)
-);
-
-// PUT /users/:id - Update user
-router.put('/:id',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.updateUser(req, res)
-);
-
-// DELETE /users/:id - Delete user
-router.delete('/:id',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.deleteUser(req, res)
-);
-
-export default router;
-```
-
----
-
-## Complete Repository
-
-### UserRepository
-
-```typescript
-// repositories/UserRepository.ts
-import { PrismaService } from '@project-lifecycle-portal/database';
-import type { User, Prisma } from '@prisma/client';
-
-export class UserRepository {
-    async findById(id: string): Promise<User | null> {
-        return PrismaService.main.user.findUnique({
-            where: { id },
-            include: { profile: true },
-        });
-    }
-
-    async findByEmail(email: string): Promise<User | null> {
-        return PrismaService.main.user.findUnique({
-            where: { email },
-            include: { profile: true },
-        });
-    }
-
-    async findActive(): Promise<User[]> {
-        return PrismaService.main.user.findMany({
-            where: { isActive: true },
-            include: { profile: true },
-            orderBy: { createdAt: 'desc' },
-        });
-    }
-
-    async create(data: Prisma.UserCreateInput): Promise<User> {
-        return PrismaService.main.user.create({
-            data,
-            include: { profile: true },
-        });
-    }
-
-    async update(id: string, data: Prisma.UserUpdateInput): Promise<User> {
-        return PrismaService.main.user.update({
-            where: { id },
-            data,
-            include: { profile: true },
-        });
-    }
-
-    async delete(id: string): Promise<User> {
-        // Soft delete
-        return PrismaService.main.user.update({
-            where: { id },
-            data: {
-                isActive: false,
-                deletedAt: new Date(),
-            },
-        });
-    }
-}
-```
-
----
-
-## Refactoring Example: Bad to Good
-
-### BEFORE: Business Logic in Routes ❌
-
-```typescript
-// routes/postRoutes.ts (BAD - 200+ lines)
-router.post('/posts', async (req, res) => {
-    try {
-        const username = res.locals.claims.preferred_username;
-        const responses = req.body.responses;
-        const stepInstanceId = req.body.stepInstanceId;
-
-        // ❌ Permission check in route
-        const userId = await userProfileService.getProfileByEmail(username).then(p => p.id);
-        const canComplete = await permissionService.canCompleteStep(userId, stepInstanceId);
-        if (!canComplete) {
-            return res.status(403).json({ error: 'No permission' });
-        }
-
-        // ❌ Business logic in route
-        const post = await postRepository.create({
-            title: req.body.title,
-            content: req.body.content,
-            authorId: userId
-        });
-
-        // ❌ More business logic...
-        if (res.locals.isImpersonating) {
-            impersonationContextStore.storeContext(...);
-        }
-
-        // ... 100+ more lines
-
-        res.json({ success: true, data: result });
-    } catch (e) {
-        handler.handleException(res, e);
-    }
-});
-```
-
-### AFTER: Clean Separation ✅
-
-**1. Clean Route:**
-```typescript
-// routes/postRoutes.ts
-import { PostController } from '../controllers/PostController';
-
-const router = Router();
-const controller = new PostController();
-
-// ✅ CLEAN: 8 lines total!
-router.post('/',
-    SSOMiddlewareClient.verifyLoginStatus,
-    auditMiddleware,
-    async (req, res) => controller.createPost(req, res)
-);
-
-export default router;
-```
-
-**2. Controller:**
-```typescript
-// controllers/PostController.ts
-export class PostController extends BaseController {
-    private postService: PostService;
-
-    constructor() {
-        super();
-        this.postService = new PostService();
-    }
-
-    async createPost(req: Request, res: Response): Promise<void> {
-        try {
-            const validated = createPostSchema.parse({
-                ...req.body,
-            });
-
-            const result = await this.postService.createPost(
-                validated,
-                res.locals.userId
-            );
-
-            this.handleSuccess(res, result, 'Post created successfully');
-        } catch (error) {
-            this.handleError(error, res, 'createPost');
-        }
-    }
-}
-```
-
-**3. Service:**
-```typescript
-// services/postService.ts
-export class PostService {
-    async createPost(
-        data: CreatePostDTO,
-        userId: string
-    ): Promise<SubmissionResult> {
-        // Permission check
-        const canComplete = await permissionService.canCompleteStep(
-            userId,
-            data.stepInstanceId
-        );
-
-        if (!canComplete) {
-            throw new ForbiddenError('No permission to complete step');
-        }
-
-        // Execute workflow
-        const engine = await createWorkflowEngine();
-        const command = new CompleteStepCommand(
-            data.stepInstanceId,
-            userId,
-            data.responses
-        );
-        const events = await engine.executeCommand(command);
-
-        // Handle impersonation
-        if (context.isImpersonating) {
-            await this.handleImpersonation(data.stepInstanceId, context);
-        }
-
-        return { events, success: true };
-    }
-
-    private async handleImpersonation(stepInstanceId: number, context: any) {
-        impersonationContextStore.storeContext(stepInstanceId, {
-            originalUserId: context.originalUserId,
-            effectiveUserId: context.effectiveUserId,
-        });
-    }
-}
-```
-
-**Result:**
-- Route: 8 lines (was 200+)
-- Controller: 25 lines
-- Service: 40 lines
-- **Testable, maintainable, reusable!**
-
----
-
-## End-to-End Feature Example
-
-### Complete User Management Feature
-
-**1. Types:**
-```typescript
-// types/user.types.ts
-export interface User {
-    id: string;
-    email: string;
-    isActive: boolean;
-    profile?: UserProfile;
-}
-
-export interface CreateUserDTO {
-    email: string;
-    firstName: string;
-    lastName: string;
-    age: number;
-}
-
-export interface UpdateUserDTO {
-    email?: string;
-    firstName?: string;
-    lastName?: string;
-}
-```
-
-**2. Validators:**
-```typescript
-// validators/userSchemas.ts
-import { z } from 'zod';
-
-export const createUserSchema = z.object({
-    email: z.string().email(),
-    firstName: z.string().min(1).max(100),
-    lastName: z.string().min(1).max(100),
-    age: z.number().int().min(18).max(120),
-});
-
-export const updateUserSchema = z.object({
-    email: z.string().email().optional(),
-    firstName: z.string().min(1).max(100).optional(),
-    lastName: z.string().min(1).max(100).optional(),
-});
-```
-
-**3. Repository:**
-```typescript
-// repositories/UserRepository.ts
-export class UserRepository {
-    async findById(id: string): Promise<User | null> {
-        return PrismaService.main.user.findUnique({
-            where: { id },
-            include: { profile: true },
-        });
-    }
-
-    async create(data: Prisma.UserCreateInput): Promise<User> {
-        return PrismaService.main.user.create({
-            data,
-            include: { profile: true },
-        });
-    }
-}
-```
-
-**4. Service:**
-```typescript
-// services/userService.ts
-export class UserService {
-    private userRepository: UserRepository;
-
-    constructor() {
-        this.userRepository = new UserRepository();
-    }
-
-    async create(data: CreateUserDTO): Promise<User> {
-        const existing = await this.userRepository.findByEmail(data.email);
-        if (existing) {
-            throw new ConflictError('Email already exists');
-        }
-
-        return await this.userRepository.create({
-            email: data.email,
-            profile: {
-                create: {
-                    firstName: data.firstName,
-                    lastName: data.lastName,
-                    age: data.age,
-                },
-            },
-        });
-    }
-}
-```
-
-**5. Controller:**
-```typescript
-// controllers/UserController.ts
-export class UserController extends BaseController {
-    private userService: UserService;
-
-    constructor() {
-        super();
-        this.userService = new UserService();
-    }
-
-    async createUser(req: Request, res: Response): Promise<void> {
-        try {
-            const validated = createUserSchema.parse(req.body);
-            const user = await this.userService.create(validated);
-            this.handleSuccess(res, user, 'User created', 201);
-        } catch (error) {
-            this.handleError(error, res, 'createUser');
-        }
-    }
-}
-```
-
-**6. Routes:**
-```typescript
-// routes/userRoutes.ts
-const router = Router();
-const controller = new UserController();
-
-router.post('/',
-    SSOMiddlewareClient.verifyLoginStatus,
-    async (req, res) => controller.createUser(req, res)
-);
-
-export default router;
-```
-
-**7. Register in app.ts:**
-```typescript
-// app.ts
-import userRoutes from './routes/userRoutes';
-
-app.use('/api/users', userRoutes);
-```
-
-**Complete Request Flow:**
-```
-POST /api/users
-  ↓
-userRoutes matches /
-  ↓
-SSOMiddleware authenticates
-  ↓
-controller.createUser called
-  ↓
-Validates with Zod
-  ↓
-userService.create called
-  ↓
-Checks business rules
-  ↓
-userRepository.create called
-  ↓
-Prisma creates user
-  ↓
-Returns up the chain
-  ↓
-Controller formats response
-  ↓
-200/201 sent to client
-```
-
----
-
-**Related Files:**
-- [SKILL.md](SKILL.md)
-- [routing-and-controllers.md](routing-and-controllers.md)
-- [services-and-repositories.md](services-and-repositories.md)
-- [validation-patterns.md](validation-patterns.md)