store-api-py 0.1.0__tar.gz

store_api_py-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: store-api-py
+Version: 0.1.0
+Summary: FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)
+License: MIT
+Keywords: py-store,storepy,fastapi,rest,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: uvicorn>=0.29; extra == "dev"
+
+# store-api-py
+
+FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL).
+
+Full documentation: https://github.com/coenddt/store-api

store_api_py-0.1.0/README.md

@@ -0,0 +1,5 @@
+# store-api-py
+
+FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL).
+
+Full documentation: https://github.com/coenddt/store-api

store_api_py-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "store-api-py"
+version = "0.1.0"
+description = "FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["py-store", "storepy", "fastapi", "rest", "crud", "gql"]
+dependencies = ["fastapi>=0.110"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "httpx>=0.27", "uvicorn>=0.29"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

store_api_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

store_api_py-0.1.0/src/store_api_py/__init__.py

@@ -0,0 +1,10 @@
+"""store-api-py — 为 py-store schema 自动生成 RESTful API 的 FastAPI 适配器。
+
+    from store_api_py import create_app
+    app = create_app(store, prefix='/api')  # uvicorn main:app
+"""
+
+from .app import create_app, filter_archived
+from .params import ParamError, convert_value, parse_query_params
+
+__all__ = ["create_app", "filter_archived", "parse_query_params", "convert_value", "ParamError"]

store_api_py-0.1.0/src/store_api_py/app.py

@@ -0,0 +1,200 @@
+"""store-api-py — FastAPI 适配器：为已注册 schema 自动生成 RESTful 路由。
+
+路由/参数/错误/上下文语义全部以 spec/*.md 为唯一依据（双端 parity，改动先改 spec）。
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from typing import Any, Callable
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from .errors import (
+    StoreApiError,
+    context_error,
+    error_payload,
+    invalid_body,
+    map_error,
+    not_found,
+)
+from .params import parse_query_params
+
+ARCHIVE_SUFFIX = "Deleted"
+
+ContextProvider = Callable[[Request], Any]
+
+
+def filter_archived(names: list[str]) -> list[str]:
+    """归档表过滤（spec/01-routing.md）：`XxxDeleted` 且 `Xxx` 也在列表中 ⇒ 视为归档表。"""
+    s = set(names)
+    return [n for n in names if not (n.endswith(ARCHIVE_SUFFIX) and n[: -len(ARCHIVE_SUFFIX)] in s)]
+
+
+async def _resolve_ctx(provider: ContextProvider, request: Request) -> Any:
+    ctx = provider(request)
+    if inspect.isawaitable(ctx):
+        ctx = await ctx
+    return ctx
+
+
+def create_app(
+    store: Any,
+    *,
+    prefix: str = "",
+    id_field: str = "_id",
+    context_provider: ContextProvider | None = None,
+    resources: list[str] | None = None,
+    permission_error: type[BaseException] | None = None,
+) -> FastAPI:
+    """为 store（py-store 的 store 实例，需已 init + register）生成 RESTful FastAPI 应用。
+
+    - prefix: 路由前缀，如 '/api'
+    - id_field: 单条路由主键字段名（双端一致，spec/01-routing.md，默认 '_id'）
+    - context_provider: 每请求上下文钩子（spec/04-context.md）；非权限类抛错 ⇒ 401 CONTEXT_ERROR
+    - resources: 显式资源名；缺省取 store.list() 并过滤归档表
+    - permission_error: store 权限错误类；缺省取 store.PermissionError
+    """
+    app = FastAPI(title="store-api")
+    if permission_error is None:
+        permission_error = getattr(store, "PermissionError", None)
+
+    def _respond(mapped: StoreApiError) -> JSONResponse:
+        return JSONResponse(status_code=mapped.status_code, content=error_payload(mapped.code, mapped.message))
+
+    if context_provider is not None:
+
+        @app.middleware("http")
+        async def _inject_context(request: Request, call_next):
+            try:
+                ctx = await _resolve_ctx(context_provider, request)
+            except Exception as e:  # noqa: BLE001 — spec/04-context.md：PermissionError ⇒ 403（RBAC 拒绝）；其余 ⇒ 401，message 原样透传
+                if permission_error is not None and isinstance(e, permission_error):
+                    return _respond(map_error(e, permission_error))
+                return _respond(context_error(str(e) or None))
+            # spec/04：返回 None 时同样显式注入空上下文（store.set_context(None) 语义为清除，
+            # 有状态持有的运行时禁止残留上一请求上下文，防身份跨请求泄漏）
+            store.set_context(ctx)
+            return await call_next(request)
+
+    # B6：`x-cache` 响应头注记位——取值唯一来源为宿主 store.cache_status（未实现时恒 BYPASS）；
+    # 覆盖所有响应（含错误响应）。非法值回落 BYPASS（宿主侧已对非法/异常走反馈通道留痕）。
+    _CACHE_VALUES = ("HIT", "MISS", "BYPASS")
+
+    @app.middleware("http")
+    async def _annotate_cache(request: Request, call_next):
+        response = await call_next(request)
+        fn = getattr(store, "cache_status", None)
+        v = fn() if callable(fn) else "BYPASS"
+        response.headers["x-cache"] = v if v in _CACHE_VALUES else "BYPASS"
+        return response
+
+    names = resources if resources is not None else filter_archived(store.list())
+    for name in names:
+        # 显式投影（spec/01+02）：GQL 省略投影段 = 只返回 _id（三端 core 契约）。
+        # 列表路由仅在 q 缺失时用它；q 存在时投影完全由 q 决定，适配层不追加。
+        proj = _schema_projection(store, name)
+        _register_resource(app, store, name, prefix, id_field, permission_error, proj)
+
+    return app
+
+
+def _schema_projection(store: Any, name: str) -> str:
+    """从 store 元数据生成显式投影串（' { f1, f2 }'）。
+    取值顺序：store.get(name)（nodejs 形态）→ py_store.schema 模块（py-store 未在 Store 类暴露 get）。
+    两者皆不可得 / fields 为空 → 空串（无投影，data 仅 _id——上游 schema 定义不完整的显式后果）。"""
+    fields: dict | None = None
+    get = getattr(store, "get", None)
+    if callable(get):
+        try:
+            meta = get(name)
+        except KeyError:
+            meta = None
+        if isinstance(meta, dict):
+            fields = meta.get("fields")
+        else:
+            fields = getattr(meta, "fields", None)
+    if fields is None:
+        try:
+            from py_store import schema as py_schema
+
+            fields = (py_schema.get(name) or {}).get("fields")
+        except Exception:
+            fields = None
+    keys = list((fields or {}).keys())
+    return f" {{ {', '.join(keys)} }}" if keys else ""
+
+
+def _guard(permission_error: type[BaseException] | None) -> Callable:
+    """单一错误出口：handler 抛出的所有错误统一走 map_error 判定（禁 catch 后洗成成功）。"""
+
+    def deco(fn: Callable) -> Callable:
+        @functools.wraps(fn)  # 保留原签名，FastAPI 靠 inspect.signature 注入 Request/路径参数
+        async def wrapper(*args, **kwargs):
+            try:
+                return await fn(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — 错误必须映射为带语义的 HTTP 响应，禁止静默
+                mapped = map_error(e, permission_error)
+                return JSONResponse(status_code=mapped.status_code, content=error_payload(mapped.code, mapped.message))
+
+        return wrapper
+
+    return deco
+
+
+def _register_resource(
+    app: FastAPI,
+    store: Any,
+    name: str,
+    prefix: str,
+    id_field: str,
+    permission_error: type[BaseException] | None,
+    proj: str,
+) -> None:
+    # 工厂函数隔离闭包：handler 签名只含 Request 与路径参数，
+    # 否则 FastAPI 会把捕获变量解析成查询参数（缺参即 422）
+    base = f"{prefix}/{name}"
+
+    @app.get(base)
+    @_guard(permission_error)
+    async def list_resource(request: Request):
+        params = parse_query_params(request.query_params)
+        # q 缺失 → 全字段投影（spec/02）；q 存在 → 投影完全由 q 决定
+        gql = name + (request.query_params.get("q") or proj)
+        return {"data": await store.query(gql, params)}
+
+    @app.get(base + "/{rid}")
+    @_guard(permission_error)
+    async def get_one(rid: str):
+        data = await store.query_one(f"{name}($condition: @c0){proj}", {"c0": {id_field: rid}})
+        if data is None:
+            raise not_found(f"记录不存在: {id_field}={rid}")
+        return {"data": data}
+
+    @app.post(base, status_code=201)
+    @_guard(permission_error)
+    async def create_resource(request: Request):
+        return {"data": await store.insert(name, await _read_json_body(request))}
+
+    @app.patch(base + "/{rid}")
+    @_guard(permission_error)
+    async def update_one(rid: str, request: Request):
+        return {"data": await store.update(name, {id_field: rid}, await _read_json_body(request))}
+
+    @app.delete(base + "/{rid}")
+    @_guard(permission_error)
+    async def delete_one(rid: str):
+        return {"data": await store.remove(name, {id_field: rid})}
+
+
+async def _read_json_body(request: Request) -> dict:
+    try:
+        body = await request.json()
+    except json.JSONDecodeError as e:
+        raise invalid_body(f"请求体不是合法 JSON: {e}") from e
+    if not isinstance(body, dict):
+        raise invalid_body("请求体必须是 JSON 对象")
+    return body

store_api_py-0.1.0/src/store_api_py/errors.py

@@ -0,0 +1,62 @@
+"""错误 → HTTP 状态码映射。
+
+规范依据：spec/03-errors.md（判定顺序双端一致，改动必须先改 spec）。
+遵循 no-error-masking：message 原样透传、取不到置 None（禁伪造），成功响应不得带 error 字段。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .params import ParamError
+
+
+class StoreApiError(Exception):
+    """适配层自身守卫错误（400/401/404），message 为确定性描述。"""
+
+    def __init__(self, status_code: int, code: str, message: str | None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+def error_payload(code: str, message: str | None) -> dict[str, Any]:
+    return {"error": {"code": code, "message": message}}
+
+
+def store_code(err: BaseException) -> str:
+    """store 错误的分类码：优先 err.code，缺省用错误类名，再缺省用通用码。"""
+    return getattr(err, "code", None) or type(err).__name__ or "STORE_ERROR"
+
+
+def invalid_body(message: str) -> StoreApiError:
+    return StoreApiError(400, "INVALID_BODY", message)
+
+
+def not_found(message: str) -> StoreApiError:
+    return StoreApiError(404, "NOT_FOUND", message)
+
+
+def context_error(message: str | None) -> StoreApiError:
+    return StoreApiError(401, "CONTEXT_ERROR", message)
+
+
+def map_error(err: BaseException, permission_error: type[BaseException] | None) -> StoreApiError:
+    """判定顺序（spec/03-errors.md）：
+    适配层守卫(400) → PermissionError(403) → queryOne 空结果(404) → 其余 500 透传
+    """
+    if isinstance(err, StoreApiError):
+        return err
+    if isinstance(err, ParamError):
+        return StoreApiError(400, "INVALID_PARAM", str(err) or None)
+    if permission_error is not None and isinstance(err, permission_error):
+        # 按类型判定，禁按 message 匹配
+        return StoreApiError(403, store_code(err), str(err) or None)
+    # spec/03 判定顺序第 3 层：GQL 解析失败（core 稳定前缀 ERR_GQL_PARSE:，与
+    # ERR_PERM_PREFIX 同构的类型级契约——前缀判定非文案脆弱匹配）→ 400 GQL_PARSE，
+    # message 剥前缀取原文（与 go/rust/node 同语义）。
+    text = str(err)
+    if text.startswith("ERR_GQL_PARSE:"):
+        return StoreApiError(400, "GQL_PARSE", text[len("ERR_GQL_PARSE:"):])
+    return StoreApiError(500, store_code(err), text or None)

store_api_py-0.1.0/src/store_api_py/params.py

@@ -0,0 +1,50 @@
+"""查询参数 → GQL params 绑定。
+
+规范依据：spec/02-params.md（双端逐字一致，改动必须先改 spec）。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_INT_RE = re.compile(r"^-?\d+$")
+_FLOAT_RE = re.compile(r"^-?\d+\.\d+$")
+
+
+class ParamError(Exception):
+    code = "INVALID_PARAM"
+
+
+def convert_value(raw: str) -> Any:
+    """p.<name> 值的类型转换：true/false/null → 字面量；整数/浮点正则全匹配 → 数值；
+    ``{``/``[`` 开头 → JSON 解析（失败抛 ParamError，禁静默当字符串）；其余 → 字符串原样。
+    """
+    if raw == "true":
+        return True
+    if raw == "false":
+        return False
+    if raw == "null":
+        return None
+    if _INT_RE.match(raw):
+        return int(raw)
+    if _FLOAT_RE.match(raw):
+        return float(raw)
+    if raw.startswith("{") or raw.startswith("["):
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ParamError(f"参数 JSON 解析失败: {e}") from e
+    return raw
+
+
+def parse_query_params(query_params) -> dict[str, Any]:
+    """从 QueryParams 收集 p.* 参数。同名重复出现 → 列表（每元素各自转换）；单次 → 标量。"""
+    params: dict[str, Any] = {}
+    for key in query_params.keys():
+        if not key.startswith("p."):
+            continue
+        converted = [convert_value(v) for v in query_params.getlist(key)]
+        params[key[2:]] = converted if len(converted) > 1 else converted[0]
+    return params

store_api_py-0.1.0/src/store_api_py.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: store-api-py
+Version: 0.1.0
+Summary: FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)
+License: MIT
+Keywords: py-store,storepy,fastapi,rest,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: uvicorn>=0.29; extra == "dev"
+
+# store-api-py
+
+FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL).
+
+Full documentation: https://github.com/coenddt/store-api

store_api_py-0.1.0/src/store_api_py.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/store_api_py/__init__.py
+src/store_api_py/app.py
+src/store_api_py/errors.py
+src/store_api_py/params.py
+src/store_api_py.egg-info/PKG-INFO
+src/store_api_py.egg-info/SOURCES.txt
+src/store_api_py.egg-info/dependency_links.txt
+src/store_api_py.egg-info/requires.txt
+src/store_api_py.egg-info/top_level.txt
+tests/test_smoke.py

store_api_py-0.1.0/src/store_api_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

store_api_py-0.1.0/src/store_api_py.egg-info/requires.txt

@@ -0,0 +1,6 @@
+fastapi>=0.110
+
+[dev]
+pytest>=8
+httpx>=0.27
+uvicorn>=0.29

store_api_py-0.1.0/src/store_api_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+store_api_py

store_api_py-0.1.0/tests/test_smoke.py

@@ -0,0 +1,225 @@
+"""smoke 测试：mock store（不连真实库），镜像 node/test/smoke.test.js 的用例矩阵。
+
+conformance 纪律：两端断言逐项对应，任何一端改动必须同步另一端。
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from store_api_py import ParamError, create_app, filter_archived, parse_query_params  # noqa: E402
+from store_api_py.params import convert_value  # noqa: E402
+
+
+class MockPermissionError(Exception):
+    pass
+
+
+class MockStore:
+    """mock store：只实现适配器调用面（query/query_one/insert/update/remove/list/set_context）。"""
+
+    PermissionError = MockPermissionError
+
+    def __init__(self):
+        self.rows: dict[str, dict] = {}
+        self.last_query: tuple | None = None
+        self.last_context = None
+
+    def list(self):
+        return ["user", "userDeleted"]
+
+    def get(self, name):
+        if name == "user":
+            return {"name": "user", "fields": {"name": {"type": "string"}, "age": {"type": "number"}}}
+        raise KeyError(name)
+
+    def set_context(self, ctx):
+        self.last_context = ctx
+
+    async def query(self, gql, params=None):
+        self.last_query = (gql, params)
+        return list(self.rows.values())
+
+    async def query_one(self, gql, params=None):
+        self.last_query = (gql, params)
+        rid = (params or {}).get("c0", {}).get("_id")
+        return self.rows.get(rid)
+
+    async def insert(self, name, data):
+        rid = data.get("_id") or f"u{len(self.rows) + 1}"
+        row = {"_id": rid, **data}
+        self.rows[rid] = row
+        return row
+
+    async def update(self, name, cond, data):
+        row = self.rows.get(cond.get("_id"))
+        if row:
+            row.update(data)
+        return row
+
+    async def remove(self, name, cond):
+        return self.rows.pop(cond.get("_id"), None)
+
+
+def build_app(store, **extra):
+    return create_app(store, prefix="/api", **extra)
+
+
+def test_filter_archived():
+    assert filter_archived(["user", "userDeleted", "post", "logDeleted"]) == ["user", "post", "logDeleted"]
+
+
+def test_params_convert_matrix():
+    qp = parse_query_params(
+        _QP({"p.a": "true", "p.b": "false", "p.c": "null", "p.d": "42", "p.e": "-1.5", "p.f": "abc"})
+    )
+    assert qp == {"a": True, "b": False, "c": None, "d": 42, "e": -1.5, "f": "abc"}
+    assert parse_query_params(_QP({"p.o": '{"age":{"$gte":18}}'})) == {"o": {"age": {"$gte": 18}}}
+    # 同名重复出现 → 列表（每元素各自转换）
+    assert parse_query_params(_QP([("p.tag", "a"), ("p.tag", "b")])) == {"tag": ["a", "b"]}
+
+
+def test_params_convert_value_scalars():
+    assert convert_value("true") is True
+    assert convert_value("null") is None
+    assert convert_value("42") == 42
+    assert convert_value("abc") == "abc"
+
+
+def test_params_invalid_json():
+    with pytest.raises(ParamError):
+        parse_query_params(_QP({"p.o": '{"age":'}))
+
+
+class _QP:
+    """starlette QueryParams 的最小替身"""
+
+    def __init__(self, items):
+        self._items = [(k, v) for k, v in (items.items() if isinstance(items, dict) else items)]
+
+    def keys(self):
+        return list(dict.fromkeys(k for k, _ in self._items))
+
+    def getlist(self, key):
+        return [v for k, v in self._items if k == key]
+
+    def get(self, key, default=None):
+        vs = self.getlist(key)
+        return vs[0] if vs else default
+
+
+def test_crud_full_chain():
+    store = MockStore()
+    client = TestClient(build_app(store))
+
+    created = client.post("/api/user", json={"name": "a", "age": 1})
+    assert created.status_code == 201
+    assert created.json()["data"]["name"] == "a"
+    rid = created.json()["data"]["_id"]
+
+    listed = client.get("/api/user", params={"q": "($condition: @c0)", "p.c0": '{"age":{"$gte":18}}'})
+    assert listed.status_code == 200
+    assert isinstance(listed.json()["data"], list)
+    # 拼接结果 = 资源名 + q 原样（spec/02-params.md）
+    assert store.last_query == ("user($condition: @c0)", {"c0": {"age": {"$gte": 18}}})
+
+    # 无 q → 适配器生成全字段投影（spec/02）
+    listed_no_q = client.get("/api/user")
+    assert listed_no_q.status_code == 200
+    assert store.last_query == ("user { name, age }", {})
+
+    got = client.get(f"/api/user/{rid}")
+    assert got.status_code == 200
+    assert store.last_query == ("user($condition: @c0) { name, age }", {"c0": {"_id": rid}})
+
+    patched = client.patch(f"/api/user/{rid}", json={"age": 2})
+    assert patched.status_code == 200
+    assert patched.json()["data"]["age"] == 2
+
+    removed = client.delete(f"/api/user/{rid}")
+    assert removed.status_code == 200
+
+    gone = client.get(f"/api/user/{rid}")
+    assert gone.status_code == 404
+    assert gone.json()["error"]["code"] == "NOT_FOUND"
+
+
+def test_error_mapping_400_403_401():
+    store = MockStore()
+
+    def provider(request):
+        who = request.headers.get("x-user")
+        if who == "denied":
+            raise MockPermissionError("权限不足")
+        if who == "broken":
+            raise ValueError("token 解析失败")
+        return {"uid": who}
+
+    app = build_app(store, context_provider=provider)
+    client = TestClient(app)
+
+    bad_body = client.post("/api/user", json=[1, 2])
+    assert bad_body.status_code == 400
+    assert bad_body.json()["error"]["code"] == "INVALID_BODY"
+
+    bad_param = client.get("/api/user", params={"p.c0": '{"age":'})
+    assert bad_param.status_code == 400
+    assert bad_param.json()["error"]["code"] == "INVALID_PARAM"
+    assert "JSON" in bad_param.json()["error"]["message"]
+
+    denied = client.get("/api/user", headers={"x-user": "denied"})
+    assert denied.status_code == 403
+    assert denied.json()["error"]["code"] == "MockPermissionError"
+    assert denied.json()["error"]["message"] == "权限不足"
+
+    broken = client.get("/api/user", headers={"x-user": "broken"})
+    assert broken.status_code == 401
+    assert broken.json()["error"]["code"] == "CONTEXT_ERROR"
+    assert broken.json()["error"]["message"] == "token 解析失败"
+
+    ok = client.get("/api/user", headers={"x-user": "u1"})
+    assert ok.status_code == 200
+    assert "error" not in ok.json()  # 成功响应不得带 error 字段
+    assert store.last_context == {"uid": "u1"}
+
+
+def test_store_error_passthrough_500():
+    store = MockStore()
+
+    async def boom(gql, params=None):
+        e = RuntimeError("连接超时")
+        e.code = "CONN_TIMEOUT"
+        raise e
+
+    store.query = boom
+    client = TestClient(build_app(store))
+    res = client.get("/api/user")
+    assert res.status_code == 500
+    assert res.json()["error"]["code"] == "CONN_TIMEOUT"
+    assert res.json()["error"]["message"] == "连接超时"
+
+
+def test_fastapi_instance():
+    assert isinstance(build_app(MockStore()), FastAPI)
+
+
+def test_x_cache_header():
+    """x-cache 注记位（B6）：无 provider 恒 BYPASS（含错误响应）；provider=HIT 透传"""
+    store = MockStore()
+    client = TestClient(build_app(store))
+
+    ok = client.get("/api/user")
+    assert ok.headers["x-cache"] == "BYPASS"
+
+    missing = client.get("/api/user/nope")
+    assert missing.status_code == 404
+    assert missing.headers["x-cache"] == "BYPASS"  # 错误响应同样带注记
+
+    store.cache_status = lambda: "HIT"
+    hit = client.get("/api/user")
+    assert hit.headers["x-cache"] == "HIT"