clqms-be/.serena/memories/task_completion_checklist.md

# Task Completion Checklist

This checklist should be followed after completing any development task to ensure code quality and consistency.

## Immediate Post-Task Actions

### 1. Run Tests
```bash
# Run all tests to ensure nothing is broken
vendor/bin/phpunit

# If tests fail, run specific test file for debugging
vendor/bin/phpunit tests/feature/[SpecificTestFile].php
```

### 2. Check for PHP Syntax Errors
```bash
# Check syntax of modified files
php -l app/Controllers/YourController.php
php -l app/Models/YourModel.php
```

### 3. Verify Database Changes
```bash
# If you created a migration, verify it was applied
php spark migrate:status

# If you created a migration, run it
php spark migrate
```

### 4. Update API Documentation (CRITICAL)
- **MUST** update `public/api-docs.yaml` after modifying ANY controller
- Update OpenAPI schema definitions for new/changed endpoints
- Update field names, types, and response formats
- Ensure schemas match actual controller responses

## Code Quality Verification

### Controllers Checklist
- [ ] Extends `BaseController`
- [ ] Uses `ResponseTrait`
- [ ] Defines `$this->rules` array for validation
- [ ] Validates input: `$this->validateData($input, $rules)`
- [ ] Uses try-catch with `$this->failServerError()`
- [ ] Returns consistent JSON format: `['status' => 'success', 'message' => '...', 'data' => ...]`
- [ ] Uses `$this->request->getJSON(true)` for POST/PATCH
- [ ] Uses `$this->request->getVar()` for GET parameters
- [ ] Proper HTTP status codes: 200 (success), 201 (created), 400 (validation), 404 (not found), 500 (error)

### Models Checklist
- [ ] Extends `BaseModel` (for UTC normalization)
- [ ] Defines `$table`, `$primaryKey`, `$allowedFields`
- [ ] Uses soft deletes: `$useSoftDeletes = true`, `$deletedField = 'DelDate'`
- [ ] Wraps multi-table operations in transactions
- [ ] Uses `$this->checkDbError($db, 'context')` after DB operations
- [ ] Uses Query Builder, not raw SQL
- [ ] Escapes inputs properly via parameter binding

### Code Style Checklist
- [ ] 2-space indentation
- [ ] Same-line opening braces: `public function index() {`
- [ ] No trailing whitespace
- [ ] Namespace at top: `namespace App\Controllers\...`
- [ ] Organized imports: Framework first, then App libraries/models
- [ ] Classes: PascalCase (`PatientController`)
- [ ] Methods: camelCase (`getPatient`)
- [ ] Variables: camelCase (`$patientId`)
- [ ] Database fields: PascalCase with underscores (`PatientID`, `NameFirst`)

### Security Checklist
- [ ] No secrets logged or committed (JWT_SECRET, passwords)
- [ ] User inputs validated before processing
- [ ] JWT authentication required for protected endpoints
- [ ] SQL injection prevention via Query Builder
- [ ] XSS prevention via proper escaping

### Data Integrity Checklist
- [ ] UTC date normalization via BaseModel
- [ ] Soft delete using `DelDate` field
- [ ] Referential integrity maintained
- [ ] Transactional data consistency via `$db->transBegin()`, `$db->transCommit()`, `$db->transRollback()`

### Testing Checklist
- [ ] Tests written for new functionality
- [ ] Tests extend `CIUnitTestCase`
- [ ] Feature tests use `FeatureTestTrait`
- [ ] JWT token injected via `withHeaders(['Cookie' => 'token=' . $this->token])`
- [ ] Assert JSON structure: `$this->assertIsArray($body['data'])`
- [ ] All tests passing: `vendor/bin/phpunit`

### ValueSet Checklist
- [ ] If using static lookups, use `ValueSet::get('name')`
- [ ] Transform labels: `ValueSet::transformLabels($data, ['Field' => 'valueset'])`
- [ ] If modifying valueset JSON files, call `ValueSet::clearCache()`
- [ ] Valueset JSON files in `app/Libraries/Data/valuesets/`

