# Backend 渐进式优化设计

> 本文面向 dcalc backend 的渐进式架构优化。目标是在不改变 `/calc` API 契约、不破坏 frontendNew 计算链路的前提下，逐步提升后端可维护性、扩展性、计算效率与开发规范。

## 背景

当前仓库前端迁移主线是 `frontend -> frontendNew`，backend 必须优先服务 Dcalc Character 模块的稳定计算链路：equipment、skill、forge、result。backend 现有结构已经完成过一次 `core/basic/character_old.py` 到 `core/basic/character/` 多文件 mixin 的拆分，说明当前更适合继续做小步收口，而不是推倒重写。

关键入口：

- `/calc` 路由：`backend/api/routes/calc.py`
- 应用入口：`backend/main.py`
- 角色计算核心：`backend/core/basic/character/`
- 装备数据装载：`backend/core/basic/equipment.py`
- 数据库连接：`backend/database/connect.py`
- Redis 预热：`backend/api/core/RedisPreheat.py`

## 非目标

- 不改 `/calc` 的请求语义、响应包装、`data` 主体字段结构。
- 不改 frontendNew 依赖的 IResult 数据消费方式。
- 不重写 Skill、Forge、装备效果、职业技能的核心业务逻辑。
- 不在 backend 优化中引入新的 UI、前端状态管理或前端接口契约调整。
- 不一次性格式化全仓 Python 文件，避免制造大规模无关 diff。

## 现状问题

### API 与计算耦合

`backend/api/routes/calc.py` 直接 `createCharacter(...).calc(config)`。这让鉴权、请求适配、计算编排、错误处理和未来耗时统计都挤在 API 调用路径上，不利于扩展。

### config 读取分散

计算过程中大量直接访问 `setInfo.get(...)`、`info['equips']`、`info['oaths']`。默认值、兼容逻辑和输入容错散落在 mixin 中，后续 Skill/Forge 配置演进时容易漏字段。

### 装备数据全局缓存边界不清

`backend/core/basic/equipment.py` 启动时构造 `equ0 = Equipments('0')`，`get_equipment()` 通过动态变量和 `eval` 获取版本。该方式对当前性能有帮助，但多版本扩展、测试隔离、热更新和错误定位较弱。

### 计算对象状态可变

`Character` 实例在 `calc_init -> calc_* -> calc_*_skills` 过程中持续变异属性、技能等级、装备效果和输出类型。该模式符合当前业务写法，但缺少明确的一次性计算上下文，测试和复用成本偏高。

### 性能缺少量化

已有内存化装备数据、技能类缓存、Redis 预热等优化点，但 `/calc` 的耗时瓶颈没有分段统计。后续不应凭感觉优化。

### 测试安全网不足

当前仅看到 `backend/test.py`，没有正式 `tests/` 体系。后续重构计算链路时，缺少 golden case 来确认字段与数值没有回退。

## 优化原则

1. 接口冻结：先用测试固定 `/calc` 外部行为，再改内部结构。
2. 小步可回滚：每个阶段能单独合并、单独验证。
3. 先边界后算法：优先整理 service、config view、repository/registry，再考虑公式与缓存。
4. 只搬运不改义：拆文件、封 helper 时不改变公式含义。
5. 先量化后性能：先加耗时指标，再按热点优化。

## 目标架构

```text
backend/
  api/
    routes/
      calc.py              # 只负责 HTTP 层：依赖注入、Body、response
  services/
    calc_service.py        # /calc 应用服务：创建角色、执行计算、计时、错误上下文
  schemas/
    calc.py                # 宽松 config schema 与响应类型别名
    response.py            # 通用响应类型，保持旧格式兼容
  core/
    basic/
      character/
        config_view.py     # CalcConfigView：统一默认值、兼容旧 config
        effect_apply.py    # 统一属性提取与 effect 执行 helper
      equipment.py         # 保留现有模型，逐步委托给 registry
      equipment_registry.py # EquipmentRegistry：装备版本懒加载与缓存
  tests/
    contract/
      test_calc_contract.py
    golden/
      test_calc_golden.py
    unit/
      test_equipment_registry.py
      test_calc_config_view.py
```

## 数据流

```text
HTTP POST /api/calc
  -> AltersDep 解析 alter/equVersion
  -> calc_service.calculate(state, raw_config)
  -> CalcConfigView.from_raw(raw_config)
  -> createCharacter(state.alter, state.equVersion)
  -> character.calc(config_view 或兼容 dict)
  -> calc_service 返回原始计算 data
  -> response(data=data)
```

短期内 `Character.calc()` 仍接收原 `dict`，`CalcConfigView` 先作为内部读取辅助逐步接入。等测试稳定后，再考虑让 `Character.calc()` 接收 `CalcConfigView`。

