fix: 修复额度解析与前端产物定位两处真实缺陷

1. CodeBuddy 个人版额度解析完全错误（本地用真实凭证验证时暴露）
   真实响应是三层嵌套 data.Response.Data.Accounts，我只读了顶层
   data.Accounts —— 结果有效凭证被误判为「未探测到额度」。
   另外上游把 *Precise 字段返回成字符串（"500"），原解析只认 int/float，
   整批额度会被算成 0。
   → 按已知路径依次尝试提取；_number 接受数字字符串。
   → 用脱敏后的真实响应固化为 fixture（含字符串 Precise），契约测试锁死。

2. 前端产物路径依赖当前工作目录
   从仓库根以外的目录启动服务时找不到 web/dist，界面只给一句
   英文「frontend build not found」，用户不知道该怎么办。
   → 路径锚定项目根（源码运行）/ /app/web/dist（容器）/ cwd 兜底；
     缺失时返回中文说明页：给出可执行的构建命令，并明确 API 仍可用。

SPA 测试改为注入临时产物目录，不再在仓库里建删 web/dist。

后端 582 测试 / 覆盖 100%。真实凭证验证：额度 9071.29/9305、健康度 97%、
周期结束 2026-10-11，凭证状态恢复「可用」。

Author: RobbsLuo

src/main.py

@@ -460,19 +460,23 @@ async def authorize(request: Request):
 
     @app.get("/{path:path}", include_in_schema=False)
     async def spa(path: str):
-        """生产模式服务 web/dist；开发模式由 Vite 代理，无需此路由。"""
-        from fastapi.responses import FileResponse, PlainTextResponse
+        """生产模式服务前端产物；开发模式由 Vite 代理，不经过此路由。
 
-        dist = Path("web/dist")
-        if not dist.is_dir():
-            return PlainTextResponse("frontend build not found; run pnpm build in web/",
-                                     status_code=404)
+        路径锚定到项目根（而不是当前工作目录），否则从其他目录启动服务时
+        会找不到前端产物。找不到时给出可执行的下一步，而不是一句
+        「frontend build not found」。
+        """
+        from fastapi.responses import FileResponse, HTMLResponse
+
+        dist = _frontend_dist()
+        if dist is None:
+            return HTMLResponse(_FRONTEND_MISSING_HTML, status_code=503)
         candidate = (dist / path).resolve()
         if path and candidate.is_file() and dist.resolve() in candidate.parents:
             return FileResponse(candidate)
         index = dist / "index.html"
         if not index.is_file():
-            return PlainTextResponse("index.html missing", status_code=404)
+            return HTMLResponse(_FRONTEND_MISSING_HTML, status_code=503)
         return FileResponse(index)
 
     return app
