plcode-linux-x64-baseline-musl 2.1.0

package/.plcode/skill/core/backend-dev-guidelines/resources/complete-examples.md

@@ -0,0 +1,607 @@
+# 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
+- [routing-and-controllers.md](routing-and-controllers.md)
+- [services-and-repositories.md](services-and-repositories.md)
+- [validation-patterns.md](validation-patterns.md)