## 分阶段设计

### Phase 0：测试安全网

建立 pytest 测试结构，固定 `/calc` 契约和典型职业结果结构。

重点：

- 增加 `pytest` 开发依赖。
- 增加可复用的最小 config fixture。
- 增加 `/api/calc` HTTP contract 测试。
- 增加 `createCharacter(...).calc(...)` golden smoke 测试。

成功标准：

- `uv run pytest` 可执行。
- `/calc` 响应仍包含 `code/message/data`。
- `data` 至少包含 `uuid/skills/info/suits/buffer`。

### Phase 1：API service 边界

新增 `backend/services/calc_service.py`，API route 不再直接编排计算。

重点：

- route 保持原路径、请求体和响应格式。
- service 负责 `createCharacter`、空 config 兜底、计算执行。
- 为后续日志、耗时、缓存预留 service 层。

成功标准：

- `/api/calc` 行为不变。
- route 文件只保留 HTTP 层职责。
- Phase 0 测试全部通过。

### Phase 2：config view 与计算输入收口

新增 `CalcConfigView`，集中处理 config 的默认值与字段读取。

重点：

- `equips/oaths/emblems/skills/avatar/sundry/jades/options` 都有稳定默认值。
- 先在 `calc_init()`、`SetDetail()`、`SetSkills()` 等入口使用，不一次性替换所有 mixin。
- 保留向后兼容，仍支持原始 dict。

成功标准：

- 缺少可选字段时不抛出 KeyError。
- Skill/Forge 配置链路不变：config 变化 -> result.execute -> saveConfig。
- golden case 结果字段不变。

### Phase 3：装备数据 registry

新增 `EquipmentRegistry`，替换 `get_equipment()` 内部的 `eval` 与模块全局变量访问。

重点：

- `get_equipment(version)` 作为兼容门面继续存在。
- registry 内部使用 `functools.cache` 或显式 dict 缓存。
- 版本不存在时保持回退 `0` 的现有行为，但记录原因。

成功标准：

- 现有调用方无需一次性改动。
- 多版本装备数据加载路径清晰。
- 单元测试覆盖缓存、回退和不存在版本。

### Phase 4：计算核心 helper 化

抽取重复且无业务争议的 helper，降低 mixin 复杂度。

重点：

- `apply_uppercase_attrs(character, source)` 统一处理首字母大写属性应用。
- `execute_effect(effects, key, *args)` 统一处理效果函数不存在时的行为。
- 优先处理 `calc_suits/calc_equs/calc_oaths/calc_emblems` 中重复逻辑。

成功标准：

- helper 有单元测试。
- 业务公式位置不变或仅做等价搬迁。
- `calc_equip.py` 可读性提升，结果不变。

### Phase 5：性能观测与热点优化

在 service 层引入轻量计时，再针对热点做优化。

重点：

- 记录 `createCharacter`、`calc` 总耗时。
- 可选记录 `calc_*` 分段耗时，默认不影响响应结构。
- 优化重复 `获取基础属性()` 调用。
- 评估技能实例模板缓存，但必须避免可变技能状态污染请求。

成功标准：

- 能拿到典型配置的平均耗时和 p95。
- 优化前后 golden case 一致。
- 性能优化有数据支撑。

### Phase 6：规范与文档

清理运行缓存、废弃文件和文档入口。

重点：

- 确认 `.venv/.ruff_cache/__pycache__/.DS_Store` 不进入 git。
- 评估 `character_old.py` 移到归档或删除。
- 补充 backend README：运行、测试、质量检查、目录职责。
- 不在本阶段大规模格式化老文件。

成功标准：

- 新人可通过文档理解 backend 入口和测试方式。
- 废弃代码不会继续误导维护。
- 规范变更不产生大规模业务 diff。

## 风险与缓解

| 风险 | 缓解 |
| --- | --- |
| 重构导致 `/calc` 字段变化 | Phase 0 先做 contract/golden 测试 |
| 技能对象可变状态污染缓存 | 技能模板缓存必须后置，且只缓存类或不可变模板 |
| 装备版本回退行为改变 | `get_equipment()` 保留兼容门面，并测试回退 |
| config 字段默认值与前端不一致 | `CalcConfigView` 先只集中现有默认值，不新增语义 |
| 性能统计污染响应 | 默认只写日志，不改变 API data |

## 验收总标准

- `uv run pytest` 通过。
- `/api/calc` 响应契约不变。
- frontendNew 的 result.execute 与 saveConfig 链路无需调整。
- 典型职业 golden case 在重构前后字段一致，关键数值在允许误差内。
- backend 文档说明清晰，后续任务可以分阶段执行。