### Database Checklist
- [ ] Migrations follow naming convention: `YYYY-MM-DD-NNNNNN_Description.php`
- [ ] Migrations define both `up()` and `down()` methods
- [ ] Foreign keys properly defined
- [ ] Indexes added for performance
- [ ] Tables dropped in reverse order in `down()` method

### API Documentation Checklist
- [ ] `public/api-docs.yaml` updated with new/changed endpoints
- [ ] Schemas match actual controller responses
- [ ] Field names and types documented
- [ ] Request/response examples provided
- [ ] Authentication requirements documented

## Verification Steps

### 1. Verify API Endpoints (If Applicable)
```bash
# If you have curl, test the endpoints
curl -X GET http://localhost:8080/api/patient \
  -H "Cookie: token=your_jwt_token"

# Or use a REST client like Postman
```

### 2. Check Logs
```bash
# View recent application logs
type writable\logs\log-*.log  # Windows
# or
tail -f writable/logs/log-*.log  # Unix/Linux
```

### 3. Check Database
```bash
# Verify database state
php spark db:table [table_name]

# Or use your database client (MySQL Workbench, phpMyAdmin, etc.)
```

## Common Issues to Check

### Potential Issues
1. **Tests failing**: Check error messages, add debug output, verify database state
2. **Syntax errors**: Run `php -l` on modified files
3. **Validation errors**: Check `$this->rules` array, ensure input matches expected format
4. **Database errors**: Check migration status, verify table structure
5. **Authentication issues**: Verify JWT token, check `AuthFilter`, ensure route has auth filter
6. **Date issues**: BaseModel handles UTC normalization, verify date formats
7. **Soft deletes**: Check if `DelDate` field is being set, verify queries filter deleted records

### Performance Considerations
- [ ] Database queries optimized (use indexes, avoid SELECT *)
- [ ] Caching used appropriately (ValueSet, query caching)
- [ ] N+1 query problem avoided (use eager loading)
- [ ] Large datasets paginated

## Final Steps

### Before Marking Task Complete
1. **Run all tests**: `vendor/bin/phpunit`
2. **Check syntax**: `php -l` on modified files
3. **Update documentation**: `public/api-docs.yaml` (CRITICAL)
4. **Verify manually**: Test API endpoints if applicable
5. **Clean up**: Remove debug code, comments (unless requested)

### Git Commit (If Requested)
Only commit when explicitly requested by user. If committing:
1. Review changes: `git diff` and `git status`
2. Stage relevant files: `git add .`
3. Create meaningful commit message
4. Commit: `git commit -m "message"`
5. Do NOT push unless explicitly requested

## Example Task Completion Workflow

### Adding a New Controller Method
1. Implement controller method following pattern
2. Add model methods if needed
3. Add route in `app/Config/Routes.php`
4. Create test: `php spark make:test Feature/NewEndpointTest`
5. Implement tests
6. Run tests: `vendor/bin/phpunit`
7. Update `public/api-docs.yaml`
8. Verify with curl or REST client
9. Check syntax: `php -l app/Controllers/YourController.php`
10. Done!

### Modifying Existing Endpoint
1. Modify controller/model code
2. Run tests: `vendor/bin/phpunit`
3. Update `public/api-docs.yaml`
4. Test endpoint manually
5. Check syntax: `php -l` on modified files
6. Done!

### Creating a Database Migration
1. Create migration: `php spark make:migration Description`
2. Define `up()` and `down()` methods
3. Run migration: `php spark migrate`
4. Verify: `php spark migrate:status`
5. Create seeder if needed
6. Run tests to verify no regressions
7. Done!

## Quick Reference Commands

```bash
# Run all tests
vendor/bin/phpunit

# Run specific test
vendor/bin/phpunit tests/feature/SpecificTest.php

# Check PHP syntax
php -l path/to/file.php

# Run migrations
php spark migrate

# Check migration status
php spark migrate:status

# Start dev server
php spark serve

# Clear cache
php spark cache:clear
```