# Backend 渐进式优化执行清单

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在保持 `/calc` API 契约和 frontendNew 计算链路不变的前提下，逐步提升 backend 的可维护性、扩展性、计算效率与开发规范。

**Architecture:** 先建立测试安全网，再把 HTTP route 与计算编排拆到 service 层，随后用 config view 和 equipment registry 收口隐式边界。最后基于耗时观测做性能优化，并补齐 backend 文档与规范。

**Tech Stack:** Python 3.10+、FastAPI、Pydantic、SQLAlchemy、Redis、SQLite、pytest、ruff、uv。

---

## 文件结构规划

- Create: `backend/tests/conftest.py`  
  提供测试用 FastAPI client、alter token、最小 calc config fixture。

- Create: `backend/tests/contract/test_calc_contract.py`  
  固定 `/api/calc` HTTP 响应契约。

- Create: `backend/tests/golden/test_calc_golden.py`  
  固定典型职业计算结果结构，后续可扩展数值快照。

- Create: `backend/services/__init__.py`  
  标记 service 包。

- Create: `backend/services/calc_service.py`  
  承接 `/calc` 应用服务编排。

- Create: `backend/core/basic/character/config_view.py`  
  集中处理 calc config 默认值与读取。

- Create: `backend/core/basic/equipment_registry.py`  
  装备版本 registry 与缓存。

- Modify: `backend/api/routes/calc.py`  
  改为调用 `calc_service.calculate()`，保持 route 契约不变。

- Modify: `backend/core/basic/character/calc_equip.py`  
  逐步使用 `CalcConfigView` 与 helper，不改计算语义。

- Modify: `backend/core/basic/equipment.py`  
  `get_equipment()` 委托 `EquipmentRegistry`，保留兼容函数。

- Modify: `backend/pyproject.toml`  
  增加 `pytest`、必要时增加测试配置。

- Create or Modify: `backend/README.md`  
  说明运行、测试、质量检查、目录职责。

## Task 1：建立 pytest 基础与最小 contract 测试

**Files:**

- Modify: `backend/pyproject.toml`
- Create: `backend/tests/conftest.py`
- Create: `backend/tests/contract/test_calc_contract.py`

- [ ] **Step 1: 添加 pytest 开发依赖**

在 `backend/pyproject.toml` 的 `[dependency-groups].dev` 中加入：

```toml
[dependency-groups]
dev = [
    "pytest>=8.4.0",
    "ruff>=0.15.15",
]
```

- [ ] **Step 2: 同步依赖**

Run:

```bash
cd backend && uv sync
```

Expected: `pytest` 安装完成，`uv.lock` 更新。

- [ ] **Step 3: 创建测试 fixture**

Create `backend/tests/conftest.py`:

```python
import base64
import json
import time

import pytest
from fastapi.testclient import TestClient

from main import application


@pytest.fixture
def client():
    return TestClient(application)


@pytest.fixture
def alter_token():
    payload = {
        'alter': '1.1.1',
        'equVersion': '0',
        'time': int(time.time() * 1000),
    }
    return base64.b64encode(json.dumps(payload).encode('utf-8')).decode('utf-8')


@pytest.fixture
def minimal_calc_config():
    parts = [
        '武器',
        '副武器',
        '称号',
        '上衣',
        '头肩',
        '下装',
        '腰带',
        '鞋',
        '手镯',
        '项链',
        '戒指',
        '辅助装备',
        '魔法石',
        '耳环',
    ]
    return {
        'equips': {
            part: {
                'id': '',
                'reinforce': 0,
                'reinforceType': 0,
                'enchant': '0',
                'refine': 0,
                'adaptation': 0,
            }
            for part in parts
        },
        'oaths': {},
        'emblems': {},
        'skills': {},
        'avatar': {},
        'sundry': {},
        'jades': {},
        'options': {},
        'DSB': False,
        'BUFF': False,
    }
```

- [ ] **Step 4: 创建 contract 测试**

Create `backend/tests/contract/test_calc_contract.py`:

```python
def test_calc_response_contract(client, alter_token, minimal_calc_config):
    response = client.post(
        '/api/calc',
        headers={'alter-token': alter_token},
        json=minimal_calc_config,
    )

    assert response.status_code == 200
    payload = response.json()
    assert payload['code'] == 200
    assert payload['message'] == 'Success'
    assert isinstance(payload['data'], dict)

    data = payload['data']
    assert set(['uuid', 'skills', 'info', 'suits', 'buffer']).issubset(data)
    assert isinstance(data['uuid'], str)
    assert isinstance(data['skills'], list)
    assert isinstance(data['info'], list)
    assert isinstance(data['buffer'], bool)
```

