AD dMRI 边缘端 Demo

本项目是 AD dMRI 边缘端 Demo，用于在低成本边缘设备（香橙派 AIPro 20T）或本地电脑（WSL Ubuntu）上展示从影像上传 → 3D 预览 → 皮层柱 RI 指标分析 → 评估报告的完整闭环流程。

实现以 AGENT.md + docs/REFACTOR_SPEC.md 为准。文件地图见 docs/README.md。

---

在 WSL Ubuntu 终端内直接运行（推荐）

如果你已经在 WSL 终端里、且工作目录是 /home/hp/ad-edge-demo，按下面顺序操作即可。

0. 一次性环境检查

which node npm                # 应该输出 node/npm 路径（Windows 版挂载在 /mnt/d/... 也可用）
ls .venv/bin/python           # 后端 Python 虚拟环境
ls frontend/node_modules      # 前端依赖（缺则跑 npm install）

1. 启动后端（FastAPI，端口 8000）

.venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

后端启动后，验证健康检查与配置接口：

curl -s http://127.0.0.1:8000/api/health
curl -s "http://127.0.0.1:8000/api/config?mode=pc"

2. 启动前端（Vite，端口 5173）

新开一个 WSL 终端（后端那个保持运行），然后：

cd /home/hp/ad-edge-demo/frontend

npm run dev

浏览器打开 http://127.0.0.1:5173。

3. 验证（前端构建 / 后端测试 / 文案红线）

# 前端：类型检查 + 生产构建
cd /home/hp/ad-edge-demo/frontend
npm run build

# 前端：UTF-8 与 UI 红线文案检查
npm run check:utf8

# 后端：单元测试（应 24 passed）
cd /home/hp/ad-edge-demo
.venv/bin/python -m pytest backend/tests -q

# 后端：RI 三病例真算冒烟
.venv/bin/python backend/tests/ri_smoke.py

4. 切换运行模式（电脑 / 香橙派）

• 默认 电脑(pc)，浏览根 ./data/Real_MRI，开箱即演示。
• 切到 香橙派(orangepi) 在前端右上角 ⚙ 设置面板里完成（首页不暴露设备身份）。
• 真要读物理 U 盘，编辑根目录 .env 设 BROWSE_ROOT_PC=/mnt/e（或你的挂载点），后端重启生效。

5. 常用关停 / 清理

# 端口被占
lsof -i :8000 -i :5173
kill <PID>

# 重建前端依赖
cd /home/hp/ad-edge-demo/frontend && rm -rf node_modules && npm install

---

从 Windows 侧调用 WSL（不建议常用）

如果必须从 PowerShell / Windows 终端触发，统一使用：

wsl -d Ubuntu --cd /home/hp/ad-edge-demo -- bash -lc "<command>"

不要在 Windows 终端里直接对本项目跑 npm install、pip install、uvicorn、vite——会污染 .venv/ / node_modules/，导致跨系统软链接和二进制不兼容。

---

开发环境约束

• 开发、依赖、运行、测试固定在 WSL Ubuntu 内。
• 项目路径：/home/hp/ad-edge-demo（不要放在 /mnt/c/...）。
• .venv/、node_modules/、dist/、build/ 只由 WSL 工具创建和维护。

---

当前 Demo 边界

• 板端不真跑 DisC-Diff 超分模型、FreeSurfer、全脑配准（这些属于赛前 PC/科研端准备）。
• 上传的低分辨 dMRI / T1 文件只用于：① 按文件名经映射表判定组（HC/MCI/AD）；② 在 3D 预览页被 NiiVue 渲染。
• RI 真算从 data/cases/<case_id>/ 里预算好的小数据进行，秒级完成；运行时不读 170MB 大文件。

---

🤖 AI Agent 协同操作手册 (AI Operational Manual)

如果你是正在协助开发此项目的 AI Agent，请务必阅读并遵守以下操作范式，以解决跨系统环境兼容性问题：

1. 环境铁律：严禁在 Windows 侧直接执行构建/运行

由于本项目位于 WSL 的 UNC 路径 (\\wsl.localhost\Ubuntu\...)，Windows 侧的 npm/node 无法处理此路径，会报 UNC paths are not supported。

• 错误方式：在 PowerShell 中直接运行 npm install 或 npm run build。
• 正确方式：通过 wsl 包装器，并在内部使用显式 PATH 和 node --run。

2. 核心验证指令 (针对 AI)

请直接复制以下指令进行验证，避免 Shell 语法解析错误：

# 前端构建验证 (生产环境)
wsl bash -c "cd /home/hp/ad-edge-demo/frontend && export PATH=/home/hp/.vscode-server/bin/6a44c352bd24569c417e530095901b649960f9f8:\$PATH && node --run build"

# 前端文案红线检查
wsl bash -c "cd /home/hp/ad-edge-demo/frontend && export PATH=/home/hp/.vscode-server/bin/6a44c352bd24569c417e530095901b649960f9f8:\$PATH && node --run check:utf8"

# 后端全量测试
wsl bash -c "cd /home/hp/ad-edge-demo && .venv/bin/python -m pytest backend/tests -q"

3. 常见问题排查 (Troubleshooting)

问题现象	根本原因	解决方法
UNC paths are not supported	在 Windows CMD/PS 下操作 WSL 目录	切换到 wsl bash -c 模式进入 Linux 原生环境。
node --run build 报错 env: '--run': No such file	环境变量未正确传递或路径包含特殊字符	使用 export PATH=... && node --run 的组合命令。
截图脚本无法连接 5174 端口	Vite 服务未在后台启动或端口冲突	使用 wsl bash -c "..." & 启动后，通过 wsl ss -lntp 确认端口。
中文文案变成问号	PowerShell 管道编码污染	严禁通过 PS 管道写入含中文的文件。优先使用 Node fs.writeFile 或 Python。

4. UI 自动化截图流程

若需验证视觉修改并保存截图，请按此顺序：

1. 启动服务：wsl bash -c "cd /home/hp/ad-edge-demo/frontend && export PATH=... && node --run dev -- --port 5174" &
2. 运行脚本：在 Windows 侧运行 node frontend/scripts/capture-ui.cjs（该脚本使用 CDP 连接浏览器）。
3. 清理服务：结束后务必 kill 掉 WSL 内的 node 进程。

---

基础目录

frontend/        # React + Vite + TS 七步向导
backend/         # FastAPI + RI 真算 + 文件浏览/分组匹配接口
data/cases/      # RI 真算的预算好数据（小、已就绪）
data/Real_MRI/   # 上传样例（health/MCI/AD 三组低分辨 dMRI + T1）
data/runtime/    # EDGE_DATA_HOME，运行时上传文件落地处
docs/            # 工作协议、SPEC、UI 设计参考
debug/           # 调试产物（错误记录、临时脚本、资源探针）
scripts/         # mock 数据生成与病例包校验