@@ -483,6 +487,38 @@ def resolve_public_callback_url(settings: Settings) -> str:
     return settings.public_base_url.rstrip("/") + "/authorize"
 
 
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+_CONTAINER_DIST = Path("/app/web/dist")
+
+_FRONTEND_MISSING_HTML = """<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><title>coding2api</title>
+<style>body{font-family:ui-sans-serif,system-ui,sans-serif;max-width:44rem;margin:4rem auto;
+padding:0 1.5rem;line-height:1.7;color:#1f2937}
+code{background:#f3f4f6;padding:.15rem .4rem;border-radius:.25rem;font-size:.9em}
+pre{background:#f3f4f6;padding:1rem;border-radius:.5rem;overflow-x:auto}
+h1{font-size:1.25rem}</style></head>
+<body><h1>管理台前端尚未构建</h1>
+<p>后端已经在运行，但找不到前端产物，因此无法显示管理界面。</p>
+<p>在项目根目录执行：</p>
+<pre>cd web &amp;&amp; pnpm install &amp;&amp; pnpm build</pre>
+<p>构建完成后刷新本页即可。API 端点（<code>/v1/*</code>、<code>/api/*</code>）
+不受影响，现在就可以用。</p>
+</body></html>"""
+
+
+def _frontend_dist() -> Path | None:
+    """定位前端产物目录；不存在时返回 None。"""
+    candidates = (
+        _PROJECT_ROOT / "web" / "dist",       # 源码运行
+        _CONTAINER_DIST,                       # 容器内固定路径
+        Path.cwd() / "web" / "dist",           # 兜底：从仓库根启动
+    )
+    for candidate in candidates:
+        if (candidate / "index.html").is_file():
+            return candidate
+    return None
+
+
 def describe_probe_failure(error: Exception) -> str:
     """把探测异常翻译成用户能据以行动的原因。
 

src/provider/codebuddy/client.py

@@ -114,15 +114,9 @@ async def _fetch_personal_quota(self, credential: CodeBuddyCredential) -> Quota:
             "PackageEndTimeRangeBegin": time.strftime("%Y-%m-%d %H:%M:%S", now),
             "PackageEndTimeRangeEnd": QUOTA_RANGE_END,
         }
-        data = await self._post_json(f"{self.endpoint}{EP_USER_RESOURCE}", payload,
+        body = await self._post_json(f"{self.endpoint}{EP_USER_RESOURCE}", payload,
                                      credential, quota_only=True)
-        if "Accounts" not in data:
-            raise UpstreamProtocolViolation("quota response missing Accounts")
-        accounts = data.get("Accounts")
-        if accounts is None:                    # null = 探测成功但无个人版额度
-            accounts = []
-        if not isinstance(accounts, list):
-            raise UpstreamProtocolViolation("quota Accounts is not an array")
+        accounts = _extract_accounts(body)
         total = 0.0
         remaining = 0.0
         cycle_end: int | None = None
@@ -164,17 +158,63 @@ async def _post_json(self, url: str, payload: dict[str, Any],
         return data
 
 
+def _extract_accounts(body: dict[str, Any]) -> list[Any]:
+    """从上游响应里取出账户列表。
+
+    真实结构是三层嵌套：``data.Response.Data.Accounts``。
+    只读 ``data.Accounts`` 会把有效凭证误判成「未探测到额度」。
+    上游历史上出现过不同层级，因此按已知路径依次尝试，最后才失败。
+    """
+    data = body.get("data")
+    if not isinstance(data, dict):
+        raise UpstreamProtocolViolation("quota response missing data")
+    for path in (
+        ("Response", "Data", "Accounts"),   # 实测结构
+        ("Response", "Accounts"),
+        ("Data", "Accounts"),
+        ("Accounts",),                       # 兼容更早的扁平结构
+    ):
+        node: Any = data
+        for key in path:
+            node = node.get(key) if isinstance(node, dict) else None
+        if isinstance(node, list):
+            return node
+        if node is None and path == ("Response", "Data", "Accounts"):
+            # 该路径存在但值为 null → 探测成功但无个人版额度
+            holder: Any = data
+            for key in path[:-1]:
+                holder = holder.get(key) if isinstance(holder, dict) else None
+            if isinstance(holder, dict) and path[-1] in holder:
+                return []
+    raise UpstreamProtocolViolation("quota response missing Accounts")
+
+
 def _cycle_capacity(account: dict[str, Any], field: str) -> float:
-    """优先 *Precise 字段（AGENTS.md：额度以 Precise 为准）。"""
+    """优先 *Precise 字段（AGENTS.md：额度以 Precise 为准）。
+
+    上游把 Precise 值返回成**字符串**（"500"），因此必须能解析数字字符串，
+    否则整批额度都会被算成 0。
+    """
     precise = account.get(f"{field}Precise")
     value = precise if precise is not None else account.get(field)
     return _number(value) or 0.0
 
 
 def _number(value: Any) -> float | None:
-    if isinstance(value, bool) or not isinstance(value, (int, float)):
+    """接受 int/float 以及上游返回的数字字符串（Precise 字段是字符串）。"""
+    if isinstance(value, bool):
         return None
-    return float(value)
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            return float(text)
+        except ValueError:
+            return None
+    return None
 
 
 def _cycle_end_epoch(value: Any) -> int | None:

src/provider/fixtures/codebuddy/quota-personal.json

@@ -0,0 +1,121 @@
+{
+  "code": 0,
+  "msg": "OK",
+  "requestId": "<redacted>",
+  "data": {
+    "Response": {
+      "Data": {
+        "TotalCount": 36,
+        "TotalDosage": 9070,
+        "Accounts": [
+          {
+            "AccountId": 3336507,
+            "Uin": "<redacted>",
+            "AppId": "<redacted>",
+            "DealName": "<redacted>",
+            "CapacityType": 4,
+            "CapacityUnit": "credits",
+            "CreateTime": 1773153389000,
+            "CycleStartTime": "2026-09-01 00:00:00",
+            "CycleEndTime": "2026-09-30 23:59:59",
+            "DeductionStartTime": 1773153388000,
+            "DeductionEndTime": 2033562987000,
+            "FeeType": 1,
+            "Region": "ap-others",
+            "Zone": "ap-others-4",
+            "OriginUnit": "credits",
+            "PackageCode": "<redacted>",
+            "PackageName": "CodeBuddy个人体验版",
+            "PackageType": "1",
+            "PkgSourceType": 0,
+            "ProductCode": "p_tcaca",
+            "ProductName": "腾讯云代码助手",
+            "SubProductCode": "sp_tcaca_codebuddy_ide",
+            "SubProductName": "腾讯云代码助手 (IDE)",
+            "CapacityRemain": 500,
+            "CapacityUsed": 0,
+            "CapacitySize": 500,
+            "CycleCapacityRemain": 500,
+            "CycleCapacitySize": 500,
+            "RemainCycles": 0,
+            "TotalCycles": 1,
+            "ResourceCycleId": 0,
+            "ResourceId": "<redacted>",
+            "ResourceType": "2",
+            "Status": 0,
+            "Threshold": 0,
+            "SupportAutoRenew": 0,
+            "SupportManualRenew": 0,
+            "AutoRenewFlag": 0,
+            "ExpiredTime": "",
+            "DeductionProperties": [],
+            "AutoRenewTimeUnit": "",
+            "AutoRenewTimeSpan": 0,
+            "RegionId": 47,
+            "ZoneId": 470004,
+            "CapacitySizePrecise": "500",
+            "CapacityRemainPrecise": "500",
+            "CapacityUsedPrecise": "0",
+            "CycleCapacitySizePrecise": "500",
+            "CycleCapacityRemainPrecise": "500",
+            "CycleCapacityUsedPrecise": "0"
+          },
+          {
+            "AccountId": 6890091,
+            "Uin": "<redacted>",
+            "AppId": "<redacted>",
+            "DealName": "<redacted>",
+            "CapacityType": 1,
+            "CapacityUnit": "credits",
+            "CreateTime": 1774883836000,
+            "CycleStartTime": "2026-03-30 23:17:16",
+            "CycleEndTime": "2027-03-30 23:17:15",
+            "DeductionStartTime": 1774883836000,
+            "DeductionEndTime": 1806419835000,
+            "FeeType": 1,
+            "Region": "ap-others",
+            "Zone": "ap-others-4",
+            "OriginUnit": "credits",
+            "PackageCode": "<redacted>",
+            "PackageName": "CodeBuddy个人版国内运营裂变包",
+            "PackageType": "1",
+            "PkgSourceType": 0,
+            "ProductCode": "p_tcaca",
+            "ProductName": "腾讯云代码助手",
+            "SubProductCode": "sp_tcaca_codebuddyide_bonus_pack",
+            "SubProductName": "腾讯云代码助手 (IDE) - 赠送包",
+            "CapacityRemain": 4767,
+            "CapacityUsed": 232,
+            "CapacitySize": 5000,
+            "CycleCapacityRemain": 4767,
+            "CycleCapacitySize": 5000,
+            "CycleCapacityUsed": 232,
+            "RemainCycles": 0,
+            "TotalCycles": 1,
+            "ResourceCycleId": 0,
+            "ResourceId": "<redacted>",
+            "ResourceType": "2",
+            "Status": 0,
+            "Threshold": 0,
+            "SupportAutoRenew": 0,
+            "SupportManualRenew": 0,
+            "AutoRenewFlag": 0,
+            "ExpiredTime": "",
+            "DeductionProperties": [],
+            "AutoRenewTimeUnit": "",
+            "AutoRenewTimeSpan": 0,
+            "RegionId": 47,
+            "ZoneId": 470004,
+            "CapacitySizePrecise": "5000",
+            "CapacityRemainPrecise": "4767.50000158",
+            "CapacityUsedPrecise": "232.49999842",
+            "CycleCapacitySizePrecise": "5000",
+            "CycleCapacityRemainPrecise": "4767.50000158",
+            "CycleCapacityUsedPrecise": "232.49999842"
+          }
+        ]
+      },
+      "RequestId": "<redacted>"
+    }
+  }
+}