[SERVICE] Add CostCalcService for Cost Calculation Engine

[ilramdhan]

Service Information

Basic Info

• Domain: [x] finance [ ] iam [ ] hr [ ] it [ ] Other: _______
• Service Name: CostCalcService
• Entity Name: CalJob, CostResult

Service Definition

Entity Message

// Core entity messages for Cost Calculation
message CalJob {
  string id = 1;
  string period = 2;
  string status = 3;
  // Additional audit and metadata fields...
}

message CostResult {
  string id = 1;
  string product_id = 2;
  string period = 3;
  // Detail breakdown and evaluation fields...
}

RPC Methods

Method	Description
TriggerCalcJob	Initiates a new cost calculation job for a specific period
GetCalJob	Retrieves calculation job details
ListCalJobs	Lists and filters calculation jobs
GetCalJobChunks	Retrieves chunks associated with a calculation job
GetCalJobProducts	Retrieves products linked to a specific calculation job
CancelCalJob	Cancels an ongoing calculation job
ProcessChunkInternal	Internal worker bridge delegating to app.Service.ProcessChunk (gated by finance.cost.caljob.trigger permission, no REST exposure)
GetCostResult	Retrieves specific cost result details
GetCostBreakdown	Retrieves detailed cost breakdown (LevelBreakdown, CostRMDetail)
GetCostHistory	Retrieves historical cost data (CostHistoryEntry)
VerifyCostResult	Marks a cost result as verified
ApproveCostResult	Approves a finalized cost result
ListCostResults	Cross-product list/filter for active cost results (latest-period default)

REST Endpoints

Method	Path	Description
POST	/api/v1/finance/cost-calc-jobs	Trigger calculation job
GET	/api/v1/finance/cost-calc-jobs	List calculation jobs
GET	/api/v1/finance/cost-calc-jobs/{id}	Get calculation job details
POST	/api/v1/finance/cost-calc-jobs/{id}/cancel	Cancel calculation job
GET	/api/v1/finance/cost-results	List active cost results across products
GET	/api/v1/finance/cost-results/{id}	Get specific cost result
POST	/api/v1/finance/cost-results/{id}/verify	Verify cost result
POST	/api/v1/finance/cost-results/{id}/approve	Approve cost result

Validation Requirements

Field	Validation
period	Required, format validation for period (e.g., YYYY-MM)
chunk_data	Required for ProcessChunkInternal worker bridge
product_id	UUID format (resolved to string representation in responses)

Dependencies

• Uses common/v1/common.proto
• Uses google/api/annotations.proto
• Uses buf/validate/validate.proto
• Other domain protos: _______________

Checklist

• I have read RULES.md
• Field names follow snake_case
• Enums have UNSPECIFIED = 0
• REST mappings follow conventions