4、分摊引擎架构：分摊计算引擎的模块划分、输入输出接口、调度流程

分摊计算引擎是成本台账系统的核心计算单元，负责将公共成本（如水电费、折旧、管理费）按照预定义的分摊规则精确分配到多个成本对象（项目、部门、产品）。本章从架构视角拆解引擎的模块边界、接口契约与调度机制，为后续接口测试提供结构化的分析基础。

4.1 模块划分与职责

分摊引擎采用分层+微内核设计，核心模块包括以下五个部分：

4.2 输入输出接口定义

分摊引擎对外暴露三个核心接口，接口契约采用JSON Schema定义，确保上下游系统解耦。

4.2.1 分摊任务提交接口（输入）

POST /api/v1/allocation/task
Content-Type: application/json

{
  "taskId": "ALLOC_20250321_001",
  "period": "2025-03",
  "costCenterIds": ["CC001", "CC002"],
  "ruleGroupId": "RG_DEFAULT",
  "targetObjects": [
    {"type": "project", "ids": ["PJ-A", "PJ-B", "PJ-C"]},
    {"type": "department", "ids": ["DEPT-SALES", "DEPT-RD"]}
  ],
  "options": {
    "dryRun": false,
    "rollbackOnError": true,
    "timeoutSeconds": 300
  }
}

4.2.2 分摊结果查询接口（输出）

GET /api/v1/allocation/result/{taskId}
Response:

{
  "taskId": "ALLOC_20250321_001",
  "status": "COMPLETED",
  "totalCost": 1250000.00,
  "allocatedCost": 1250000.00,
  "details": [
    {
      "sourceCostCenter": "CC001",
      "targetObject": {"type": "project", "id": "PJ-A"},
      "amount": 350000.00,
      "ruleApplied": "按面积分摊",
      "baseValue": 3500.0,
      "unit": "平方米"
    }
  ],
  "errors": []
}

4.2.3 接口对比表

4.3 调度流程与状态机

分摊引擎的调度流程采用有限状态机模型，确保每个任务的生命周期可追踪、可恢复。下图展示了从任务提交到结果回写的完整调度路径：

4.4 调度时序与重试机制

引擎调度控制器按以下时序执行任务，并内置三级重试策略：

1. 任务接收： 控制器校验taskId唯一性，若重复则直接返回已有结果（幂等）。
2. 数据加载： 调用数据加载器，若加载超时（默认30秒）或数据不完整，触发一级重试（最多3次，间隔5秒）。
3. 分摊计算： 计算器执行策略树，若计算过程中出现除零、空指针等异常，触发二级重试（最多2次，间隔10秒）。
4. 结果持久化： 写入数据库时若发生死锁或唯一键冲突，触发三级重试（最多5次，间隔1秒，使用指数退避）。
5. 回调通知： 任务最终状态（COMPLETED/FAILED）通过Webhook通知调用方，通知失败则进入死信队列人工处理。

4.5 架构图：模块间依赖与数据流

下图展示了分摊引擎各模块之间的依赖关系与数据流向，帮助测试人员理解接口调用的上下游依赖：