- [ ] **Step 5: 运行测试，记录真实失败**

Run:

```bash
cd backend && uv run pytest backend/tests/contract/test_calc_contract.py -v
```

Expected: 如果 Redis 依赖导致失败，记录失败原因；不要绕过 `/calc` 鉴权契约。后续可在 fixture 中 monkeypatch `api.dp.get_redis_info` 或提供本地 Redis。

- [ ] **Step 6: 提交本任务**

Run:

```bash
git add backend/pyproject.toml backend/uv.lock backend/tests/conftest.py backend/tests/contract/test_calc_contract.py
git commit -m "test: add backend calc contract coverage"
```

## Task 2：增加 core golden smoke 测试

**Files:**

- Create: `backend/tests/golden/test_calc_golden.py`

- [ ] **Step 1: 创建核心计算 smoke 测试**

Create `backend/tests/golden/test_calc_golden.py`:

```python
from core.basic.character import createCharacter


def test_character_calc_returns_result_shape(minimal_calc_config):
    character = createCharacter('1.1.1', '0')

    result = character.calc(minimal_calc_config)

    assert isinstance(result, dict)
    assert set(['uuid', 'skills', 'info', 'suits', 'buffer']).issubset(result)
    assert isinstance(result['skills'], list)
    assert isinstance(result['info'], list)
    assert result['buffer'] is False
```

- [ ] **Step 2: 运行 golden smoke**

Run:

```bash
cd backend && uv run pytest backend/tests/golden/test_calc_golden.py -v
```

Expected: PASS。若职业 `1.1.1` 不存在，改用 `core.character.adventure` 中第一个 `open=True` 的职业，并同步更新 Task 1 fixture。

- [ ] **Step 3: 运行全部测试**

Run:

```bash
cd backend && uv run pytest -v
```

Expected: PASS，或仅 contract 测试因外部 Redis 环境失败且原因明确。

- [ ] **Step 4: 提交本任务**

Run:

```bash
git add backend/tests/golden/test_calc_golden.py
git commit -m "test: add backend calc golden smoke"
```

## Task 3：引入 calc service，瘦身 API route

**Files:**

- Create: `backend/services/__init__.py`
- Create: `backend/services/calc_service.py`
- Modify: `backend/api/routes/calc.py`
- Test: `backend/tests/contract/test_calc_contract.py`
- Test: `backend/tests/golden/test_calc_golden.py`

- [ ] **Step 1: 创建 service 包**

Create `backend/services/__init__.py`:

```python
"""Application services for backend API orchestration."""
```

- [ ] **Step 2: 创建 calc service**

Create `backend/services/calc_service.py`:

```python
from typing import Any

from api.core.Auth import AlterState
from core.basic.character import createCharacter


def calculate(state: AlterState, config: dict[str, Any] | None) -> dict[str, Any]:
    safe_config = config or {}
    character = createCharacter(state.alter, state.equVersion)
    return character.calc(safe_config)
```

- [ ] **Step 3: 修改 route 调用 service**

Modify `backend/api/routes/calc.py`:

```python
from api.core.Gzip import register_gzip_request
from fastapi import APIRouter, Body
from api.core.Response import response
from api.dp import AltersDep
from services.calc_service import calculate

router = APIRouter()

register_gzip_request(router)


@router.post('/calc')
async def calc(state: AltersDep, config=Body(None)):
    return response(data=calculate(state, config))
```

- [ ] **Step 4: 运行测试**

Run:

```bash
cd backend && uv run pytest backend/tests/contract/test_calc_contract.py backend/tests/golden/test_calc_golden.py -v
```

Expected: PASS。

- [ ] **Step 5: 提交本任务**

Run:

```bash
git add backend/services/__init__.py backend/services/calc_service.py backend/api/routes/calc.py
git commit -m "refactor: route calc through service layer"
```

## Task 4：增加 CalcConfigView，集中 config 默认值

**Files:**

- Create: `backend/core/basic/character/config_view.py`
- Modify: `backend/core/basic/character/calc_equip.py`
- Test: `backend/tests/unit/test_calc_config_view.py`

- [ ] **Step 1: 创建 config view**

Create `backend/core/basic/character/config_view.py`:

