feat(routes): entry-named counts in /cached-hits; deprecate the *_hits fields (#336)

[allen0099]

Fixes #336

Summary

/cached-hits reported cached_hits, total_hits, valid_hits and expired_hits. These count cache entries, not hits, so the docs had to explain the names.

As the issue proposes, this PR adds correctly named fields and keeps the old ones as deprecated aliases:

New (use these)	Deprecated alias, same value
entries	cached_hits
total_entries	total_hits
valid_entries	valid_hits
expired_entries	expired_hits

• The old fields are still filled as before, so no client breaks now. They are marked deprecated: true in the OpenAPI schema through pydantic's Field(deprecated=...), with a message naming the replacement, so generated clients and the docs UI flag them. Pydantic's floor (2.7) supports it; the lowest job checks that.
• Removal is planned for 0.6.0. The issue said "until 0.4.0", which has already passed. 0.6.0 follows the rule of deprecating in a release first and removing in the next minor.
• There is no Python runtime warning: the deprecated surface is JSON fields, and a server-side FutureWarning would reach the server's logs, not the API's consumers. The OpenAPI flag, the docs, the deprecated changelog entry and the release notes are where consumers will see it.
• The route is still /cached-hits. Renaming it, for example adding /cached-entries, would be a separate decision.
• Changelog: 336.added.md and 336.deprecated.md.
• Docs: the monitoring section of HTTP_CACHING.md, in English and zh-TW.

Follow-up for 0.6.0: remove the four fields and add a section to MIGRATING_0_6.md.

Checklist

• The issue above is assigned to me (maintainer's own issue)

• Tests under tests/ cover the change. A new TestEntryNamedFields covers:

  • the new fields listing and counting entries, with the old fields equal to them
  • an expired entry counted under expired_entries
  • OpenAPI marking only the *_hits fields deprecated

  Breaking the expired count or dropping one deprecation mark fails them. The existing tests on the old fields pass unchanged.

• Changelog fragments added

• uv run pre-commit run --all-files and uv run pytest --cov pass: 1254 passed, 192 skipped, 93.11% coverage. So do mypy strict, mypy tests, mypy scripts and both zensical build --strict runs.

---

Generated by Claude Code