@khester/create-dynamics-app 2.1.0 → 2.3.0

package/templates/react-custom-page/docs/BEST_PRACTICES.md

@@ -1,723 +0,0 @@
-# Best Practices - Dynamics 365 Template
-
-## Overview
-
-This document outlines best practices for developing robust Dynamics 365 applications using the
-enhanced template patterns.
-
-## Architecture Best Practices
-
-### 1. Entity Model Design
-
-#### ✅ DO: Use Static Methods for CRUD Operations
-
-```typescript
-export class Account extends BaseEntity {
-  public static async create(apiService: IApiService, account: Account): Promise<Account> {
-    return await this.createEntity<Account>(
-      apiService,
-      account,
-      AccountConstants.EntityCollectionName,
-      'Account.create'
-    );
-  }
-
-  public static async retrieveByName(apiService: IApiService, name: string): Promise<Account[]> {
-    const fetchXml = this.buildFetchXml(
-      AccountConstants.EntityLogicalName,
-      ['accountid', 'name', 'emailaddress1'],
-      `<filter type="and">
-         <condition attribute="name" operator="like" value="%${this.escapeXml(name)}%" />
-       </filter>`
-    );
-
-    return await this.retrieveEntitiesByFilter<Account>(
-      apiService,
-      AccountConstants.EntityCollectionName,
-      fetchXml,
-      Account,
-      'Account.retrieveByName'
-    );
-  }
-}
-```
-
-#### ❌ DON'T: Mix Instance and Static Methods
-
-```typescript
-// Avoid this pattern
-export class Account {
-  public async save() {
-    /* instance method */
-  }
-  public static async create() {
-    /* static method */
-  }
-  public async delete() {
-    /* instance method */
-  }
-}
-```
-
-#### ✅ DO: Implement Comprehensive Validation
-
-```typescript
-export class Account extends BaseEntity {
-  public validate(): boolean {
-    const errors: string[] = [];
-
-    // Required field validation
-    if (!this.name?.trim()) {
-      errors.push('Account name is required');
-    }
-
-    // Length validation
-    if (this.name && this.name.length > 160) {
-      errors.push('Account name cannot exceed 160 characters');
-    }
-
-    // Format validation
-    if (this.emailaddress1 && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.emailaddress1)) {
-      errors.push('Invalid email format');
-    }
-
-    // Business rule validation
-    if (this.revenue && this.revenue < 0) {
-      errors.push('Revenue cannot be negative');
-    }
-
-    if (errors.length > 0) {
-      Logger.validation('Account', errors, 'Account.validate');
-      throw new Error(`Validation failed: ${errors.join(', ')}`);
-    }
-
-    return true;
-  }
-}
-```
-
-### 2. Service Layer Architecture
-
-#### ✅ DO: Use the Service Factory Pattern
-
-```typescript
-// Let the factory determine the appropriate service
-const apiService = ServiceFactory.createApiService();
-
-// Environment-aware service creation
-const apiService = ServiceFactory.createApiService(
-  ServiceFactory.isDynamics365Context() ? (window as any).Xrm : undefined
-);
-```
-
-#### ❌ DON'T: Hard-code Service Selection
-
-```typescript
-// Avoid hard-coding environment detection
-const apiService =
-  window.location.hostname === 'localhost'
-    ? new MockApiService()
-    : new XrmApiService((window as any).Xrm);
-```
-
-#### ✅ DO: Implement Proper Error Handling in Services
-
-```typescript
-export class XrmApiService implements IApiService {
-  async createRecord(entityName: string, record: any): Promise<any> {
-    try {
-      if (!this.xrm?.WebApi) {
-        throw new Error('Xrm.WebApi is not available');
-      }
-
-      const result = await this.xrm.WebApi.createRecord(entityName, record);
-      Logger.apiOperation('CREATE', entityName, record, 'XrmApiService.createRecord');
-      return result;
-    } catch (error) {
-      Logger.error(`Failed to create ${entityName} record`, 'XrmApiService.createRecord', error);
-      throw new Error(`Unable to create ${entityName}: ${error}`);
-    }
-  }
-}
-```
-
-### 3. Component Architecture
-
-#### ✅ DO: Use the Provider Pattern for API Services
-
-```typescript
-function App() {
-  return (
-    <DynamicsProvider>
-      <LoggingProvider>
-        <Router>
-          <Routes>
-            <Route path="/accounts" element={<AccountManagement />} />
-            <Route path="/contacts" element={<ContactManagement />} />
-          </Routes>
-        </Router>
-      </LoggingProvider>
-    </DynamicsProvider>
-  );
-}
-
-function AccountManagement() {
-  const { apiService } = useDynamicsApi(); // Gets service from context
-  // Component implementation
-}
-```
-
-#### ✅ DO: Implement Proper Loading and Error States
-
-```typescript
-export const AccountManagement: React.FC = () => {
-  const [accounts, setAccounts] = useState<Account[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const loadAccounts = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-
-    try {
-      const accountsData = await Account.retrieveActiveAccounts(apiService);
-      setAccounts(accountsData);
-      Logger.log(`Loaded ${accountsData.length} accounts`, 'AccountManagement.loadAccounts');
-    } catch (error) {
-      const errorMessage = 'Failed to load accounts';
-      setError(errorMessage);
-      Logger.error(errorMessage, 'AccountManagement.loadAccounts', error);
-    } finally {
-      setLoading(false);
-    }
-  }, [apiService]);
-
-  if (loading) return <div>Loading accounts...</div>;
-  if (error) return <div>Error: {error}</div>;
-  if (accounts.length === 0) return <div>No accounts found</div>;
-
-  return (
-    <DetailsList
-      items={accounts}
-      columns={columns}
-      onItemInvoked={handleItemInvoked}
-    />
-  );
-};
-```
-
-#### ❌ DON'T: Ignore Error States
-
-```typescript
-// Avoid this - no error handling
-export const AccountManagement: React.FC = () => {
-  const [accounts, setAccounts] = useState<Account[]>([]);
-
-  useEffect(() => {
-    Account.retrieveActiveAccounts(apiService)
-      .then(setAccounts); // No error handling
-  }, []);
-
-  return <DetailsList items={accounts} columns={columns} />;
-};
-```
-
-## Development Best Practices
-
-### 1. Logging Strategy
-
-#### ✅ DO: Use Structured Logging
-
-```typescript
-// User actions
-Logger.userAction(
-  'Account created',
-  { accountId: result.accountid, accountName: result.name },
-  'AccountForm.handleSubmit'
-);
-
-// API operations
-Logger.apiOperation('CREATE', 'account', accountData, 'Account.create');
-
-// Business logic
-Logger.log('Processing high-value opportunity', 'SalesWorkflow.applyBusinessRules');
-
-// Errors with context
-Logger.error('Validation failed', 'AccountForm.validateForm', {
-  error,
-  formData,
-  validationErrors,
-});
-```
-
-#### ❌ DON'T: Use Console Directly
-
-```typescript
-// Avoid direct console usage
-console.log('Account created'); // No context
-console.error(error); // No structured data
-```
-
-#### ✅ DO: Use Appropriate Log Levels
-
-```typescript
-// Development debugging
-Logger.debug('Form state updated', 'AccountForm.handleInputChange', formData);
-
-// User feedback
-Logger.userAction('Search performed', { searchTerm, resultCount }, 'AccountManagement');
-
-// Performance monitoring
-Logger.timing('Account list load', startTime, 'AccountManagement.loadAccounts');
-
-// Validation feedback
-Logger.validation('Account', errors, 'Account.validate');
-
-// Critical errors
-Logger.error('API service unavailable', 'ServiceFactory.createApiService', error);
-```
-
-### 2. Error Handling Patterns
-
-#### ✅ DO: Implement Layered Error Handling
-
-```typescript
-// Entity Layer - Business logic errors
-export class Account extends BaseEntity {
-  public static async create(apiService: IApiService, account: Account): Promise<Account> {
-    try {
-      account.validate(); // Throws validation errors
-      return await this.createEntity<Account>(apiService, account, AccountConstants.EntityCollectionName);
-    } catch (error) {
-      Logger.error('Account creation failed', 'Account.create', error);
-      throw error; // Re-throw for component handling
-    }
-  }
-}
-
-// Component Layer - User feedback
-export const AccountForm: React.FC = () => {
-  const [submitError, setSubmitError] = useState<string>('');
-
-  const handleSubmit = async () => {
-    try {
-      setSubmitError('');
-      const account = new Account(formData);
-      await Account.create(apiService, account);
-      onSave?.(); // Success callback
-    } catch (error) {
-      if (error instanceof Error) {
-        setSubmitError(error.message); // Show user-friendly message
-      } else {
-        setSubmitError('An unexpected error occurred');
-      }
-      Logger.error('Form submission failed', 'AccountForm.handleSubmit', error);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      {submitError && <div className="error-message">{submitError}</div>}
-      {/* Form fields */}
-    </form>
-  );
-};
-```
-
-#### ✅ DO: Provide User-Friendly Error Messages
-
-```typescript
-const getErrorMessage = (error: unknown): string => {
-  if (error instanceof Error) {
-    // Handle specific error types
-    if (error.message.includes('validation failed')) {
-      return 'Please check your input and try again.';
-    }
-    if (error.message.includes('network')) {
-      return 'Unable to connect to server. Please check your connection.';
-    }
-    if (error.message.includes('permission')) {
-      return 'You do not have permission to perform this action.';
-    }
-    return error.message;
-  }
-  return 'An unexpected error occurred. Please try again.';
-};
-```
-
-### 3. Performance Optimization
-
-#### ✅ DO: Use React Performance Optimizations
-
-```typescript
-// Memoize expensive calculations
-const filteredAccounts = useMemo(() => {
-  return accounts.filter(account =>
-    account.name?.toLowerCase().includes(searchText.toLowerCase())
-  );
-}, [accounts, searchText]);
-
-// Memoize callbacks to prevent unnecessary re-renders
-const handleItemInvoked = useCallback((item: Account) => {
-  Logger.userAction('Account selected', { accountId: item.accountid });
-  setSelectedAccount(item);
-}, []);
-
-// Use React.memo for stable components
-export const AccountListItem = React.memo<{ account: Account }>((props) => {
-  return <div>{props.account.name}</div>;
-});
-```
-
-#### ✅ DO: Implement Efficient Data Loading
-
-```typescript
-// Load only required fields
-const fetchXml = Account.buildFetchXml(
-  AccountConstants.EntityLogicalName,
-  ['accountid', 'name', 'emailaddress1'], // Only fields needed for list
-  filter,
-  { attribute: 'createdon', descending: true }
-);
-
-// Implement pagination for large datasets
-const loadAccountsPage = async (pageNumber: number, pageSize: number = 50) => {
-  const fetchXml = `
-    <fetch mapping="logical" count="${pageSize}" page="${pageNumber}">
-      <entity name="account">
-        <attribute name="accountid" />
-        <attribute name="name" />
-        <attribute name="emailaddress1" />
-        <order attribute="createdon" descending="true" />
-      </entity>
-    </fetch>`;
-
-  return await Account.retrieveEntitiesByFilter(apiService, 'accounts', fetchXml, Account);
-};
-```
-
-### 4. Type Safety
-
-#### ✅ DO: Use Strong Typing Throughout
-
-```typescript
-// Define proper interfaces
-interface AccountFormData {
-  name: string;
-  emailaddress1: string;
-  telephone1: string;
-  revenue: number | null;
-  industrycode: number;
-}
-
-// Use generic types with constraints
-export class BaseEntity {
-  protected static async createEntity<T extends BaseEntity>(
-    apiService: IApiService,
-    entity: T,
-    entityName: string,
-    loggerContext?: string
-  ): Promise<T> {
-    // Implementation
-  }
-}
-
-// Type component props properly
-interface AccountFormProps {
-  accountId?: string;
-  initialData?: Partial<AccountFormData>;
-  onSave?: (account: Account) => void;
-  onCancel?: () => void;
-}
-```
-
-#### ❌ DON'T: Use 'any' Unless Necessary
-
-```typescript
-// Avoid this - too permissive
-const handleSubmit = (data: any) => {
-  // No type safety
-};
-
-// Better - use proper types
-const handleSubmit = (data: AccountFormData) => {
-  // Full type safety
-};
-```
-
-## Deployment Best Practices
-
-### 1. Build Optimization
-
-#### ✅ DO: Use Environment-Specific Builds
-
-```typescript
-// Development build - unminified, with source maps
-"build:dev": "node scripts/custom-build.js --dev"
-
-// Production build - minified, optimized
-"build:prod": "node scripts/custom-build.js"
-
-// D365-specific build - single bundle, web resource ready
-"build:d365": "node scripts/custom-build.js"
-```
-
-#### ✅ DO: Monitor Bundle Size
-
-```typescript
-// Check deployment info after build
-const deploymentInfo = require('./dist/deployment-info.json');
-console.log(`Bundle size: ${deploymentInfo.performance.totalSize} bytes`);
-
-// Ensure size is under D365 limits
-if (deploymentInfo.performance.totalSize > 2000000) {
-  // 2MB limit
-  console.warn('Bundle size exceeds recommended limit for web resources');
-}
-```
-
-### 2. Web Resource Management
-
-#### ✅ DO: Use Consistent Naming Convention
-
-```
-// Web Resource Names
-new_/scripts/accountmanagement_main.js
-new_/scripts/contactmanagement_main.js
-new_/styles/dynamics_ui_styles.css
-new_/pages/accountmanagement.html
-```
-
-#### ✅ DO: Implement Proper Caching Strategy
-
-```typescript
-// Add version numbers to web resources
-const CACHE_VERSION = '1.0.0';
-
-// Check for cached API services
-const getCachedApiService = () => {
-  const cached = sessionStorage.getItem(`apiService_${CACHE_VERSION}`);
-  return cached ? JSON.parse(cached) : null;
-};
-```
-
-### 3. Security Considerations
-
-#### ✅ DO: Validate User Permissions
-
-```typescript
-export class AccountService {
-  public static async create(apiService: IApiService, account: Account): Promise<Account> {
-    // Check user permissions before operations
-    if (!(await this.checkCreatePermission(apiService))) {
-      throw new Error('Insufficient permissions to create accounts');
-    }
-
-    return await Account.create(apiService, account);
-  }
-
-  private static async checkCreatePermission(apiService: IApiService): Promise<boolean> {
-    try {
-      // Use D365 security context
-      const userPrivileges = await apiService.executeRequest('RetrieveUserPrivileges', {});
-      return userPrivileges.some((p) => p.Name === 'prvCreateAccount');
-    } catch {
-      return false; // Fail secure
-    }
-  }
-}
-```
-
-#### ✅ DO: Sanitize User Input
-
-```typescript
-export class BaseEntity {
-  protected static escapeXml(value: string): string {
-    if (!value) return value;
-
-    return value
-      .replace(/&/g, '&amp;')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;')
-      .replace(/"/g, '&quot;')
-      .replace(/'/g, '&apos;');
-  }
-
-  protected static validateInput(input: string, maxLength: number): string {
-    if (!input) return '';
-
-    // Remove potentially dangerous characters
-    const cleaned = input.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
-
-    // Enforce length limits
-    return cleaned.substring(0, maxLength);
-  }
-}
-```
-
-### 4. Testing Strategy
-
-#### ✅ DO: Test in Multiple Environments
-
-```typescript
-// Environment-specific testing
-describe('Account Management', () => {
-  beforeEach(() => {
-    // Test with mock service
-    const mockService = new MockApiService();
-    render(
-      <DynamicsProvider customApiService={mockService}>
-        <AccountManagement />
-      </DynamicsProvider>
-    );
-  });
-
-  test('should create account successfully', async () => {
-    // Test implementation
-  });
-
-  test('should handle validation errors', async () => {
-    // Test error scenarios
-  });
-});
-
-// Integration testing with real D365
-describe('Account Management - Integration', () => {
-  beforeEach(() => {
-    // Test with real Xrm service (in development environment)
-    const xrmService = new XrmApiService((window as any).Xrm);
-    render(
-      <DynamicsProvider customApiService={xrmService}>
-        <AccountManagement />
-      </DynamicsProvider>
-    );
-  });
-});
-```
-
-#### ✅ DO: Implement Quality Gates
-
-```typescript
-// Pre-commit quality checks
-"precommit": "npm run quality"
-"quality": "npm run lint && npm run typecheck"
-
-// Pre-deployment validation
-"validate": "npm run quality && npm run build:prod"
-"prepublishOnly": "npm run validate"
-```
-
-## Maintenance Best Practices
-
-### 1. Documentation
-
-#### ✅ DO: Maintain Comprehensive Documentation
-
-````typescript
-/**
- * Creates a new account with full validation and business rule enforcement
- *
- * @param apiService - The API service instance for Dynamics 365 operations
- * @param account - The account instance to create
- * @returns Promise resolving to the created account with server-generated fields
- *
- * @throws {Error} When validation fails or API operation fails
- *
- * @example
- * ```typescript
- * const account = new Account({ name: 'ACME Corp', emailaddress1: 'info@acme.com' });
- * const created = await Account.create(apiService, account);
- * console.log('Created account:', created.accountid);
- * ```
- */
-public static async create(apiService: IApiService, account: Account): Promise<Account> {
-  // Implementation
-}
-````
-
-### 2. Monitoring and Logging
-
-#### ✅ DO: Implement Production Monitoring
-
-```typescript
-// Performance monitoring
-const performanceObserver = new PerformanceObserver((list) => {
-  for (const entry of list.getEntries()) {
-    if (entry.duration > 1000) {
-      // Log slow operations
-      Logger.performance('Slow operation detected', {
-        name: entry.name,
-        duration: entry.duration,
-        context: 'ProductionMonitoring',
-      });
-    }
-  }
-});
-
-// Error tracking with context
-window.addEventListener('error', (event) => {
-  Logger.error('Unhandled error in production', 'GlobalErrorHandler', {
-    message: event.error?.message,
-    filename: event.filename,
-    lineno: event.lineno,
-    colno: event.colno,
-    stack: event.error?.stack,
-  });
-});
-
-// API failure tracking
-const trackApiFailures = (operation: string, entityName: string, error: Error) => {
-  Logger.error(`API operation failed: ${operation}`, 'ApiFailureTracker', {
-    operation,
-    entityName,
-    error: error.message,
-    timestamp: new Date().toISOString(),
-    userAgent: navigator.userAgent,
-  });
-};
-```
-
-### 3. Version Management
-
-#### ✅ DO: Implement Semantic Versioning
-
-```json
-{
-  "name": "dynamics-365-app",
-  "version": "1.2.3", // MAJOR.MINOR.PATCH
-  "description": "Version changes tracked in CHANGELOG.md"
-}
-```
-
-#### ✅ DO: Maintain Backward Compatibility
-
-```typescript
-// Support both old and new API patterns
-export class Account extends BaseEntity {
-  // New method (preferred)
-  public static async retrieveByName(apiService: IApiService, name: string): Promise<Account[]> {
-    // Implementation
-  }
-
-  // Legacy method (deprecated but supported)
-  /** @deprecated Use retrieveByName instead */
-  public static async findByName(apiService: IApiService, name: string): Promise<Account[]> {
-    Logger.warn('findByName is deprecated, use retrieveByName', 'Account.findByName');
-    return this.retrieveByName(apiService, name);
-  }
-}
-```
-
-## Conclusion
-
-Following these best practices ensures that your Dynamics 365 applications are:
-
-- **Robust**: Comprehensive error handling and validation
-- **Maintainable**: Clean architecture and proper documentation
-- **Performant**: Optimized builds and efficient data loading
-- **Secure**: Input validation and permission checking
-- **Scalable**: Modular architecture that grows with your needs
-- **Type-Safe**: Full TypeScript support throughout
-
-Regular review and adherence to these practices will result in high-quality, enterprise-grade
-Dynamics 365 applications.