Add an HTTP-level regression path for the local ACR service

Constraint: A service intended for industrialization needs a real process-level smoke test, not only direct function imports
Rejected: Rely on unit-style handler calls alone | Misses uvicorn startup and actual HTTP surface regressions
Confidence: high
Scope-risk: narrow
Directive: Keep service_smoke.py lightweight and dependency-free so it remains the fastest operational gate before broader API expansion
Tested: /usr/local/miniconda3/bin/python -m py_compile acr-engine/scripts/service_smoke.py; /usr/local/miniconda3/bin/python acr-engine/scripts/service_smoke.py
Not-tested: /recognize and /index/build over HTTP remain pending dedicated API smoke inputs

@@ -11,10 +11,8 @@
 
 
 ```bash
 ```bash
 cd acr-engine
 cd acr-engine
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python run_demo.py full-demo
+/usr/local/miniconda3/bin/python -m pip install -r requirements.txt
+/usr/local/miniconda3/bin/python run_demo.py full-demo --device cpu
 ```
 ```
 
 
 ## 常用命令
 ## 常用命令
@@ -53,6 +51,30 @@ python run_demo.py recognize \
 python run_demo.py full-demo --device cpu
 python run_demo.py full-demo --device cpu
 ```
 ```
 
 
+
+## 服务启动与 smoke
+
+### 启动服务
+
+```bash
+cd acr-engine
+/usr/local/miniconda3/bin/python -m uvicorn src.service.app:app --host 127.0.0.1 --port 8000
+```
+
+### 运行服务 smoke
+
+```bash
+cd acr-engine
+/usr/local/miniconda3/bin/python scripts/service_smoke.py
+```
+
+### 常看接口
+
+- `GET /health`
+- `GET /ready`
+- `GET /config`
+- `GET /cache`
+
 ## 目录
 ## 目录
 
 
 - `train.py`：训练入口
 - `train.py`：训练入口

+#!/usr/bin/env python3
+"""Minimal local smoke test for the FastAPI ACR service."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from urllib.request import urlopen
+from urllib.error import URLError, HTTPError
+
+BASE = "http://127.0.0.1:8000"
+
+
+def fetch_json(path: str):
+    with urlopen(BASE + path, timeout=10) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def main():
+    cmd = [
+        "/usr/local/miniconda3/bin/python",
+        "-m",
+        "uvicorn",
+        "src.service.app:app",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        "8000",
+    ]
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    try:
+        last_error = None
+        for _ in range(20):
+            time.sleep(0.5)
+            try:
+                health = fetch_json("/health")
+                ready = fetch_json("/ready")
+                config = fetch_json("/config")
+                cache = fetch_json("/cache")
+                print(json.dumps({
+                    "status": "ok",
+                    "health": health,
+                    "ready": ready,
+                    "config": config,
+                    "cache": cache,
+                }, indent=2, ensure_ascii=False))
+                return
+            except (URLError, HTTPError, ConnectionError) as exc:
+                last_error = str(exc)
+        raise SystemExit(json.dumps({
+            "status": "failed",
+            "reason": "service_not_ready_in_time",
+            "last_error": last_error,
+        }, indent=2, ensure_ascii=False))
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+
+
+if __name__ == "__main__":
+    main()

@@ -228,6 +228,31 @@
 
 
 
 
 
 
+
+### Stage: 服务 HTTP smoke
+
+完成项：
+- 新增 [acr-engine/scripts/service_smoke.py](../acr-engine/scripts/service_smoke.py)
+- 用 `uvicorn` 真正拉起 FastAPI 服务，而不是只做函数级调用
+- 更新 [acr-engine/README.md](../acr-engine/README.md) 与 [docs/service-api.md](./service-api.md) 的服务运行说明
+
+验证结果：
+- `/usr/local/miniconda3/bin/python -m py_compile scripts/service_smoke.py` 成功
+- `/usr/local/miniconda3/bin/python scripts/service_smoke.py` 成功
+- 当前 smoke 已验证：
+  - `/health`
+  - `/ready`
+  - `/config`
+  - `/cache`
+- 当前结果：
+  - `health.ready=true`
+  - `ready.ready=true`
+  - `engine_cache_size=0`（未执行 recognize 前）
+
+结论：
+- 服务现在已经具备最小 HTTP 级 smoke 验证
+- 后续继续做鉴权、异步任务、监控时，有了更真实的回归入口
+
 ### Stage: 服务就绪探针与缓存可见性
 ### Stage: 服务就绪探针与缓存可见性
 
 
 完成项：
 完成项：

@@ -117,5 +117,27 @@ sequenceDiagram
 返回当前进程内 engine cache 统计。
 返回当前进程内 engine cache 统计。
 
 
 
 
+
+## 6. 本地运行与 smoke
+
+```bash
+cd acr-engine
+/usr/local/miniconda3/bin/python -m uvicorn src.service.app:app --host 127.0.0.1 --port 8000
+```
+
+另一个终端可直接执行：
+
+```bash
+cd acr-engine
+/usr/local/miniconda3/bin/python scripts/service_smoke.py
+```
+
+该 smoke 当前会校验：
+
+- `/health`
+- `/ready`
+- `/config`
+- `/cache`
+
 ## Sources
 ## Sources
 - See [references-and-sources.md](./references-and-sources.md) for the current source map.
 - See [references-and-sources.md](./references-and-sources.md) for the current source map.