```python
from collections.abc import Mapping
from typing import Any


class CalcConfigView:
    def __init__(self, raw: Mapping[str, Any] | None):
        self.raw = dict(raw or {})

    @property
    def equips(self) -> dict[str, dict[str, Any]]:
        return dict(self.raw.get('equips') or {})

    @property
    def oaths(self) -> dict[str, dict[str, Any]]:
        return dict(self.raw.get('oaths') or {})

    @property
    def emblems(self) -> dict[str, dict[str, Any]]:
        return dict(self.raw.get('emblems') or {})

    @property
    def skills(self) -> dict[str, dict[str, Any]]:
        return dict(self.raw.get('skills') or {})

    @property
    def avatar(self) -> dict[str, Any]:
        return dict(self.raw.get('avatar') or {})

    @property
    def sundry(self) -> dict[str, Any]:
        return dict(self.raw.get('sundry') or {})

    @property
    def jades(self) -> dict[str, Any]:
        return dict(self.raw.get('jades') or {})

    @property
    def options(self) -> dict[str, Any]:
        return dict(self.raw.get('options') or {})

    @property
    def dsb(self) -> bool:
        return bool(self.raw.get('DSB', False))

    @property
    def buff(self) -> bool:
        return bool(self.raw.get('BUFF', False))

    def as_legacy_dict(self) -> dict[str, Any]:
        data = dict(self.raw)
        data.setdefault('equips', {})
        data.setdefault('oaths', {})
        data.setdefault('emblems', {})
        data.setdefault('skills', {})
        data.setdefault('avatar', {})
        data.setdefault('sundry', {})
        data.setdefault('jades', {})
        data.setdefault('options', {})
        data.setdefault('DSB', False)
        data.setdefault('BUFF', False)
        return data
```

- [ ] **Step 2: 添加单元测试**

Create `backend/tests/unit/test_calc_config_view.py`:

```python
from core.basic.character.config_view import CalcConfigView


def test_config_view_provides_defaults():
    view = CalcConfigView(None)

    assert view.equips == {}
    assert view.oaths == {}
    assert view.emblems == {}
    assert view.skills == {}
    assert view.avatar == {}
    assert view.sundry == {}
    assert view.jades == {}
    assert view.options == {}
    assert view.dsb is False
    assert view.buff is False


def test_config_view_preserves_legacy_keys():
    view = CalcConfigView({'skills': {'100': {'lv': 1}}, 'BUFF': True})

    data = view.as_legacy_dict()

    assert data['skills'] == {'100': {'lv': 1}}
    assert data['BUFF'] is True
    assert data['DSB'] is False
    assert data['equips'] == {}
```

- [ ] **Step 3: 在 calc_init 入口使用兼容 dict**

Modify `backend/core/basic/character/calc_equip.py`:

```python
from .config_view import CalcConfigView
```

在 `calc()` 起始处改为：

```python
def calc(self, setInfo: dict[str, dict]):
    config = CalcConfigView(setInfo).as_legacy_dict()
    self.calc_init(config)
    self.SetBaseStatus()
    self.calc_jade(config.get('jades', []))
    self.calc_avatar(config.get('avatar', {}))
    self.calc_basic()
    self.calc_sundry(config.get('sundry', {}))
    self.calc_emblems()
    suit = self.calc_suits()
    self.calc_equs()
    self.calc_oaths()
    skillInfos = []
    if self.buffer:
        skillInfos = self.calc_buffer_skills()
        info = self.get_buffer_info()
    else:
        if len(self.输出类型选项) > 1:
            temp = self.输出类型选项[0]
            if '固伤' in temp:
                if self.INT > self.STR:
                    self.输出类型 = '魔法固伤'
                else:
                    self.输出类型 = '物理固伤'
            else:
                if self.INT > self.STR and self.AtkM > self.AtkP:
                    self.输出类型 = '魔法百分比'
                else:
                    self.输出类型 = '物理百分比'
        skillInfos = self.calc_carry_skills(config.get('DSB', False), config.get('BUFF', False))
        info = self.get_carry_info()
    return {'uuid': uuid1().hex, 'skills': skillInfos, 'info': info, 'suits': suit, 'buffer': self.buffer}
```

- [ ] **Step 4: 运行测试**

Run:

```bash
cd backend && uv run pytest backend/tests/unit/test_calc_config_view.py backend/tests/golden/test_calc_golden.py -v
```

Expected: PASS。

- [ ] **Step 5: 提交本任务**

Run:

```bash
git add backend/core/basic/character/config_view.py backend/core/basic/character/calc_equip.py backend/tests/unit/test_calc_config_view.py
git commit -m "refactor: centralize calc config defaults"
```

