CNWei
1c98340fc5
- 添加导航条目和分类数据模型 - 实现导航卡片网格展示 - 支持点击卡片打开链接 - 添加主题样式（渐变色、卡片阴影） - 区分系统默认和自定义条目 - 添加分类统计信息"
72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# Navius 前端（Flutter Web）
|
||
|
||
导航站前端，使用 Flutter 构建。当前目标平台只有 Web，数据来自 Rust 后端
|
||
（`GET /api/nav`）。
|
||
|
||
界面基准是仓库根目录的 `index3.html`：可折叠的层级侧栏 + 居中的顶部控制栏
|
||
（折叠按钮 + 搜索框）+ 分组卡片网格 + 右下角圆形回到顶部。
|
||
|
||
## 和后端一起跑
|
||
|
||
前端启动时会请求后端，所以两个都要起：
|
||
|
||
```bash
|
||
cd backend && cargo run # 默认 http://127.0.0.1:8080
|
||
cd frontend && flutter run -d chrome
|
||
```
|
||
|
||
后端地址默认是 `http://127.0.0.1:8080`，打包或换环境时用编译期变量覆盖：
|
||
|
||
```bash
|
||
flutter build web --dart-define=NAVIUS_API_BASE=https://api.example.com
|
||
```
|
||
|
||
后端没起来时页面会显示「加载失败」和具体原因，并给一个「重试」按钮。
|
||
|
||
侧栏底部的「提交网站」会打开提交表单：填完直接进后端的用户分组（不需要审核），
|
||
提交成功后页面会静默重新拉一次数据，新站点立刻出现在侧栏里。
|
||
|
||
用户提交 / 接口推送进来的站点（后端返回的 `editable == true`）在卡片悬停时右上角
|
||
会露出「编辑 / 删除」：编辑复用同一个表单（预填现有内容）走 `PATCH`，
|
||
删除会先确认再走 `DELETE`，两个操作成功后都会静默刷新。系统内置的卡片没有这两个入口。
|
||
|
||
站点名和搜索框提示也来自后端（`data/site.json`），前端不再写死。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
flutter pub get # 拉取依赖
|
||
flutter run -d chrome # 本地运行
|
||
flutter analyze # 静态分析
|
||
flutter test # 单元测试与组件测试
|
||
flutter build web # 构建产物输出到 build/web
|
||
```
|
||
|
||
## 目录约定
|
||
|
||
- `lib/core/`：与业务无关的基础设施——主题、尺寸常量、断点计算、打开链接的能力。
|
||
- `lib/features/<功能>/`：按功能划分，内部再分 `data`（数据来源与仓库）、`domain`（模型与规则）、`presentation`（页面与组件）。
|
||
- `test/`：目录结构与 `lib/` 保持一致。
|
||
|
||
依赖方向固定为 `features/ → core/`：`core` 不引用任何功能代码，
|
||
功能之间也不互相引用。
|
||
|
||
## 接后端的位置
|
||
|
||
页面只依赖仓库接口，不关心数据来自后端还是本地 mock：
|
||
|
||
- 契约：`lib/features/home/data/home_repository.dart`
|
||
- 后端实现：`lib/features/home/data/http_home_repository.dart`
|
||
- mock 实现：`lib/features/home/data/mock_home_repository.dart`（测试用）
|
||
|
||
接口对应关系：读 `GET /api/nav`、提交 `POST /api/sites`、编辑 `PATCH /api/sites/{id}`、
|
||
删除 `DELETE /api/sites/{id}`。表单在 `presentation/widgets/site_form_dialog.dart`
|
||
（新增和编辑共用），设计见 [docs/submit-site-form.md](../docs/submit-site-form.md)。
|
||
|
||
接口返回的分组树在 `http_home_repository.dart` 里映射成前端模型：分组变成侧栏导航，
|
||
**只有挂着网站的分组才进内容区**（空分组留在侧栏，点了没有对应内容——和原型一致），
|
||
子分组的内容标题会带上父级（「素材资源 - UI 设计」）。
|
||
|
||
完整的目录树、设计令牌映射、响应式规则与实现取舍见
|
||
[docs/frontend-architecture.md](../docs/frontend-architecture.md)。
|