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

# 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

# Check syntax of modified files
php -l app/Controllers/YourController.php
php -l app/Models/YourModel.php

3. Verify Database Changes

# 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)

# 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

# View recent application logs
type writable\logs\log-*.log  # Windows
# or
tail -f writable/logs/log-*.log  # Unix/Linux

3. Check Database

# 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

# 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