## Task 5：引入 EquipmentRegistry，替换 eval 获取装备数据

**Files:**

- Create: `backend/core/basic/equipment_registry.py`
- Modify: `backend/core/basic/equipment.py`
- Test: `backend/tests/unit/test_equipment_registry.py`

- [ ] **Step 1: 创建 registry**

Create `backend/core/basic/equipment_registry.py`:

```python
from functools import cache


class EquipmentRegistry:
    def __init__(self, equipment_cls):
        self.equipment_cls = equipment_cls

    @cache
    def get(self, version: str = '0'):
        normalized = version or '0'
        try:
            return self.equipment_cls(normalized)
        except Exception:
            if normalized == '0':
                raise
            return self.get('0')
```

- [ ] **Step 2: 修改 equipment.py 兼容门面**

Modify `backend/core/basic/equipment.py` 底部：

```python
from core.basic.equipment_registry import EquipmentRegistry


_equipment_registry = EquipmentRegistry(Equipments)


def get_equipment(version: str = '0') -> Equipments:
    return _equipment_registry.get(version)
```

删除或停止使用：

```python
global equ0
equ0 = Equipments('0')
```

以及 `eval(f'equ{version}'.format(version))` 相关逻辑。

- [ ] **Step 3: 添加 registry 测试**

Create `backend/tests/unit/test_equipment_registry.py`:

```python
from core.basic.equipment import get_equipment


def test_get_equipment_returns_cached_default_version():
    first = get_equipment('0')
    second = get_equipment('0')

    assert first is second
    assert first.version == '0'


def test_get_equipment_falls_back_to_default_version():
    equipment = get_equipment('missing-version')

    assert equipment.version == '0'
```

- [ ] **Step 4: 运行测试**

Run:

```bash
cd backend && uv run pytest backend/tests/unit/test_equipment_registry.py backend/tests/golden/test_calc_golden.py -v
```

Expected: PASS。

- [ ] **Step 5: 提交本任务**

Run:

```bash
git add backend/core/basic/equipment_registry.py backend/core/basic/equipment.py backend/tests/unit/test_equipment_registry.py
git commit -m "refactor: add equipment registry"
```

## Task 6：增加 calc service 耗时观测

**Files:**

- Modify: `backend/services/calc_service.py`
- Test: `backend/tests/contract/test_calc_contract.py`

- [ ] **Step 1: 添加轻量日志计时**

Modify `backend/services/calc_service.py`:

```python
import logging
import time
from typing import Any

from api.core.Auth import AlterState
from core.basic.character import createCharacter


logger = logging.getLogger('dcalc.calc')


def calculate(state: AlterState, config: dict[str, Any] | None) -> dict[str, Any]:
    started_at = time.perf_counter()
    safe_config = config or {}
    character = createCharacter(state.alter, state.equVersion)
    created_at = time.perf_counter()
    result = character.calc(safe_config)
    finished_at = time.perf_counter()
    logger.info(
        'calc completed alter=%s equVersion=%s create_ms=%.2f calc_ms=%.2f total_ms=%.2f',
        state.alter,
        state.equVersion,
        (created_at - started_at) * 1000,
        (finished_at - created_at) * 1000,
        (finished_at - started_at) * 1000,
    )
    return result
```

- [ ] **Step 2: 运行 contract 测试**

Run:

```bash
cd backend && uv run pytest backend/tests/contract/test_calc_contract.py -v
```

Expected: PASS。响应 data 不新增耗时字段。

- [ ] **Step 3: 手动观察日志**

Run:

```bash
cd backend && uv run python main.py
```

Expected: 服务正常启动。发起 `/api/calc` 后可在日志处理器中接入 `dcalc.calc` logger；本任务不要求改变线上日志格式。

- [ ] **Step 4: 提交本任务**

Run:

```bash
git add backend/services/calc_service.py
git commit -m "chore: add calc timing logs"
```

## Task 7：抽取 effect 应用 helper

**Files:**

- Create: `backend/core/basic/character/effect_apply.py`
- Modify: `backend/core/basic/character/calc_equip.py`
- Test: `backend/tests/unit/test_effect_apply.py`
- Test: `backend/tests/golden/test_calc_golden.py`

- [ ] **Step 1: 创建 helper**

Create `backend/core/basic/character/effect_apply.py`:

