@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,447 @@
+# Migration Guide - Dynamics 365 Template
+
+## Overview
+
+This guide helps you migrate existing Dynamics 365 projects to use the enhanced template patterns
+and architecture.
+
+## Migration Scenarios
+
+### 1. From Basic React D365 Apps
+
+If you have a basic React application for Dynamics 365:
+
+#### Before (Basic Pattern)
+
+```typescript
+// Direct API calls without abstraction
+function createAccount(data) {
+  return Xrm.WebApi.createRecord('account', data);
+}
+
+// Component with inline API logic
+function AccountForm() {
+  const handleSubmit = async () => {
+    try {
+      await Xrm.WebApi.createRecord('account', formData);
+    } catch (error) {
+      console.error(error);
+    }
+  };
+}
+```
+
+#### After (Enhanced Pattern)
+
+```typescript
+// Entity model with validation and logging
+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'
+    );
+  }
+}
+
+// Component using service layer
+function AccountForm() {
+  const { apiService } = useDynamicsApi();
+
+  const handleSubmit = async () => {
+    try {
+      const account = new Account(formData);
+      await Account.create(apiService, account);
+      Logger.userAction('Account created', { name: formData.name });
+    } catch (error) {
+      Logger.error('Failed to create account', 'AccountForm', error);
+    }
+  };
+}
+```
+
+#### Migration Steps
+
+1. **Install the Template Dependencies**
+
+   ```bash
+   npm install @khester/dynamics-ui-components @khester/dynamics-ui-api-client
+   ```
+
+2. **Create Entity Models**
+   - Copy `src/models/BaseEntity.ts` to your project
+   - Create entity models extending BaseEntity
+   - Add constants files for field definitions
+
+3. **Implement Service Layer**
+   - Copy `src/services/ServiceFactory.ts`
+   - Copy API service implementations
+   - Update components to use the service layer
+
+4. **Add Logging System**
+   - Copy `src/components/Logging/` directory
+   - Wrap your app with `LoggingProvider`
+   - Replace console calls with Logger methods
+
+### 2. From PCF Controls to Template
+
+If you're building PCF controls:
+
+#### Before (Basic PCF)
+
+```typescript
+export class MyControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
+  public init(context: ComponentFramework.Context<IInputs>): void {
+    // Direct DOM manipulation or basic React
+    this.container.innerHTML = '<div>Basic Content</div>';
+  }
+}
+```
+
+#### After (Template PCF)
+
+```typescript
+export class MyControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
+  public init(context: ComponentFramework.Context<IInputs>): void {
+    // Use sophisticated wrapper components
+    ReactDOM.render(
+      React.createElement(CustomPCFWrapper, {
+        context,
+        entityType: 'contact',
+        enableLogging: true,
+        showTabs: true,
+      }),
+      this.container
+    );
+  }
+}
+```
+
+#### Migration Steps
+
+1. **Copy PCF Wrapper Components**
+   - Copy `src/pcf/` directory to your PCF project
+   - Update your PCF control to use the wrappers
+
+2. **Integrate with Entity Models**
+   - Copy entity models and constants
+   - Use the service factory for API access
+
+3. **Update PCF Configuration**
+   - Update your `ControlManifest.Input.xml`
+   - Ensure React dependencies are included
+
+### 3. From Web Resources to Template
+
+If you're using traditional web resources:
+
+#### Before (Traditional Web Resources)
+
+```html
+<!-- HTML Web Resource -->
+<script src="/scripts/jquery.min.js"></script>
+<script src="/scripts/custom.js"></script>
+<div id="myApp">
+  <!-- Static HTML content -->
+</div>
+
+<script>
+  // Direct Xrm calls
+  function loadAccounts() {
+    Xrm.WebApi.retrieveMultipleRecords('account', '?$select=name,accountid').then(
+      function (result) {
+        // Manual DOM manipulation
+        var html = '';
+        result.entities.forEach(function (account) {
+          html += '<div>' + account.name + '</div>';
+        });
+        document.getElementById('accountList').innerHTML = html;
+      }
+    );
+  }
+</script>
+```
+
+#### After (Template Web Resources)
+
+```html
+<!-- Modern React Web Resource -->
+<div id="root"></div>
+<script src="/scripts/main.js"></script>
+
+<!-- main.js contains the compiled React app -->
+<script>
+  // Sophisticated React application with:
+  // - Entity models and validation
+  // - Service layer abstraction
+  // - Comprehensive logging
+  // - Error handling
+  // - Type safety
+</script>
+```
+
+#### Migration Steps
+
+1. **Generate Template Application**
+
+   ```bash
+   npx @khester/create-dynamics-app my-app --template dynamics-365
+   ```
+
+2. **Copy Existing Business Logic**
+   - Convert existing functions to entity model methods
+   - Move validation to model classes
+   - Replace direct DOM manipulation with React components
+
+3. **Build and Deploy**
+   ```bash
+   npm run build:prod
+   # Upload dist/main.js as Script (JScript) web resource
+   # Upload dist/index.html as Web Page (HTML) web resource
+   ```
+
+## Best Practices for Migration
+
+### 1. Incremental Migration
+
+Don't migrate everything at once. Start with:
+
+1. **Core Infrastructure**
+   - Service factory and API services
+   - Logging system
+   - Base entity class
+
+2. **One Entity at a Time**
+   - Pick the most important entity
+   - Create model, constants, and components
+   - Test thoroughly before moving to next entity
+
+3. **Component by Component**
+   - Replace existing forms with template components
+   - Update list views to use DetailsList patterns
+   - Add proper error handling and validation
+
+### 2. Data Validation Migration
+
+#### Before
+
+```typescript
+function validateAccount(data) {
+  var errors = [];
+  if (!data.name) {
+    errors.push('Name is required');
+  }
+  return errors;
+}
+```
+
+#### After
+
+```typescript
+export class Account extends BaseEntity {
+  public validate(): boolean {
+    const errors: string[] = [];
+
+    if (!this.name?.trim()) {
+      errors.push('Account name is required');
+    }
+
+    if (this.name && this.name.length > 160) {
+      errors.push('Account name cannot exceed 160 characters');
+    }
+
+    if (errors.length > 0) {
+      Logger.validation('Account', errors, 'Account.validate');
+      throw new Error(`Validation failed: ${errors.join(', ')}`);
+    }
+
+    return true;
+  }
+}
+```
+
+### 3. Error Handling Migration
+
+#### Before
+
+```typescript
+try {
+  await Xrm.WebApi.createRecord('account', data);
+  alert('Success');
+} catch (error) {
+  alert('Error: ' + error.message);
+}
+```
+
+#### After
+
+```typescript
+try {
+  const account = new Account(data);
+  const result = await Account.create(apiService, account);
+  Logger.userAction('Account created successfully', { accountId: result.accountid });
+  // Use proper UI notifications instead of alerts
+} catch (error) {
+  Logger.error('Failed to create account', 'AccountForm.handleSubmit', error);
+  // Show user-friendly error message
+  setErrorMessage('Unable to create account. Please try again.');
+}
+```
+
+### 4. Environment Detection Migration
+
+#### Before
+
+```typescript
+// Hard-coded environment logic
+if (window.location.hostname === 'localhost') {
+  // Use mock data
+} else {
+  // Use Xrm.WebApi
+}
+```
+
+#### After
+
+```typescript
+// Sophisticated environment detection
+const apiService = ServiceFactory.createApiService();
+// Automatically detects environment and provides appropriate service
+```
+
+## Common Migration Challenges
+
+### 1. TypeScript Adoption
+
+**Challenge**: Existing JavaScript code needs TypeScript conversion
+
+**Solution**:
+
+1. Start with `.ts` files and `any` types
+2. Gradually add proper type definitions
+3. Use the template's interface definitions as examples
+
+### 2. Bundle Size Concerns
+
+**Challenge**: React app may be larger than traditional web resources
+
+**Solution**:
+
+- Use the template's optimized build configuration
+- Production build is only ~726KB
+- Enable compression in IIS for web resources
+- Consider code splitting for large applications
+
+### 3. PCF Framework Limitations
+
+**Challenge**: PCF has restrictions on external dependencies
+
+**Solution**:
+
+- Use the template's PCF wrapper patterns
+- Bundle dependencies in the control
+- Use the provided ComponentFramework type definitions
+
+### 4. Dynamics 365 API Differences
+
+**Challenge**: Different API behaviors between environments
+
+**Solution**:
+
+- Use the ServiceFactory to abstract differences
+- Implement environment-specific logic in service classes
+- Test thoroughly in both development and production
+
+## Migration Checklist
+
+### Pre-Migration Assessment
+
+- [ ] Inventory existing entities and operations
+- [ ] Identify current validation logic
+- [ ] Document existing API usage patterns
+- [ ] Assess current error handling approaches
+
+### Migration Implementation
+
+- [ ] Set up development environment with template
+- [ ] Create entity models for core entities
+- [ ] Implement service layer abstraction
+- [ ] Add logging throughout application
+- [ ] Create management components
+- [ ] Implement proper error handling
+- [ ] Add comprehensive validation
+
+### Testing and Validation
+
+- [ ] Test in development environment
+- [ ] Validate all CRUD operations
+- [ ] Test error scenarios
+- [ ] Verify logging functionality
+- [ ] Test build and deployment process
+- [ ] User acceptance testing
+
+### Production Deployment
+
+- [ ] Build production bundle
+- [ ] Upload web resources to D365
+- [ ] Configure security roles
+- [ ] Train users on new interface
+- [ ] Monitor for issues
+
+## Support and Resources
+
+### Template Resources
+
+- **Documentation**: README.md in template root
+- **Examples**: `/src/examples/` directory
+- **Integration Tests**: INTEGRATION_TEST_RESULTS.md
+
+### Development Tools
+
+- **Quality Scripts**: `npm run quality`
+- **Build Validation**: `npm run validate`
+- **Type Checking**: `npm run typecheck`
+
+### Community and Support
+
+- **GitHub Issues**: Report problems or ask questions
+- **Documentation**: Comprehensive inline documentation
+- **Examples**: Real-world implementation patterns
+
+## Version Compatibility
+
+### Dynamics 365 Versions
+
+- **Online**: Fully supported
+- **On-Premises**: Compatible with modern browsers
+- **Government Cloud**: Supported
+
+### Browser Support
+
+- **Chrome**: 70+
+- **Edge**: 79+
+- **Firefox**: 65+
+- **Safari**: 12+
+
+### Node.js Versions
+
+- **Minimum**: Node 16+
+- **Recommended**: Node 18+
+- **Latest**: Node 20+
+
+## Conclusion
+
+Migrating to the enhanced Dynamics 365 template provides significant benefits:
+
+- **Type Safety**: Full TypeScript support
+- **Error Handling**: Comprehensive error management
+- **Logging**: Detailed operation tracking
+- **Validation**: Client-side and business rule validation
+- **Performance**: Optimized build process
+- **Maintainability**: Clean architecture patterns
+- **Developer Experience**: Modern tooling and documentation
+
+The migration process, while requiring initial effort, results in more robust, maintainable, and
+scalable Dynamics 365 applications.

