website refactor

docs/architecture/website/WEBSITE_CONTRACT_WRITE_FLOW.md

@@ -39,14 +39,15 @@ import { AdminUserMutation } from '@/lib/mutations/admin/AdminUserMutation';
 import { revalidatePath } from 'next/cache';
 
 export async function updateUserStatus(userId: string, status: string) {
-  try {
-    const mutation = new AdminUserMutation();
-    await mutation.updateUserStatus(userId, status);
-    revalidatePath('/admin/users');
-  } catch (error) {
-    console.error('updateUserStatus failed:', error);
+  const mutation = new AdminUserMutation();
+  const result = await mutation.updateUserStatus(userId, status);
+  
+  if (result.isErr()) {
+    console.error('updateUserStatus failed:', result.getError());
     throw new Error('Failed to update user status');
   }
+  
+  revalidatePath('/admin/users');
 }
 ```
 
@@ -54,6 +55,8 @@ export async function updateUserStatus(userId: string, status: string) {
 
 ```typescript
 // lib/mutations/admin/AdminUserMutation.ts
+import { Result, ResultFactory } from '@/lib/contracts/Result';
+
 export class AdminUserMutation {
   private service: AdminService;
   
@@ -70,8 +73,13 @@ export class AdminUserMutation {
     this.service = new AdminService(apiClient);
   }
   
-  async updateUserStatus(userId: string, status: string): Promise<void> {
-    await this.service.updateUserStatus(userId, status);
+  async updateUserStatus(userId: string, status: string): Promise<Result<void, string>> {
+    try {
+      await this.service.updateUserStatus(userId, status);
+      return ResultFactory.ok(undefined);
+    } catch (error) {
+      return ResultFactory.error('UPDATE_USER_STATUS_FAILED');
+    }
   }
 }
 ```
@@ -82,11 +90,13 @@ export class AdminUserMutation {
 2. **Mutation** (framework-agnostic) - creates infrastructure, calls service
 3. **Service** (business logic) - orchestrates API calls
 4. **API Client** (infrastructure) - makes HTTP requests
+5. **Result** - type-safe error handling
 
 ### Rationale
 
 - **Framework independence**: Mutations can be tested without Next.js
 - **Consistency**: Mirrors PageQuery pattern for reads/writes
+- **Type-safe errors**: Result pattern eliminates exceptions
 - **Migration ease**: Can switch frameworks without rewriting business logic
 - **Testability**: Can unit test mutations in isolation
 - **Reusability**: Can be called from other contexts (cron jobs, etc.)
@@ -99,7 +109,7 @@ export class AdminUserMutation {
 | Location | `lib/page-queries/` | `lib/mutations/` |
 | Framework | Called from RSC | Called from Server Actions |
 | Infrastructure | Manual DI | Manual DI |
-| Returns | Page DTO | void or result |
+| Returns | `Result<ApiDto, string>` | `Result<void, string>` |
 | Revalidation | N/A | Server Action handles it |
 
 ### See Also