# Semi Design React 前端看板交付记录

时间：2026-06-12
前端位置：`frontend/`
云端部署：`/srv/goods-ledger/frontend/dist`
访问路径：`http://127.0.0.1:8791/dashboard/`（云服务器本机）

## 技术栈

按要求使用字节 DouyinFE / Semi Design React：

```text
@douyinfe/semi-ui 2.100.0
@douyinfe/semi-icons 2.100.0
GitHub: https://github.com/DouyinFE/semi-design
官网: https://semi.design
```

图表按要求使用 ECharts：

```text
echarts 6.1.0
echarts-for-react 3.0.6
GitHub: https://github.com/apache/echarts
官网: https://echarts.apache.org
```

## 已完成页面

- 总览
- 库存 / 进出库
- 订单 / 合同
- 渠道分配
- 发货签收
- 对账补货
- 统一搜索

## 接入接口

前端默认同源请求以下 API：

```text
/api/dashboard/overview
/api/dashboard/inventory
/api/dashboard/orders
/api/dashboard/channels
/api/dashboard/shipments
/api/dashboard/reconciliation
/api/search
```

开发环境支持 Vite proxy：

```text
LEDGER_API_PROXY_TARGET 或 http://127.0.0.1:8791
```

生产构建使用：

```bash
VITE_BASE_PATH=/dashboard/ npm run build
```

## 构建与部署

由于 NAS 目录上安装大量 npm 依赖较慢，实际构建采用本地临时构建目录：

```text
/tmp/goods-ledger-dashboard-build
```

构建结果已复制回项目：

```text
frontend/dist/
```

并同步到云端：

```text
/srv/goods-ledger/frontend/dist
```

后端 `goods-ledger-api` 已挂载静态前端：

```text
/dashboard
```

## 验证结果

官方包核对：

```text
@douyinfe/semi-ui version=2.100.0
repository=https://github.com/DouyinFE/semi-design.git
echarts version=6.1.0
repository=https://github.com/apache/echarts.git
```

构建验证：

```text
npm run build: 通过
输出：frontend/dist/index.html + assets
```

本地开发代理验证：

```text
http://127.0.0.1:5174/ => 200
http://127.0.0.1:5174/api/dashboard/overview => open_issue_count=15
```

云端部署验证：

```text
/health => 200, ok=True, database=goods_ledger
/dashboard/ => 200, text/html, title=Goods Ledger Dashboard
/dashboard/assets/index-*.js => 200, text/javascript
/api/dashboard/overview => 200, open_issue_count=15
```

PM2：

```text
goods-ledger-api online
restart_time=3
```

## 注意

- 当前是只读看板，不包含页面写入动作；写入仍走 `goods-ledger-manager` 的受控 MCP/API。
- `/dashboard/` 目前仅在云服务器本机 `127.0.0.1:8791` 可访问；如要给运营外部访问，需要另行确认反向代理、域名、鉴权和权限边界。
- Semi Design 的完整 CSS 已复制到 `frontend/src/vendor/semi.css`，避免 Vite 8 对 package exports 的限制导致无法直接 import `dist/css/semi.css`。