package/templates/dynamics-365-starter/docs/team-standards/README.md

@@ -0,0 +1,273 @@
+# Developer Team Standards
+
+This directory contains standards, guidelines, and best practices for the development team working
+on Dynamics 365 consulting projects.
+
+## Table of Contents
+
+1. [Coding Standards](./coding-standards.md) - Code style, naming conventions, and structure
+2. [Entity Development Guidelines](./entity-development.md) - Standards for entity model development
+3. [Code Review Checklist](./code-review-checklist.md) - Comprehensive review checklist
+4. [Client Onboarding Procedures](./client-onboarding.md) - Process for new client projects
+5. [Quality Assurance Standards](./quality-assurance.md) - Testing and QA requirements
+6. [Deployment Best Practices](./deployment-practices.md) - Deployment procedures and standards
+7. [Security Guidelines](./security-guidelines.md) - Security requirements and best practices
+8. [Performance Standards](./performance-standards.md) - Performance optimization guidelines
+9. [Documentation Standards](./documentation-standards.md) - Documentation requirements
+10. [Team Workflows](./team-workflows.md) - Development team processes
+
+## Quick Reference
+
+### Before Starting Development
+
+- [ ] Review client requirements and configuration
+- [ ] Set up development environment
+- [ ] Understand entity relationships and business logic
+- [ ] Review existing codebase and patterns
+
+### During Development
+
+- [ ] Follow coding standards and naming conventions
+- [ ] Write comprehensive unit tests
+- [ ] Document all public APIs and complex logic
+- [ ] Use the entity generator for new entities
+- [ ] Implement proper error handling and logging
+
+### Before Code Review
+
+- [ ] Run all quality checks: `npm run quality`
+- [ ] Ensure all tests pass
+- [ ] Update documentation if needed
+- [ ] Test in development environment
+- [ ] Verify client-specific requirements are met
+
+### Before Deployment
+
+- [ ] Complete code review process
+- [ ] Verify deployment checklist
+- [ ] Test in staging environment
+- [ ] Get client approval
+- [ ] Execute deployment plan
+
+## Tools and Automation
+
+### Available Scripts
+
+```bash
+# Quality checks
+npm run quality          # Run all quality checks
+npm run lint            # Code linting
+npm run typecheck       # TypeScript type checking
+npm run test           # Run unit tests
+
+# Code generation
+npm run generate:entity -- --entity customentity --display-name "Custom Entity"
+
+# Building
+npm run build:dev      # Development build
+npm run build:prod     # Production build
+npm run build:d365     # Dynamics 365 optimized build
+
+# Development
+npm run start          # Start development server
+npm run dev           # Development mode with hot reload
+```
+
+### Automated Quality Gates
+
+All projects include automated quality gates:
+
+- **ESLint** - Code style and potential error detection
+- **TypeScript** - Type safety and compile-time error checking
+- **Prettier** - Code formatting consistency
+- **Jest** - Unit testing framework
+- **Husky** - Git hooks for pre-commit quality checks
+
+## Team Structure
+
+### Roles and Responsibilities
+
+**Technical Lead**
+
+- Architecture decisions
+- Code review oversight
+- Client technical discussions
+- Team mentoring
+
+**Senior Developers**
+
+- Feature implementation
+- Code reviews
+- Junior developer mentoring
+- Technical documentation
+
+**Developers**
+
+- Feature development
+- Unit testing
+- Bug fixes
+- Documentation updates
+
+**QA Engineer**
+
+- Test plan creation
+- Manual testing
+- Automated test development
+- Client acceptance testing
+
+**DevOps Engineer**
+
+- Deployment automation
+- Environment management
+- CI/CD pipeline maintenance
+- Infrastructure monitoring
+
+## Communication Standards
+
+### Daily Standups
+
+- Progress since last standup
+- Plans for today
+- Any blockers or issues
+- Client-specific updates
+
+### Code Reviews
+
+- All code must be reviewed by at least one senior developer
+- Use GitHub pull request process
+- Follow code review checklist
+- Provide constructive feedback
+
+### Client Communication
+
+- Weekly status updates
+- Demo sessions for new features
+- Issue escalation procedures
+- Change request processes
+
+## Emergency Procedures
+
+### Production Issues
+
+1. Immediately notify Technical Lead
+2. Create incident ticket
+3. Assess impact and severity
+4. Implement hotfix if needed
+5. Communicate with client
+6. Post-incident review
+
+### Data Loss Prevention
+
+- Daily automated backups
+- Point-in-time recovery capability
+- Data validation procedures
+- Access control and audit logging
+
+## Training and Development
+
+### New Team Member Onboarding
+
+1. Environment setup and access
+2. Codebase walkthrough
+3. Client background and requirements
+4. Pair programming session
+5. First feature assignment with mentoring
+
+### Continuous Learning
+
+- Monthly tech talks
+- Code kata sessions
+- Conference attendance budget
+- Certification support
+- Knowledge sharing sessions
+
+## Metrics and KPIs
+
+### Code Quality Metrics
+
+- Code coverage percentage (target: >80%)
+- Technical debt ratio
+- Bug report rate
+- Code review cycle time
+
+### Client Satisfaction Metrics
+
+- Feature delivery on time
+- Bug resolution time
+- Client feedback scores
+- Change request turnaround
+
+### Team Performance Metrics
+
+- Sprint velocity
+- Burndown accuracy
+- Code review participation
+- Knowledge sharing activities
+
+## Resources
+
+### Internal Resources
+
+- [Internal Wiki](https://wiki.company.com/dynamics365)
+- [Code Templates](https://github.com/company/dynamics-templates)
+- [Best Practices Repository](https://github.com/company/best-practices)
+
+### External Resources
+
+- [Microsoft Dynamics 365 Documentation](https://docs.microsoft.com/dynamics365/)
+- [Power Platform Documentation](https://docs.microsoft.com/power-platform/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
+- [React Documentation](https://reactjs.org/docs/)
+- [Fluent UI Documentation](https://developer.microsoft.com/fluentui/)
+
+## Getting Help
+
+### Technical Issues
+
+1. Check documentation and existing solutions
+2. Ask team members in Slack
+3. Escalate to Technical Lead if needed
+4. Create knowledge base entry for solution
+
+### Client Issues
+
+1. Review client requirements and SOW
+2. Discuss with Account Manager
+3. Schedule client meeting if needed
+4. Document resolution for future reference
+
+## Version Control
+
+### Branch Naming
+
+- `feature/client-feature-name` - New features
+- `bugfix/issue-description` - Bug fixes
+- `hotfix/critical-issue` - Emergency fixes
+- `release/version-number` - Release branches
+
+### Commit Messages
+
+Follow conventional commit format:
+
+```
+type(scope): description
+
+Examples:
+feat(entities): add Opportunity entity with validation
+fix(auth): resolve token refresh issue
+docs(readme): update deployment instructions
+```
+
+### Release Process
+
+1. Create release branch
+2. Update version numbers
+3. Generate changelog
+4. Test in staging environment
+5. Deploy to production
+6. Tag release
+7. Merge to main branch
+
+---
+
+For questions about these standards, contact the Technical Lead or refer to the team wiki.