```python
from typing import Any


def uppercase_attrs(source: Any) -> dict[str, Any]:
    return {
        key: value
        for key, value in source.__dict__.items()
        if key and key[0].isupper()
    }


def apply_uppercase_attrs(character: Any, source: Any) -> None:
    character.SetStatus(**uppercase_attrs(source))


def execute_effect(effects: Any, key: str, *args: Any) -> bool:
    fun = effects.execture(key)
    if fun is None:
        return False
    fun(*args)
    return True
```

- [ ] **Step 2: 添加 helper 测试**

Create `backend/tests/unit/test_effect_apply.py`:

```python
from core.basic.character.effect_apply import uppercase_attrs


class Source:
    STR = 10

    def __init__(self):
        self.INT = 20
        self.name = 'ignored'


def test_uppercase_attrs_returns_only_uppercase_keys():
    assert uppercase_attrs(Source()) == {'INT': 20}
```

- [ ] **Step 3: 在 calc_equip.py 中逐步替换重复代码**

Modify selected occurrences in `backend/core/basic/character/calc_equip.py`:

```python
from .effect_apply import apply_uppercase_attrs, execute_effect, uppercase_attrs
```

将简单重复片段：

```python
filtered_dict = {k: v for k, v in suit.__dict__.items() if k[0].isupper()}
self.SetStatus(**filtered_dict)
```

替换为：

```python
apply_uppercase_attrs(self, suit)
```

将：

```python
fun = effects.execture(f'equ_{equ.id}')
if fun is None:
    continue
filtered_dict = {k: v for k, v in equ.__dict__.items() if k[0].isupper()}
self.SetStatus(**filtered_dict)
fun(self)
```

替换为：

```python
fun = effects.execture(f'equ_{equ.id}')
if fun is None:
    continue
apply_uppercase_attrs(self, equ)
fun(self)
```

- [ ] **Step 4: 运行测试**

Run:

```bash
cd backend && uv run pytest backend/tests/unit/test_effect_apply.py backend/tests/golden/test_calc_golden.py -v
```

Expected: PASS。

- [ ] **Step 5: 提交本任务**

Run:

```bash
git add backend/core/basic/character/effect_apply.py backend/core/basic/character/calc_equip.py backend/tests/unit/test_effect_apply.py
git commit -m "refactor: extract character effect helpers"
```

## Task 8：补充 backend README

**Files:**

- Create or Modify: `backend/README.md`

- [ ] **Step 1: 编写 backend README**

Create or Modify `backend/README.md`:

````markdown
# dcalc backend

## Run

```bash
uv sync
python main.py
```

## Test

```bash
uv run pytest -v
```

## Quality

```bash
uv run ruff check .
```

## Runtime Entry

- `main.py`: FastAPI application and uvicorn entry.
- `api/routes/calc.py`: `/api/calc` HTTP route.
- `services/calc_service.py`: calculation orchestration.
- `core/basic/character/`: character calculation implementation.
- `core/basic/equipment.py`: equipment data models and compatibility access.
- `core/basic/equipment_registry.py`: equipment version registry and cache.
- `database/connect.py`: SQLite and Redis connections.

## Compatibility Rules

- Do not change `/calc` request and response contract without frontend migration approval.
- Do not change frontendNew result data shape during backend refactors.
- Keep Skill and Forge business formulas behavior-compatible unless a dedicated formula task says otherwise.
````

- [ ] **Step 2: 运行文档相关检查**

Run:

```bash
cd backend && uv run ruff check .
```

Expected: PASS，或只出现既有遗留问题。若有既有问题，不在本任务做大范围修复。

- [ ] **Step 3: 提交本任务**

Run:

```bash
git add backend/README.md
git commit -m "docs: document backend runtime structure"
```

## Task 9：阶段性全量验证

**Files:**

- No source changes expected.

- [ ] **Step 1: 运行测试**

Run:

```bash
cd backend && uv run pytest -v
```

Expected: PASS。

- [ ] **Step 2: 运行 lint**

Run:

```bash
cd backend && uv run ruff check .
```

Expected: PASS，或输出仅包含已登记的遗留问题。

- [ ] **Step 3: 启动服务**

Run:

```bash
cd backend && uv run python main.py
```

Expected: 输出 `Application startup complete.`，服务监听 `config.PORT`。

- [ ] **Step 4: 手动验证 frontendNew 链路**

Run:

```bash
cd frontendNew && pnpm dev
```

Expected: 在 Character 模块修改 Skill/Forge 配置后，仍满足 `config 变化 -> result.execute -> saveConfig`。

- [ ] **Step 5: 提交验证记录**

Run:

```bash
git status --short
```

Expected: 工作区干净，所有阶段任务已独立提交。