feat(api): enhance batch and task management with automatic status transitions

[shark0F0497]

Pull Request Checklist

Please ensure your PR meets the following requirements:

• Code follows the style guidelines
• Tests pass locally
• Code is formatted
• Documentation updated if needed
• Commit messages follow conventional commits
• PR description is complete and clear

---

Summary

This PR implements a complete production lifecycle management system, adding batch/task lifecycle automation, Axon recorder integration, and automatic order/batch status transitions based on task completion.

---

Motivation

The current API lacks proper batch and task lifecycle management. Key issues addressed:

• No way to create batches with tasks programmatically
• Manual status tracking required for batch/order completion
• No integration with Axon recorder devices for task state synchronization
• No support for batch recall functionality
• Task status transitions were not validated against parent batch state

This PR solves these by implementing automatic status advancement, device-side notifications, and declarative batch management.

---

Changes

Modified Files

• cmd/keystone-edge/main.go - Added recorder RPC timeout configuration
• docs/designs/production-units.md - Updated design documentation
• internal/api/handlers/auth.go - Extended auth handler with recorder hub
• internal/api/handlers/axon_rpc.go - Added automatic task status advancement on config/begin RPCs, device disconnect handling
• internal/api/handlers/batch.go - Major enhancement: added CreateBatch, AdjustBatchTasks, RecallBatch, ListBatchTasks; refactored PatchBatch for cancellation-only; added task status counting (completed/cancelled/failed)
• internal/api/handlers/common.go - Common function updates
• internal/api/handlers/episode.go - Episode handler updates
• internal/api/handlers/order.go - Added task count fields, automatic status advancement (created→in_progress→completed), target_count validation, open batch finalization on order completion
• internal/api/handlers/robot.go - Robot handler updates
• internal/api/handlers/skill.go - Skill handler updates
• internal/api/handlers/sop.go - SOP handler updates
• internal/api/handlers/station.go - Station handler updates
• internal/api/handlers/task.go - Added task_id filter, removed direct cancellation (must use batch), added batch status validation, new status transitions (pending→ready→in_progress→completed/failed)
• internal/api/handlers/transfer.go - Enhanced upload handling, added batch/order status advancement after upload complete, device disconnect task revert
• internal/server/server.go - Updated handler initialization to include recorder hub
• internal/services/recorder_hub.go - Hub updates for new functionality
• internal/storage/database/migrations/000001_initial_schema.up.sql - Schema changes: batches.name nullable, removed skills/sops name columns, updated unique constraints

Added Files

• (No new files - all changes are modifications to existing files)

Deleted Files

• (No files deleted)

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update (documentation changes only)
• Refactoring (code improvement without functional changes)
• Performance improvement (code changes that improve performance)
• Test changes (adding, modifying, or removing tests)

---

Impact Analysis

Breaking Changes

The following breaking changes require attention:

1. PATCH /batches/:id behavior change: Previously allowed pending→active and active→completed transitions. Now only supports cancellation (pending/active→cancelled). Use automatic status advancement instead.

2. PUT /tasks/:id cancellation removed: Setting status to "cancelled" is no longer allowed via task endpoint. Must use PATCH /batches/:id to cancel the parent batch.

3. DELETE /batches/:id response changed: Returns 200 with JSON body instead of 204 No Content.

4. Database schema changes:

   • batches.name is now nullable
   • skills.name column removed (use slug)
   • sops.name column removed (use slug)

Backward Compatibility

Partially backward compatible with deprecation warnings in API responses. Client applications using PATCH batch for status transitions other than cancellation will need to be updated.

---

Testing

Test Environment

• Go 1.22+
• MySQL 8.0+
• golangci-lint passed

Test Cases

• Unit tests pass locally
• Integration tests pass locally
• E2E tests pass (if applicable)
• Manual testing completed

Manual Testing Steps

Tested via curl/Postman:

1. Created batch with task_groups via POST /batches
2. Adjusted task quantities via POST /batches/:id/tasks
3. Cancelled batch via PATCH /batches/:id (status=cancelled)
4. Recalled active/completed batch via POST /batches/:id/recall
5. Verified task status transitions: pending→ready→in_progress→completed
6. Verified order auto-advancement: created→in_progress→completed
7. Verified recorder device disconnect reverts runnable tasks

Test Coverage

• New tests added
• Existing tests updated
• Coverage maintained or improved

---

Screenshots / Recordings

---

Performance Impact

• Memory usage: No change
• CPU usage: No change (async status advancement uses goroutines)
• Throughput: No change
• Lock contention: Reduced (status advancement uses row-level FOR UPDATE)

---

Documentation

• README.md updated
• ARCHITECTURE.md updated
• CONTRIBUTING.md updated
• API documentation updated (inline Swagger annotations)
• Design docs updated in docs/designs/production-units.md
• No documentation changes needed

---

Related Issues

• Fixes # (create issue first)
• Related to #
• Refers to #

---

Additional Notes

1. Status Advancement: Batch and order status advancement happens automatically after task completion. No manual intervention required.

2. Recorder Integration: When devices connect/disconnect or batches are cancelled, the system automatically notifies the Axon recorder to clear/cancel configurations.

3. Transaction Safety: All critical operations use transactions to ensure consistency between tasks, batches, and orders.

4. Best-Effort Notifications: Recorder RPC failures are logged but do not block the main operation (e.g., batch cancellation still succeeds even if device is unreachable).

---

Reviewers

@kilo-code-bot

---

Notes for Reviewers

• Please review the batch state machine changes in internal/api/handlers/batch.go
• Focus on the concurrency safety of tryAdvanceBatchStatus and tryAdvanceOrderStatus
• Verify recorder notification logic handles edge cases (device offline, network timeout)
• Check backward compatibility implications for existing API clients

---

Checklist for Reviewers

• Code changes are correct and well-implemented
• Tests are adequate and pass
• Documentation is updated and accurate
• No unintended side effects
• Performance impact is acceptable
• Backward compatibility maintained (where applicable)

[shark0F0497]

kilo reviewer crashed, run locally