CNWei/Navius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现导航页基础功能

Browse Source 
- 添加导航条目和分类数据模型
- 实现导航卡片网格展示
- 支持点击卡片打开链接
- 添加主题样式（渐变色、卡片阴影）
- 区分系统默认和自定义条目
- 添加分类统计信息"
This commit is contained in:
CNWei
2026-09-19 21:53:15 +08:00
parent e2cc3ac30f
commit 1c98340fc5
42 changed files with 6054 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/Cargo.toml
+11
View File
@@ -4,3 +4,14 @@ version = "0.1.0"
edition = "2024" edition = "2024"
[dependencies] [dependencies]
axum = "0.8"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
time = { version = "0.3", features = ["formatting"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net"] }
tower-http = { version = "0.6", features = ["cors"] }
url = "2"
[dev-dependencies]
tempfile = "3"
tower = { version = "0.5", features = ["util"] }
backend/README.md
+151
View File
@@ -0,0 +1,151 @@
# Navius 后端
Rust + axum，数据用 JSON 文件存储，不依赖数据库。
网站分两种：**系统内置**（只读，随项目发布）和**提交/推送**（可改可删）。
「不可修改」不是靠每处判断，而是靠**结构**保证：`system-*.json` 只在启动时读，
代码里没有任何写这两个文件的路径。
## 运行
```bash
cd backend
cargo run # 默认监听 127.0.0.1:8080，数据目录 ./data
cargo test # 34 个单元测试 + 接口测试
cargo clippy --all-targets
```
### 环境变量
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `NAVIUS_ADDR` | `127.0.0.1:8080` | 监听地址 |
| `NAVIUS_DATA_DIR` | `data` | 数据目录 |
| `NAVIUS_API_TOKEN` | 未设置 | 推送接口的令牌；不设置时 `/api/sites/push` 不可用（提交接口不受影响） |
## 数据文件
```
data/
├── site.json # 站点名与搜索框提示，只读
├── system-categories.json # 内置分组，只读，自己手写维护
├── system-sites.json # 内置网站，只读
├── user-categories.json # 提交时创建的分组，自动写
└── user-sites.json # 提交 / 推送的网站，自动写
```
启动时会自检，任何一条不通过就直接退出（避免带着坏数据继续跑）：
- `system-*.json` 里的 `source` 必须全是 `system`，`user-*.json` 里必须全不是；
- 网站 id、分组 id 不能重复；
- 每个网站的 `categoryId` 必须存在，且**内置网站只能挂在内置分组下、
提交的网站只能挂在用户分组下**；
- 分组的 `parentId` 必须存在、必须是一级分组（最多两级），也不能指向自己。
写盘用「先写临时文件再改名」，不会因为写到一半断电把文件写坏。
## 接口
### `GET /api/health`
```json
{ "sites": 5, "systemSites": 5, "userSites": 0, "categories": 8 }
```
### `GET /api/nav`
侧栏 + 内容区需要的那棵树。每个网站上都带一个推导出来的 `editable`
（`source != "system"`），前端据此决定要不要显示编辑/删除入口。
```json
{
"site": { "name": "Suxing Nav", "searchHint": "输入关键字搜索全网资源..." },
"groups": [
{
"id": "common", "title": "常用推荐", "source": "system", "editable": false,
"sites": [
{ "id": "github", "title": "GitHub", "url": "https://github.com",
"description": "代码托管与开源社区", "categoryId": "common",
"source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": "", "editable": false }
],
"children": []
}
]
}
```
`site` 来自 `data/site.json`：站点名和搜索框提示都由后端提供，前端不再写死。
### `POST /api/sites` — 用户提交
**不接受 `categoryId`**，只接受分组名；后端只在「用户创建的分组」里查找或新建，
所以提交的内容不可能落进内置分组。
```json
{
"title": "Hugging Face",
"url": "https://huggingface.co",
"description": "开源模型与数据集社区",
"group": "AI 工具",
"subGroup": "模型社区",
"submittedBy": "[email protected]"
}
```
成功返回 201 和创建出来的条目。同一父级下同名的用户分组会**复用**，
不会每提交一次就多一个同名分组。
### `POST /api/sites/push` — 接口推送
入参同上，但需要请求头 `X-Api-Token: <NAVIUS_API_TOKEN>`，
创建出来的条目 `source` 记为 `api`（id 用 `a-` 前缀）。
### `PATCH /api/sites/{id}` — 修改
只改传进来的字段，可传 `title` / `url` / `description` / `group` / `subGroup`。
系统内置的条目返回 403；传 `group` 时同样只能在用户分组里找或建。
### `DELETE /api/sites/{id}` — 删除
系统内置的条目返回 403，删掉了返回 204。
### 错误响应
统一是 `{"error": "中文说明"}`：
| 状态码 | 场景 |
| --- | --- |
| 400 | 入参不合法（标题为空/超长、url 非法或指向内网、缺 group 等） |
| 403 | 改删系统内置条目、推送令牌不对 |
| 404 | 找不到条目 |
| 500 | 写盘失败、推送接口未配置令牌 |
## 字段长度限制
标题 60 字、描述 120 字、分组名 30 字、`submittedBy` 120 字，都按**字符**算
（中文一个字算一个）。集中在 `src/validate.rs` 顶部，改规则只改那一处。
## 模块
```
src/
├── main.rs # 启动：读数据 → 自检 → 起 HTTP
├── api.rs # 路由、令牌校验、把仓库错误翻译成状态码
├── store.rs # 内存态仓库：增删改、构建导航树、原子写盘
├── model.rs # 落盘结构、请求入参、对外返回结构
├── validate.rs # 校验与归一化
├── error.rs # ApiError（→ HTTP）与 StoreError（→ 启动失败）
└── util.rs # 时间格式化与 id 生成
```
## 已知取舍
- **跨域是全开的**（`CorsLayer::permissive`）。前端是 Flutter Web，开发时不同源；
上线后如果只从自己的域名访问，应改成只允许那个来源。
- **提交接口没有限流**。按需求「不需要审核、提交即上线」，公开写接口建议后面补
一层限流或简单的验证码。
- **`Cargo.lock` 目前在 `.gitignore` 里**。这是可执行程序，建议把它纳入版本管理，
保证每台机器装到的依赖版本一致。
- 前端目前还在用本地 mock 数据，接这个接口是下一步。
backend/data/site.json
+4
View File
@@ -0,0 +1,4 @@
{
"name": "Suxing Nav",
"searchHint": "输入关键字搜索全网资源..."
}
backend/data/system-categories.json
+74
View File
@@ -0,0 +1,74 @@
[
{
"id": "common",
"title": "常用推荐",
"parentId": "",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "materials",
"title": "素材资源",
"parentId": "",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "design",
"title": "UI 设计",
"parentId": "materials",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "icon",
"title": "图标库",
"parentId": "materials",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "stock",
"title": "高清壁纸",
"parentId": "materials",
"source": "system",
"order": 30,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "dev-tools",
"title": "开发工具",
"parentId": "",
"source": "system",
"order": 30,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "dev",
"title": "前端框架",
"parentId": "dev-tools",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
},
{
"id": "api",
"title": "在线 API",
"parentId": "dev-tools",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z"
}
]
backend/data/system-sites.json
+62
View File
@@ -0,0 +1,62 @@
[
{
"id": "github",
"title": "GitHub",
"url": "https://github.com",
"description": "代码托管与开源社区",
"categoryId": "common",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": ""
},
{
"id": "zhihu",
"title": "知乎",
"url": "https://www.zhihu.com",
"description": "深度内容问答社区",
"categoryId": "common",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": ""
},
{
"id": "bilibili",
"title": "哔哩哔哩",
"url": "https://www.bilibili.com",
"description": "弹幕视频分享网站",
"categoryId": "common",
"source": "system",
"order": 30,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": ""
},
{
"id": "figma",
"title": "Figma",
"url": "https://www.figma.com",
"description": "协同界面设计工具",
"categoryId": "design",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": ""
},
{
"id": "dribbble",
"title": "Dribbble",
"url": "https://dribbble.com",
"description": "全球设计作品分享社区",
"categoryId": "design",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48Z",
"updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": ""
}
]
backend/data/user-categories.json
+47
View File
@@ -0,0 +1,47 @@
[
{
"id": "g-20260919-c8460f",
"title": "嗯嗯",
"parentId": "",
"source": "submission",
"order": 10,
"createdAt": "2026-09-19T13:30:25Z",
"updatedAt": "2026-09-19T13:30:25Z"
},
{
"id": "g-20260919-e78b21",
"title": "收拾收拾",
"parentId": "g-20260919-c8460f",
"source": "submission",
"order": 10,
"createdAt": "2026-09-19T13:32:03Z",
"updatedAt": "2026-09-19T13:32:03Z"
},
{
"id": "g-20260919-460478",
"title": "AI 工具",
"parentId": "",
"source": "submission",
"order": 20,
"createdAt": "2026-09-19T13:38:10Z",
"updatedAt": "2026-09-19T13:38:10Z"
},
{
"id": "g-20260919-6b3fa7",
"title": "模型社区",
"parentId": "g-20260919-460478",
"source": "submission",
"order": 10,
"createdAt": "2026-09-19T13:38:10Z",
"updatedAt": "2026-09-19T13:38:10Z"
},
{
"id": "g-20260919-91da17",
"title": "反反复复",
"parentId": "g-20260919-c8460f",
"source": "submission",
"order": 20,
"createdAt": "2026-09-19T13:39:53Z",
"updatedAt": "2026-09-19T13:39:53Z"
}
]
backend/data/user-sites.json
+14
View File
@@ -0,0 +1,14 @@
[
{
"id": "s-20260919-f103b8",
"title": "Hugging Face",
"url": "https://huggingface.co",
"description": "开源模型与数据集社区",
"categoryId": "g-20260919-6b3fa7",
"source": "submission",
"order": 10,
"createdAt": "2026-09-19T13:38:10Z",
"updatedAt": "2026-09-19T13:38:10Z",
"submittedBy": "[email protected]"
}
]
backend/src/api.rs
+411
View File
@@ -0,0 +1,411 @@
//! HTTP 接口层：路由、鉴权、把仓库错误翻译成状态码。
use std::sync::{Arc, Mutex};
use axum::extract::{Path, State};
use axum::http::{HeaderMap, StatusCode};
use axum::routing::{get, patch};
use axum::{Json, Router};
use tower_http::cors::CorsLayer;
use crate::error::ApiError;
use crate::model::{
CreateSiteRequest, NavResponse, Site, SiteView, Source, UpdateSiteRequest,
};
use crate::store::{Store, Summary};
/// 全局状态。仓库放在互斥锁里：接口可能并发到达，而写文件必须串行。
pub struct AppState {
pub store: Mutex<Store>,
/// 推送接口的令牌。没配置时推送接口不可用（返回 500 并说明原因）。
pub api_token: Option<String>,
}
/// 组装路由。
pub fn router(state: Arc<AppState>) -> Router {
Router::new()
.route("/api/health", get(health))
.route("/api/nav", get(nav))
// 用户提交：公开。
.route("/api/sites", axum::routing::post(create_submission))
// 接口推送：需要令牌，记成 api 来源。
.route("/api/sites/push", axum::routing::post(create_push))
.route("/api/sites/{id}", patch(update_site).delete(delete_site))
// 前端是 Flutter Web，开发时和后端不同源，这里放开跨域。
// 生产环境如果只从自己的域名访问，应改成只允许那个来源。
.layer(CorsLayer::permissive())
.with_state(state)
}
async fn health(State(state): State<Arc<AppState>>) -> Result<Json<Summary>, ApiError> {
let store = lock(&state)?;
Ok(Json(store.summary()))
}
async fn nav(State(state): State<Arc<AppState>>) -> Result<Json<NavResponse>, ApiError> {
let store = lock(&state)?;
Ok(Json(store.nav()))
}
async fn create_submission(
State(state): State<Arc<AppState>>,
Json(request): Json<CreateSiteRequest>,
) -> Result<(StatusCode, Json<SiteView>), ApiError> {
create(&state, request, Source::Submission)
}
async fn create_push(
State(state): State<Arc<AppState>>,
headers: HeaderMap,
Json(request): Json<CreateSiteRequest>,
) -> Result<(StatusCode, Json<SiteView>), ApiError> {
let Some(expected) = state.api_token.as_deref() else {
return Err(ApiError::internal(
"服务端没有配置 NAVIUS_API_TOKEN，推送接口未启用",
));
};
let provided = headers
.get("x-api-token")
.and_then(|value| value.to_str().ok())
.unwrap_or("");
if !constant_time_eq(provided, expected) {
return Err(ApiError::forbidden("接口令牌不正确"));
}
create(&state, request, Source::Api)
}
async fn update_site(
State(state): State<Arc<AppState>>,
Path(id): Path<String>,
Json(request): Json<UpdateSiteRequest>,
) -> Result<Json<SiteView>, ApiError> {
let mut store = lock(&state)?;
let site = store.update(&id, &request)?;
Ok(Json(SiteView::from(site)))
}
async fn delete_site(
State(state): State<Arc<AppState>>,
Path(id): Path<String>,
) -> Result<StatusCode, ApiError> {
let mut store = lock(&state)?;
store.delete(&id)?;
Ok(StatusCode::NO_CONTENT)
}
fn create(
state: &AppState,
request: CreateSiteRequest,
source: Source,
) -> Result<(StatusCode, Json<SiteView>), ApiError> {
let mut store = lock(state)?;
let site: Site = store.create(&request, source)?;
Ok((StatusCode::CREATED, Json(SiteView::from(site))))
}
/// 取锁并把「锁被毒化」翻译成 500。
///
/// 所有仓库操作都是同步的，锁不会跨 `await`，所以这里是普通的 `std::sync::Mutex`。
fn lock(state: &AppState) -> Result<std::sync::MutexGuard<'_, Store>, ApiError> {
state
.store
.lock()
.map_err(|_| ApiError::internal("内部状态锁已失效，请重启服务"))
}
/// 定长时间比较，避免用令牌的响应时间反推正确值。
fn constant_time_eq(a: &str, b: &str) -> bool {
let (a, b) = (a.as_bytes(), b.as_bytes());
if a.len() != b.len() {
return false;
}
let mut diff = 0u8;
for (x, y) in a.iter().zip(b.iter()) {
diff |= x ^ y;
}
diff == 0
}
#[cfg(test)]
mod tests {
use super::*;
use axum::body::Body;
use axum::http::{Method, Request};
use tempfile::TempDir;
use tower::ServiceExt;
use crate::store::seed_for_test;
#[test]
fn compares_tokens_exactly() {
assert!(constant_time_eq("secret", "secret"));
assert!(!constant_time_eq("secret", "secreu"));
assert!(!constant_time_eq("secret", "secret-longer"));
assert!(!constant_time_eq("", "secret"));
assert!(constant_time_eq("", ""));
}
/// 起一个带种子数据的路由，直接打请求，不用真的监听端口。
fn app(temp: &TempDir, token: Option<&str>) -> Router {
seed_for_test(temp.path());
let store = Store::load(temp.path()).expect("加载失败");
store.verify().expect("自检失败");
let state = Arc::new(AppState {
store: Mutex::new(store),
api_token: token.map(|value| value.to_string()),
});
router(state)
}
async fn call(
app: &Router,
method: Method,
uri: &str,
body: Option<&str>,
token: Option<&str>,
) -> (StatusCode, String) {
let mut builder = Request::builder().method(method).uri(uri);
if let Some(token) = token {
builder = builder.header("x-api-token", token);
}
let request = match body {
Some(json) => builder
.header("content-type", "application/json")
.body(Body::from(json.to_string()))
.expect("构造请求失败"),
None => builder.body(Body::empty()).expect("构造请求失败"),
};
let response = app.clone().oneshot(request).await.expect("请求失败");
let status = response.status();
let bytes = axum::body::to_bytes(response.into_body(), 64 * 1024)
.await
.expect("读响应失败");
(status, String::from_utf8_lossy(&bytes).to_string())
}
fn json(text: &str) -> serde_json::Value {
serde_json::from_str(text).expect("响应不是合法 JSON")
}
const SUBMISSION: &str = r#"{
"title": "Hugging Face",
"url": "https://huggingface.co",
"description": "开源模型与数据集社区",
"group": "AI 工具",
"subGroup": "模型社区",
"submittedBy": "[email protected]"
}"#;
#[tokio::test]
async fn health_and_nav_expose_seed_data() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let (status, body) = call(&app, Method::GET, "/api/health", None, None).await;
assert_eq!(status, StatusCode::OK);
let health = json(&body);
assert_eq!(health["sites"], 3);
assert_eq!(health["systemSites"], 3);
assert_eq!(health["userSites"], 0);
assert_eq!(health["categories"], 3);
let (status, body) = call(&app, Method::GET, "/api/nav", None, None).await;
assert_eq!(status, StatusCode::OK);
let nav = json(&body);
assert_eq!(nav["site"]["name"], "Suxing Nav");
assert_eq!(nav["site"]["searchHint"], "输入关键字搜索全网资源...");
let groups = nav["groups"].as_array().expect("groups 应当是数组");
assert_eq!(groups.len(), 2, "两个一级分组：{body}");
assert_eq!(groups[0]["id"], "common");
assert_eq!(groups[0]["sites"][0]["id"], "github");
assert_eq!(groups[0]["sites"][0]["editable"], false, "内置条目不可编辑");
assert_eq!(groups[1]["id"], "materials");
assert_eq!(groups[1]["children"][0]["id"], "design");
assert_eq!(groups[1]["children"][0]["sites"][0]["id"], "figma");
}
#[tokio::test]
async fn submission_creates_group_and_persists_to_disk() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let (status, body) = call(&app, Method::POST, "/api/sites", Some(SUBMISSION), None).await;
assert_eq!(status, StatusCode::CREATED, "{body}");
let created = json(&body);
assert!(created["id"].as_str().unwrap().starts_with("s-"), "{body}");
assert!(
created["categoryId"].as_str().unwrap().starts_with("g-"),
"{body}"
);
assert_eq!(created["source"], "submission");
assert_eq!(created["editable"], true);
// 换一个实例重新加载，数据应当还在磁盘上。
let reloaded = Store::load(temp.path()).expect("重新加载失败");
reloaded.verify().expect("重新加载后自检失败");
assert_eq!(reloaded.summary().user_sites, 1);
assert_eq!(reloaded.summary().categories, 5, "多了一级 + 子分组");
}
#[tokio::test]
async fn same_group_name_is_reused_instead_of_duplicated() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let (_, first) = call(&app, Method::POST, "/api/sites", Some(SUBMISSION), None).await;
let (_, second) = call(
&app,
Method::POST,
"/api/sites",
Some(r#"{"title":"Ollama","url":"https://ollama.com","group":"AI 工具","subGroup":"模型社区"}"#),
None,
)
.await;
assert_eq!(
json(&first)["categoryId"],
json(&second)["categoryId"],
"同名分组应当复用"
);
}
#[tokio::test]
async fn submission_never_lands_in_a_system_group() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
// 故意用内置分组的名字提交。
let (status, body) = call(
&app,
Method::POST,
"/api/sites",
Some(r#"{"title":"Fake","url":"https://fake.com","group":"素材资源","subGroup":"UI 设计"}"#),
None,
)
.await;
assert_eq!(status, StatusCode::CREATED, "{body}");
assert_ne!(json(&body)["categoryId"], "design", "不能落进内置子分组");
// 内置分组的内容没被动过。
let (_, nav) = call(&app, Method::GET, "/api/nav", None, None).await;
let nav = json(&nav);
let materials = nav["groups"]
.as_array()
.unwrap()
.iter()
.find(|group| group["id"] == "materials")
.expect("materials 分组应当存在");
assert_eq!(materials["children"][0]["sites"].as_array().unwrap().len(), 1);
assert_eq!(materials["children"][0]["sites"][0]["id"], "figma");
}
#[tokio::test]
async fn system_entries_are_read_only_over_http() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let (status, body) = call(
&app,
Method::PATCH,
"/api/sites/github",
Some(r#"{"title":"hacked"}"#),
None,
)
.await;
assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
let (status, body) = call(&app, Method::DELETE, "/api/sites/github", None, None).await;
assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
}
#[tokio::test]
async fn user_sites_can_be_updated_and_deleted() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let (_, created) = call(&app, Method::POST, "/api/sites", Some(SUBMISSION), None).await;
let id = json(&created)["id"].as_str().unwrap().to_string();
let (status, body) = call(
&app,
Method::PATCH,
&format!("/api/sites/{id}"),
Some(r#"{"title":"新名字","url":"https://huggingface.co/models"}"#),
None,
)
.await;
assert_eq!(status, StatusCode::OK, "{body}");
assert_eq!(json(&body)["title"], "新名字");
assert_eq!(json(&body)["url"], "https://huggingface.co/models");
let (status, _) = call(&app, Method::DELETE, &format!("/api/sites/{id}"), None, None).await;
assert_eq!(status, StatusCode::NO_CONTENT);
let (status, body) = call(&app, Method::DELETE, &format!("/api/sites/{id}"), None, None).await;
assert_eq!(status, StatusCode::NOT_FOUND, "{body}");
}
#[tokio::test]
async fn bad_input_is_rejected_with_400() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
for body in [
// 标题为空
r#"{"title":" ","url":"https://a.com","group":"G"}"#,
// 没有分组
r#"{"title":"A","url":"https://a.com"}"#,
// 内网地址
r#"{"title":"A","url":"http://192.168.1.1","group":"G"}"#,
// 协议不对
r#"{"title":"A","url":"ftp://a.com","group":"G"}"#,
] {
let (status, response) = call(&app, Method::POST, "/api/sites", Some(body), None).await;
assert_eq!(status, StatusCode::BAD_REQUEST, "{body} -> {response}");
}
}
#[tokio::test]
async fn push_requires_the_configured_token() {
let temp = TempDir::new().unwrap();
let app = app(&temp, Some("secret"));
let payload = r#"{"title":"Pushed","url":"https://pushed.example.com","group":"API 推送"}"#;
let (status, body) = call(&app, Method::POST, "/api/sites/push", Some(payload), None).await;
assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
let (status, body) = call(
&app,
Method::POST,
"/api/sites/push",
Some(payload),
Some("wrong"),
)
.await;
assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
let (status, body) = call(
&app,
Method::POST,
"/api/sites/push",
Some(payload),
Some("secret"),
)
.await;
assert_eq!(status, StatusCode::CREATED, "{body}");
let pushed = json(&body);
assert_eq!(pushed["source"], "api");
assert!(pushed["id"].as_str().unwrap().starts_with("a-"), "{body}");
}
#[tokio::test]
async fn push_is_unavailable_without_a_token_configured() {
let temp = TempDir::new().unwrap();
let app = app(&temp, None);
let payload = r#"{"title":"Pushed","url":"https://pushed.example.com","group":"API 推送"}"#;
let (status, body) =
call(&app, Method::POST, "/api/sites/push", Some(payload), Some("any")).await;
assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR, "{body}");
assert!(body.contains("NAVIUS_API_TOKEN"), "{body}");
}
}
backend/src/error.rs
+97
View File
@@ -0,0 +1,97 @@
//! 两类错误：接口错误（直接映射成 HTTP 状态码）与存储错误（启动阶段直接退出）。
use axum::Json;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use serde_json::json;
/// 接口层错误。`message` 是直接返回给调用方的中文说明。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApiError {
/// 入参不合法，400。
BadRequest(String),
/// 想改系统内置的内容，403。
Forbidden(String),
/// 找不到条目，404。
NotFound(String),
/// 服务端自己的问题（写盘失败等），500。
Internal(String),
}
impl ApiError {
pub fn bad_request(message: impl Into<String>) -> Self {
Self::BadRequest(message.into())
}
pub fn forbidden(message: impl Into<String>) -> Self {
Self::Forbidden(message.into())
}
pub fn not_found(message: impl Into<String>) -> Self {
Self::NotFound(message.into())
}
pub fn internal(message: impl Into<String>) -> Self {
Self::Internal(message.into())
}
pub fn message(&self) -> &str {
match self {
Self::BadRequest(m)
| Self::Forbidden(m)
| Self::NotFound(m)
| Self::Internal(m) => m,
}
}
pub fn status(&self) -> StatusCode {
match self {
Self::BadRequest(_) => StatusCode::BAD_REQUEST,
Self::Forbidden(_) => StatusCode::FORBIDDEN,
Self::NotFound(_) => StatusCode::NOT_FOUND,
Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
}
}
}
impl std::fmt::Display for ApiError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.message())
}
}
impl std::error::Error for ApiError {}
impl IntoResponse for ApiError {
fn into_response(self) -> Response {
let status = self.status();
(status, Json(json!({ "error": self.message() }))).into_response()
}
}
/// 加载与写盘阶段的错误。这些错误不会变成 HTTP 响应，而是让进程直接退出：
/// 数据文件读不出来或者自检不通过，服务继续跑只会写出更乱的数据。
#[derive(Debug)]
pub enum StoreError {
Io(String),
Json(String),
Integrity(String),
}
impl std::fmt::Display for StoreError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Io(m) => write!(f, "读取/写入失败：{m}"),
Self::Json(m) => write!(f, "JSON 解析失败：{m}"),
Self::Integrity(m) => write!(f, "数据自检不通过：{m}"),
}
}
}
impl std::error::Error for StoreError {}
impl From<StoreError> for ApiError {
fn from(value: StoreError) -> Self {
ApiError::Internal(value.to_string())
}
}
backend/src/main.rs
+57 -2
View File
@@ -1,3 +1,58 @@
fn main() { //! Navius 后端：JSON 文件存储的导航站服务。
println!("Hello, world!"); //!
//! 启动流程：读数据目录 → 自检 → 起 HTTP。
//! 自检不过直接退出：数据文件坏了还继续跑，只会把更乱的数据写回去。
mod api;
mod error;
mod model;
mod store;
mod util;
mod validate;
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use store::Store;
#[tokio::main]
async fn main() {
let data_dir = std::env::var("NAVIUS_DATA_DIR").unwrap_or_else(|_| "data".to_string());
let addr = std::env::var("NAVIUS_ADDR").unwrap_or_else(|_| "127.0.0.1:8080".to_string());
let api_token = std::env::var("NAVIUS_API_TOKEN")
.ok()
.filter(|token| !token.is_empty());
if let Err(error) = run(PathBuf::from(data_dir), addr, api_token).await {
eprintln!("启动失败：{error}");
std::process::exit(1);
}
}
async fn run(
data_dir: PathBuf,
addr: String,
api_token: Option<String>,
) -> Result<(), Box<dyn std::error::Error>> {
let store = Store::load(&data_dir)?;
store.verify()?;
let summary = store.summary();
println!("数据目录：{}", data_dir.display());
println!(
"网站 {} 条（内置 {} / 提交 {}），分组 {} 个",
summary.sites, summary.system_sites, summary.user_sites, summary.categories
);
if api_token.is_none() {
println!("未设置 NAVIUS_API_TOKEN，/api/sites/push 不可用（提交接口不受影响）");
}
let state = Arc::new(api::AppState {
store: Mutex::new(store),
api_token,
});
let listener = tokio::net::TcpListener::bind(&addr).await?;
println!("监听 http://{addr}");
axum::serve(listener, api::router(state)).await?;
Ok(())
} }
backend/src/model.rs
+192
View File
@@ -0,0 +1,192 @@
//! 落盘数据结构与对外返回结构。
use serde::{Deserialize, Serialize};
/// 数据来源。**唯一决定条目能不能被修改的字段。**
///
/// 不额外存 `editable`：存两份状态迟早会不一致，比如手改 JSON 把 `source`
/// 改成 `system`、`editable` 却还是 `true`。对外返回时按这里推导。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Source {
/// 系统内置：随项目发布，只读，只有项目维护者手改 JSON 能改。
System,
/// 用户提交。
Submission,
/// 第三方通过接口推送。
Api,
}
impl Source {
/// 系统内置的条目不可修改。
pub fn is_system(self) -> bool {
matches!(self, Source::System)
}
}
/// 一个网站条目。
///
/// 字段名在 JSON 里是 camelCase（和前端 Dart 的 `fromJson` 一致），
/// 以后新增字段一律加 `#[serde(default)]`，老 JSON 文件仍然能读，不必写迁移。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Site {
/// 唯一标识，也是接口路径里的 id。
pub id: String,
/// 显示名称。前端取它的首字当图标。
pub title: String,
/// 跳转地址。
pub url: String,
#[serde(default)]
pub description: String,
/// 所属分组或子分组的 id。
pub category_id: String,
pub source: Source,
/// 同一分组内的排序值，小的在前。
#[serde(default)]
pub order: i32,
pub created_at: String,
pub updated_at: String,
/// 提交来源标识；系统内置为空。
#[serde(default)]
pub submitted_by: String,
}
impl Site {
/// 能不能被接口修改。
pub fn is_editable(&self) -> bool {
!self.source.is_system()
}
}
/// 分组。`parent_id` 为空表示一级分组，不为空表示子分组。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Category {
pub id: String,
pub title: String,
#[serde(default)]
pub parent_id: String,
pub source: Source,
#[serde(default)]
pub order: i32,
pub created_at: String,
pub updated_at: String,
}
impl Category {
/// 是不是一级分组。
pub fn is_root(&self) -> bool {
self.parent_id.is_empty()
}
/// 能不能被接口改动（提交时新建的分组才能被后续提交复用，内置分组只看不改）。
pub fn is_editable(&self) -> bool {
!self.source.is_system()
}
}
/// 对外返回的网站：在落盘结构上补一个推导出来的 `editable`。
///
/// 这里存一份 `Site` 的拷贝而不是借用：接口层需要先把互斥锁放开、
/// 再去序列化响应，借用会让生命周期绑死在锁上。
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SiteView {
#[serde(flatten)]
pub site: Site,
/// 由 `source` 推导，不落盘。前端据此决定要不要显示编辑/删除入口。
pub editable: bool,
}
impl From<Site> for SiteView {
fn from(site: Site) -> Self {
Self {
editable: site.is_editable(),
site,
}
}
}
impl From<&Site> for SiteView {
fn from(site: &Site) -> Self {
Self::from(site.clone())
}
}
/// 对外返回的分组节点：带上自己直接挂着的网站与下一级子分组。
///
/// 前端侧栏与内容区需要的正是这棵树，所以直接在接口层拼好，
/// 前端不用再拿两份数组自己组装。
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct NavGroupView {
pub id: String,
pub title: String,
pub source: Source,
pub editable: bool,
pub sites: Vec<SiteView>,
pub children: Vec<NavGroupView>,
}
/// `GET /api/nav` 的响应体。
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct NavResponse {
/// 站点级配置，前端不再自己写死站点名和搜索框提示。
pub site: SiteMeta,
pub groups: Vec<NavGroupView>,
}
/// 站点级配置，存在 `data/site.json`，由项目维护者手改。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SiteMeta {
/// 站点名，显示在侧栏顶部与浏览器标题。
pub name: String,
/// 搜索框占位文案。
#[serde(default)]
pub search_hint: String,
}
/// 提交 / 推送一个网站的入参。
///
/// **没有 `categoryId`**：提交方只能给分组名，由后端在「用户创建的分组」里
/// 查找或新建，这样提交的内容不可能落进内置分组。
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateSiteRequest {
// 下面三个字段也用 `default`：缺字段时不要让 axum 抛 422 和英文错误，
// 交给 `validate` 给出统一的中文 400 说明。
#[serde(default)]
pub title: String,
#[serde(default)]
pub url: String,
#[serde(default)]
pub description: String,
/// 一级分组名。
#[serde(default)]
pub group: String,
/// 子分组名，可选；给了就挂到两级下面。
#[serde(default)]
pub sub_group: String,
#[serde(default)]
pub submitted_by: String,
}
/// 修改一个网站的入参，只改传进来的字段。
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct UpdateSiteRequest {
#[serde(default)]
pub title: Option<String>,
#[serde(default)]
pub url: Option<String>,
#[serde(default)]
pub description: Option<String>,
/// 给了就表示要把条目挪到（或挪进）这个用户分组。
#[serde(default)]
pub group: Option<String>,
#[serde(default)]
pub sub_group: Option<String>,
}
backend/src/store.rs
+828
View File
@@ -0,0 +1,828 @@
//! 数据仓库：启动时把四个 JSON 文件读进内存，之后读内存、写文件。
//!
//! 「系统内置不可修改」是靠结构保证的：`system-*.json` 只在 `load` 里被读，
//! 模块里根本没有写这两个文件的函数，任何接口都改不到它们。
use std::collections::HashSet;
use std::fs;
use std::path::{Path, PathBuf};
use serde::Serialize;
use serde::de::DeserializeOwned;
use crate::error::{ApiError, StoreError};
use crate::model::{
Category, CreateSiteRequest, NavGroupView, NavResponse, Site, SiteMeta, SiteView, Source,
UpdateSiteRequest,
};
use crate::util::{generate_id, now_iso8601};
use crate::validate::{self, SiteDraft, SitePatch};
/// 同一分组里每新增一条，排序值加这么多，给以后手工插入留出空隙。
const ORDER_STEP: i32 = 10;
/// 四个数据文件的位置。
#[derive(Debug, Clone)]
pub struct DataPaths {
pub site: PathBuf,
pub system_categories: PathBuf,
pub system_sites: PathBuf,
pub user_categories: PathBuf,
pub user_sites: PathBuf,
}
impl DataPaths {
pub fn in_dir(dir: &Path) -> Self {
Self {
site: dir.join("site.json"),
system_categories: dir.join("system-categories.json"),
system_sites: dir.join("system-sites.json"),
user_categories: dir.join("user-categories.json"),
user_sites: dir.join("user-sites.json"),
}
}
}
/// 内存态数据仓库。
pub struct Store {
paths: DataPaths,
site: SiteMeta,
system_categories: Vec<Category>,
system_sites: Vec<Site>,
user_categories: Vec<Category>,
user_sites: Vec<Site>,
}
impl Store {
/// 从数据目录读取全部数据。系统文件必须存在；用户文件缺失时当空处理，
/// 这样第一次跑起来只需要带上种子数据。
pub fn load(dir: &Path) -> Result<Self, StoreError> {
let paths = DataPaths::in_dir(dir);
Ok(Self {
site: read_json(&paths.site, true)?,
system_categories: read_list(&paths.system_categories, true)?,
system_sites: read_list(&paths.system_sites, true)?,
user_categories: read_list(&paths.user_categories, false)?,
user_sites: read_list(&paths.user_sites, false)?,
paths,
})
}
/// 启动自检。不通过就直接让进程退出——数据文件坏了还继续跑，
/// 只会把更乱的数据写回去。
pub fn verify(&self) -> Result<(), StoreError> {
// 0. 站点配置是必需的：站点名不能空。
if self.site.name.trim().is_empty() {
return Err(StoreError::Integrity(
"site.json 里的 name 不能为空".to_string(),
));
}
// 1. source 必须和文件归属一致，防止手改 JSON 越权。
for category in &self.system_categories {
if !category.source.is_system() {
return Err(StoreError::Integrity(format!(
"system-categories.json 里的分组「{}」source 不是 system",
category.id
)));
}
}
for category in &self.user_categories {
if category.source.is_system() {
return Err(StoreError::Integrity(format!(
"user-categories.json 里的分组「{}」source 不能是 system",
category.id
)));
}
}
for site in &self.system_sites {
if !site.source.is_system() {
return Err(StoreError::Integrity(format!(
"system-sites.json 里的网站「{}」source 不是 system",
site.id
)));
}
}
for site in &self.user_sites {
if site.source.is_system() {
return Err(StoreError::Integrity(format!(
"user-sites.json 里的网站「{}」source 不能是 system",
site.id
)));
}
}
// 2. id 不能重复。
ensure_unique(self.categories().map(|c| c.id.as_str()), "分组")?;
ensure_unique(self.sites().map(|s| s.id.as_str()), "网站")?;
// 3. 分组层级：parentId 必须存在、必须是一级分组、不能自指。
for category in self.categories() {
if category.parent_id.is_empty() {
continue;
}
if category.parent_id == category.id {
return Err(StoreError::Integrity(format!(
"分组「{}」的 parentId 指向了自己",
category.id
)));
}
let parent = self.find_category(&category.parent_id).ok_or_else(|| {
StoreError::Integrity(format!(
"分组「{}」的 parentId「{}」不存在",
category.id, category.parent_id
))
})?;
if !parent.is_root() {
return Err(StoreError::Integrity(format!(
"分组「{}」挂在子分组「{}」下，层级最多两级",
category.id, parent.id
)));
}
if parent.source.is_system() != category.source.is_system() {
return Err(StoreError::Integrity(format!(
"分组「{}」和它的父分组「{}」来源不一致",
category.id, parent.id
)));
}
}
// 4. 每个网站都要挂在一个存在的分组上，而且来源要对得上：
// 内置网站只能在内置分组下，提交的网站只能在用户分组下。
for site in &self.system_sites {
let category = self.require_category(&site.category_id)?;
if !category.source.is_system() {
return Err(StoreError::Integrity(format!(
"内置网站「{}」挂在了用户分组「{}」下",
site.id, category.id
)));
}
}
for site in &self.user_sites {
let category = self.require_category(&site.category_id)?;
if category.source.is_system() {
return Err(StoreError::Integrity(format!(
"提交的网站「{}」挂在了内置分组「{}」下",
site.id, category.id
)));
}
}
Ok(())
}
/// 统计信息，给健康检查用。
pub fn summary(&self) -> Summary {
Summary {
sites: self.system_sites.len() + self.user_sites.len(),
system_sites: self.system_sites.len(),
user_sites: self.user_sites.len(),
categories: self.categories().count(),
}
}
/// 侧栏 + 内容区需要的那棵树。
pub fn nav(&self) -> NavResponse {
let mut roots: Vec<&Category> =
self.categories().filter(|c| c.is_root()).collect();
sort_categories(&mut roots);
NavResponse {
site: self.site.clone(),
groups: roots.into_iter().map(|c| self.group_view(c)).collect(),
}
}
/// 新增一个提交 / 推送的网站。
pub fn create(
&mut self,
request: &CreateSiteRequest,
source: Source,
) -> Result<Site, ApiError> {
if source.is_system() {
return Err(ApiError::internal("新增接口不接受 system 来源"));
}
let draft = validate::submission(request)?;
// 先改副本，落盘成功后再替换内存：写盘失败时不会留下「内存有、磁盘没有」的状态。
let mut categories = self.user_categories.clone();
let mut sites = self.user_sites.clone();
let category_id = resolve_user_group(&mut categories, &draft)?;
let order = next_order(&sites, &category_id);
let now = now_iso8601();
let site = Site {
id: new_id(site_prefix(source), &sites),
title: draft.title,
url: draft.url,
description: draft.description,
category_id,
source,
order,
created_at: now.clone(),
updated_at: now,
submitted_by: draft.submitted_by,
};
sites.push(site.clone());
write_list(&self.paths.user_categories, &categories)?;
write_list(&self.paths.user_sites, &sites)?;
self.user_categories = categories;
self.user_sites = sites;
Ok(site)
}
/// 修改一个网站。系统内置的直接 403。
pub fn update(&mut self, id: &str, request: &UpdateSiteRequest) -> Result<Site, ApiError> {
let patch = validate::patch(request)?;
let index = self.user_sites.iter().position(|s| s.id == id);
let Some(index) = index else {
if self.system_sites.iter().any(|s| s.id == id) {
return Err(ApiError::forbidden(format!(
"「{id}」是系统内置网站，不能修改"
)));
}
return Err(ApiError::not_found(format!("找不到网站：{id}")));
};
let mut categories = self.user_categories.clone();
let mut sites = self.user_sites.clone();
let moved_to = if let Some(group) = &patch.group {
let sub = patch.sub_group.clone().unwrap_or_default();
Some(resolve_named_group(&mut categories, group, &sub)?)
} else if let Some(sub) = &patch.sub_group {
if sub.is_empty() {
None
} else {
// 只给子分组：沿用条目当前所属的一级分组。
let root = root_title_of(&categories, &sites[index].category_id)
.ok_or_else(|| ApiError::internal("当前条目的一级分组找不到"))?;
Some(resolve_named_group(&mut categories, &root, sub)?)
}
} else {
None
};
// 排序值要在拿到 `sites[index]` 的可变借用之前算好，否则借用冲突。
let moved_order = moved_to.as_ref().map(|id| next_order(&sites, id));
let site = &mut sites[index];
apply_patch(site, patch);
if let Some(category_id) = moved_to {
if let Some(order) = moved_order {
site.order = order;
}
site.category_id = category_id;
}
site.updated_at = now_iso8601();
let updated = site.clone();
write_list(&self.paths.user_categories, &categories)?;
write_list(&self.paths.user_sites, &sites)?;
self.user_categories = categories;
self.user_sites = sites;
Ok(updated)
}
/// 删除一个网站。系统内置的直接 403。
pub fn delete(&mut self, id: &str) -> Result<(), ApiError> {
if self.system_sites.iter().any(|s| s.id == id) {
return Err(ApiError::forbidden(format!(
"「{id}」是系统内置网站，不能删除"
)));
}
let mut sites = self.user_sites.clone();
let before = sites.len();
sites.retain(|s| s.id != id);
if sites.len() == before {
return Err(ApiError::not_found(format!("找不到网站：{id}")));
}
write_list(&self.paths.user_sites, &sites)?;
self.user_sites = sites;
Ok(())
}
// ---- 内部 ----
fn categories(&self) -> impl Iterator<Item = &Category> {
self.system_categories.iter().chain(self.user_categories.iter())
}
fn sites(&self) -> impl Iterator<Item = &Site> {
self.system_sites.iter().chain(self.user_sites.iter())
}
fn find_category(&self, id: &str) -> Option<&Category> {
self.categories().find(|c| c.id == id)
}
fn require_category(&self, id: &str) -> Result<&Category, StoreError> {
self.find_category(id).ok_or_else(|| {
StoreError::Integrity(format!("分组「{id}」不存在，但有网站挂在它下面"))
})
}
fn group_view(&self, category: &Category) -> NavGroupView {
let mut children: Vec<&Category> = self
.categories()
.filter(|c| c.parent_id == category.id)
.collect();
sort_categories(&mut children);
let mut sites: Vec<&Site> = self
.sites()
.filter(|s| s.category_id == category.id)
.collect();
sort_sites(&mut sites);
NavGroupView {
id: category.id.clone(),
title: category.title.clone(),
source: category.source,
editable: category.is_editable(),
sites: sites.into_iter().map(SiteView::from).collect(),
children: children.into_iter().map(|c| self.group_view(c)).collect(),
}
}
}
/// 健康检查 / 启动日志用的统计。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Summary {
pub sites: usize,
pub system_sites: usize,
pub user_sites: usize,
pub categories: usize,
}
/// 解析（必要时新建）用户分组，返回网站该挂到的分组 id。
///
/// 只在传进来的 `user_categories` 里查找——内置分组不参与，
/// 所以提交的内容不可能落进内置分组。
fn resolve_user_group(
categories: &mut Vec<Category>,
draft: &SiteDraft,
) -> Result<String, ApiError> {
resolve_named_group(categories, &draft.group, &draft.sub_group)
}
fn resolve_named_group(
categories: &mut Vec<Category>,
group: &str,
sub_group: &str,
) -> Result<String, ApiError> {
let root_id = match categories.iter().find(|c| c.is_root() && c.title == group) {
Some(found) => found.id.clone(),
None => push_category(categories, group, "")?,
};
if sub_group.is_empty() {
return Ok(root_id);
}
match categories
.iter()
.find(|c| c.parent_id == root_id && c.title == sub_group)
{
Some(found) => Ok(found.id.clone()),
None => push_category(categories, sub_group, &root_id),
}
}
fn push_category(
categories: &mut Vec<Category>,
title: &str,
parent_id: &str,
) -> Result<String, ApiError> {
let id = new_id("g", categories);
let order = categories
.iter()
.filter(|c| c.parent_id == parent_id)
.map(|c| c.order)
.max()
.unwrap_or(0)
+ ORDER_STEP;
let now = now_iso8601();
categories.push(Category {
id: id.clone(),
title: title.to_string(),
parent_id: parent_id.to_string(),
source: Source::Submission,
order,
created_at: now.clone(),
updated_at: now,
});
Ok(id)
}
fn apply_patch(site: &mut Site, patch: SitePatch) {
if let Some(value) = patch.title {
site.title = value;
}
if let Some(value) = patch.url {
site.url = value;
}
if let Some(value) = patch.description {
site.description = value;
}
}
/// 找出某个分组所属的一级分组标题。
fn root_title_of(categories: &[Category], category_id: &str) -> Option<String> {
let category = categories.iter().find(|c| c.id == category_id)?;
if category.is_root() {
return Some(category.title.clone());
}
categories
.iter()
.find(|c| c.id == category.parent_id)
.map(|root| root.title.clone())
}
fn next_order(sites: &[Site], category_id: &str) -> i32 {
sites
.iter()
.filter(|s| s.category_id == category_id)
.map(|s| s.order)
.max()
.unwrap_or(0)
+ ORDER_STEP
}
fn site_prefix(source: Source) -> &'static str {
match source {
Source::Submission => "s",
Source::Api => "a",
// 系统内置的 id 是手写的，不会走到这里。
Source::System => "sys",
}
}
/// 生成一个当前集合里没用过的 id。
fn new_id<T: HasId>(prefix: &str, existing: &[T]) -> String {
for _ in 0..8 {
let candidate = generate_id(prefix);
if !existing.iter().any(|item| item.id() == candidate) {
return candidate;
}
}
// 理论上到不了这里；真撞上了就退化成带纳秒的 id，保证唯一。
format!("{prefix}-{}", now_iso8601().replace([':', '-'], ""))
}
trait HasId {
fn id(&self) -> &str;
}
impl HasId for Site {
fn id(&self) -> &str {
&self.id
}
}
impl HasId for Category {
fn id(&self) -> &str {
&self.id
}
}
fn sort_categories(items: &mut [&Category]) {
items.sort_by(|a, b| {
a.order
.cmp(&b.order)
.then_with(|| a.created_at.cmp(&b.created_at))
.then_with(|| a.id.cmp(&b.id))
});
}
fn sort_sites(items: &mut [&Site]) {
items.sort_by(|a, b| {
a.order
.cmp(&b.order)
.then_with(|| a.created_at.cmp(&b.created_at))
.then_with(|| a.id.cmp(&b.id))
});
}
fn ensure_unique<'a>(ids: impl Iterator<Item = &'a str>, label: &str) -> Result<(), StoreError> {
let mut seen = HashSet::new();
for id in ids {
if !seen.insert(id) {
return Err(StoreError::Integrity(format!("{label} id 重复：{id}")));
}
}
Ok(())
}
/// 读一个 JSON 数组。`required` 为 false 时，文件不存在按空数组处理。
fn read_list<T: DeserializeOwned>(path: &Path, required: bool) -> Result<Vec<T>, StoreError> {
if !path.exists() {
if required {
return Err(StoreError::Io(format!("找不到数据文件：{}", path.display())));
}
return Ok(Vec::new());
}
let text = fs::read_to_string(path)
.map_err(|e| StoreError::Io(format!("{}：{e}", path.display())))?;
serde_json::from_str(&text)
.map_err(|e| StoreError::Json(format!("{}：{e}", path.display())))
}
/// 读一个 JSON 对象。`required` 为 false 时，文件不存在会报错并要求补上——
/// 站点配置是必需项，缺了就说明数据目录不完整。
fn read_json<T: DeserializeOwned>(path: &Path, required: bool) -> Result<T, StoreError> {
if !path.exists() {
if required {
return Err(StoreError::Io(format!("找不到数据文件：{}", path.display())));
}
}
let text = fs::read_to_string(path)
.map_err(|e| StoreError::Io(format!("{}：{e}", path.display())))?;
serde_json::from_str(&text)
.map_err(|e| StoreError::Json(format!("{}：{e}", path.display())))
}
/// 原子写：先写临时文件再改名，避免写到一半断电把数据文件写坏。
fn write_list<T: Serialize>(path: &Path, value: &[T]) -> Result<(), StoreError> {
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)
.map_err(|e| StoreError::Io(format!("{}：{e}", parent.display())))?;
}
let mut text = serde_json::to_string_pretty(value)
.map_err(|e| StoreError::Json(e.to_string()))?;
text.push('\n');
let tmp = path.with_extension("json.tmp");
fs::write(&tmp, text).map_err(|e| StoreError::Io(format!("{}：{e}", tmp.display())))?;
fs::rename(&tmp, path).map_err(|e| StoreError::Io(format!("{}：{e}", path.display())))?;
Ok(())
}
#[cfg(test)]
/// 造一份最小的种子数据，供单元测试与接口测试共用。
pub fn seed_for_test(dir: &Path) {
fs::write(
dir.join("site.json"),
r#"{ "name": "Suxing Nav", "searchHint": "输入关键字搜索全网资源..." }"#,
)
.expect("写测试数据失败");
fs::write(
dir.join("system-categories.json"),
r#"[
{ "id": "common", "title": "常用推荐", "parentId": "", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" },
{ "id": "materials", "title": "素材资源", "parentId": "", "source": "system", "order": 20,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" },
{ "id": "design", "title": "UI 设计", "parentId": "materials", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" }
]"#,
)
.expect("写测试数据失败");
fs::write(
dir.join("system-sites.json"),
r#"[
{ "id": "github", "title": "GitHub", "url": "https://github.com", "description": "代码托管与开源社区",
"categoryId": "common", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z", "submittedBy": "" },
{ "id": "zhihu", "title": "知乎", "url": "https://www.zhihu.com", "description": "深度内容问答社区",
"categoryId": "common", "source": "system", "order": 20,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z", "submittedBy": "" },
{ "id": "figma", "title": "Figma", "url": "https://www.figma.com", "description": "协同界面设计工具",
"categoryId": "design", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z", "submittedBy": "" }
]"#,
)
.expect("写测试数据失败");
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
fn write(path: &Path, text: &str) {
fs::write(path, text).expect("写测试数据失败");
}
fn store_in(temp: &TempDir) -> Store {
seed_for_test(temp.path());
let store = Store::load(temp.path()).expect("加载失败");
store.verify().expect("自检失败");
store
}
fn submission(title: &str, url: &str, group: &str, sub_group: &str) -> CreateSiteRequest {
CreateSiteRequest {
title: title.to_string(),
url: url.to_string(),
description: "一句话描述".to_string(),
group: group.to_string(),
sub_group: sub_group.to_string(),
submitted_by: "[email protected]".to_string(),
}
}
#[test]
fn loads_seed_data_and_builds_nav_tree() {
let temp = TempDir::new().unwrap();
let store = store_in(&temp);
let nav = store.nav();
assert_eq!(nav.groups.len(), 2, "两个一级分组");
assert_eq!(nav.groups[0].id, "common");
assert_eq!(nav.groups[0].sites.len(), 2, "common 下有两条");
assert_eq!(nav.groups[1].id, "materials");
assert_eq!(nav.groups[1].children.len(), 1);
assert_eq!(nav.groups[1].children[0].id, "design");
assert_eq!(nav.groups[1].children[0].sites[0].site.id, "figma");
assert!(!nav.groups[1].children[0].sites[0].editable, "内置条目不可编辑");
}
#[test]
fn submission_creates_its_own_group_and_lands_there() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
let site = store
.create(&submission("Hugging Face", "https://huggingface.co", "AI 工具", "模型社区"), Source::Submission)
.expect("提交应当成功");
assert!(site.id.starts_with("s-"), "用户提交的 id 用 s- 前缀：{}", site.id);
assert!(site.category_id.starts_with("g-"), "分组是新建的：{}", site.category_id);
assert_eq!(site.source, Source::Submission);
assert!(site.is_editable());
// 新分组挂在第一位，且是两级结构。
let nav = store.nav();
let created_root = nav.groups.iter().find(|g| g.id != "common" && g.id != "materials").unwrap();
assert_eq!(created_root.title, "AI 工具");
assert_eq!(created_root.children[0].title, "模型社区");
assert_eq!(created_root.children[0].sites[0].site.id, site.id);
// 真的写到磁盘了：重新加载还能看到。
let reloaded = Store::load(temp.path()).expect("重新加载失败");
reloaded.verify().expect("重新加载后自检失败");
assert_eq!(reloaded.summary().user_sites, 1);
}
#[test]
fn same_group_name_is_reused() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
let first = store
.create(&submission("A", "https://a.com", "AI 工具", "模型社区"), Source::Submission)
.unwrap();
let second = store
.create(&submission("B", "https://b.com", "AI 工具", "模型社区"), Source::Submission)
.unwrap();
assert_eq!(first.category_id, second.category_id, "同名分组应当复用");
assert_eq!(store.summary().categories, 5, "只多了一级 + 子分组两个");
}
#[test]
fn submission_can_never_land_in_a_system_group() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
// 故意用内置分组的名字提交。
let site = store
.create(&submission("Fake", "https://fake.com", "素材资源", "UI 设计"), Source::Submission)
.unwrap();
assert_ne!(site.category_id, "design", "不能挂进内置子分组");
assert!(site.category_id.starts_with("g-"), "应当在用户分组里");
// 内置分组下的内容没被动过。
let nav = store.nav();
let materials = nav.groups.iter().find(|g| g.id == "materials").unwrap();
assert_eq!(materials.children[0].id, "design");
assert_eq!(materials.children[0].sites.len(), 1, "design 下仍然只有 Figma");
assert!(materials.children[0].sites[0].site.id == "figma");
}
#[test]
fn system_sites_cannot_be_updated_or_deleted() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
let update = UpdateSiteRequest {
title: Some("改个名字".to_string()),
..Default::default()
};
let err = store.update("github", &update).unwrap_err();
assert_eq!(err.status(), axum::http::StatusCode::FORBIDDEN);
let err = store.delete("github").unwrap_err();
assert_eq!(err.status(), axum::http::StatusCode::FORBIDDEN);
}
#[test]
fn user_sites_can_be_updated_and_deleted() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
let site = store
.create(&submission("A", "https://a.com", "AI 工具", ""), Source::Submission)
.unwrap();
let update = UpdateSiteRequest {
title: Some("新名字".to_string()),
url: Some("https://a2.com".to_string()),
..Default::default()
};
let updated = store.update(&site.id, &update).unwrap();
assert_eq!(updated.title, "新名字");
assert_eq!(updated.url, "https://a2.com");
assert_eq!(updated.category_id, site.category_id, "没传 group 就不换分组");
store.delete(&site.id).unwrap();
assert_eq!(store.summary().user_sites, 0);
let err = store.delete(&site.id).unwrap_err();
assert_eq!(err.status(), axum::http::StatusCode::NOT_FOUND);
}
#[test]
fn update_can_move_a_site_between_user_groups() {
let temp = TempDir::new().unwrap();
let mut store = store_in(&temp);
let site = store
.create(&submission("A", "https://a.com", "AI 工具", ""), Source::Submission)
.unwrap();
let update = UpdateSiteRequest {
group: Some("效率工具".to_string()),
sub_group: Some("笔记".to_string()),
..Default::default()
};
let updated = store.update(&site.id, &update).unwrap();
assert_ne!(updated.category_id, site.category_id);
let nav = store.nav();
let moved = nav
.groups
.iter()
.find(|g| g.title == "效率工具")
.expect("新分组应当存在");
assert_eq!(moved.children[0].title, "笔记");
assert_eq!(moved.children[0].sites[0].site.id, site.id);
}
#[test]
fn verify_rejects_a_tampered_file() {
let temp = TempDir::new().unwrap();
seed_for_test(temp.path());
// 把内置网站标成 api 来源，模拟手改 JSON 越权。
write(
&temp.path().join("system-sites.json"),
r#"[{ "id": "github", "title": "GitHub", "url": "https://github.com",
"categoryId": "common", "source": "api",
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" }]"#,
);
let store = Store::load(temp.path()).expect("加载应当成功");
let err = store.verify().unwrap_err();
assert!(err.to_string().contains("source"), "{err}");
}
#[test]
fn verify_rejects_user_site_under_system_group() {
let temp = TempDir::new().unwrap();
seed_for_test(temp.path());
write(
&temp.path().join("user-sites.json"),
r#"[{ "id": "s-1", "title": "A", "url": "https://a.com",
"categoryId": "common", "source": "submission",
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" }]"#,
);
let store = Store::load(temp.path()).expect("加载应当成功");
let err = store.verify().unwrap_err();
assert!(err.to_string().contains("内置分组"), "{err}");
}
#[test]
fn verify_rejects_three_level_groups() {
let temp = TempDir::new().unwrap();
seed_for_test(temp.path());
write(
&temp.path().join("system-categories.json"),
r#"[{ "id": "materials", "title": "素材资源", "parentId": "", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" },
{ "id": "design", "title": "UI 设计", "parentId": "materials", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" },
{ "id": "deep", "title": "更深一层", "parentId": "design", "source": "system", "order": 10,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z" }]"#,
);
write(&temp.path().join("system-sites.json"), "[]");
let store = Store::load(temp.path()).expect("加载应当成功");
let err = store.verify().unwrap_err();
assert!(err.to_string().contains("两级"), "{err}");
}
#[test]
fn missing_user_files_are_treated_as_empty() {
let temp = TempDir::new().unwrap();
seed_for_test(temp.path());
let store = Store::load(temp.path()).expect("加载失败");
store.verify().expect("自检失败");
assert_eq!(store.summary().user_sites, 0);
}
}
backend/src/util.rs
+91
View File
@@ -0,0 +1,91 @@
//! 与业务无关的小工具：时间格式化与 id 生成。
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};
use time::OffsetDateTime;
use time::format_description::well_known::Rfc3339;
/// 进程内自增计数，用来保证同一纳秒内生成的 id 也不重复。
static COUNTER: AtomicU64 = AtomicU64::new(0);
/// 当前时间的 ISO 8601 UTC 字符串，例如 `2026-09-19T06:02:11Z`。
///
/// 统一用 UTC：客户端拿到的时刻永远无歧义，展示成哪个时区是前端的事。
/// 截掉秒以下的小数位，和手写的种子数据保持同一种格式。
pub fn now_iso8601() -> String {
let now = OffsetDateTime::now_utc();
// `replace_nanosecond` 返回 Result（纳秒可能越界），0 一定合法，取不到就用原值。
let now = now.replace_nanosecond(0).unwrap_or(now);
now.format(&Rfc3339)
.unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
}
/// 今天的日期，格式 `20260919`，只用来拼可读的 id。
pub fn today_compact() -> String {
let today = now_iso8601();
today.get(0..10).unwrap_or("1970-01-01").replace('-', "")
}
/// 生成 `<prefix>-<日期>-<6 位十六进制>` 形式的 id。
///
/// 日期段让人一眼看出创建时间；随机段用「纳秒 + 自增计数」混合后取低 24 位，
/// 不引第三方随机数库，也不依赖操作系统的随机源。
pub fn generate_id(prefix: &str) -> String {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_nanos() as u64)
.unwrap_or(0);
let counter = COUNTER.fetch_add(0x9E37_79B9_7F4A_7C15, Ordering::Relaxed);
let mixed = splitmix64(nanos ^ counter);
format!("{prefix}-{}-{:06x}", today_compact(), mixed & 0xFF_FFFF)
}
/// splitmix64：把低位不稳定的输入（纳秒）打散，让取出来的后 24 位分布更均匀。
fn splitmix64(seed: u64) -> u64 {
let mut z = seed.wrapping_add(0x9E37_79B9_7F4A_7C15);
z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
z ^ (z >> 31)
}
/// 字符数（不是字节数）。
///
/// 用 `chars()` 而不是 `len()`：中文一个字是 3 个字节，按字节数判断长度会误判。
pub fn char_count(value: &str) -> usize {
value.trim().chars().count()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn now_iso8601_uses_utc_and_seconds_precision() {
let now = now_iso8601();
assert!(now.ends_with('Z'), "should end with Z: {now}");
assert_eq!(now.len(), 20, "should look like 2026-09-19T06:02:11Z: {now}");
}
#[test]
fn today_compact_has_no_separators() {
let today = today_compact();
assert_eq!(today.len(), 8, "should look like 20260919: {today}");
assert!(today.chars().all(|c| c.is_ascii_digit()), "{today}");
}
#[test]
fn generate_id_is_prefixed_and_unique() {
let first = generate_id("s");
let second = generate_id("s");
assert!(first.starts_with("s-"), "{first}");
assert_eq!(first.len(), 17, "s-20260919-8f3a1c: {first}");
assert_ne!(first, second, "连续两次生成不应该相同");
}
#[test]
fn char_count_counts_chars_not_bytes() {
assert_eq!(char_count(" 知乎 "), 2);
assert_eq!(char_count("abc"), 3);
assert_eq!(char_count(" "), 0);
}
}
backend/src/validate.rs
+299
View File
@@ -0,0 +1,299 @@
//! 写入前的校验与归一化。
//!
//! 所有外部写入（用户提交、接口推送、修改）都必须先过这里，
//! 保证进内存的数据是干净的：空白已去掉、长度有上限、url 可用。
use std::net::IpAddr;
use url::Url;
use crate::error::ApiError;
use crate::model::{CreateSiteRequest, UpdateSiteRequest};
use crate::util::char_count;
/// 字段长度上限，集中放在这里，改规则只改这一处。
const MAX_TITLE_CHARS: usize = 60;
const MAX_DESCRIPTION_CHARS: usize = 120;
const MAX_GROUP_CHARS: usize = 30;
const MAX_SUBMITTED_BY_CHARS: usize = 120;
/// 校验并归一化之后的提交内容。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SiteDraft {
pub title: String,
pub url: String,
pub description: String,
pub group: String,
pub sub_group: String,
pub submitted_by: String,
}
/// 校验并归一化之后的修改内容；`None` 表示这个字段不改。
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SitePatch {
pub title: Option<String>,
pub url: Option<String>,
pub description: Option<String>,
pub group: Option<String>,
pub sub_group: Option<String>,
}
impl SitePatch {
/// 这次修改是不是什么都没带。
pub fn is_empty(&self) -> bool {
self.title.is_none()
&& self.url.is_none()
&& self.description.is_none()
&& self.group.is_none()
&& self.sub_group.is_none()
}
}
/// 校验提交 / 推送的入参。
pub fn submission(request: &CreateSiteRequest) -> Result<SiteDraft, ApiError> {
Ok(SiteDraft {
title: title(&request.title)?,
url: url(&request.url)?,
description: description(&request.description)?,
group: group(&request.group)?,
sub_group: optional_group("subGroup", &request.sub_group)?,
submitted_by: submitted_by(&request.submitted_by)?,
})
}
/// 校验修改的入参。
pub fn patch(request: &UpdateSiteRequest) -> Result<SitePatch, ApiError> {
let mut result = SitePatch::default();
if let Some(value) = &request.title {
result.title = Some(title(value)?);
}
if let Some(value) = &request.url {
result.url = Some(url(value)?);
}
if let Some(value) = &request.description {
result.description = Some(description(value)?);
}
if let Some(value) = &request.group {
result.group = Some(group(value)?);
}
if let Some(value) = &request.sub_group {
result.sub_group = Some(optional_group("subGroup", value)?);
}
if result.is_empty() {
return Err(ApiError::bad_request(
"请求里没有任何可修改的字段：title / url / description / group / subGroup 至少要给一个",
));
}
Ok(result)
}
fn title(raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
if value.is_empty() {
return Err(ApiError::bad_request("title 不能为空"));
}
if char_count(value) > MAX_TITLE_CHARS {
return Err(ApiError::bad_request(format!(
"title 最多 {MAX_TITLE_CHARS} 个字符，收到 {} 个",
char_count(value)
)));
}
Ok(value.to_string())
}
fn description(raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
if char_count(value) > MAX_DESCRIPTION_CHARS {
return Err(ApiError::bad_request(format!(
"description 最多 {MAX_DESCRIPTION_CHARS} 个字符，收到 {} 个",
char_count(value)
)));
}
Ok(value.to_string())
}
fn group(raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
if value.is_empty() {
return Err(ApiError::bad_request(
"group 不能为空：提交的网站必须自带一个分组名，不能放进内置分组",
));
}
if char_count(value) > MAX_GROUP_CHARS {
return Err(ApiError::bad_request(format!(
"group 最多 {MAX_GROUP_CHARS} 个字符，收到 {} 个",
char_count(value)
)));
}
Ok(value.to_string())
}
fn optional_group(field: &str, raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
if char_count(value) > MAX_GROUP_CHARS {
return Err(ApiError::bad_request(format!(
"{field} 最多 {MAX_GROUP_CHARS} 个字符，收到 {} 个",
char_count(value)
)));
}
Ok(value.to_string())
}
fn submitted_by(raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
if char_count(value) > MAX_SUBMITTED_BY_CHARS {
return Err(ApiError::bad_request(format!(
"submittedBy 最多 {MAX_SUBMITTED_BY_CHARS} 个字符"
)));
}
Ok(value.to_string())
}
/// 地址必须是可解析的 http(s)，且不能指向本机或内网。
///
/// 后端并不会去抓这个地址，这条规则是为了保持收录的数据干净：
/// 内网地址、localhost 对访客没有意义，出现在导航站里只会是坏链接。
fn url(raw: &str) -> Result<String, ApiError> {
let value = raw.trim();
let parsed = Url::parse(value)
.map_err(|_| ApiError::bad_request(format!("url 不是合法地址：{value}")))?;
match parsed.scheme() {
"http" | "https" => {}
other => {
return Err(ApiError::bad_request(format!(
"url 协议只能是 http 或 https，收到 {other}"
)));
}
}
let host = parsed
.host_str()
.ok_or_else(|| ApiError::bad_request("url 缺少主机名"))?;
if is_internal_host(host) {
return Err(ApiError::bad_request(format!(
"url 不能是本机或内网地址：{host}"
)));
}
Ok(value.to_string())
}
fn is_internal_host(host: &str) -> bool {
let host = host.to_ascii_lowercase();
if host == "localhost" || host.ends_with(".localhost") || host.ends_with(".local") {
return true;
}
// IPv6 的 host_str() 带方括号（例如 `[::1]`），去掉后才能当 IP 解析。
let bare = host
.strip_prefix('[')
.and_then(|value| value.strip_suffix(']'))
.unwrap_or(&host);
match bare.parse::<IpAddr>() {
Ok(IpAddr::V4(v4)) => {
v4.is_loopback() || v4.is_private() || v4.is_link_local() || v4.is_unspecified()
}
Ok(IpAddr::V6(v6)) => v6.is_loopback() || v6.is_unspecified(),
Err(_) => false,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn request(title: &str, url: &str, group: &str) -> CreateSiteRequest {
CreateSiteRequest {
title: title.to_string(),
url: url.to_string(),
description: String::new(),
group: group.to_string(),
sub_group: String::new(),
submitted_by: String::new(),
}
}
#[test]
fn accepts_normal_submission_and_trims() {
let draft = submission(&request(" Hugging Face ", " https://huggingface.co ", " AI 工具 "))
.expect("应当通过");
assert_eq!(draft.title, "Hugging Face");
assert_eq!(draft.url, "https://huggingface.co");
assert_eq!(draft.group, "AI 工具");
assert_eq!(draft.sub_group, "");
}
#[test]
fn rejects_empty_title() {
let err = submission(&request(" ", "https://a.com", "组")).unwrap_err();
assert_eq!(err.status(), axum::http::StatusCode::BAD_REQUEST);
assert!(err.message().contains("title"));
}
#[test]
fn rejects_too_long_title_counting_chars() {
let long = "一".repeat(MAX_TITLE_CHARS + 1);
assert!(submission(&request(&long, "https://a.com", "组")).is_err());
let exact = "一".repeat(MAX_TITLE_CHARS);
assert!(submission(&request(&exact, "https://a.com", "组")).is_ok());
}
#[test]
fn rejects_empty_group() {
let err = submission(&request("标题", "https://a.com", " ")).unwrap_err();
assert!(err.message().contains("group"));
}
#[test]
fn rejects_non_http_scheme() {
assert!(submission(&request("标题", "ftp://a.com", "组")).is_err());
assert!(submission(&request("标题", "javascript:alert(1)", "组")).is_err());
assert!(submission(&request("标题", "不是地址", "组")).is_err());
assert!(submission(&request("标题", "http://a.com", "组")).is_ok());
}
#[test]
fn rejects_internal_hosts() {
for url in [
"http://localhost:8080",
"http://127.0.0.1",
"http://10.0.0.5",
"http://192.168.1.10",
"http://172.16.0.1",
"http://169.254.0.1",
"http://0.0.0.0",
"http://[::1]",
"http://nas.local",
] {
assert!(
submission(&request("标题", url, "组")).is_err(),
"{url} 应当被拒绝"
);
}
}
#[test]
fn rejects_too_long_description() {
let mut req = request("标题", "https://a.com", "组");
req.description = "字".repeat(MAX_DESCRIPTION_CHARS + 1);
assert!(submission(&req).is_err());
}
#[test]
fn rejects_too_long_sub_group() {
let mut req = request("标题", "https://a.com", "组");
req.sub_group = "字".repeat(MAX_GROUP_CHARS + 1);
assert!(submission(&req).is_err());
}
#[test]
fn patch_requires_at_least_one_field() {
let empty = UpdateSiteRequest::default();
assert!(patch(&empty).is_err());
let with_title = UpdateSiteRequest {
title: Some(" 新名字 ".to_string()),
..Default::default()
};
let result = patch(&with_title).expect("应当通过");
assert_eq!(result.title.as_deref(), Some("新名字"));
assert!(result.url.is_none());
}
}
docs/backend-site-schema.md
+219
View File
@@ -0,0 +1,219 @@
# 后端数据结构设计：网站与分组
> 本文是设计稿，已按此实现。代码在 `backend/`，接口与运行方式见
> [backend/README.md](../backend/README.md)。
## 1. 需求与边界
- 后端是 Rust，**数据用 JSON 文件存储**，不引入数据库。
- 网站分两类：
- **系统内置**：随项目发布，只读，只有项目维护者能改。
- **可修改**：用户提交、或第三方通过接口推送进来的，能改、能删。
- **不需要审核**：提交即上线。
- **图标沿用当前逻辑**：前端取名称首字渲染，后端不存图标。
- **不统计访问量**。
- **提交的网站不能放进内置分组**：提交时必须自带分组名（或分组 + 子分组名），
后端只在「用户创建的分组」里找或建；内置分组只有项目维护者自己维护。
## 2. 一个网站条目的完整结构
系统内置的一条（`index3.html` 里的 GitHub）：
```json
{
"id": "github",
"title": "GitHub",
"url": "https://github.com",
"description": "代码托管与开源社区",
"categoryId": "common",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48+08:00",
"updatedAt": "2026-09-13T10:29:48+08:00",
"submittedBy": ""
}
```
用户提交的一条：
```json
{
"id": "s-20260919-8f3a1c",
"title": "Hugging Face",
"url": "https://huggingface.co",
"description": "开源模型与数据集社区",
"categoryId": "g-20260919-4d21ab",
"source": "submission",
"order": 0,
"createdAt": "2026-09-19T14:02:11+08:00",
"updatedAt": "2026-09-19T14:02:11+08:00",
"submittedBy": "[email protected]"
}
```
## 3. 字段说明
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 唯一标识，同时是接口路径里的 id。命名规则见 3.1。 |
| `title` | string | 是 | 显示名称。前端取它的首字当图标。上限 60 字符。 |
| `url` | string | 是 | 跳转地址，必须是可解析的 `http` / `https`。 |
| `description` | string | 否 | 一句话描述，卡片副标题。上限 120 字符。 |
| `categoryId` | string | 是 | 所属分组或子分组的 id。**必须指向用户创建的分组**（见第 5 节）。 |
| `source` | enum | 是 | `system` / `submission` / `api`。它同时决定这条能不能被修改。 |
| `order` | int | 否 | 同一分组内的排序值，小的在前，默认 0。内置条目靠它固定顺序，提交进来的默认追加到末尾。 |
| `createdAt` | string | 是 | 创建时间，ISO 8601 带时区。 |
| `updatedAt` | string | 是 | 最后修改时间，ISO 8601 带时区。 |
| `submittedBy` | string | 否 | 提交来源标识：用户提交放邮箱或用户名，接口推送放调用方标识，内置为空。 |
### 3.1 id 命名规则
| 来源 | 规则 | 例子 |
| --- | --- | --- |
| 系统内置网站 | 手写，语义化，小写字母 + 数字 + `-` | `github`、`can-i-use` |
| 用户提交网站 | 后端生成：`s-` + 日期 + 随机后缀 | `s-20260919-8f3a1c` |
| 接口推送网站 | 后端生成：`a-` + 日期 + 随机后缀 | `a-20260919-2b77d0` |
| 用户创建分组 | 后端生成：`g-` + 日期 + 随机后缀 | `g-20260919-4d21ab` |
前缀分开是为了**一眼看出这条是谁写的**，也从生成规则上杜绝和内置 id 撞车。
### 3.2 source：唯一决定「能不能改」的字段
```rust
pub enum SiteSource {
System, // 系统内置，只读
Submission, // 用户提交
Api, // 接口推送
}
```
- 只有 `source == "system"` 的条目不可修改：修改、删除接口一律返回 403。
- 不单独存 `editable` 字段，它由 `source` 推导。存两份状态迟早不一致，
比如手改 JSON 把 `source` 改成 `system`、`editable` 却还是 `true`。
- 访客接口返回时附带派生的 `editable` 给前端用，不落盘。
## 4. 提交时为什么必须自带分组
分组也是同样的两套：
```json
{
"id": "materials",
"title": "素材资源",
"parentId": "",
"source": "system",
"order": 20,
"createdAt": "2026-09-13T10:29:48+08:00",
"updatedAt": "2026-09-13T10:29:48+08:00"
}
```
```json
{
"id": "design",
"title": "UI 设计",
"parentId": "materials",
"source": "system",
"order": 10,
"createdAt": "2026-09-13T10:29:48+08:00",
"updatedAt": "2026-09-13T10:29:48+08:00"
}
```
- `parentId` 为空 = 一级分组；不为空 = 子分组，指向它所属的一级分组。
- 层级上限两级，和侧栏的结构一致（`index3.html` 就是两级）。
- `source == "system"` 的分组只看不改，由项目维护者手写 JSON 维护。
- `source != "system"` 的分组只可能由提交产生。
### 4.1 提交接口的入参
提交方**不能指定 `categoryId`**，只能给分组名：
```json
{
"title": "Hugging Face",
"url": "https://huggingface.co",
"description": "开源模型与数据集社区",
"group": "AI 工具",
"subGroup": "模型社区",
"submittedBy": "[email protected]"
}
```
后端按这个顺序处理：
1. 在**用户创建的分组**里按名字找一级分组 `AI 工具`；找不到就新建一个
（`source = "submission"`，id 自动生成）。
2. 如果带了 `subGroup`，在 `AI 工具` 下面按名字找子分组；找不到就新建。
3. 新建网站条目，`categoryId` 指向解析出来的子分组（没带 `subGroup` 就指向一级分组）。
规则上：
- 内置分组**永远不参与**第 1、2 步的查找，所以提交的内容不可能落进内置分组。
- 同一个父级下同名的用户分组**复用**，不会每提交一次就多出一个同名分组。
如果希望「每次提交都新建」，把查找那一步去掉即可。
- 修改接口同样不允许把已有条目挪进内置分组，判定标准和创建时一致。
## 5. 两种数据如何隔离
```
backend/data/
├── site.json # 站点名与搜索框提示，只读
├── system-categories.json # 内置分组，只读，项目维护者手写
├── system-sites.json # 内置网站，只读
├── user-categories.json # 提交时创建的分组，可写
└── user-sites.json # 提交 / 推送的网站，可写
```
- 读：启动时全量加载进内存，之后都从内存读，不再碰磁盘。
- 写：只写 `user-*.json` 两个文件。**代码里不存在写 `system-*.json` 的路径**，
「不可修改」靠结构保证，而不是靠每处调用都记得判断。
- 写盘用「先写临时文件再改名」，避免写到一半断电把文件写坏。
- JSON 用 2 空格缩进、保留中文原文，方便直接看 diff。
### 5.1 启动时的自检
启动时校验一遍，不通过就直接启动失败（防止手改 JSON 越权）：
- `system-*.json` 里的条目 `source` 必须全是 `system`；
`user-*.json` 里必须全不是。
- 每个网站的 `categoryId` 必须存在，并且**分组来源要和网站来源一致**：
内置网站只能挂在系统分组下，提交的网站只能挂在用户分组下。
- 分组 `parentId` 指向的分组必须存在，且不能出现两级以上、不能自己指向自己。
## 6. 校验规则
写入（用户提交 / 接口推送）时逐条校验，任何一条不过就整体拒绝并返回原因：
| 规则 | 说明 |
| --- | --- |
| `id` 唯一 | 与已有网站都不冲突 |
| `title` 非空、≤ 60 字符 | 去掉首尾空白后判断 |
| `url` 合法 | 可解析，协议必须是 `http` / `https`，且不能是 localhost 与内网地址 |
| `description` ≤ 120 字符 | 允许为空 |
| `group` 非空、≤ 30 字符 | 没有它就没地方放，直接拒绝 |
| `subGroup` ≤ 30 字符 | 可选；给了就必须和 `group` 一起解析成两级 |
| `source` 只能是 `submission` / `api` | 外部写入不允许声称自己是 `system` |
## 7. 和前端现有模型的关系
前端 `LinkItem` 目前用到 `id` / `title` / `url` / `description` 四个字段，
本次结构是它的超集，前端不改也能读出来；`categoryId`、`source`、`editable`
等字段等前端要用时再接。
字段名统一用 **camelCase**，和前端 Dart 的 `fromJson` 对齐，前端不用做名字转换；
Rust 侧用 `#[serde(rename_all = "camelCase")]` 映射。
**新加字段一律带 `#[serde(default)]`**，这样以后往结构里加字段，老 JSON 仍然能读，
不需要写迁移脚本。
## 8. 这次没有放进结构里的东西
按「先保留当前逻辑」处理，以下都不存；以后要用再加字段（加字段不需要迁移）：
| 没放的 | 原因 | 以后要加时 |
| --- | --- | --- |
| `icon` | 前端当前是取 `title` 首字渲染 | 加 `icon` 字段，存 favicon 地址或 emoji |
| `tags` | 当前侧栏和卡片都没有标签 | 加 `tags: []`，提交接口再放开这个入参 |
| `visits` | 不统计访问量 | 要么由后端跳转接口累加，要么接第三方统计 |
| `status` | 不需要审核，提交即上线 | 加 `status` 字段并给默认值 `published` |
docs/frontend-architecture.md
+429
View File
@@ -0,0 +1,429 @@
# Navius Flutter 前端结构与实现说明
## 1. 范围与前提
本文档描述 `frontend/`（Flutter Web 前端）的目录结构、分层理由，以及它如何从静态原型落地为可维护的产品代码。
约束条件：
- 目标平台只有 **Web**，不做移动端 / 桌面端适配。
- 数据来自 **Rust 后端的 `GET /api/nav`**（本地 mock 保留给测试用）。
- **不修改 `backend/`（Rust）**，只在架构上为将来接入后端留好接口位置。
- **视觉与交互基准是项目根目录的 `index3.html`**，逐条对齐、不自行发挥。
整理目标按优先级排列：**可读**（新人能顺着目录找到代码）→ **可测**（核心逻辑不依赖浏览器）→ **可扩展**（接后端时改动面最小）。
> 逐条核对（每一条 CSS 规则、每一段 JS 对应到哪个文件）见
> [index3-alignment.md](./index3-alignment.md)；本文讲结构与取舍。
## 2. 基准：根目录的 index3.html
`index3.html` 是一份独立静态原型，也是本轮实现的唯一视觉基准：
```
┌──────────────┬──────────────────────────────────────────────┐
│ Suxing Nav │ ☰ 🔍 搜索框 ← 750px 居中顶栏 │
│ │ │
│ 常用推荐 │ ▍常用推荐 │
│ 素材资源 › │ ┌──────┐ ┌──────┐ ┌──────┐ │
│ ├ UI 设计 │ │ 卡片 │ │ 卡片 │ │ 卡片 │ │
│ ├ 图标库 │ └──────┘ └──────┘ └──────┘ │
│ └ 高清壁纸 │ │
│ 开发工具 › │ ▍素材资源 - UI 设计 │
│ ├ 前端框架 │ ┌──────┐ ┌──────┐ │
│ └ 在线 API │ └──────┘ └──────┘ │
│ │ │
│ ────────── │ ⬆ 回到 │
│ 提交网站 │ 顶部 │
└──────────────┴──────────────────────────────────────────────┘
230px（可折叠到 64px）
```
它是一份**原型**而不是成品：搜索框没有任何行为、导航的 `active` 是写死的、折叠后只剩一排空方块、导航里七个锚点有五个没有对应分区、整份文件没有任何媒体查询。这些差距在本轮实现中全部补齐，补齐内容见第 6 节。
## 3. 最终目录结构
仓库整体：
```
Navius/
├── index.html # 早期静态原型（历史版本，保留作参考）
├── index3.html # 当前视觉基准（静态原型，不被构建流程引用）
├── backend/ # Rust 后端，本轮未改动
│ ├── Cargo.toml
│ └── src/main.rs
├── docs/ # 项目级文档
│ └── frontend-architecture.md
└── frontend/ # Flutter Web 前端
├── lib/ # 应用代码（见下方展开）
├── test/ # 测试代码，目录结构与 lib/ 镜像对应
├── web/ # Web 平台资源（index.html、manifest、图标）
├── android/ ios/ linux/ macos/ windows/ # Flutter 脚手架生成，Web 目标不使用
├── analysis_options.yaml # 静态分析与 lint 规则
└── pubspec.yaml # 依赖与项目描述
```
`lib/` 展开：
```
lib/
├── main.dart # 入口：runApp 一行
├── app.dart # 应用根组件：主题配置 + 依赖装配
│
├── core/ # 与业务无关的基础设施
│ ├── constants/
│ │ ├── app_sizes.dart # 尺寸与动效常量
│ │ └── app_breakpoints.dart # 网格列数计算（等价 CSS auto-fill）
│ ├── services/
│ │ ├── url_opener.dart # 打开链接的抽象接口
│ │ └── web_url_opener.dart # Web 实现（唯一依赖 package:web 的文件）
│ ├── theme/
│ │ ├── app_colors.dart # 颜色与阴影
│ │ ├── app_text_styles.dart # 语义化文字样式
│ │ └── app_theme.dart # ThemeData
│ └── utils/
│ └── text.dart # 取首字符（中文 / emoji 安全）
│
└── features/ # 一个功能一个目录
└── home/ # 首页：导航站主界面
├── data/
│ ├── home_repository.dart # 仓库契约（读 / 提交 / 编辑 / 删除，异步）
│ ├── http_home_repository.dart # 后端实现：四个接口 + 映射成前端模型
│ ├── mock_home_data.dart # mock 数据（3 个一级导航 / 2 个分区 / 5 个站点）
│ └── mock_home_repository.dart # mock 仓库实现（测试用）
├── domain/models/
│ ├── nav_node.dart # 侧栏导航节点（叶子 / 可展开分组）
│ ├── link_item.dart # 站点条目模型（含搜索匹配规则）
│ ├── link_section.dart # 分区模型（含分区过滤）
│ └── home_data.dart # 首页聚合根（导航树 + 分区 + 跨分区搜索）
└── presentation/
├── pages/home_page.dart # 首页：布局、状态与交互
└── widgets/
├── sidebar_nav.dart # 侧栏：折叠、层级导航、提交入口
├── top_bar.dart # 顶部控制栏：折叠按钮 + 搜索框
├── link_search_field.dart # 搜索框（含聚焦光晕）
├── link_section_view.dart # 分区标题 + 自适应网格
├── link_card.dart # 站点卡片
├── back_to_top_button.dart # 右下角圆形回到顶部
├── dialog_buttons.dart # 对话框的主/次按钮
├── confirm_dialog.dart # 通用确认框（删除前确认）
├── site_form_dialog.dart # 网站表单（新增 / 编辑共用）
└── ...
```
`test/` 展开（与 `lib/` 一一对应）：
```
test/
├── core/constants/app_breakpoints_test.dart # 断点与网格列数
├── features/home/
│ ├── data/mock_home_repository_test.dart # 导航树、数据自洽性与搜索规则
│ └── presentation/
│ ├── home_page_test.dart # 布局 / 折叠 / 子菜单 / 搜索 / 联动
│ └── link_card_test.dart # 卡片渲染、点击、悬停
└── helpers/fake_url_opener.dart # 假实现，避免测试真的弹浏览器
```
## 4. 依赖方向与数据流
依赖方向是单向的，箭头表示「可以引用」：
```
main.dart → app.dart
│
▼
features/home ──▶ core/
```
两条硬规则：
1. `core/` 不引用 `features/`。
2. `domain/` 不引用 `data/` 与 `presentation/`。
数据流：
```
后端 GET /api/nav ──▶ { site: { name, searchHint }, groups: [ { …, sites: [] } ] }
│ ▲
│ │ POST /api/sites（提交）
│ │ PATCH /api/sites/{id}（编辑）
│ │ DELETE /api/sites/{id}（删除）
▼ │
HttpHomeRepository ──实现──▶ HomeRepository（读 / 提交 / 编辑 / 删除）
│ 把分组树映射成前端模型：分组 → 侧栏导航；有网站的组 → 内容分区；
│ 每个网站带 editable，决定卡片上有没有编辑/删除入口
▼
HomePage State：_load() 拿到 HomeData，并在加载中 / 失败（可重试）/ 完成三种状态间切换
│ （页面持有交互状态：当前分区、侧栏折叠、已展开的分组）
▼
展示组件：只接收数据 + 回调，不自己取数、不自己跳转
```
## 5. 设计令牌：从 CSS 到常量
`index3.html` 用 CSS 变量组织样式，这里逐条映射到 `core/theme` 与 `core/constants`，组件只引用语义名，不再出现十六进制色值或魔法数字。
| index3.html 中的来源 | 取值 | Flutter 对应 |
| --- | --- | --- |
| `--bg-color` | `#f7f9fb` | `AppColors.background` |
| `--card-bg` | `#ffffff` | `AppColors.surface` |
| `--primary-color` | `#3b82f6` | `AppColors.primary` |
| `--text-main` | `#1e293b` | `AppColors.textPrimary` |
| `--text-sub` | `#64748b` | `AppColors.textSecondary` |
| `--border-color` | `#e2e8f0` | `AppColors.border` |
| `--shadow` | `0 4px 6px -1px rgba(0,0,0,.05)` + `0 2px 4px -1px rgba(0,0,0,.03)` | `AppColors.cardShadow` |
| `--shadow-hover` | `0 10px 15px -3px rgba(0,0,0,.08)` + `0 4px 6px -2px rgba(0,0,0,.04)` | `AppColors.cardShadowHover` |
| `.nav-link.active` | `#eff6ff` | `AppColors.primaryFaint` |
| `.nav-link:hover` | `#f8fafc` | `AppColors.navItemHover` |
| `.submit-btn:hover` | `#f1f5f9` | `AppColors.navItemHoverDeep` |
| `.arrow-icon` | `#94a3b8` | `AppColors.navArrow` |
| `.card-icon` 底色 | `#f1f5f9` | `AppColors.iconSurface` |
| `.search-box:focus` 光晕 | `0 0 0 3px rgba(59,130,246,.15)` | `AppColors.focusRing` + `AppSizes.focusRingWidth` |
| `--sidebar-width` | `230px` | `AppSizes.sidebarWidth` |
| `--sidebar-collapsed-width` | `64px` | `AppSizes.sidebarCollapsedWidth` |
| `.sidebar` 内边距 | `20px 12px 12px 12px` | `sidebarPaddingTop / Horizontal / Bottom` |
| 折叠态内边距 | `20px 8px 12px 8px` | `sidebarCollapsedPaddingHorizontal` |
| 折叠动画 | `width .3s cubic-bezier(.4,0,.2,1)` | `sidebarTransition` + `Curves.fastOutSlowIn` |
| `.sidebar-header` | `height:40px; margin-bottom:24px`，logo 居中 | `sidebarHeaderHeight`、`sidebarHeaderGap` |
| `.logo` | `18px / 700` | `AppTextStyles.logo` |
| `.logo-icon` | `20px / 800` | `AppTextStyles.logoIcon` |
| `.nav-link` | `padding: 11px 16px`，圆角 8px，14px / 500 | `navItemPaddingVertical/Horizontal`、`navItemRadius`、`AppTextStyles.navItem` |
| `.nav-item-wrapper` | `margin-bottom: 4px` | `navItemGap` |
| 折叠态 `.nav-link` | `padding: 12px 0` + 居中 | `navItemCollapsedPaddingVertical` |
| `.sub-menu` | `padding-left: 16px`，`.3s` 高度动画 | `subMenuIndent`、`subMenuTransition` |
| `.sub-menu .nav-link` | `padding: 8px 16px`，13px | `subNavItemPaddingVertical/Horizontal`、`AppTextStyles.subNavItem` |
| `.sidebar-footer` | 上边框 + `padding-top:12px; margin-top:8px` | `sidebarFooterPaddingTop`、`sidebarFooterMarginTop` |
| `.submit-btn` | `padding: 10px 16px`，圆角 8px | `submitButtonPaddingVertical/Horizontal` |
| `.main-content` | `padding: 24px 40px 40px 40px` | `contentPaddingTop / Horizontal / Bottom` |
| `.top-bar` | `max-width:750px; gap:16px; margin-bottom:36px`，水平居中 | `topBarMaxWidth`、`topBarGap`、`topBarMarginBottom` |
| `.toggle-btn` | `44×44`，圆角 12px | `toggleButtonSize`、`toggleButtonRadius` |
| `.search-box` | `height:44px; padding: 0 20px`，圆角 12px，15px | `searchHeight`、`searchPaddingHorizontal`、`searchRadius`、`AppTextStyles.searchInput` |
| `.section-title` | `16px / 600`，`::before` 为 4×16 竖条 | `AppTextStyles.sectionTitle`、`sectionAccentWidth/Height/Radius/Gap` |
| 分区下间距 / 网格间距 | `36px` / `16px` | `sectionGap`、`gridGap` |
| `.grid` | `repeat(auto-fill, minmax(220px, 1fr))` | `gridMinItemWidth` + `AppBreakpoints.gridColumnsFor` |
| `.card` | 圆角 10px，内边距 `14px 16px`，悬停 `translateY(-2px)` | `cardRadius`、`cardPaddingVertical/Horizontal`、`cardHoverLift` |
| `.card-icon` | `36px`，圆角 8px，右侧间距 12px | `cardIconSize`、`cardIconRadius`、`cardIconGap` |
| `.card-title` / `.card-desc` | `14px / 600` / `12px`，单行省略 | `AppTextStyles.cardTitle` / `cardDesc` |
| `.back-to-top` | `44×44` 圆形，距右下角 `30px`，悬停 `translateY(-3px)` | `backToTopSize`、`backToTopOffset`、`backToTopHoverLift` |
| `transition: 0.2s` | 200ms | `AppSizes.transition` |
## 6. 明确不实现的原型缺口
当前实现是 `index3.html` 的逐条还原，**没有补任何原型之外的行为**。原型里没做的，这里也不做：
| 原型的状态 | 当前实现 |
| --- | --- |
| 搜索框没有任何 JS | 只接收输入，不过滤内容 |
| `active` 写死在「常用推荐」上 | 高亮固定不动 |
| 没有媒体查询 | 侧栏始终 230px（可手动折到 64px），主内容内边距始终 `24/40/40/40` |
| `#icon`、`#stock`、`#dev`、`#api`、`#submit` 没有对应元素 | 点击后没有任何反应 |
| 只有 `#common`、`#design` 两段内容 | 内容区就是两段、五张卡片 |
唯一必须偏离 CSS 的地方是分区标题的换行：`.section-title` 是 `display:flex`，
浏览器会把过长文字折行，而 Flutter 的 `Row` 会直接溢出报错，
所以标题用 `Flexible` 包住并单行省略。这条差异会随着标题文案的调整而消失。
### 响应式规则
| 视口宽度 | 布局 |
| --- | --- |
| ≥ 900px | 侧栏默认展开（230px） |
| < 900px | 主内容内边距 40 → 20，侧栏默认折叠（64px） |
断点取 900 而不是常见的 768：侧栏 230 + 主内容左右内边距 + 一个 220 的卡片，
再留出可读留白，900 是这套栅格开始舒展的下限。规则写成纯函数
`AppBreakpoints.layoutFor(width)`，可以被单元测试覆盖。
「默认折叠」而不是「强制折叠」：用户手动切换过之后，
`_collapsedOverride` 就接管了控制权，拖窗口不会再覆盖用户的意愿。
### 网格列数
```dart
columns = floor((availableWidth + gap) / (minItemWidth + gap))
```
这与 CSS 的 `repeat(auto-fill, minmax(220px, 1fr))` 等价：比如可用宽度 456 时正好放下两列（220×2 + 16），455 时退回一列。测试里有一个用例专门验证这条边界。
## 7. 为什么这样整理
### 7.1 为什么 `main.dart` 只留几行
入口文件的职责只有一个：把根组件挂到 Flutter 引擎上。任何额外逻辑（主题、依赖装配、路由）放进 `main.dart` 都会让「程序从哪里开始」变得模糊，也没法在测试里绕开它。
### 7.2 为什么是 `core` + `features`，而不是 `models/` `services/` `widgets/`
按技术类型平铺，在项目只有一两个页面时看着整齐；页面一多就会出现「改一个功能要翻五个目录」，而且同名文件互相污染。
按功能切分后，`features/home/` 里的东西只服务于首页，删掉整个目录不影响其它部分。`core/` 则只放与业务无关的东西——主题、尺寸常量、断点计算、取首字符、打开链接的能力。判断标准很简单：**如果它能被原样复制到另一个 App 里，它就属于 `core`**。
### 7.3 为什么功能内部再分 `data / domain / presentation`
- `domain/` 是模型与规则，不依赖 Flutter、不依赖网络，最容易测试。
- `data/` 是「数据从哪来」：后端实现、mock 实现，以及它们共同实现的仓库契约。
- `presentation/` 是「数据怎么显示」，包含页面与组件。
好处是接后端时改动落点明确：只加一个 `data/` 下的实现类，`domain/` 与 `presentation/` 基本不动。
### 7.4 为什么导航用一棵树（`NavNode`）而不是两个列表
侧栏里同时存在两种条目：直接跳转的（常用推荐）和可展开的（素材资源、开发工具）。
如果拆成「一级列表 + 二级字典」，页面就要在两份数据之间来回对照，
「某个分区属于哪个分组」这种问题会散落在多处。
用同一棵树表达，`NavNode.leaves` 能把树拍平成内容区需要的顺序，
`HomeData.groupIdOf(id)` 能回答「这个分区属于哪个分组」，
`isGroup` 决定渲染成跳转项还是展开项。树是唯一真相。
### 7.5 为什么搜索规则写在 `domain` 而不是页面里
`HomeData.search()` 与 `LinkItem.matches()` 是纯函数，不依赖任何 Widget。这样「搜什么、怎么算命中、命中后空分区要不要保留」这几条规则可以直接被单元测试覆盖，不必挂载界面。放到页面里就得先 pump 一整棵组件树才能验证一条过滤规则。
### 7.6 为什么要有 `Repository` 接口 + `Mock` 实现
页面只依赖接口，不依赖具体数据源。这换来两件事：接 Rust 后端时新增一个实现类即可；测试里可以注入任意数据集，不用为「测试专用数据」改动生产代码。
### 7.7 为什么仓库返回 `Future`
接上后端之前，`fetchHomeData` 是同步的：mock 数据是恒定常量，套一层 `Future`
只会凭空多出 loading 与 error 两个分支。
接上 `GET /api/nav` 之后这两个状态变成真实存在的——网络会慢、会断、后端会重启——
所以契约改成 `Future<HomeData>`，页面里相应地有了加载中、加载失败（带重试）、
加载完成三种状态。改动只落在 `data/` 与页面的取数那一处，模型和展示组件没动。
### 7.8 为什么把「打开链接」抽成 `UrlOpener`
卡片直接调用 `web.window.open` 会让组件无法在测试里验证，也会让平台相关代码散落在 UI 里。抽象成接口后，`package:web` 只出现在 `web_url_opener.dart` 一个文件里，测试可以注入假实现，断言「点了哪张卡片、打开了哪个地址」。
### 7.9 为什么不做滚动联动
侧栏的 `active` 只由点击决定，滚动内容区不会改动侧栏。
曾经实现过一版「滚到哪个分区、侧栏就高亮哪一项」的联动，
结果是滚动右侧时左侧一直在闪，观感像有只鼠标在侧栏上一路划过去。
原因有两层：一是内容区每个分区只有一百多像素高，连续滚动时高亮会
一个接一个地亮起；二是当时的路由是「滚动监听 → 页面 `setState`
→ 整棵子树（含侧栏）重建」，为了压住这个抖动又叠了去抖、
激活线、程序化滚动的抑制标志，越修越复杂。
最后直接去掉联动。理由：
1. 左侧栏和右侧内容区没有因果关系，滚动内容区不该触发侧栏重建。
去掉后这一点是结构性的——`initState` 里不再给 `ScrollController`
挂监听，滚动只重绘内容区，侧栏一个 widget 都不会重建。
2. 这个导航站的分区标题本身就在页面上，用户不需要侧栏替他回答
「我在哪一节」。
3. 原型里 `active` 本来就是静态的，去掉联动反而更接近给定设计。
测试里有一条用例守住这条边界：滚动到内容底部后，
断言侧栏第一行的 `AnimatedContainer` 仍是**同一个 widget 实例**
（没有重建），且高亮位置不变。
### 7.10 为什么折叠态显示首字，而不是照搬原型的空白
原型折叠后把 `.nav-text` 全部 `display:none` 且没有准备图标，
侧栏会变成一列没有信息的空方块，用户没有任何线索知道点哪个是哪个。
改成显示标题首字，是在不引入图标资源的前提下、与原设计语言最一致的做法——
logo 折叠后显示的也正是站点名的首字「S」。同理，取首字用 `runes`
而不是 `substring`，中文与 emoji 才不会被截成半个字符。
### 7.11 为什么子菜单收起时把子项从树里移除
CSS 的 `max-height: 0` 只是视觉上收起了子菜单，DOM 里那些链接还在：
屏幕阅读器仍会读到，键盘 Tab 也会跳进去。Flutter 里对应的做法是用
`AnimatedSize` 配合「关掉时不渲染子项」，既保留高度渐变的观感，
又让语义树与点击命中都保持干净。
### 7.12 为什么组件只发回调、状态集中在页面
搜索词、当前分区、侧栏折叠状态、已展开的分组都由页面持有，
组件只负责显示并向上发回调。这样同一个数据不会有两个真相来源。
只有纯本地的、与外界无关的瞬时状态（悬停）才允许留在组件内部。
### 7.13 为什么把颜色、尺寸、文字样式集中
组件里散落十六进制颜色和魔法数字，会让「改主题色」变成全局搜索替换。现在颜色在 `app_colors.dart`、尺寸在 `app_sizes.dart`、文字样式在 `app_text_styles.dart`，组件只引用语义名。要改主色，只改一处。
### 7.14 为什么测试目录镜像 `lib/`
`test/features/home/presentation/link_card_test.dart` 对应 `lib/features/home/presentation/widgets/link_card.dart`。看测试路径就能猜出被测文件的位置，避免测试文件越堆越多之后找不到归属。
### 7.15 为什么保留看起来「没用」的 `cupertino_icons`
项目不使用 Cupertino 图标，但 Flutter 构建时会引用 CupertinoIcons 字体，移除依赖会导致构建出现字体缺失警告。保留模板自带的版本，是为了构建输出干净。
### 7.16 为什么坚持「注释写为什么，不写是什么」
「给变量赋值」这类注释没有信息量，代码本身就能表达。真正值得写下来的是**取舍**：为什么断点取 900、为什么点击时要关掉滚动联动、为什么折叠态用首字。
这类信息一旦丢失，后来者很容易「好心」改回去。
## 8. 编码约定
`analysis_options.yaml` 在 `flutter_lints` 之上补充了这些规则：
- `strict-raw-types`：禁止裸泛型（如 `List` 而非 `List<String>`）。
- `always_declare_return_types`：函数与方法必须显式声明返回类型。
- `avoid_print`：禁止遗留调试输出。
- `prefer_single_quotes`：统一单引号，减少无意义的 diff。
- `require_trailing_commas`：配合 `dart format` 减少改动噪音。
- `sort_child_properties_last`：`child` 固定在参数末尾。
- `unawaited_futures`：未处理的 `Future` 必须显式处理。
未由 lint 强制、但代码里保持一致的几条：
- 依赖方向由人工把关：新增共享代码前先判断它属于 `core` 还是某个功能。
- 每个公开类与公开成员都写 `///` 文档注释，且注释解释「为什么」。
- 组件的构造函数以 `super.key` 开头，参数按「必填数据 → 可选数据 → 回调」排列。
- 能用 `const` 的地方一律加 `const`。
## 9. 验证结果
| 检查 | 命令 | 结果 |
| --- | --- | --- |
| 静态分析 | `flutter analyze` | 1 条告警（`sidebar_nav.dart` 里 `_NavRow` 的 `super.key` 从未被传入，见下方说明） |
| 单元与组件测试 | `flutter test` | 57 个用例通过，6 个失败（都是侧栏实现与既有用例不一致，见下方说明） |
| Web 构建 | `flutter build web --no-wasm-dry-run` | 构建成功 |
> 上面这两处不是本轮对接引入的：`e2cc3ac` 那次提交重写了侧栏（行内改用 `Container`、
> 折叠态改回显示首字、logo 换成 `AnimatedCrossFade`），而 `test/` 里那几条用例
> 描述的是重写前的行为。对接后端时没有动侧栏，也没有改这些用例。
测试覆盖的关键行为：
- 网格列数：与 CSS `auto-fill` 规则一致，含「刚好放下两列」的边界。
- 导航树：一级条目形态、叶子 id 与原型锚点一致、`active` 取第一个条目。
- mock 数据自洽性：只有两个分区、共五张卡片，`#icon` 等原型里没有内容的锚点取不到分区，id 唯一、字段完整、地址合法。
- 布局：侧栏展开常驻并渲染 logo 与三条导航、子菜单默认收起、两个分区与五张卡片全部渲染。
- 侧栏折叠：折叠到 64px 且 logo 变首字、导航与提交文字都消失、再点可展开回来。
- 分组子菜单：点击展开、再点收起、折叠状态下点分组会先展开侧栏。
- 导航：高亮固定写在第一个条目上；点有对应分区的导航会滚过去且高亮不变；点 `#icon` 这类没有对应元素的导航滚动偏移不变。
- 搜索框：输入后仍是两个分区、五张卡片（不过滤）。
- 滚动：滚动主内容不会重建侧栏、也不会改动高亮；回到顶部把偏移归零。
- 其它：点击卡片把对应 URL 交给 `UrlOpener`；点「提交网站」没有任何反应；卡片渲染首字母、名称与描述，悬停上浮量等于 `AppSizes.cardHoverLift`。
- 后端对接：请求打到 `/api/nav`；分组映射成侧栏导航树；只有挂着网站的分组进内容区；
子分组标题带父级前缀；网站顺序按后端给的排；非 200、非 JSON、缺 `groups`、
连不上后端分别给出对应提示；缺字段的单条数据被跳过而不是整页失败。
- 加载状态：数据没回来时显示「正在加载…」；失败时显示原因和「重试」；点重试会重新取数并在成功后渲染内容。
- 提交表单：空表单提交会逐项提示且不发请求；内网地址被拦下；合法内容按 camelCase
字段发给仓库；后端报错时留在表单里显示原话；提交中按钮变「提交中…」且不可再点；
模板里只列用户分组（内置分组不出现在建议里），点建议会填进输入框。
- 联调：点侧栏「提交网站」打开表单；提交成功后静默重新拉一次数据并弹提示。
- 编辑 / 删除：可修改的条目才有入口；编辑表单预填现有内容且不显示提交者字段；
删除要先确认，点取消什么都不发生；确认后调删除接口并静默刷新；内置条目没有这两个入口。
- 站点信息：站点名与搜索框提示来自后端 `site` 字段，前端不再写死。
## 10. 后续演进建议
按优先级：
1. **做提交网站的界面。** 后端已经有了 `POST /api/sites`（提交）与 `/api/sites/push`（推送），
前端侧栏底部的「提交网站」目前还是个空按钮——`index3.html` 里没有这个表单，
所以要先定表单长什么样再动手。
2. **同步那 6 条侧栏用例。** 要么把侧栏改回用例描述的行为，要么按现在的实现改用例。
3. **换成真实图标。** 目前卡片左侧是站点名首字母、折叠态是导航首字。若要改成站点图标，需要引入 favicon 抓取或本地图标资源，并处理加载失败的占位。
4. **替换 PWA 图标。** `web/icons/` 与 `web/favicon.png` 仍是 Flutter 默认图标，需要替换为项目自己的图标。
4. **记住用户的偏好。** 侧栏折叠状态、展开的分组、当前分区现在都是内存状态，刷新即丢失；可以写进 `localStorage`。
5. **编辑模式。** 导航站的下一步通常是允许用户自行增删分组与站点，那会需要把状态提升为可持久化的模型，并给 `HomeRepository` 增加写入接口。
6. **深色模式。** 现在的颜色令牌是单套浅色值，做法是在 `AppColors` 中按 `Brightness` 提供两套值，并在 `AppTheme` 里增加 `dark` 主题。
docs/index3-alignment.md
+173
View File
@@ -0,0 +1,173 @@
# index3.html 逐条对照
本文档把 `index3.html` 里的每一条 CSS 规则与 JS 行为，逐条对应到 Flutter 实现的位置，用来回答「有没有跑偏」。
对照方式：`index3.html` 里的选择器 / 声明 → Flutter 文件与常量。
## 1. 设计变量
| index3.html | Flutter |
| --- | --- |
| `--bg-color: #f7f9fb` | `AppColors.background` |
| `--card-bg: #ffffff` | `AppColors.surface` |
| `--primary-color: #3b82f6` | `AppColors.primary` |
| `--text-main: #1e293b` | `AppColors.textPrimary` |
| `--text-sub: #64748b` | `AppColors.textSecondary` |
| `--border-color: #e2e8f0` | `AppColors.border` |
| `--shadow` | `AppColors.cardShadow` |
| `--shadow-hover` | `AppColors.cardShadowHover` |
| `--sidebar-width: 230px` | `AppSizes.sidebarWidth` |
| `--sidebar-collapsed-width: 64px` | `AppSizes.sidebarCollapsedWidth` |
## 2. 全局
| index3.html | Flutter |
| --- | --- |
| `* { box-sizing: border-box; margin: 0; padding: 0 }` | Flutter 无 box-sizing 概念，等价于默认行为 |
| `html { scroll-behavior: smooth }` | `Scrollable.ensureVisible(..., duration: 300ms)` |
| `body { background-color: var(--bg-color) }` | `Scaffold.backgroundColor = AppColors.background` |
| `body { color: var(--text-main) }` | `AppTheme.light` + 各文字样式自带颜色 |
| `body { font-family: -apple-system, ... }` | 不指定 `fontFamily`，沿用系统字体栈 |
| `body { display: flex; min-height: 100vh }` | `Scaffold.body = Stack[ Row[侧栏, Expanded(内容)] ]` |
## 3. 侧栏
| index3.html | Flutter |
| --- | --- |
| `.sidebar { width: 230px }` | `SidebarNav` 根 `AnimatedContainer.width` |
| `.sidebar { background-color: card-bg }` | `AppColors.surface` |
| `.sidebar { border-right: 1px solid border }` | `BoxDecoration(border: Border(right: ...))` |
| `.sidebar { padding: 20px 12px 12px 12px }` | `sidebarPaddingTop / Horizontal / Bottom` |
| `.sidebar { flex-direction: column }` | `Column` |
| `.sidebar { height: 100vh }` | `Row(crossAxisAlignment: stretch)` |
| `.sidebar { transition: width .3s cubic-bezier(.4,0,.2,1) }` | `sidebarTransition` + `Curves.fastOutSlowIn`（该曲线即 Material standard easing） |
| `.sidebar { overflow-x: hidden }` | 根部 `ClipRect` |
| `body.sidebar-collapsed .sidebar { width: 64px; padding: 20px 8px 12px 8px }` | `sidebarCollapsedWidth` + `sidebarCollapsedPaddingHorizontal` |
| `.sidebar-header { height: 40px; margin-bottom: 24px; 居中 }` | `_SidebarHeader`（`sidebarHeaderHeight` / `sidebarHeaderGap`） |
| `.logo { font-size: 18px; font-weight: 700; color: primary }` | `AppTextStyles.logo` |
| `.logo-icon { font-size: 20px; font-weight: 800; color: primary }` | `AppTextStyles.logoIcon` |
| `body.sidebar-collapsed .logo-text { display: none }` | 折叠时渲染 `logoIcon` 分支 |
| `body.sidebar-collapsed .logo-icon { display: block }` | 同上 |
| `.nav-container { flex: 1; overflow-y: auto; overflow-x: hidden }` | `Expanded(child: SingleChildScrollView(...))` |
## 4. 导航
| index3.html | Flutter |
| --- | --- |
| `.nav-item-wrapper { margin-bottom: 4px }` | `_NavEntry` 的 `Padding(bottom: navItemGap)` |
| `.nav-link { padding: 11px 16px; border-radius: 8px }` | `navItemPaddingVertical/Horizontal`、`navItemRadius` |
| `.nav-link { font-size: 14px; font-weight: 500 }` | `AppTextStyles.navItem` |
| `.nav-link { color: text-sub }` | `AppColors.textSecondary` |
| `.nav-link { justify-content: space-between }` | `Row(mainAxisAlignment: spaceBetween)` |
| `.nav-link { cursor: pointer }` | `MouseRegion(cursor: SystemMouseCursors.click)` |
| `.nav-link { transition: all .2s }` | `AnimatedContainer(duration: 200ms, curve: Curves.ease)` |
| `.nav-link:hover { background-color: #f8fafc; color: primary }` | `AppColors.navItemHover` + `_hovered` |
| `.nav-link.active { background-color: #eff6ff; color: primary }` | `AppColors.primaryFaint` + `selected` |
| `.arrow-icon { font-size: 14px; font-weight: bold; color: #94a3b8; font-family: monospace }` | `AppTextStyles.navArrow` |
| `.arrow-icon { transition: transform .3s ease }` | `AnimatedRotation(duration: 300ms, curve: Curves.ease)` |
| `.nav-item-wrapper.open > .nav-link .arrow-icon { transform: rotate(90deg) }` | `turns: open ? 0.25 : 0` |
| `.sub-menu { padding-left: 16px; max-height: 0; overflow: hidden }` | `subMenuIndent` + `AnimatedSize`（未展开时不渲染子项） |
| `.sub-menu { transition: max-height .3s cubic-bezier(0,1,0,1) }` | `curve: const Cubic(0, 1, 0, 1)` |
| `.open .sub-menu { max-height: 500px; transition: max-height .3s ease-in-out }` | `curve: Curves.easeInOut` |
| `.sub-menu .nav-link { padding: 8px 16px; font-size: 13px }` | `_SubNavItem` + `AppTextStyles.subNavItem` |
| `body.sidebar-collapsed .nav-text { display: none }` | 折叠时 `_NavRow` 不渲染任何子节点 |
| `body.sidebar-collapsed .arrow-icon { display: none }` | 折叠时 `_NavRow` 走无 trailing 分支 |
| `body.sidebar-collapsed .sub-menu { display: none }` | 折叠时根本不构建 `AnimatedSize` |
| `body.sidebar-collapsed .nav-link { justify-content: center; padding: 12px 0 }` | `navItemCollapsedPaddingVertical` + 水平 0 |
## 5. 侧栏底部
| index3.html | Flutter |
| --- | --- |
| `.sidebar-footer { border-top: 1px solid border; padding-top: 12px; margin-top: 8px }` | `_SidebarFooter` |
| `.submit-btn { padding: 10px 16px; border-radius: 8px; font-size: 14px; font-weight: 500 }` | `submitButtonPaddingVertical/Horizontal`、`AppTextStyles.submitButton` |
| `.submit-btn { color: text-sub; transition: all .2s }` | `AnimatedContainer(curve: Curves.ease)` |
| `.submit-btn:hover { background-color: #f1f5f9; color: primary }` | `AppColors.navItemHoverDeep` |
| `.submit-btn` 的 `title="提交网站"` | `Tooltip('提交网站')` |
| `body.sidebar-collapsed .submit-text { display: none }` | 折叠时不渲染文字 |
## 6. 主内容区与顶栏
| index3.html | Flutter |
| --- | --- |
| `.main-content { margin-left: 230px / 64px }` | `Row[ SizedBox(width: 侧栏), Expanded(内容) ]` |
| `.main-content { transition: margin-left .3s cubic-bezier(.4,0,.2,1) }` | 侧栏宽度动画，同一曲线 |
| `.main-content { padding: 24px 40px 40px 40px }` | `contentPaddingTop / Horizontal / Bottom` |
| `.top-bar { gap: 16px; max-width: 750px; margin: 0 auto 36px auto }` | `TopBar`（`topBarGap` / `topBarMaxWidth` / `topBarMarginBottom` + `Center`） |
| `.toggle-btn { width/height: 44px; border-radius: 12px; border: 1px solid border }` | `toggleButtonSize` / `toggleButtonRadius` |
| `.toggle-btn { box-shadow: var(--shadow) }` | `AppColors.cardShadow` |
| `.toggle-btn { font-size: 18px; color: text-sub }` | `Text('☰', fontSize: 18)` |
| `.toggle-btn { transition: all .2s }` | `AnimatedContainer(curve: Curves.ease)` |
| `.toggle-btn:hover { border-color: primary; color: primary }` | `_hovered` 分支 |
| `.toggle-btn` 的 `title="展开/折叠侧边栏"` | `Tooltip('展开/折叠侧边栏')` |
| `.search-container { flex: 1 }` | `Expanded(child: LinkSearchField)` |
| `.search-box { height: 44px; padding: 0 20px; border-radius: 12px; font-size: 15px }` | `searchHeight` / `searchPaddingHorizontal` / `searchRadius` / `AppTextStyles.searchInput` |
| `.search-box { box-shadow: var(--shadow) }` | 未聚焦时的 `boxShadow` |
| `.search-box:focus { border-color: primary; box-shadow: 0 0 0 3px rgba(59,130,246,.15) }` | 聚焦时**只用**光晕（覆盖默认阴影，与 CSS 一致） |
| `.search-box { transition: border-color .2s, box-shadow .2s }` | `AnimatedContainer(curve: Curves.ease)` |
## 7. 分组与卡片
| index3.html | Flutter |
| --- | --- |
| `.section-title { font-size: 16px; font-weight: 600; margin-bottom: 16px }` | `AppTextStyles.sectionTitle` + `sectionTitleGap` |
| `.section-title::before { width: 4px; height: 16px; margin-right: 8px; border-radius: 2px }` | `_SectionTitle` 的竖条（`sectionAccent*`） |
| `.grid { grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 16px }` | `AppBreakpoints.gridColumnsFor` + `gridGap` |
| `.grid { margin-bottom: 36px }` | 每个分区统一 `sectionGap` 下间距（最后一个也一样） |
| `.card { border-radius: 10px; padding: 14px 16px; border: 1px solid border }` | `cardRadius` / `cardPadding*` / `AppColors.border` |
| `.card { box-shadow: var(--shadow); transition: transform .2s, box-shadow .2s }` | `AnimatedContainer(curve: Curves.ease)` |
| `.card:hover { transform: translateY(-2px); box-shadow: var(--shadow-hover) }` | `cardHoverLift` + `cardShadowHover` |
| `.card-icon { width/height: 36px; border-radius: 8px; background: #f1f5f9; color: primary }` | `_CardIcon`（`cardIconSize` / `cardIconRadius` / `AppColors.iconSurface`） |
| `.card-icon { font-weight: 600; margin-right: 12px }` | `AppTextStyles.cardIcon` + `cardIconGap` |
| `.card-icon` 未设 font-size，继承 body 的 16px | `AppTextStyles.cardIcon.fontSize = 16` |
| `.card-info { overflow: hidden }` + `.card-title/.card-desc` 单行省略 | `Expanded` + `maxLines: 1, overflow: ellipsis` |
| `.card-title { font-size: 14px; font-weight: 600 }` | `AppTextStyles.cardTitle` |
| `.card-desc { font-size: 12px; color: text-sub; margin-top: 2px }` | `AppTextStyles.cardDesc` + `cardTitleGap` |
## 8. 回到顶部
| index3.html | Flutter |
| --- | --- |
| `.back-to-top { position: fixed; bottom: 30px; right: 30px }` | `Positioned(right: 30, bottom: 30)`（`backToTopOffset`） |
| `.back-to-top { width/height: 44px; border-radius: 50% }` | `backToTopSize` + `BoxShape.circle` |
| `.back-to-top { font-size: 18px; color: text-sub; box-shadow: var(--shadow) }` | `Text('↑', fontSize: 18)` + `cardShadow` |
| `.back-to-top { transition: all .2s ease }` | `AnimatedContainer(curve: Curves.ease)` |
| `.back-to-top:hover { color/border-color: primary; transform: translateY(-3px); box-shadow: hover }` | `backToTopHoverLift` + `cardShadowHover` |
| `.back-to-top` 的 `title="回到顶部"` | `Tooltip('回到顶部')` |
## 9. JS 行为
| index3.html 的脚本 | Flutter |
| --- | --- |
| 点 `#toggleBtn` → `body.classList.toggle('sidebar-collapsed')` | `HomePage._toggleSidebar` |
| 点 `.has-sub` → 若已折叠先移除 `sidebar-collapsed` | `HomePage._toggleGroup` 里 `collapsed` 为真时先 `_collapsedOverride = false` |
| 点 `.has-sub` → `parentItem.classList.toggle('open')` | 同一批 id 集合 `_openGroupIds` 的增删 |
## 10. 当前实现没有任何原型之外的行为
以下都是「原型里没有」的行为，**都不实现**：
| 原型的状态 | 当前实现 |
| --- | --- |
| 搜索框没有任何 JS | 只接收输入，不过滤内容；没有空状态、没有清空按钮 |
| `active` 写死在「常用推荐」上 | 高亮固定不动，点其它导航项也不会变 |
| 没有媒体查询 | 侧栏始终 230px（点折叠按钮变 64px），主内容内边距始终 `24/40/40/40` |
| `#icon`、`#stock`、`#dev`、`#api` 没有对应元素 | 这四个导航项点击后没有任何反应（不滚动、不报错） |
| `#submit` 没有对应元素 | 点「提交网站」没有任何反应 |
| 只有 `#common`（3 张卡）与 `#design`（2 张卡）两段内容 | 内容区就是这两段、五张卡片 |
历史上曾经额外加过、现已全部删除的：滚动的侧栏联动、折叠态首字短标签、分组包含当前分区时的强调色、点二级条目自动展开分组、卡片上弹出网址的 tooltip、搜索过滤与空状态、点导航切换高亮、窄屏自动折叠、补齐缺失的四个分区、提交按钮的提示。
## 11. 验证方式
- `flutter analyze` → No issues found
- `flutter test` → 36 个用例通过
- `flutter build web --no-wasm-dry-run` → 构建成功
其中几条专门守住「不加戏」的边界：
- 滚动主内容时，侧栏第一行仍是**同一个 widget 实例**（没有被重建），高亮不变。
- 折叠态下 `navText('常用推荐')`、`navText('提交网站')` 都找不到——文字确实被隐藏了，与 `display: none` 一致。
- 输入搜索词后，仍然是 2 个分区、5 张卡片。
- 点 `#icon` 这类没有对应元素的导航，滚动偏移不变。
- 点「提交网站」不会弹出任何东西。
docs/submit-site-form.md
+116
View File
@@ -0,0 +1,116 @@
# 提交网站表单设计
> 已按本文实现（含「错误色 / 可点建议 / 提交后刷新」三条确认）。代码在
> `frontend/lib/features/home/presentation/widgets/submit_site_dialog.dart`。
> 实现与本文有几处按实际取舍收敛，差异记在第 8 节。
## 1. 目标与约束
- 入口：侧栏底部的「提交网站」按钮（现在是个空按钮）。原型里没有这个表单，
所以这里定完之后再动手写。
- 只管**用户提交**这一条路（`POST /api/sites`）。接口推送是给第三方用的，
走令牌，不在页面上暴露。
- **表单里没有「选择分组」这个动作**：后端不接受 `categoryId`，只接受分组名，
而且提交的内容永远不会落进内置分组。表单要顺着这个规则设计，
不能让用户以为可以把站点塞进「常用推荐」「素材资源」这些内置分组。
- 视觉只能用现有设计令牌（`index3.html` 那套），不引入新的配色和圆角体系。
## 2. 交互流程
```
点侧栏「提交网站」
│
▼
弹出对话框（遮罩 + 白底卡片，居中）
│ 填写（改动某个字段时清掉它上一次的错误）
▼
点「提交」
├─ 有字段不合格 → 定位到第一个不合格的字段并提示，不发请求
└─ 都合格 → 按钮进入「提交中…」，禁用整张表单
├─ 201 → 关掉对话框 + 顶部提示「已提交，感谢」+ 重新拉一次 /api/nav
└─ 其它 → 留在对话框里，顶部显示后端返回的原因，可以改了再提交
```
关闭方式：右上角 ×、点遮罩、「取消」按钮、Esc 键。提交中不允许关闭（避免请求还没回来
就把界面收了）。
## 3. 字段定义
字段与后端 `POST /api/sites` 的入参一一对应，校验规则也和后端保持一致——
前端先拦一遍是为了即时反馈，后端那一遍才是权威。
| 字段 | 控件 | 必填 | 限制 | 不合格时的提示 | 后端字段 |
| --- | --- | --- | --- | --- | --- |
| 网站名称 | 单行输入 | 是 | ≤ 60 字 | 请填写网站名称 / 网站名称最多 60 个字 | `title` |
| 网站地址 | 单行输入 | 是 | 可解析的 http(s)，不能是本机或内网地址 | 请填写网站地址 / 地址要以 http:// 或 https:// 开头 / 不能填本机或内网地址 | `url` |
| 一句话描述 | 多行输入（3 行） | 否 | ≤ 120 字 | 描述最多 120 个字 | `description` |
| 分组 | 单行输入 | 是 | ≤ 30 字 | 请填写分组名称 | `group` |
| 子分组 | 单行输入 | 否 | ≤ 30 字 | 子分组名称最多 30 个字 | `subGroup` |
| 你的称呼或邮箱 | 单行输入 | 否 | ≤ 120 字 | 最多 120 个字 | `submittedBy` |
### 3.1 分组与子分组怎么填
- 两个都是**填名字**，不是选内置分类。placeholder 分别写：
「例如：AI 工具（会创建你自己的分组）」「例如：模型社区（可不填）」。
- 分组下面给一行浅色说明：**「提交的网站会放在你自己的分组里，不会进内置分类。」**
这句话必须留着，否则用户会以为能提交到「常用推荐」。
- 名字和已有的用户分组重名时会**复用**那个分组，不会重复创建——
所以两个输入框下面给一排可点的建议：分组建议列出现有用户分组，
子分组建议列出所选分组下已有的用户子分组（数据来自 `/api/nav` 里
`editable == true` 的分组）。点一下即填入，不想用就直接手打新名字。
- 子分组留空表示直接放在一级分组下。
## 4. 布局与视觉
沿用现有令牌，不新增尺寸：
| 部分 | 取值 |
| --- | --- |
| 遮罩 | `rgba(17, 24, 39, .45)` |
| 卡片 | 白底 + 1px `#e2e8f0` 描边 + 12px 圆角 + `cardShadowHover` |
| 卡片宽度 | 480px，两侧留 24px（窄屏时自适应） |
| 卡片内边距 | 24px |
| 标题 | 「提交网站」，`AppTextStyles.sectionTitle`，右侧一个 × 关闭按钮 |
| 字段标签 | 13px，`--text-sub`，与输入框间隔 6px |
| 输入框 | 复用搜索框那套：44px 高、1px 描边、12px 圆角、聚焦时主色边框 + 3px 光晕 |
| 多行框 | 同上，高度 88px（3 行），垂直内边距 10px |
| 字段间距 | 16px |
| 底部按钮 | 右侧并排：`取消`（描边次级）+ `提交`（主色实底，8px 圆角——和侧栏「提交网站」一致） |
| 字段错误文案 | 12px，紧随输入框下方，间隔 4px |
## 5. 状态
| 状态 | 表现 |
| --- | --- |
| 初始 | 所有输入为空，「提交」可点 |
| 校验失败 | 不合格的字段旁显示提示，输入框边框变错误色；不发请求 |
| 提交中 | 「提交」文案变「提交中…」并禁用，整张表单只读，× / 遮罩 / Esc 都不响应 |
| 提交失败 | 卡片顶部一条错误条，显示后端 `{"error": "…"}` 里的原话；表单恢复可编辑 |
| 提交成功 | 关闭卡片，弹一条「已提交，感谢」提示，并**静默**重新拉一次 `/api/nav`（不闪加载页） |
## 6. 三点确认结果
1. **错误色**：已新增 `AppColors.danger = #E5484D` 与它 8% 的叠加色
`dangerFaint`，只用在错误提示和错误边框上。
2. **分组建议**：保留，做成可点胶囊；只列 `editable == true` 的分组，
内置分组不出现（点了也进不去）。
3. **提交成功后刷新**：保留，用静默刷新——页面继续显示旧内容，
拉到新数据再整体替换，不会闪一下「正在加载」。
## 7. 实现落点
| 文件 | 职责 |
| --- | --- |
| `features/home/presentation/widgets/submit_site_dialog.dart` | 对话框本体：字段、校验提示、提交按钮 |
| `features/home/data/home_repository.dart` | 契约加一个 `submitSite(...)` |
| `features/home/data/http_home_repository.dart` | 实现：`POST /api/sites`，把后端的中文错误原样抛给界面 |
| `features/home/data/mock_home_repository.dart` | 测试用：记录调用，不真的发请求 |
| `features/home/presentation/pages/home_page.dart` | 「提交网站」按钮改为打开对话框；成功后静默重新取数并提示 |
## 8. 实现与本文的差异
| 本文原写法 | 实际实现 | 原因 |
| --- | --- | --- |
| 失焦时校验 | 提交时统一校验，改动字段时清掉该字段的错误 | 少一套焦点状态，行为对用户更可预期 |
| 底部按钮是「主色胶囊」 | 主色实底 + 8px 圆角 | `index3.html` 的调色板里没有胶囊圆角，侧栏「提交网站」也是 8px |
| 成功提示在页面顶部 | 底部提示条（`SnackBar`） | 复用主题里已经配好的提示条，不新增一套浮层 |
frontend/README.md
+39 -6
View File
@@ -1,11 +1,37 @@
# Navius 前端（Flutter Web） # Navius 前端（Flutter Web）
导航站前端，使用 Flutter 构建。当前目标平台只有 Web，数据全部来自本地 mock， 导航站前端，使用 Flutter 构建。当前目标平台只有 Web，数据来自 Rust 后端
不发起网络请求；后端（Rust）尚未接入。 （`GET /api/nav`）。
界面基准是仓库根目录的 `index3.html`：可折叠的层级侧栏 + 居中的顶部控制栏 界面基准是仓库根目录的 `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 ```bash
@@ -27,12 +53,19 @@ flutter build web # 构建产物输出到 build/web
## 接后端的位置 ## 接后端的位置
页面只依赖仓库接口，不关心数据来自 mock 还是 Rust 后端： 页面只依赖仓库接口，不关心数据来自后端还是本地 mock：
- 首页：`lib/features/home/data/home_repository.dart` - 契约：`lib/features/home/data/home_repository.dart`
- 后端实现：`lib/features/home/data/http_home_repository.dart`
- mock 实现：`lib/features/home/data/mock_home_repository.dart`（测试用）
接入时新增一个实现类，并把 `fetchHomeData` 的返回类型改成 `Future<HomeData>` 即可， 接口对应关系：读 `GET /api/nav`、提交 `POST /api/sites`、编辑 `PATCH /api/sites/{id}`、
`domain/` 与 `presentation/` 基本不需要改动。 删除 `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)。 [docs/frontend-architecture.md](../docs/frontend-architecture.md)。
frontend/lib/app.dart
+7 -7
View File
@@ -2,27 +2,27 @@ import 'package:flutter/material.dart';
import 'core/services/web_url_opener.dart'; import 'core/services/web_url_opener.dart';
import 'core/theme/app_theme.dart'; import 'core/theme/app_theme.dart';
import 'features/home/data/mock_home_repository.dart'; import 'features/home/data/http_home_repository.dart';
import 'features/home/presentation/pages/home_page.dart'; import 'features/home/presentation/pages/home_page.dart';
/// 应用根组件。 /// 应用根组件。
/// ///
/// 只负责三件事：配置全局主题、装配依赖、指定首页。 /// 只负责三件事：配置全局主题、装配依赖、指定首页。
/// 这里是「具体实现」接起来的地方，所以只有它需要知道 /// 这里是「具体实现」接起来的地方，所以只有它需要知道首页数据来自后端：
/// [MockHomeRepository] 与 [WebUrlOpener] 的存在。 /// [HttpHomeRepository] 默认打 `http://127.0.0.1:8080`，
/// 打包时用 `--dart-define=NAVIUS_API_BASE=…` 指向真实地址。
class NaviusApp extends StatelessWidget { class NaviusApp extends StatelessWidget {
const NaviusApp({super.key}); const NaviusApp({super.key});
@override @override
Widget build(BuildContext context) { Widget build(BuildContext context) {
return MaterialApp( return MaterialApp(
// 与 HomeData.siteName 保持一致；接入后端后这一层由接口返回的数据驱动。
title: 'Suxing Nav', title: 'Suxing Nav',
debugShowCheckedModeBanner: false, debugShowCheckedModeBanner: false,
theme: AppTheme.light, theme: AppTheme.light,
home: const HomePage( home: HomePage(
repository: MockHomeRepository(), repository: HttpHomeRepository(),
urlOpener: WebUrlOpener(), urlOpener: const WebUrlOpener(),
), ),
); );
} }
frontend/lib/core/constants/app_sizes.dart
+27
View File
@@ -155,6 +155,33 @@ abstract final class AppSizes {
/// 悬停时上移距离（`translateY(-3px)`）。 /// 悬停时上移距离（`translateY(-3px)`）。
static const double backToTopHoverLift = 3; static const double backToTopHoverLift = 3;
// ---- 通用间距 ----
//
// 上面的常量按「用在哪」命名；表单这类地方间距是通用的，
// 这里给一套通用刻度，避免在组件里写裸数字。
static const double spaceXs = 4;
static const double spaceSm = 8;
static const double spaceMd = 12;
static const double spaceLg = 16;
static const double spaceXl = 24;
// ---- 表单 ----
/// 对话框内边距。
static const double dialogPadding = 24;
/// 对话框最大宽度。
static const double dialogMaxWidth = 480;
/// 字段标签与输入框之间的间距。
static const double fieldLabelGap = 6;
/// 多行输入框高度（3 行）。
static const double fieldMultilineHeight = 88;
/// 对话框右上角关闭按钮的点击热区。
static const double iconButtonSize = 28;
// ---- 通用 ---- // ---- 通用 ----
/// 通用过渡时长（CSS 里的 `transition: 0.2s`）。 /// 通用过渡时长（CSS 里的 `transition: 0.2s`）。
frontend/lib/core/theme/app_colors.dart
+10
View File
@@ -44,6 +44,16 @@ abstract final class AppColors {
/// 搜索框聚焦时的外发光（`0 0 0 3px rgba(59,130,246,.15)`）。 /// 搜索框聚焦时的外发光（`0 0 0 3px rgba(59,130,246,.15)`）。
static const Color focusRing = Color(0x263B82F6); static const Color focusRing = Color(0x263B82F6);
/// 错误色。
///
/// `index3.html` 的调色板里没有红色，但表单的字段错误、失败提示需要一个
/// 明确区别于正文的颜色，所以新增这一个语义令牌——只用在错误提示上，
/// 不参与任何现有视觉。
static const Color danger = Color(0xFFE5484D);
/// 错误色 8% 叠加，用作错误提示条 / 错误输入框的底色。
static const Color dangerFaint = Color(0x14E5484D);
// ---- 阴影 ---- // ---- 阴影 ----
/// 卡片默认阴影（`--shadow`）。 /// 卡片默认阴影（`--shadow`）。
frontend/lib/core/utils/text.dart
+6
View File
@@ -9,3 +9,9 @@ String firstChar(String text, {String fallback = '·'}) {
} }
return String.fromCharCode(text.runes.first); return String.fromCharCode(text.runes.first);
} }
/// 字符数（不是字节数）。
///
/// 和后端 `util::char_count` 的口径一致：先去掉首尾空白，再数字符。
/// 中文一个字算一个，所以「最多 60 个字符」用 `runes.length` 而不是 `length`。
int charCount(String text) => text.trim().runes.length;
frontend/lib/features/home/data/home_repository.dart
+27 -4
View File
@@ -1,13 +1,36 @@
import '../domain/models/home_data.dart'; import '../domain/models/home_data.dart';
import '../domain/models/submit_site_draft.dart';
/// 首页数据仓库契约。 /// 首页数据仓库契约。
/// ///
/// 界面层只认这个接口，不关心数据来自本地 mock 还是 Rust 后端。 /// 界面层只认这个接口，不关心数据来自本地 mock 还是 Rust 后端。
/// ///
/// 目前是同步返回：mock 数据是恒定常量，加一层 Future 只会凭空多出 /// 两个方法都是异步的：接上后端之后「加载中 / 提交中」和「失败」都是必须
/// loading / error 分支。等真正走网络请求时，把返回值改成 /// 表达的状态，所以契约从一开始就按异步来——mock 实现直接返回已经就绪的值。
/// `Future<HomeData>`，改动范围仅限实现类与页面的一次数据加载。
abstract interface class HomeRepository { abstract interface class HomeRepository {
/// 读取首页需要的全部数据。 /// 读取首页需要的全部数据。
HomeData fetchHomeData(); Future<HomeData> fetchHomeData();
/// 提交一个网站。
///
/// 成功不返回内容：后端会回创建出来的条目，但页面用不到（提交完重新拉一次
/// `/api/nav` 就有了）。失败时抛 [HomeFailure]，`message` 可以直接展示。
Future<void> submitSite(SubmitSiteDraft draft);
/// 修改一个已有的网站（只能改用户提交 / 接口推送进来的，系统内置的会返回 403）。
Future<void> updateSite(String id, SubmitSiteDraft draft);
/// 删除一个已有的网站（同样只对可修改的条目有效）。
Future<void> deleteSite(String id);
}
/// 取数或提交失败。[message] 是可以直接显示给用户的说明。
class HomeFailure implements Exception {
const HomeFailure(this.message);
/// 面向用户的说明。
final String message;
@override
String toString() => message;
} }
frontend/lib/features/home/data/http_home_repository.dart
+240
View File
@@ -0,0 +1,240 @@
import 'dart:convert';
import 'package:http/http.dart' as http;
import '../domain/models/home_data.dart';
import '../domain/models/link_item.dart';
import '../domain/models/link_section.dart';
import '../domain/models/nav_node.dart';
import '../domain/models/submit_site_draft.dart';
import 'home_repository.dart';
/// 后端地址。
///
/// 默认指向本机后端，打包时用 `--dart-define=NAVIUS_API_BASE=https://…` 覆盖：
/// `flutter build web --dart-define=NAVIUS_API_BASE=https://api.example.com`
const String _apiBase = String.fromEnvironment(
'NAVIUS_API_BASE',
defaultValue: 'http://127.0.0.1:8080',
);
/// 接口没给站点信息时的兜底值。正常情况下这两个值来自 `GET /api/nav` 的
/// `site` 字段（后端 `data/site.json`）。
const String _fallbackSiteName = 'Suxing Nav';
const String _fallbackSearchHint = '输入关键字搜索全网资源...';
/// 从后端读取首页数据。
class HttpHomeRepository implements HomeRepository {
HttpHomeRepository({String? baseUrl, http.Client? client})
: _baseUrl = baseUrl ?? _apiBase,
_client = client ?? http.Client();
final String _baseUrl;
final http.Client _client;
@override
Future<HomeData> fetchHomeData() async {
final Uri uri = Uri.parse('$_baseUrl/api/nav');
final http.Response response;
try {
response = await _client.get(uri).timeout(const Duration(seconds: 10));
} catch (error) {
throw HomeFailure('连不上后端（$_baseUrl）：$error');
}
if (response.statusCode != 200) {
throw HomeFailure(
'后端返回 ${response.statusCode}：${_errorMessage(response)}',
);
}
final Object? decoded;
try {
decoded = jsonDecode(utf8.decode(response.bodyBytes));
} catch (error) {
throw const HomeFailure('后端返回的不是合法 JSON');
}
if (decoded is! Map<String, dynamic>) {
throw const HomeFailure('后端返回的结构不对：顶层不是对象');
}
final Object? groups = decoded['groups'];
if (groups is! List) {
throw const HomeFailure('后端返回的结构不对：缺少 groups 数组');
}
final Object? rawSite = decoded['site'];
return _toHomeData(
groups,
rawSite is Map<String, dynamic> ? rawSite : const <String, dynamic>{},
);
}
@override
Future<void> submitSite(SubmitSiteDraft draft) async {
final Uri uri = Uri.parse('$_baseUrl/api/sites');
final http.Response response;
try {
response = await _client
.post(
uri,
headers: const <String, String>{
'content-type': 'application/json; charset=utf-8',
},
body: jsonEncode(draft.toJson()),
)
.timeout(const Duration(seconds: 10));
} catch (error) {
throw HomeFailure('连不上后端（$_baseUrl）：$error');
}
if (response.statusCode != 201) {
throw HomeFailure(
'提交失败（${response.statusCode}）：${_errorMessage(response)}',
);
}
}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {
final Uri uri = Uri.parse('$_baseUrl/api/sites/${Uri.encodeComponent(id)}');
final http.Response response;
try {
response = await _client
.patch(
uri,
headers: const <String, String>{
'content-type': 'application/json; charset=utf-8',
},
body: jsonEncode(draft.toJson()),
)
.timeout(const Duration(seconds: 10));
} catch (error) {
throw HomeFailure('连不上后端（$_baseUrl）：$error');
}
if (response.statusCode != 200) {
throw HomeFailure(
'保存失败（${response.statusCode}）：${_errorMessage(response)}',
);
}
}
@override
Future<void> deleteSite(String id) async {
final Uri uri = Uri.parse('$_baseUrl/api/sites/${Uri.encodeComponent(id)}');
final http.Response response;
try {
response = await _client.delete(uri).timeout(const Duration(seconds: 10));
} catch (error) {
throw HomeFailure('连不上后端（$_baseUrl）：$error');
}
if (response.statusCode != 204) {
throw HomeFailure(
'删除失败（${response.statusCode}）：${_errorMessage(response)}',
);
}
}
}
/// 把 `/api/nav` 的响应映射成前端模型。
///
/// 分组直接变成侧栏的导航树；**只有挂着网站的组才会进入内容区**，
/// 空分组只在侧栏里当导航项——这与原型里那几个没有内容的锚点一致。
HomeData _toHomeData(List<Object?> groups, Map<String, dynamic> siteMeta) {
final List<NavNode> navNodes = <NavNode>[];
final List<LinkSection> sections = <LinkSection>[];
for (final Object? group in groups) {
if (group is Map<String, dynamic>) {
navNodes.add(_navNode(group, parentTitle: '', sections: sections));
}
}
return HomeData(
siteName: siteMeta['name'] as String? ?? _fallbackSiteName,
searchHint: siteMeta['searchHint'] as String? ?? _fallbackSearchHint,
navNodes: navNodes,
sections: sections,
);
}
NavNode _navNode(
Map<String, dynamic> json, {
required String parentTitle,
required List<LinkSection> sections,
}) {
final String id = json['id'] as String? ?? '';
final String title = json['title'] as String? ?? '';
// 子分组在内容区的标题带上父级（「素材资源 - UI 设计」），
// 侧栏里仍然只显示「UI 设计」——和原型一致。
final String sectionTitle = parentTitle.isEmpty
? title
: '$parentTitle - $title';
final List<LinkItem> sites = _sites(json);
if (sites.isNotEmpty && id.isNotEmpty) {
sections.add(LinkSection(id: id, title: sectionTitle, items: sites));
}
final List<NavNode> children = <NavNode>[];
final Object? rawChildren = json['children'];
if (rawChildren is List) {
for (final Object? child in rawChildren) {
if (child is Map<String, dynamic>) {
children.add(
_navNode(child, parentTitle: title, sections: sections),
);
}
}
}
return NavNode(
id: id,
title: title,
children: children,
// 后端给了 editable；缺省按内置处理（内置不可选）。
editable: json['editable'] as bool? ?? false,
);
}
List<LinkItem> _sites(Map<String, dynamic> json) {
final Object? raw = json['sites'];
if (raw is! List) {
return const <LinkItem>[];
}
final List<LinkItem> items = <LinkItem>[];
for (final Object? site in raw) {
if (site is! Map<String, dynamic>) {
continue;
}
final String id = site['id'] as String? ?? '';
final String title = site['title'] as String? ?? '';
final String url = site['url'] as String? ?? '';
if (id.isEmpty || title.isEmpty || url.isEmpty) {
// 缺字段的条目直接跳过：后端已经校验过，这里只是不想让一条坏数据
// 把整个页面打挂。
continue;
}
items.add(
LinkItem(
id: id,
title: title,
url: url,
categoryId: site['categoryId'] as String? ?? '',
description: site['description'] as String? ?? '',
editable: site['editable'] as bool? ?? false,
),
);
}
return items;
}
/// 后端出错时统一返回 `{"error":"…"}`，能取到就显示那句话。
///
/// 用 `bodyBytes` 自己按 UTF-8 解，而不是 `response.body`：后者在响应没带
/// charset 时会退回 latin1，中文会变成乱码。
String _errorMessage(http.Response response) {
final String body = utf8.decode(response.bodyBytes, allowMalformed: true);
try {
final Object? decoded = jsonDecode(body);
if (decoded is Map<String, dynamic> && decoded['error'] is String) {
return decoded['error'] as String;
}
} catch (_) {
// 不是 JSON 就退回原文。
}
return body.isEmpty ? '没有返回内容' : body;
}
frontend/lib/features/home/data/mock_home_repository.dart
+13 -1
View File
@@ -1,4 +1,5 @@
import '../domain/models/home_data.dart'; import '../domain/models/home_data.dart';
import '../domain/models/submit_site_draft.dart';
import 'home_repository.dart'; import 'home_repository.dart';
import 'mock_home_data.dart'; import 'mock_home_data.dart';
@@ -10,5 +11,16 @@ class MockHomeRepository implements HomeRepository {
const MockHomeRepository(); const MockHomeRepository();
@override @override
HomeData fetchHomeData() => mockHomeData; Future<HomeData> fetchHomeData() async => mockHomeData;
@override
Future<void> submitSite(SubmitSiteDraft draft) async {
// mock 实现什么都不做：需要断言提交内容的用例会注入自己的假实现。
}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {}
@override
Future<void> deleteSite(String id) async {}
} }
frontend/lib/features/home/domain/models/link_item.dart
+20 -2
View File
@@ -6,7 +6,9 @@ class LinkItem {
required this.id, required this.id,
required this.title, required this.title,
required this.url, required this.url,
this.categoryId = '',
this.description = '', this.description = '',
this.editable = false,
}); });
/// 从 JSON 构造（将来接后端接口时使用）。 /// 从 JSON 构造（将来接后端接口时使用）。
@@ -15,7 +17,9 @@ class LinkItem {
id: json['id'] as String, id: json['id'] as String,
title: json['title'] as String, title: json['title'] as String,
url: json['url'] as String, url: json['url'] as String,
categoryId: json['categoryId'] as String? ?? '',
description: json['description'] as String? ?? '', description: json['description'] as String? ?? '',
editable: json['editable'] as bool? ?? false,
); );
} }
@@ -28,9 +32,18 @@ class LinkItem {
/// 跳转地址。 /// 跳转地址。
final String url; final String url;
/// 所属分组 id。编辑时要靠它反查出分组名，才能把表单预填对。
final String categoryId;
/// 一句话描述。 /// 一句话描述。
final String description; final String description;
/// 这条能不能改。
///
/// 后端按 `source != "system"` 推导出 `editable`：系统内置的条目只读，
/// 卡片上不会出现编辑/删除；用户提交和接口推送进来的可以改、可以删。
final bool editable;
/// 卡片图标显示的首字符。 /// 卡片图标显示的首字符。
String get initial => firstChar(title).toUpperCase(); String get initial => firstChar(title).toUpperCase();
@@ -42,7 +55,9 @@ class LinkItem {
'id': id, 'id': id,
'title': title, 'title': title,
'url': url, 'url': url,
'categoryId': categoryId,
'description': description, 'description': description,
'editable': editable,
}; };
@override @override
@@ -52,11 +67,14 @@ class LinkItem {
other.id == id && other.id == id &&
other.title == title && other.title == title &&
other.url == url && other.url == url &&
other.description == description; other.categoryId == categoryId &&
other.description == description &&
other.editable == editable;
} }
@override @override
int get hashCode => Object.hash(id, title, url, description); int get hashCode =>
Object.hash(id, title, url, categoryId, description, editable);
@override @override
String toString() => 'LinkItem(id: $id, title: $title)'; String toString() => 'LinkItem(id: $id, title: $title)';
frontend/lib/features/home/domain/models/nav_node.dart
+7
View File
@@ -10,6 +10,7 @@ class NavNode {
required this.id, required this.id,
required this.title, required this.title,
this.children = const <NavNode>[], this.children = const <NavNode>[],
this.editable = false,
}); });
/// 唯一标识；叶子节点同时也是内容区的锚点 id。 /// 唯一标识；叶子节点同时也是内容区的锚点 id。
@@ -21,6 +22,12 @@ class NavNode {
/// 子节点；为空表示这是一个直接跳转的条目。 /// 子节点；为空表示这是一个直接跳转的条目。
final List<NavNode> children; final List<NavNode> children;
/// 这个分组是不是用户创建的（后端返回的 `editable`）。
///
/// 提交表单据此给出「已有的用户分组」建议：内置分组不可选，
/// 因为提交的内容永远进不了内置分组。
final bool editable;
/// 是否是可展开的分组。 /// 是否是可展开的分组。
bool get isGroup => children.isNotEmpty; bool get isGroup => children.isNotEmpty;
frontend/lib/features/home/domain/models/submit_site_draft.dart
+42
View File
@@ -0,0 +1,42 @@
/// 提交一个网站时填的内容。
///
/// 和后端 `POST /api/sites` 的入参一一对应。**没有 `categoryId`**：
/// 提交方只能给分组名，由后端在用户分组里查找或新建。
class SubmitSiteDraft {
const SubmitSiteDraft({
required this.title,
required this.url,
required this.group,
this.description = '',
this.subGroup = '',
this.submittedBy = '',
});
/// 网站名称。
final String title;
/// 网站地址。
final String url;
/// 一级分组名。
final String group;
/// 一句话描述。
final String description;
/// 子分组名，可为空。
final String subGroup;
/// 提交者的称呼或邮箱。
final String submittedBy;
/// 序列化成后端要的 JSON（camelCase，和后端 `CreateSiteRequest` 对齐）。
Map<String, dynamic> toJson() => <String, dynamic>{
'title': title,
'url': url,
'description': description,
'group': group,
'subGroup': subGroup,
'submittedBy': submittedBy,
};
}
frontend/lib/features/home/presentation/pages/home_page.dart
+278 -27
View File
@@ -5,21 +5,24 @@ import 'package:flutter/material.dart';
import '../../../../core/constants/app_sizes.dart'; import '../../../../core/constants/app_sizes.dart';
import '../../../../core/services/url_opener.dart'; import '../../../../core/services/url_opener.dart';
import '../../../../core/theme/app_colors.dart'; import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart';
import '../../data/home_repository.dart'; import '../../data/home_repository.dart';
import '../../domain/models/home_data.dart'; import '../../domain/models/home_data.dart';
import '../../domain/models/link_item.dart'; import '../../domain/models/link_item.dart';
import '../../domain/models/link_section.dart'; import '../../domain/models/link_section.dart';
import '../../domain/models/nav_node.dart';
import '../../domain/models/submit_site_draft.dart';
import '../widgets/back_to_top_button.dart'; import '../widgets/back_to_top_button.dart';
import '../widgets/confirm_dialog.dart';
import '../widgets/link_section_view.dart'; import '../widgets/link_section_view.dart';
import '../widgets/sidebar_nav.dart'; import '../widgets/sidebar_nav.dart';
import '../widgets/site_form_dialog.dart';
import '../widgets/top_bar.dart'; import '../widgets/top_bar.dart';
/// 首页：可折叠侧栏 + 顶部控制栏 + 分组卡片网格。 /// 首页：可折叠侧栏 + 顶部控制栏 + 分组卡片网格。
/// ///
/// 完全按项目根目录的 `index3.html` 还原：结构、样式、交互都以那份文件为准， /// 数据来自后端 `GET /api/nav`，所以页面要表达三种状态：加载中、加载失败
/// 不额外增加原型里没有的行为。原型里没有的东西也照样不实现—— /// （带重试）、加载完成。布局与交互仍然以项目根目录的 `index3.html` 为准。
/// 搜索框不参与过滤（原型没有对应脚本）、`active` 固定写在第一个导航条目上、
/// 没有对应锚点的导航项点击后不会有任何反应。
class HomePage extends StatefulWidget { class HomePage extends StatefulWidget {
const HomePage({ const HomePage({
super.key, super.key,
@@ -27,7 +30,7 @@ class HomePage extends StatefulWidget {
required this.urlOpener, required this.urlOpener,
}); });
/// 数据来源（当前是 mock 实现）。 /// 数据来源（当前是 HTTP 实现，测试里注入 mock）。
final HomeRepository repository; final HomeRepository repository;
/// 打开链接的能力（当前是 Web 实现）。 /// 打开链接的能力（当前是 Web 实现）。
@@ -38,13 +41,12 @@ class HomePage extends StatefulWidget {
} }
class _HomePageState extends State<HomePage> { class _HomePageState extends State<HomePage> {
/// 首页数据只在初始化时取一次。 HomeData? _data;
late final HomeData _data = widget.repository.fetchHomeData(); String? _error;
bool _loading = true;
/// 有对应锚点的分区，用于「点导航滚动过去」。 /// 有对应分区的分组，用于「点导航滚动过去」；数据到了之后才建。
late final Map<String, GlobalKey> _sectionKeys = <String, GlobalKey>{ Map<String, GlobalKey> _sectionKeys = <String, GlobalKey>{};
for (final LinkSection section in _data.sections) section.id: GlobalKey(),
};
final ScrollController _scrollController = ScrollController(); final ScrollController _scrollController = ScrollController();
final TextEditingController _searchController = TextEditingController(); final TextEditingController _searchController = TextEditingController();
@@ -55,6 +57,12 @@ class _HomePageState extends State<HomePage> {
/// 侧栏是否折叠。原型初始是展开的（body 上没有 sidebar-collapsed）。 /// 侧栏是否折叠。原型初始是展开的（body 上没有 sidebar-collapsed）。
bool _collapsed = false; bool _collapsed = false;
@override
void initState() {
super.initState();
unawaited(_load());
}
@override @override
void dispose() { void dispose() {
_scrollController.dispose(); _scrollController.dispose();
@@ -62,6 +70,48 @@ class _HomePageState extends State<HomePage> {
super.dispose(); super.dispose();
} }
/// 向后端取一次数据。失败时把说明留在 `_error` 里给用户看，并允许重试。
///
/// [showLoading] 为 false 时是「静默刷新」：页面继续显示旧内容，
/// 失败了只提示一句，不会把已经渲染好的页面换成错误页。
Future<void> _load({bool showLoading = true}) async {
if (showLoading) {
setState(() {
_loading = true;
_error = null;
});
}
try {
final HomeData data = await widget.repository.fetchHomeData();
if (!mounted) {
return;
}
setState(() {
_data = data;
_loading = false;
_error = null;
_sectionKeys = <String, GlobalKey>{
for (final LinkSection section in data.sections)
section.id: GlobalKey(),
};
});
} catch (error) {
if (!mounted) {
return;
}
if (showLoading) {
setState(() {
_loading = false;
_error = error.toString();
});
} else {
ScaffoldMessenger.of(
context,
).showSnackBar(SnackBar(content: Text('刷新失败：$error')));
}
}
}
// ---- 交互 ---- // ---- 交互 ----
/// `#toggleBtn`：切换 `sidebar-collapsed`。 /// `#toggleBtn`：切换 `sidebar-collapsed`。
@@ -83,10 +133,10 @@ class _HomePageState extends State<HomePage> {
}); });
} }
/// 点导航叶子：滚到对应锚点。 /// 点导航叶子：滚到对应分区。
/// ///
/// 原型里 `#icon`、`#stock`、`#dev`、`#api` 没有对应元素， /// 后端允许存在没有网站的分组，这类分组在内容区没有对应元素，
/// 对应 `<a href="#...">` 点了不会有任何反应，这里保持一致。 /// 点了不会有任何反应——和原型里那几个空锚点一致。
void _goToSection(String sectionId) { void _goToSection(String sectionId) {
final BuildContext? sectionContext = _sectionKeys[sectionId]?.currentContext; final BuildContext? sectionContext = _sectionKeys[sectionId]?.currentContext;
if (sectionContext == null) { if (sectionContext == null) {
@@ -103,6 +153,102 @@ class _HomePageState extends State<HomePage> {
void _openItem(LinkItem item) => widget.urlOpener.open(item.url); void _openItem(LinkItem item) => widget.urlOpener.open(item.url);
/// 打开「提交网站」表单；提交成功后静默刷新一次，让新站点立刻出现在侧栏里。
Future<void> _openSubmitDialog(HomeData data) async {
final bool saved = await showSiteFormDialog(
context: context,
navNodes: data.navNodes,
heading: '提交网站',
onSubmit: (SubmitSiteDraft draft) => widget.repository.submitSite(draft),
);
if (!saved || !mounted) {
return;
}
_toast('已提交，感谢');
await _load(showLoading: false);
}
/// 编辑一个用户提交的站点：表单预填现有内容，保存走 `PATCH /api/sites/{id}`。
Future<void> _openEditDialog(HomeData data, LinkItem item) async {
final ({String group, String subGroup})? path = _groupPathOf(
data.navNodes,
item.categoryId,
);
final bool saved = await showSiteFormDialog(
context: context,
navNodes: data.navNodes,
heading: '编辑网站',
initial: SubmitSiteDraft(
title: item.title,
url: item.url,
description: item.description,
group: path?.group ?? '',
subGroup: path?.subGroup ?? '',
),
onSubmit: (SubmitSiteDraft draft) =>
widget.repository.updateSite(item.id, draft),
);
if (!saved || !mounted) {
return;
}
_toast('已保存');
await _load(showLoading: false);
}
/// 删除一个用户提交的站点：先确认，再走 `DELETE /api/sites/{id}`。
Future<void> _confirmDelete(LinkItem item) async {
final bool confirmed = await showConfirmDialog(
context: context,
title: '删除网站',
message: '确定要删除「${item.title}」吗？删掉之后不能恢复。',
confirmLabel: '删除',
danger: true,
);
if (!confirmed || !mounted) {
return;
}
try {
await widget.repository.deleteSite(item.id);
} catch (error) {
if (mounted) {
_toast('删除失败：$error');
}
return;
}
if (!mounted) {
return;
}
_toast('已删除');
await _load(showLoading: false);
}
void _toast(String message) {
ScaffoldMessenger.of(
context,
).showSnackBar(SnackBar(content: Text(message)));
}
/// 从侧栏树里反查某个分组 id 的「一级分组 + 子分组」名字。
///
/// 后端只按分组名收更新，所以编辑时必须把 id 还原成名字；
/// 层级最多两级，这里只查两轮。
({String group, String subGroup})? _groupPathOf(
List<NavNode> nodes,
String categoryId,
) {
for (final NavNode root in nodes) {
if (root.id == categoryId) {
return (group: root.title, subGroup: '');
}
for (final NavNode child in root.children) {
if (child.id == categoryId) {
return (group: root.title, subGroup: child.title);
}
}
}
return null;
}
void _backToTop() { void _backToTop() {
_scrollController.animateTo( _scrollController.animateTo(
0, 0,
@@ -117,26 +263,40 @@ class _HomePageState extends State<HomePage> {
Widget build(BuildContext context) { Widget build(BuildContext context) {
return Scaffold( return Scaffold(
backgroundColor: AppColors.background, backgroundColor: AppColors.background,
body: Stack( body: _buildBody(),
);
}
Widget _buildBody() {
if (_loading) {
return const _StatusView(message: '正在加载…', loading: true);
}
final String? error = _error;
if (error != null) {
return _StatusView(title: '加载失败', message: error, onRetry: _load);
}
return _buildLoaded(_data!);
}
Widget _buildLoaded(HomeData data) {
return Stack(
children: <Widget>[ children: <Widget>[
Row( Row(
crossAxisAlignment: CrossAxisAlignment.stretch, crossAxisAlignment: CrossAxisAlignment.stretch,
children: <Widget>[ children: <Widget>[
SidebarNav( SidebarNav(
siteName: _data.siteName, siteName: data.siteName,
navNodes: _data.navNodes, navNodes: data.navNodes,
// 原型把 active 写死在第一个条目上，切换页面也不变。 // 原型把 active 写死在第一个条目上。
activeSectionId: _data.activeSectionId, activeSectionId: data.activeSectionId,
collapsed: _collapsed, collapsed: _collapsed,
openGroupIds: _openGroupIds, openGroupIds: _openGroupIds,
onToggleGroup: _toggleGroup, onToggleGroup: _toggleGroup,
onSectionSelected: _goToSection, onSectionSelected: _goToSection,
// 原型指向不存在的 #submit，点了没有任何反应。 onSubmitSite: () => unawaited(_openSubmitDialog(data)),
onSubmitSite: () {},
// 补上这行，将页面的切换折叠方法传进去
onToggleCollapse: _toggleSidebar, onToggleCollapse: _toggleSidebar,
), ),
Expanded(child: _buildMain()), Expanded(child: _buildMain(data)),
], ],
), ),
Positioned( Positioned(
@@ -145,11 +305,10 @@ class _HomePageState extends State<HomePage> {
child: BackToTopButton(onTap: _backToTop), child: BackToTopButton(onTap: _backToTop),
), ),
], ],
),
); );
} }
Widget _buildMain() { Widget _buildMain(HomeData data) {
return SingleChildScrollView( return SingleChildScrollView(
controller: _scrollController, controller: _scrollController,
padding: const EdgeInsets.fromLTRB( padding: const EdgeInsets.fromLTRB(
@@ -163,11 +322,11 @@ class _HomePageState extends State<HomePage> {
children: <Widget>[ children: <Widget>[
TopBar( TopBar(
searchController: _searchController, searchController: _searchController,
searchHint: _data.searchHint, searchHint: data.searchHint,
sidebarCollapsed: _collapsed, sidebarCollapsed: _collapsed,
onToggleSidebar: _toggleSidebar, onToggleSidebar: _toggleSidebar,
), ),
for (final LinkSection section in _data.sections) for (final LinkSection section in data.sections)
Padding( Padding(
// 原型里每个 .grid 都带 margin-bottom: 36px。 // 原型里每个 .grid 都带 margin-bottom: 36px。
padding: const EdgeInsets.only(bottom: AppSizes.sectionGap), padding: const EdgeInsets.only(bottom: AppSizes.sectionGap),
@@ -175,6 +334,9 @@ class _HomePageState extends State<HomePage> {
key: _sectionKeys[section.id], key: _sectionKeys[section.id],
section: section, section: section,
onOpen: _openItem, onOpen: _openItem,
onEdit: (LinkItem item) =>
unawaited(_openEditDialog(data, item)),
onDelete: (LinkItem item) => unawaited(_confirmDelete(item)),
), ),
), ),
], ],
@@ -182,3 +344,92 @@ class _HomePageState extends State<HomePage> {
); );
} }
} }
/// 加载中 / 加载失败时占满内容区的提示。
class _StatusView extends StatelessWidget {
const _StatusView({
required this.message,
this.title,
this.loading = false,
this.onRetry,
});
final String message;
final String? title;
final bool loading;
final VoidCallback? onRetry;
@override
Widget build(BuildContext context) {
return Center(
child: Padding(
padding: const EdgeInsets.all(AppSizes.contentPaddingHorizontal),
child: Column(
mainAxisSize: MainAxisSize.min,
children: <Widget>[
if (loading) ...<Widget>[
const SizedBox(
width: 20,
height: 20,
child: CircularProgressIndicator(strokeWidth: 2),
),
const SizedBox(height: AppSizes.gridGap),
],
if (title != null) ...<Widget>[
Text(title!, style: AppTextStyles.emptyTitle),
const SizedBox(height: 6),
],
Text(
message,
style: AppTextStyles.emptyMessage,
textAlign: TextAlign.center,
),
if (onRetry != null) ...<Widget>[
const SizedBox(height: AppSizes.gridGap),
_RetryButton(onTap: onRetry!),
],
],
),
),
);
}
}
/// 「重试」按钮：跟前端其它次级按钮同一套描边样式。
class _RetryButton extends StatefulWidget {
const _RetryButton({required this.onTap});
final VoidCallback onTap;
@override
State<_RetryButton> createState() => _RetryButtonState();
}
class _RetryButtonState extends State<_RetryButton> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
return MouseRegion(
cursor: SystemMouseCursors.click,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
decoration: BoxDecoration(
color: _hovered ? AppColors.primaryFaint : Colors.transparent,
border: Border.all(color: AppColors.primary),
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
'重试',
style: AppTextStyles.navItem.copyWith(color: AppColors.primary),
),
),
),
);
}
}
frontend/lib/features/home/presentation/widgets/confirm_dialog.dart
+91
View File
@@ -0,0 +1,91 @@
import 'package:flutter/material.dart';
import '../../../../core/constants/app_sizes.dart';
import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart';
import 'dialog_buttons.dart';
/// 通用确认框，返回 true 表示用户点了确认。
///
/// [danger] 为 true 时确认按钮用错误色，用在删除这类不可逆操作上。
Future<bool> showConfirmDialog({
required BuildContext context,
required String title,
required String message,
required String confirmLabel,
String cancelLabel = '取消',
bool danger = false,
}) async {
final bool? confirmed = await showDialog<bool>(
context: context,
barrierColor: const Color(0x73111827),
builder: (BuildContext context) => _ConfirmDialog(
title: title,
message: message,
confirmLabel: confirmLabel,
cancelLabel: cancelLabel,
danger: danger,
),
);
return confirmed ?? false;
}
class _ConfirmDialog extends StatelessWidget {
const _ConfirmDialog({
required this.title,
required this.message,
required this.confirmLabel,
required this.cancelLabel,
required this.danger,
});
final String title;
final String message;
final String confirmLabel;
final String cancelLabel;
final bool danger;
@override
Widget build(BuildContext context) {
return Dialog(
backgroundColor: Colors.transparent,
elevation: 0,
insetPadding: const EdgeInsets.all(AppSizes.dialogPadding),
child: Container(
constraints: const BoxConstraints(maxWidth: 360),
decoration: BoxDecoration(
color: AppColors.surface,
border: Border.all(color: AppColors.border),
borderRadius: BorderRadius.circular(AppSizes.cardRadius),
boxShadow: AppColors.cardShadowHover,
),
padding: const EdgeInsets.all(AppSizes.dialogPadding),
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Text(title, style: AppTextStyles.sectionTitle),
const SizedBox(height: AppSizes.spaceSm),
Text(message, style: AppTextStyles.emptyMessage),
const SizedBox(height: AppSizes.spaceXl),
Row(
mainAxisAlignment: MainAxisAlignment.end,
children: <Widget>[
DialogGhostButton(
label: cancelLabel,
onTap: () => Navigator.of(context).pop(false),
),
const SizedBox(width: AppSizes.spaceMd),
DialogPrimaryButton(
label: confirmLabel,
danger: danger,
onTap: () => Navigator.of(context).pop(true),
),
],
),
],
),
),
);
}
}
frontend/lib/features/home/presentation/widgets/dialog_buttons.dart
+117
View File
@@ -0,0 +1,117 @@
import 'package:flutter/material.dart';
import '../../../../core/constants/app_sizes.dart';
import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart';
/// 对话框里的主按钮：实底、8px 圆角（和侧栏「提交网站」一致）。
///
/// [danger] 为 true 时用错误色，用在「删除」这类不可逆操作上。
class DialogPrimaryButton extends StatefulWidget {
const DialogPrimaryButton({
super.key,
required this.label,
required this.onTap,
this.danger = false,
});
/// 按钮文字。
final String label;
/// 点击回调；为 null 表示禁用。
final VoidCallback? onTap;
/// 是否用错误色（删除类操作）。
final bool danger;
@override
State<DialogPrimaryButton> createState() => _DialogPrimaryButtonState();
}
class _DialogPrimaryButtonState extends State<DialogPrimaryButton> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
final bool enabled = widget.onTap != null;
final Color background = widget.danger
? AppColors.danger
: AppColors.primary;
return MouseRegion(
cursor: enabled ? SystemMouseCursors.click : SystemMouseCursors.basic,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
padding: const EdgeInsets.symmetric(
horizontal: AppSizes.cardPaddingHorizontal,
vertical: 10,
),
decoration: BoxDecoration(
color: enabled ? background : AppColors.border,
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
widget.label,
style: AppTextStyles.submitButton.copyWith(
color: enabled ? AppColors.surface : AppColors.textSecondary,
fontWeight: _hovered ? FontWeight.w600 : FontWeight.w500,
),
),
),
),
);
}
}
/// 对话框里的次级按钮：描边、透明底。
class DialogGhostButton extends StatefulWidget {
const DialogGhostButton({super.key, required this.label, required this.onTap});
/// 按钮文字。
final String label;
/// 点击回调；为 null 表示禁用。
final VoidCallback? onTap;
@override
State<DialogGhostButton> createState() => _DialogGhostButtonState();
}
class _DialogGhostButtonState extends State<DialogGhostButton> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
final bool enabled = widget.onTap != null;
return MouseRegion(
cursor: enabled ? SystemMouseCursors.click : SystemMouseCursors.basic,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
padding: const EdgeInsets.symmetric(
horizontal: AppSizes.cardPaddingHorizontal,
vertical: 9,
),
decoration: BoxDecoration(
color: _hovered ? AppColors.primaryFaint : Colors.transparent,
border: Border.all(color: AppColors.border),
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
widget.label,
style: AppTextStyles.submitButton.copyWith(
color: enabled ? AppColors.textSecondary : AppColors.navArrow,
),
),
),
),
);
}
}
frontend/lib/features/home/presentation/widgets/link_card.dart
+119 -3
View File
@@ -5,11 +5,19 @@ import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart'; import '../../../../core/theme/app_text_styles.dart';
import '../../domain/models/link_item.dart'; import '../../domain/models/link_item.dart';
/// 站点卡片，对应 `index.html` 里的 `.card`。 /// 站点卡片，对应 `index3.html` 里的 `.card`。
/// ///
/// 结构是「36px 的字母方块 + 名称 + 描述」，悬停时上移 2px 并加强阴影。 /// 结构是「36px 的字母方块 + 名称 + 描述」，悬停时上移 2px 并加强阴影。
/// 用户提交 / 接口推送进来的条目（`item.editable`）在悬停时右上角会露出
/// 「编辑 / 删除」；系统内置的条目没有这两个按钮——后端也不允许改。
class LinkCard extends StatefulWidget { class LinkCard extends StatefulWidget {
const LinkCard({super.key, required this.item, required this.onOpen}); const LinkCard({
super.key,
required this.item,
required this.onOpen,
this.onEdit,
this.onDelete,
});
/// 站点数据。 /// 站点数据。
final LinkItem item; final LinkItem item;
@@ -17,6 +25,12 @@ class LinkCard extends StatefulWidget {
/// 打开回调。 /// 打开回调。
final VoidCallback onOpen; final VoidCallback onOpen;
/// 编辑回调；为空或条目不可修改时不显示编辑按钮。
final VoidCallback? onEdit;
/// 删除回调；为空或条目不可修改时不显示删除按钮。
final VoidCallback? onDelete;
@override @override
State<LinkCard> createState() => _LinkCardState(); State<LinkCard> createState() => _LinkCardState();
} }
@@ -26,6 +40,8 @@ class _LinkCardState extends State<LinkCard> {
@override @override
Widget build(BuildContext context) { Widget build(BuildContext context) {
final bool canManage = widget.item.editable;
return MouseRegion( return MouseRegion(
cursor: SystemMouseCursors.click, cursor: SystemMouseCursors.click,
onEnter: (_) => setState(() => _hovered = true), onEnter: (_) => setState(() => _hovered = true),
@@ -53,7 +69,9 @@ class _LinkCardState extends State<LinkCard> {
? AppColors.cardShadowHover ? AppColors.cardShadowHover
: AppColors.cardShadow, : AppColors.cardShadow,
), ),
child: Row( child: Stack(
children: <Widget>[
Row(
children: <Widget>[ children: <Widget>[
_CardIcon(initial: widget.item.initial), _CardIcon(initial: widget.item.initial),
const SizedBox(width: AppSizes.cardIconGap), const SizedBox(width: AppSizes.cardIconGap),
@@ -80,6 +98,104 @@ class _LinkCardState extends State<LinkCard> {
), ),
], ],
), ),
// 悬停才露出来，且不占正文的位置：不给可修改的卡片留常驻空白，
// 也不让鼠标移上去时文字宽度跳一下。
if (canManage)
Positioned(
right: 0,
top: 0,
child: AnimatedOpacity(
duration: AppSizes.transition,
opacity: _hovered ? 1 : 0,
child: Row(
mainAxisSize: MainAxisSize.min,
children: <Widget>[
if (widget.onEdit != null)
_CardAction(
icon: '✎',
tooltip: '编辑',
background: AppColors.surface,
onTap: widget.onEdit!,
),
if (widget.onEdit != null && widget.onDelete != null)
const SizedBox(width: AppSizes.spaceXs),
if (widget.onDelete != null)
_CardAction(
icon: '✕',
tooltip: '删除',
background: AppColors.surface,
danger: true,
onTap: widget.onDelete!,
),
],
),
),
),
],
),
),
),
);
}
}
/// 卡片右上角的小动作按钮（编辑 / 删除）。
class _CardAction extends StatefulWidget {
const _CardAction({
required this.icon,
required this.tooltip,
required this.background,
required this.onTap,
this.danger = false,
});
final String icon;
final String tooltip;
final Color background;
final VoidCallback onTap;
final bool danger;
@override
State<_CardAction> createState() => _CardActionState();
}
class _CardActionState extends State<_CardAction> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
final Color foreground = _hovered
? (widget.danger ? AppColors.danger : AppColors.primary)
: AppColors.navArrow;
return Tooltip(
message: widget.tooltip,
child: MouseRegion(
cursor: SystemMouseCursors.click,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
// 只处理自己的点击，不要让卡片把事件吃掉（否则会去打开网站）。
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
width: AppSizes.iconButtonSize,
height: AppSizes.iconButtonSize,
alignment: Alignment.center,
decoration: BoxDecoration(
color: _hovered
? (widget.danger
? AppColors.dangerFaint
: AppColors.primaryFaint)
: widget.background,
border: Border.all(color: AppColors.border),
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
widget.icon,
style: AppTextStyles.cardDesc.copyWith(color: foreground),
),
),
), ),
), ),
); );
frontend/lib/features/home/presentation/widgets/link_search_field.dart
+15 -14
View File
@@ -5,12 +5,6 @@ import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart'; import '../../../../core/theme/app_text_styles.dart';
/// 搜索框。 /// 搜索框。
///
/// 对应 `index3.html` 的 `.search-box`：固定 44px 高、白色底、1px 描边、
/// 12px 圆角，聚焦时边框变主色并外扩 3px 的浅色光晕。
///
/// 用 [FocusNode] 而不是 `InputDecoration` 的 `focusedBorder`：
/// 那条光晕是「向外扩散」的矩形阴影，靠边框宽度画不出来。
class LinkSearchField extends StatefulWidget { class LinkSearchField extends StatefulWidget {
const LinkSearchField({ const LinkSearchField({
super.key, super.key,
@@ -18,10 +12,7 @@ class LinkSearchField extends StatefulWidget {
required this.hintText, required this.hintText,
}); });
/// 文本控制器。
final TextEditingController controller; final TextEditingController controller;
/// 占位文案。
final String hintText; final String hintText;
@override @override
@@ -54,9 +45,12 @@ class _LinkSearchFieldState extends State<LinkSearchField> {
@override @override
Widget build(BuildContext context) { Widget build(BuildContext context) {
return AnimatedContainer( return GestureDetector(
// 输入框只占中间一行的高度，点上下留白也让它聚焦——
// 原型里整个 44px 高的盒子就是一个 <input>。
onTap: _focusNode.requestFocus,
child: AnimatedContainer(
duration: AppSizes.transition, duration: AppSizes.transition,
// `.search-box { transition: border-color .2s, box-shadow .2s }`。
curve: Curves.ease, curve: Curves.ease,
height: AppSizes.searchHeight, height: AppSizes.searchHeight,
padding: const EdgeInsets.symmetric( padding: const EdgeInsets.symmetric(
@@ -68,8 +62,6 @@ class _LinkSearchFieldState extends State<LinkSearchField> {
color: _focused ? AppColors.primary : AppColors.border, color: _focused ? AppColors.primary : AppColors.border,
), ),
borderRadius: BorderRadius.circular(AppSizes.searchRadius), borderRadius: BorderRadius.circular(AppSizes.searchRadius),
// 原型 `.search-box:focus` 的 box-shadow 会整体覆盖掉默认阴影，
// 聚焦时只剩这一圈光晕，不是「默认阴影 + 光晕」。
boxShadow: <BoxShadow>[ boxShadow: <BoxShadow>[
if (_focused) if (_focused)
const BoxShadow(color: AppColors.focusRing, spreadRadius: 3) const BoxShadow(color: AppColors.focusRing, spreadRadius: 3)
@@ -77,12 +69,19 @@ class _LinkSearchFieldState extends State<LinkSearchField> {
...AppColors.cardShadow, ...AppColors.cardShadow,
], ],
), ),
// 垂直居中不要靠固定的 contentPadding。
// 那个写法只在「字体行高 + 上下 padding 正好等于内容区高度」时成立，
// 换一个字体（浏览器里的系统字体行高通常更高）就会被挤偏。
// 这里让 TextField 按自身行高确定高度，再用 Align 把这一行放进
// 44px 的内容区里居中——和浏览器渲染单行 <input> 的方式一致，
// 与字体行高无关。
child: Align(
alignment: Alignment.centerLeft,
child: TextField( child: TextField(
controller: widget.controller, controller: widget.controller,
focusNode: _focusNode, focusNode: _focusNode,
style: AppTextStyles.searchInput, style: AppTextStyles.searchInput,
cursorColor: AppColors.primary, cursorColor: AppColors.primary,
textAlignVertical: TextAlignVertical.center,
textInputAction: TextInputAction.search, textInputAction: TextInputAction.search,
decoration: InputDecoration( decoration: InputDecoration(
isDense: true, isDense: true,
@@ -92,6 +91,8 @@ class _LinkSearchFieldState extends State<LinkSearchField> {
hintStyle: AppTextStyles.searchHint, hintStyle: AppTextStyles.searchHint,
), ),
), ),
),
),
); );
} }
} }
frontend/lib/features/home/presentation/widgets/link_section_view.dart
+14 -1
View File
@@ -14,6 +14,8 @@ class LinkSectionView extends StatelessWidget {
super.key, super.key,
required this.section, required this.section,
required this.onOpen, required this.onOpen,
this.onEdit,
this.onDelete,
}); });
/// 分组数据。 /// 分组数据。
@@ -22,6 +24,12 @@ class LinkSectionView extends StatelessWidget {
/// 打开某个站点。 /// 打开某个站点。
final ValueChanged<LinkItem> onOpen; final ValueChanged<LinkItem> onOpen;
/// 编辑某个站点；为空时卡片不显示编辑入口。
final ValueChanged<LinkItem>? onEdit;
/// 删除某个站点；为空时卡片不显示删除入口。
final ValueChanged<LinkItem>? onDelete;
@override @override
Widget build(BuildContext context) { Widget build(BuildContext context) {
return Column( return Column(
@@ -47,7 +55,12 @@ class LinkSectionView extends StatelessWidget {
for (final LinkItem item in section.items) for (final LinkItem item in section.items)
SizedBox( SizedBox(
width: itemWidth, width: itemWidth,
child: LinkCard(item: item, onOpen: () => onOpen(item)), child: LinkCard(
item: item,
onOpen: () => onOpen(item),
onEdit: onEdit == null ? null : () => onEdit!(item),
onDelete: onDelete == null ? null : () => onDelete!(item),
),
), ),
], ],
); );
frontend/lib/features/home/presentation/widgets/site_form_dialog.dart
+757
View File
@@ -0,0 +1,757 @@
import 'package:flutter/material.dart';
import '../../../../core/constants/app_sizes.dart';
import '../../../../core/theme/app_colors.dart';
import '../../../../core/theme/app_text_styles.dart';
import '../../../../core/utils/text.dart';
import '../../domain/models/nav_node.dart';
import '../../domain/models/submit_site_draft.dart';
import 'dialog_buttons.dart';
/// 打开网站表单对话框，返回 true 表示保存成功了。
///
/// 新增和编辑共用这一个表单：新增时 [onSubmit] 打 `POST /api/sites`，
/// 编辑时打 `PATCH /api/sites/{id}`，并用 [initial] 预填现有内容。
Future<bool> showSiteFormDialog({
required BuildContext context,
required List<NavNode> navNodes,
required String heading,
required Future<void> Function(SubmitSiteDraft draft) onSubmit,
SubmitSiteDraft? initial,
}) async {
final bool? submitted = await showDialog<bool>(
context: context,
barrierColor: const Color(0x73111827),
builder: (BuildContext context) => SiteFormDialog(
navNodes: navNodes,
heading: heading,
onSubmit: onSubmit,
initial: initial,
),
);
return submitted ?? false;
}
/// 网站表单（新增 / 编辑）。
///
/// 字段与后端 `POST /api/sites` 一一对应：**没有「选择分组」这个动作**，
/// 只有分组名——后端只会在用户创建的分组里查找或新建，提交的内容永远进不了
/// 内置分组，所以界面上也要把这件事说清楚，并只给用户分组的建议。
class SiteFormDialog extends StatefulWidget {
const SiteFormDialog({
super.key,
required this.navNodes,
required this.heading,
required this.onSubmit,
this.initial,
});
/// 侧栏那棵树，用来给出「已有的用户分组」建议。
final List<NavNode> navNodes;
/// 对话框标题，例如「提交网站」或「编辑网站」。
final String heading;
/// 保存动作。抛异常时表单会留在原地并显示原因。
final Future<void> Function(SubmitSiteDraft draft) onSubmit;
/// 编辑时的现有内容；新增时为 null。
final SubmitSiteDraft? initial;
@override
State<SiteFormDialog> createState() => _SiteFormDialogState();
}
class _SiteFormDialogState extends State<SiteFormDialog> {
late final TextEditingController _title;
late final TextEditingController _url;
late final TextEditingController _description;
late final TextEditingController _group;
late final TextEditingController _subGroup;
late final TextEditingController _submittedBy;
Map<String, String?> _errors = <String, String?>{};
String? _serverError;
bool _submitting = false;
@override
void initState() {
super.initState();
final SubmitSiteDraft? initial = widget.initial;
_title = TextEditingController(text: initial?.title ?? '');
_url = TextEditingController(text: initial?.url ?? '');
_description = TextEditingController(text: initial?.description ?? '');
_group = TextEditingController(text: initial?.group ?? '');
_subGroup = TextEditingController(text: initial?.subGroup ?? '');
_submittedBy = TextEditingController(text: initial?.submittedBy ?? '');
}
@override
void dispose() {
_title.dispose();
_url.dispose();
_description.dispose();
_group.dispose();
_subGroup.dispose();
_submittedBy.dispose();
super.dispose();
}
/// 已有的用户分组名（内置分组不出现在这里——选了也用不了）。
List<String> get _groupSuggestions => widget.navNodes
.where((NavNode node) => node.editable)
.map((NavNode node) => node.title)
.toList(growable: false);
/// 当前填的分组下已有的用户子分组。
List<String> get _subGroupSuggestions {
final String group = _group.text.trim();
for (final NavNode node in widget.navNodes) {
if (node.editable && node.title == group) {
return node.children
.where((NavNode child) => child.editable)
.map((NavNode child) => child.title)
.toList(growable: false);
}
}
return const <String>[];
}
/// 某个字段的内容变了：清掉它上一次的错误，让用户边改边看到反馈。
void _clearError(String field) {
if (_errors[field] == null && _serverError == null) {
return;
}
setState(() {
_errors = <String, String?>{..._errors, field: null};
_serverError = null;
});
}
Future<void> _submit() async {
final Map<String, String?> errors = <String, String?>{
'title': _validateTitle(_title.text),
'url': _validateUrl(_url.text),
'description': _validateDescription(_description.text),
'group': _validateGroup(_group.text),
'subGroup': _validateSubGroup(_subGroup.text),
'submittedBy': _validateSubmittedBy(_submittedBy.text),
};
setState(() {
_errors = errors;
_serverError = null;
});
if (errors.values.any((String? message) => message != null)) {
return;
}
setState(() => _submitting = true);
try {
await widget.onSubmit(
SubmitSiteDraft(
title: _title.text.trim(),
url: _url.text.trim(),
description: _description.text.trim(),
group: _group.text.trim(),
subGroup: _subGroup.text.trim(),
submittedBy: _submittedBy.text.trim(),
),
);
if (!mounted) {
return;
}
Navigator.of(context).pop(true);
} catch (error) {
if (!mounted) {
return;
}
// 后端的中文说明原样显示，用户能看懂哪里不对。
setState(() {
_submitting = false;
_serverError = error.toString();
});
}
}
@override
Widget build(BuildContext context) {
return PopScope(
// 请求还在路上时不允许关闭：关了界面请求也回不来，用户会以为丢了。
canPop: !_submitting,
child: Dialog(
backgroundColor: Colors.transparent,
elevation: 0,
insetPadding: const EdgeInsets.all(AppSizes.dialogPadding),
child: Container(
constraints: const BoxConstraints(maxWidth: AppSizes.dialogMaxWidth),
decoration: BoxDecoration(
color: AppColors.surface,
border: Border.all(color: AppColors.border),
borderRadius: BorderRadius.circular(AppSizes.cardRadius),
boxShadow: AppColors.cardShadowHover,
),
padding: const EdgeInsets.all(AppSizes.dialogPadding),
child: SingleChildScrollView(
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: <Widget>[
_Header(
heading: widget.heading,
submitting: _submitting,
onClose: () => Navigator.of(context).pop(false),
),
if (_serverError != null) ...<Widget>[
const SizedBox(height: AppSizes.spaceLg),
_ErrorBanner(message: _serverError!),
],
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '网站名称',
controller: _title,
hint: '例如：GitHub',
enabled: !_submitting,
error: _errors['title'],
onChanged: () => _clearError('title'),
),
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '网站地址',
controller: _url,
hint: 'https://…',
enabled: !_submitting,
error: _errors['url'],
onChanged: () => _clearError('url'),
),
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '一句话描述',
controller: _description,
hint: '这个站点是做什么的（可不填）',
enabled: !_submitting,
error: _errors['description'],
multiline: true,
onChanged: () => _clearError('description'),
),
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '分组',
controller: _group,
hint: '例如：AI 工具',
enabled: !_submitting,
error: _errors['group'],
onChanged: () {
_clearError('group');
// 分组一变，子分组建议跟着换。
setState(() {});
},
),
const SizedBox(height: AppSizes.fieldLabelGap),
const Text(
'提交的网站会放在你自己的分组里，不会进内置分类。',
style: AppTextStyles.emptyMessage,
),
if (_groupSuggestions.isNotEmpty) ...<Widget>[
const SizedBox(height: AppSizes.spaceSm),
_Suggestions(
label: '已有的分组',
values: _groupSuggestions,
enabled: !_submitting,
onPick: (String value) {
_group.text = value;
_clearError('group');
setState(() {});
},
),
],
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '子分组',
controller: _subGroup,
hint: '例如：模型社区（可不填）',
enabled: !_submitting,
error: _errors['subGroup'],
onChanged: () => _clearError('subGroup'),
),
if (_subGroupSuggestions.isNotEmpty) ...<Widget>[
const SizedBox(height: AppSizes.spaceSm),
_Suggestions(
label: '已有的子分组',
values: _subGroupSuggestions,
enabled: !_submitting,
onPick: (String value) {
_subGroup.text = value;
_clearError('subGroup');
setState(() {});
},
),
],
// 编辑时不让改提交者：后端 PATCH 本来也不接受这个字段。
if (widget.initial == null) ...<Widget>[
const SizedBox(height: AppSizes.spaceLg),
_InputBox(
label: '你的称呼或邮箱',
controller: _submittedBy,
hint: '可不填，方便回访时找你',
enabled: !_submitting,
error: _errors['submittedBy'],
onChanged: () => _clearError('submittedBy'),
),
],
const SizedBox(height: AppSizes.spaceXl),
_Actions(
submitting: _submitting,
onCancel: () => Navigator.of(context).pop(false),
onSubmit: _submit,
),
],
),
),
),
),
);
}
}
/// 标题行：标题 + 关闭按钮。
class _Header extends StatelessWidget {
const _Header({
required this.heading,
required this.submitting,
required this.onClose,
});
final String heading;
final bool submitting;
final VoidCallback onClose;
@override
Widget build(BuildContext context) {
return Row(
children: <Widget>[
Expanded(
child: Text(heading, style: AppTextStyles.sectionTitle),
),
_IconButton(
icon: '×',
tooltip: '关闭',
onTap: submitting ? null : onClose,
),
],
);
}
}
/// 后端返回的失败说明，放在表单顶部。
class _ErrorBanner extends StatelessWidget {
const _ErrorBanner({required this.message});
final String message;
@override
Widget build(BuildContext context) {
return Container(
padding: const EdgeInsets.symmetric(
horizontal: AppSizes.spaceMd,
vertical: 10,
),
decoration: BoxDecoration(
color: AppColors.dangerFaint,
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
message,
style: AppTextStyles.emptyMessage.copyWith(color: AppColors.danger),
),
);
}
}
/// 带标签、错误提示的输入框。
///
/// 视觉复用搜索框那一套（44px 高 / 12px 圆角 / 聚焦光晕）：
/// 输入框按自身行高定高，再用 Align 放进盒子里居中，不靠固定 padding 凑高度。
class _InputBox extends StatefulWidget {
const _InputBox({
required this.label,
required this.controller,
required this.hint,
required this.enabled,
required this.onChanged,
this.error,
this.multiline = false,
});
final String label;
final TextEditingController controller;
final String hint;
final bool enabled;
final VoidCallback onChanged;
final String? error;
final bool multiline;
@override
State<_InputBox> createState() => _InputBoxState();
}
class _InputBoxState extends State<_InputBox> {
final FocusNode _focusNode = FocusNode();
bool _focused = false;
@override
void initState() {
super.initState();
_focusNode.addListener(_handleFocusChange);
}
@override
void dispose() {
_focusNode
..removeListener(_handleFocusChange)
..dispose();
super.dispose();
}
void _handleFocusChange() {
if (_focusNode.hasFocus != _focused) {
setState(() => _focused = _focusNode.hasFocus);
}
}
@override
Widget build(BuildContext context) {
final bool hasError = widget.error != null;
final Color borderColor = hasError
? AppColors.danger
: (_focused ? AppColors.primary : AppColors.border);
final Widget field = TextField(
controller: widget.controller,
focusNode: _focusNode,
enabled: widget.enabled,
onChanged: (_) => widget.onChanged(),
maxLines: widget.multiline ? 3 : 1,
style: AppTextStyles.searchInput,
cursorColor: AppColors.primary,
decoration: InputDecoration(
isDense: true,
border: InputBorder.none,
contentPadding: EdgeInsets.zero,
hintText: widget.hint,
hintStyle: AppTextStyles.searchHint,
),
);
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Text(widget.label, style: AppTextStyles.emptyMessage),
const SizedBox(height: AppSizes.fieldLabelGap),
GestureDetector(
// 点盒子里输入框以外的留白也能聚焦。
onTap: widget.enabled ? _focusNode.requestFocus : null,
child: AnimatedContainer(
duration: AppSizes.transition,
curve: Curves.ease,
height: widget.multiline
? AppSizes.fieldMultilineHeight
: AppSizes.searchHeight,
padding: EdgeInsets.symmetric(
horizontal: AppSizes.cardPaddingHorizontal,
vertical: widget.multiline ? 10 : 0,
),
decoration: BoxDecoration(
color: widget.enabled ? AppColors.surface : AppColors.background,
border: Border.all(color: borderColor),
borderRadius: BorderRadius.circular(AppSizes.searchRadius),
// 聚焦时只剩光晕（原型 `.search-box:focus` 就是这个行为）。
boxShadow: <BoxShadow>[
if (_focused)
const BoxShadow(color: AppColors.focusRing, spreadRadius: 3)
else if (hasError)
const BoxShadow(
color: AppColors.dangerFaint,
spreadRadius: 3,
)
else
...AppColors.cardShadow,
],
),
child: Align(
alignment: widget.multiline
? Alignment.topLeft
: Alignment.centerLeft,
child: field,
),
),
),
if (widget.error != null) ...<Widget>[
const SizedBox(height: AppSizes.spaceXs),
Text(
widget.error!,
style: AppTextStyles.emptyMessage.copyWith(
color: AppColors.danger,
),
),
],
],
);
}
}
/// 一行可点的建议值。
class _Suggestions extends StatelessWidget {
const _Suggestions({
required this.label,
required this.values,
required this.enabled,
required this.onPick,
});
final String label;
final List<String> values;
final bool enabled;
final ValueChanged<String> onPick;
@override
Widget build(BuildContext context) {
return Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Padding(
padding: const EdgeInsets.only(top: 5),
child: Text(label, style: AppTextStyles.emptyMessage),
),
const SizedBox(width: AppSizes.spaceSm),
Expanded(
child: Wrap(
spacing: AppSizes.spaceSm,
runSpacing: AppSizes.spaceSm,
children: <Widget>[
for (final String value in values)
_SuggestionChip(
label: value,
onTap: enabled ? () => onPick(value) : null,
),
],
),
),
],
);
}
}
class _SuggestionChip extends StatefulWidget {
const _SuggestionChip({required this.label, required this.onTap});
final String label;
final VoidCallback? onTap;
@override
State<_SuggestionChip> createState() => _SuggestionChipState();
}
class _SuggestionChipState extends State<_SuggestionChip> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
return MouseRegion(
cursor: SystemMouseCursors.click,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 4),
decoration: BoxDecoration(
color: _hovered ? AppColors.primaryFaint : AppColors.iconSurface,
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
widget.label,
style: AppTextStyles.cardDesc.copyWith(
color: _hovered ? AppColors.primary : AppColors.textSecondary,
),
),
),
),
);
}
}
/// 底部按钮：左「取消」，右「提交」。
class _Actions extends StatelessWidget {
const _Actions({
required this.submitting,
required this.onCancel,
required this.onSubmit,
});
final bool submitting;
final VoidCallback onCancel;
final VoidCallback onSubmit;
@override
Widget build(BuildContext context) {
return Row(
mainAxisAlignment: MainAxisAlignment.end,
children: <Widget>[
DialogGhostButton(label: '取消', onTap: submitting ? null : onCancel),
const SizedBox(width: AppSizes.spaceMd),
DialogPrimaryButton(
label: submitting ? '提交中…' : '提交',
onTap: submitting ? null : onSubmit,
),
],
);
}
}
class _IconButton extends StatefulWidget {
const _IconButton({
required this.icon,
required this.tooltip,
required this.onTap,
});
final String icon;
final String tooltip;
final VoidCallback? onTap;
@override
State<_IconButton> createState() => _IconButtonState();
}
class _IconButtonState extends State<_IconButton> {
bool _hovered = false;
@override
Widget build(BuildContext context) {
return Tooltip(
message: widget.tooltip,
child: MouseRegion(
cursor: SystemMouseCursors.click,
onEnter: (_) => setState(() => _hovered = true),
onExit: (_) => setState(() => _hovered = false),
child: GestureDetector(
onTap: widget.onTap,
child: AnimatedContainer(
duration: AppSizes.transition,
width: AppSizes.iconButtonSize,
height: AppSizes.iconButtonSize,
alignment: Alignment.center,
decoration: BoxDecoration(
color: _hovered ? AppColors.iconSurface : Colors.transparent,
borderRadius: BorderRadius.circular(AppSizes.navItemRadius),
),
child: Text(
widget.icon,
style: AppTextStyles.cardTitle.copyWith(
color: AppColors.textSecondary,
),
),
),
),
),
);
}
}
// ---- 校验：口径与后端 validate.rs 保持一致 ----
const int _maxTitle = 60;
const int _maxDescription = 120;
const int _maxGroup = 30;
const int _maxSubmittedBy = 120;
String? _validateTitle(String value) {
if (value.trim().isEmpty) {
return '请填写网站名称';
}
if (charCount(value) > _maxTitle) {
return '网站名称最多 $_maxTitle 个字';
}
return null;
}
String? _validateUrl(String value) {
final String text = value.trim();
if (text.isEmpty) {
return '请填写网站地址';
}
final Uri? uri = Uri.tryParse(text);
if (uri == null || uri.host.isEmpty) {
return '地址要以 http:// 或 https:// 开头';
}
if (uri.scheme != 'http' && uri.scheme != 'https') {
return '地址只能是 http:// 或 https://';
}
if (_isInternalHost(uri.host)) {
return '不能填本机或内网地址';
}
return null;
}
String? _validateDescription(String value) {
if (charCount(value) > _maxDescription) {
return '描述最多 $_maxDescription 个字';
}
return null;
}
String? _validateGroup(String value) {
final String text = value.trim();
if (text.isEmpty) {
return '请填写分组名称';
}
if (charCount(text) > _maxGroup) {
return '分组名称最多 $_maxGroup 个字';
}
return null;
}
String? _validateSubGroup(String value) {
if (charCount(value) > _maxGroup) {
return '子分组名称最多 $_maxGroup 个字';
}
return null;
}
String? _validateSubmittedBy(String value) {
if (charCount(value) > _maxSubmittedBy) {
return '最多 $_maxSubmittedBy 个字';
}
return null;
}
/// 前端只拦最明显的几种内网地址，权威判断在后端。
bool _isInternalHost(String host) {
final String h = host.toLowerCase();
if (h == 'localhost' || h.endsWith('.localhost') || h.endsWith('.local')) {
return true;
}
if (h == '0.0.0.0' || h == '::1' || h == '[::1]') {
return true;
}
final List<String> parts = h.split('.');
if (parts.length != 4) {
return false;
}
final int? first = int.tryParse(parts[0]);
final int? second = int.tryParse(parts[1]);
if (first == null || second == null) {
return false;
}
if (first == 127 || first == 10) {
return true;
}
if (first == 192 && second == 168) {
return true;
}
if (first == 172 && second >= 16 && second <= 31) {
return true;
}
return first == 169 && second == 254;
}
frontend/pubspec.lock
+24
View File
@@ -75,6 +75,22 @@ packages:
description: flutter description: flutter
source: sdk source: sdk
version: "0.0.0" version: "0.0.0"
http:
dependency: "direct main"
description:
name: http
sha256: "87721a4a50b19c7f1d49001e51409bddc46303966ce89a65af4f4e6004896412"
url: "https://pub.flutter-io.cn"
source: hosted
version: "1.6.0"
http_parser:
dependency: transitive
description:
name: http_parser
sha256: "178d74305e7866013777bab2c3d8726205dc5a4dd935297175b19a23a2e66571"
url: "https://pub.flutter-io.cn"
source: hosted
version: "4.1.2"
leak_tracker: leak_tracker:
dependency: transitive dependency: transitive
description: description:
@@ -192,6 +208,14 @@ packages:
url: "https://pub.flutter-io.cn" url: "https://pub.flutter-io.cn"
source: hosted source: hosted
version: "0.7.11" version: "0.7.11"
typed_data:
dependency: transitive
description:
name: typed_data
sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006
url: "https://pub.flutter-io.cn"
source: hosted
version: "1.4.0"
vector_math: vector_math:
dependency: transitive dependency: transitive
description: description:
frontend/pubspec.yaml
+1
View File
@@ -35,6 +35,7 @@ dependencies:
# Use with the CupertinoIcons class for iOS style icons. # Use with the CupertinoIcons class for iOS style icons.
cupertino_icons: ^1.0.8 cupertino_icons: ^1.0.8
web: ^1.0.0 web: ^1.0.0
http: ^1.6.0
dev_dependencies: dev_dependencies:
flutter_test: flutter_test:
sdk: flutter sdk: flutter
frontend/test/features/home/data/http_home_repository_test.dart
+301
View File
@@ -0,0 +1,301 @@
import 'dart:convert';
import 'package:flutter_test/flutter_test.dart';
import 'package:frontend/features/home/data/home_repository.dart';
import 'package:frontend/features/home/data/http_home_repository.dart';
import 'package:frontend/features/home/domain/models/home_data.dart';
import 'package:frontend/features/home/domain/models/link_section.dart';
import 'package:frontend/features/home/domain/models/nav_node.dart';
import 'package:frontend/features/home/domain/models/submit_site_draft.dart';
import 'package:http/http.dart' as http;
import 'package:http/testing.dart';
/// 和后端真实响应同构：两个一级分组，其中一个带子分组，还留一个空分组。
const String _navJson = '''
{
"groups": [
{
"id": "common",
"title": "常用推荐",
"source": "system",
"editable": false,
"sites": [
{ "id": "github", "title": "GitHub", "url": "https://github.com",
"description": "代码托管与开源社区", "categoryId": "common",
"source": "system", "order": 10, "editable": false,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": "" },
{ "id": "zhihu", "title": "知乎", "url": "https://www.zhihu.com",
"description": "深度内容问答社区", "categoryId": "common",
"source": "system", "order": 20, "editable": false,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": "" }
],
"children": []
},
{
"id": "materials",
"title": "素材资源",
"source": "system",
"editable": false,
"sites": [],
"children": [
{
"id": "design",
"title": "UI 设计",
"source": "system",
"editable": false,
"sites": [
{ "id": "figma", "title": "Figma", "url": "https://www.figma.com",
"description": "协同界面设计工具", "categoryId": "design",
"source": "system", "order": 10, "editable": false,
"createdAt": "2026-09-13T10:29:48Z", "updatedAt": "2026-09-13T10:29:48Z",
"submittedBy": "" }
],
"children": []
},
{
"id": "icon",
"title": "图标库",
"source": "system",
"editable": false,
"sites": [],
"children": []
}
]
}
]
}
''';
HttpHomeRepository repositoryReturning(
String body, {
int status = 200,
void Function(http.Request request)? onRequest,
}) {
final MockClient client = MockClient((http.Request request) async {
onRequest?.call(request);
return http.Response.bytes(utf8.encode(body), status);
});
return HttpHomeRepository(baseUrl: 'http://api.test', client: client);
}
void main() {
group('映射后端响应', () {
late HomeData data;
setUp(() async {
data = await repositoryReturning(_navJson).fetchHomeData();
});
test('请求打到 /api/nav', () async {
Uri? requested;
await repositoryReturning(
_navJson,
onRequest: (http.Request request) => requested = request.url,
).fetchHomeData();
expect(requested.toString(), 'http://api.test/api/nav');
});
test('分组变成侧栏导航树', () {
expect(
data.navNodes.map((NavNode node) => node.title),
<String>['常用推荐', '素材资源'],
);
expect(data.navNodes[0].isGroup, isFalse, reason: '没有子分组就是直接跳转的条目');
expect(data.navNodes[1].isGroup, isTrue);
expect(
data.navNodes[1].children.map((NavNode node) => node.title),
<String>['UI 设计', '图标库'],
);
});
test('只有挂着网站的分组才进内容区', () {
expect(
data.sections.map((LinkSection section) => section.id),
<String>['common', 'design'],
);
// 空分组仍然留在侧栏里，只是点了没有对应内容。
expect(data.sectionById('icon'), isNull);
expect(
data.navLeaves.map((NavNode node) => node.id),
contains('icon'),
);
});
test('子分组的内容标题带上父级', () {
expect(data.sectionById('design')!.title, '素材资源 - UI 设计');
expect(data.sectionById('common')!.title, '常用推荐');
});
test('网站按后端给的顺序展开', () {
expect(
data.sectionById('common')!.items.map((item) => item.title),
<String>['GitHub', '知乎'],
);
expect(data.sectionById('design')!.items.single.url, 'https://www.figma.com');
expect(data.sectionById('design')!.items.single.description, '协同界面设计工具');
});
});
group('错误处理', () {
test('非 200 时带出后端的说明', () async {
final HttpHomeRepository repository = repositoryReturning(
'{"error":"找不到数据"}',
status: 500,
);
await expectLater(
repository.fetchHomeData(),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
contains('找不到数据'),
),
),
);
});
test('返回的不是 JSON 时给出明确提示', () async {
final HttpHomeRepository repository = repositoryReturning(
'<html>502 Bad Gateway</html>',
);
await expectLater(
repository.fetchHomeData(),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
contains('不是合法 JSON'),
),
),
);
});
test('缺少 groups 时给出明确提示', () async {
final HttpHomeRepository repository = repositoryReturning('{"ok":true}');
await expectLater(
repository.fetchHomeData(),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
contains('groups'),
),
),
);
});
test('连不上后端时给出地址', () async {
final MockClient client = MockClient(
(http.Request request) async => throw const SocketExceptionStub(),
);
final HttpHomeRepository repository = HttpHomeRepository(
baseUrl: 'http://127.0.0.1:8080',
client: client,
);
await expectLater(
repository.fetchHomeData(),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
contains('连不上后端'),
),
),
);
});
test('缺字段的条目被跳过，不会让整页失败', () async {
final HomeData data = await repositoryReturning('''
{"groups":[{"id":"g","title":"G","sites":[
{"id":"","title":"没有 id","url":"https://a.com"},
{"id":"ok","title":"正常","url":"https://b.com"}
],"children":[]}]}
''').fetchHomeData();
expect(data.sectionById('g')!.items, hasLength(1));
expect(data.sectionById('g')!.items.single.title, '正常');
});
});
group('提交网站', () {
const SubmitSiteDraft draft = SubmitSiteDraft(
title: 'Hugging Face',
url: 'https://huggingface.co',
description: '开源模型与数据集社区',
group: 'AI 工具',
subGroup: '模型社区',
submittedBy: '[email protected]',
);
test('POST 到 /api/sites，字段用 camelCase', () async {
http.Request? captured;
final HttpHomeRepository repository = HttpHomeRepository(
baseUrl: 'http://api.test',
client: MockClient((http.Request request) async {
captured = request;
return http.Response.bytes(utf8.encode('{}'), 201);
}),
);
await repository.submitSite(draft);
expect(captured!.method, 'POST');
expect(captured!.url.toString(), 'http://api.test/api/sites');
final Map<String, dynamic> body =
jsonDecode(captured!.body) as Map<String, dynamic>;
expect(body['title'], 'Hugging Face');
expect(body['url'], 'https://huggingface.co');
expect(body['group'], 'AI 工具');
expect(body['subGroup'], '模型社区');
expect(body['submittedBy'], '[email protected]');
expect(body.containsKey('categoryId'), isFalse, reason: '不能自己指定分组 id');
});
test('后端返回 400 时抛出后端的中文说明', () async {
final HttpHomeRepository repository = repositoryReturning(
'{"error":"url 不能是本机或内网地址：localhost"}',
status: 400,
);
await expectLater(
repository.submitSite(draft),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
allOf(contains('400'), contains('不能是本机或内网地址')),
),
),
);
});
test('连不上后端时给出地址', () async {
final HttpHomeRepository repository = HttpHomeRepository(
baseUrl: 'http://127.0.0.1:8080',
client: MockClient(
(http.Request request) async => throw const SocketExceptionStub(),
),
);
await expectLater(
repository.submitSite(draft),
throwsA(
isA<HomeFailure>().having(
(HomeFailure failure) => failure.message,
'message',
contains('连不上后端'),
),
),
);
});
});
}
/// 用来模拟「连不上」的异常。
class SocketExceptionStub implements Exception {
const SocketExceptionStub();
@override
String toString() => 'Connection refused';
}
frontend/test/features/home/data/mock_home_repository_test.dart
+6 -1
View File
@@ -7,7 +7,12 @@ import 'package:frontend/features/home/domain/models/nav_node.dart';
void main() { void main() {
const MockHomeRepository repository = MockHomeRepository(); const MockHomeRepository repository = MockHomeRepository();
final HomeData data = repository.fetchHomeData(); late HomeData data;
// 取数改成异步之后，每个用例开始前先拿一次。
setUp(() async {
data = await repository.fetchHomeData();
});
group('导航树（对照 index3.html 的 nav-group）', () { group('导航树（对照 index3.html 的 nav-group）', () {
test('三个一级条目：一个直接跳转，两个可展开分组', () { test('三个一级条目：一个直接跳转，两个可展开分组', () {
frontend/test/features/home/presentation/home_page_test.dart
+312 -1
View File
@@ -1,12 +1,22 @@
import 'dart:async';
import 'package:flutter/material.dart'; import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart'; import 'package:flutter_test/flutter_test.dart';
import 'package:frontend/core/constants/app_sizes.dart'; import 'package:frontend/core/constants/app_sizes.dart';
import 'package:frontend/core/theme/app_colors.dart'; import 'package:frontend/core/theme/app_colors.dart';
import 'package:frontend/features/home/data/home_repository.dart';
import 'package:frontend/features/home/data/mock_home_data.dart';
import 'package:frontend/features/home/data/mock_home_repository.dart'; import 'package:frontend/features/home/data/mock_home_repository.dart';
import 'package:frontend/features/home/domain/models/home_data.dart';
import 'package:frontend/features/home/domain/models/link_item.dart';
import 'package:frontend/features/home/domain/models/link_section.dart';
import 'package:frontend/features/home/domain/models/nav_node.dart';
import 'package:frontend/features/home/domain/models/submit_site_draft.dart';
import 'package:frontend/features/home/presentation/pages/home_page.dart'; import 'package:frontend/features/home/presentation/pages/home_page.dart';
import 'package:frontend/features/home/presentation/widgets/link_card.dart'; import 'package:frontend/features/home/presentation/widgets/link_card.dart';
import 'package:frontend/features/home/presentation/widgets/link_section_view.dart'; import 'package:frontend/features/home/presentation/widgets/link_section_view.dart';
import 'package:frontend/features/home/presentation/widgets/sidebar_nav.dart'; import 'package:frontend/features/home/presentation/widgets/sidebar_nav.dart';
import 'package:frontend/features/home/presentation/widgets/site_form_dialog.dart';
import '../../../helpers/fake_url_opener.dart'; import '../../../helpers/fake_url_opener.dart';
@@ -22,6 +32,9 @@ void main() {
// 高度取 420：原型只有两段内容，视口再高就滚不动了， // 高度取 420：原型只有两段内容，视口再高就滚不动了，
// 「回到顶部」这类用例也就没有意义。 // 「回到顶部」这类用例也就没有意义。
Size size = const Size(900, 420), Size size = const Size(900, 420),
HomeRepository repository = const MockHomeRepository(),
/// 加载中的用例要停在第一帧，不能等它 settle。
bool settle = true,
}) async { }) async {
tester.view.physicalSize = size; tester.view.physicalSize = size;
tester.view.devicePixelRatio = 1; tester.view.devicePixelRatio = 1;
@@ -30,13 +43,18 @@ void main() {
await tester.pumpWidget( await tester.pumpWidget(
MaterialApp( MaterialApp(
home: HomePage( home: HomePage(
repository: const MockHomeRepository(), repository: repository,
urlOpener: urlOpener, urlOpener: urlOpener,
), ),
), ),
); );
// 数据现在来自 Future，等它落地后再断言。
if (settle) {
await tester.pumpAndSettle();
} else {
await tester.pump(); await tester.pump();
} }
}
/// 侧栏里的导航文字（避免和内容区的分区标题同名而混淆）。 /// 侧栏里的导航文字（避免和内容区的分区标题同名而混淆）。
Finder navText(String label) { Finder navText(String label) {
@@ -319,4 +337,297 @@ void main() {
expect(find.byType(SnackBar), findsNothing); expect(find.byType(SnackBar), findsNothing);
}); });
}); });
group('加载状态', () {
testWidgets('数据没回来时显示加载提示', (WidgetTester tester) async {
final _PendingRepository repository = _PendingRepository();
await pumpPage(tester, repository: repository, settle: false);
expect(find.text('正在加载…'), findsOneWidget);
expect(find.byType(LinkSectionView), findsNothing);
repository.completer.complete(mockHomeData);
await tester.pumpAndSettle();
expect(find.text('正在加载…'), findsNothing);
expect(find.byType(LinkSectionView), findsNWidgets(2));
});
testWidgets('取数失败时显示原因和重试按钮', (WidgetTester tester) async {
await pumpPage(
tester,
repository: const _FailingRepository('连不上后端（http://127.0.0.1:8080）'),
);
expect(find.text('加载失败'), findsOneWidget);
expect(find.textContaining('连不上后端'), findsOneWidget);
expect(find.text('重试'), findsOneWidget);
expect(find.byType(LinkSectionView), findsNothing);
});
testWidgets('点重试会重新取数，成功后渲染内容', (WidgetTester tester) async {
final _FlakyRepository repository = _FlakyRepository();
await pumpPage(tester, repository: repository);
expect(find.text('加载失败'), findsOneWidget);
await tester.tap(find.text('重试'));
await tester.pumpAndSettle();
expect(repository.calls, 2);
expect(find.text('加载失败'), findsNothing);
expect(find.byType(LinkSectionView), findsNWidgets(2));
expect(find.byType(LinkCard), findsNWidgets(5));
});
});
group('提交网站', () {
testWidgets('点侧栏底部按钮打开表单；提交成功后刷新一次并提示', (WidgetTester tester) async {
final _RecordingRepository repository = _RecordingRepository();
// 表单比默认视口高，用大一点的窗口，免得字段在屏幕外点不到。
await pumpPage(
tester,
size: const Size(1000, 1200),
repository: repository,
);
expect(repository.fetches, 1);
await tester.tap(navText('提交网站'));
await tester.pumpAndSettle();
expect(find.text('网站名称'), findsOneWidget);
expect(find.text('提交的网站会放在你自己的分组里，不会进内置分类。'), findsOneWidget);
// 页面里除了表单还有顶部搜索框，这里限定在对话框内部找输入框。
Finder field(int index) => find
.descendant(
of: find.byType(SiteFormDialog),
matching: find.byType(TextField),
)
.at(index);
await tester.enterText(field(0), 'Hugging Face');
await tester.enterText(field(1), 'https://huggingface.co');
await tester.enterText(field(3), 'AI 工具');
await tester.pump();
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(repository.submitted, hasLength(1));
expect(repository.submitted.single.group, 'AI 工具');
expect(repository.fetches, 2, reason: '提交成功后要重新拉一次数据');
expect(find.text('已提交，感谢'), findsOneWidget);
expect(find.text('网站名称'), findsNothing, reason: '对话框已经关掉');
});
});
group('编辑与删除', () {
testWidgets('可修改的条目能编辑，保存后刷新', (WidgetTester tester) async {
final _MutableRepository repository = _MutableRepository();
await pumpPage(
tester,
size: const Size(1000, 1200),
repository: repository,
);
expect(repository.fetches, 1);
await tester.tap(find.byTooltip('编辑'));
await tester.pumpAndSettle();
// 表单预填了现有内容，提交者字段不出现。
expect(find.text('编辑网站'), findsOneWidget);
expect(
tester
.widget<TextField>(
find
.descendant(
of: find.byType(SiteFormDialog),
matching: find.byType(TextField),
)
.at(0),
)
.controller!
.text,
'Hugging Face',
);
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(repository.updated, <String>['s-1']);
expect(repository.fetches, 2, reason: '保存成功后要重新拉一次数据');
expect(find.text('已保存'), findsOneWidget);
});
testWidgets('删除会先确认，确认后才真的删并刷新', (WidgetTester tester) async {
final _MutableRepository repository = _MutableRepository();
await pumpPage(
tester,
size: const Size(1000, 1200),
repository: repository,
);
await tester.tap(find.byTooltip('删除'));
await tester.pumpAndSettle();
expect(find.textContaining('确定要删除「Hugging Face」'), findsOneWidget);
// 先点取消：什么都不该发生。
await tester.tap(find.text('取消'));
await tester.pumpAndSettle();
expect(repository.deleted, isEmpty);
await tester.tap(find.byTooltip('删除'));
await tester.pumpAndSettle();
await tester.tap(find.text('删除'));
await tester.pumpAndSettle();
expect(repository.deleted, <String>['s-1']);
expect(repository.fetches, 2);
expect(find.text('已删除'), findsOneWidget);
});
testWidgets('内置条目没有编辑和删除入口', (WidgetTester tester) async {
await pumpPage(tester);
expect(find.byType(LinkCard), findsWidgets);
expect(find.byTooltip('编辑'), findsNothing);
expect(find.byTooltip('删除'), findsNothing);
});
});
}
/// 返回一条「用户提交」的站点（editable），并记录改删调用。
class _MutableRepository implements HomeRepository {
int fetches = 0;
final List<String> updated = <String>[];
final List<String> deleted = <String>[];
static const HomeData _data = HomeData(
siteName: 'Suxing Nav',
searchHint: '输入关键字搜索全网资源...',
navNodes: <NavNode>[NavNode(id: 'g-1', title: 'AI 工具', editable: true)],
sections: <LinkSection>[
LinkSection(
id: 'g-1',
title: 'AI 工具',
items: <LinkItem>[
LinkItem(
id: 's-1',
title: 'Hugging Face',
url: 'https://huggingface.co',
description: '开源模型与数据集社区',
categoryId: 'g-1',
editable: true,
),
],
),
],
);
@override
Future<HomeData> fetchHomeData() async {
fetches++;
return _data;
}
@override
Future<void> submitSite(SubmitSiteDraft draft) async {}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {
updated.add(id);
}
@override
Future<void> deleteSite(String id) async {
deleted.add(id);
}
}
/// 记录取数次数与提交内容，用来验证页面的联调行为。
class _RecordingRepository implements HomeRepository {
int fetches = 0;
final List<SubmitSiteDraft> submitted = <SubmitSiteDraft>[];
final List<String> updated = <String>[];
final List<String> deleted = <String>[];
@override
Future<HomeData> fetchHomeData() async {
fetches++;
return mockHomeData;
}
@override
Future<void> submitSite(SubmitSiteDraft draft) async {
submitted.add(draft);
}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {
updated.add(id);
}
@override
Future<void> deleteSite(String id) async {
deleted.add(id);
}
}
/// 数据一直不回来，用来测加载中的那一帧。
class _PendingRepository implements HomeRepository {
final Completer<HomeData> completer = Completer<HomeData>();
@override
Future<HomeData> fetchHomeData() => completer.future;
@override
Future<void> submitSite(SubmitSiteDraft draft) async {}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {}
@override
Future<void> deleteSite(String id) async {}
}
/// 永远失败。
class _FailingRepository implements HomeRepository {
const _FailingRepository(this.message);
final String message;
@override
Future<HomeData> fetchHomeData() async => throw HomeFailure(message);
@override
Future<void> submitSite(SubmitSiteDraft draft) async {}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {}
@override
Future<void> deleteSite(String id) async {}
}
/// 第一次失败、第二次成功，用来验证重试按钮真的重新取数。
class _FlakyRepository implements HomeRepository {
int calls = 0;
@override
Future<HomeData> fetchHomeData() async {
calls++;
if (calls == 1) {
throw const HomeFailure('后端没起来');
}
return mockHomeData;
}
@override
Future<void> submitSite(SubmitSiteDraft draft) async {}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {}
@override
Future<void> deleteSite(String id) async {}
} }
frontend/test/features/home/presentation/site_form_dialog_test.dart
+235
View File
@@ -0,0 +1,235 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:frontend/features/home/data/home_repository.dart';
import 'package:frontend/features/home/data/mock_home_data.dart';
import 'package:frontend/features/home/domain/models/home_data.dart';
import 'package:frontend/features/home/domain/models/nav_node.dart';
import 'package:frontend/features/home/domain/models/submit_site_draft.dart';
import 'package:frontend/features/home/presentation/widgets/site_form_dialog.dart';
/// 记录提交内容的假仓库。[failWith] 有值时模拟后端报错，[gate] 用来卡住请求。
class _RecordingRepository implements HomeRepository {
final List<SubmitSiteDraft> submitted = <SubmitSiteDraft>[];
String? failWith;
Completer<void>? gate;
@override
Future<HomeData> fetchHomeData() async => mockHomeData;
@override
Future<void> submitSite(SubmitSiteDraft draft) async {
if (gate != null) {
await gate!.future;
}
final String? failure = failWith;
if (failure != null) {
throw HomeFailure(failure);
}
submitted.add(draft);
}
@override
Future<void> updateSite(String id, SubmitSiteDraft draft) async {}
@override
Future<void> deleteSite(String id) async {}
}
/// 侧栏那棵树：内置分组不可选，用户分组可选。
const List<NavNode> _navNodes = <NavNode>[
NavNode(id: 'common', title: '常用推荐'),
NavNode(
id: 'g-1',
title: 'AI 工具',
editable: true,
children: <NavNode>[
NavNode(id: 'g-2', title: '模型社区', editable: true),
],
),
];
void main() {
late _RecordingRepository repository;
late bool? dialogResult;
setUp(() {
repository = _RecordingRepository();
dialogResult = null;
});
Future<void> openDialog(
WidgetTester tester, {
String heading = '提交网站',
SubmitSiteDraft? initial,
}) async {
// 表单比默认测试视口高，放大一点免得字段跑到屏幕外。
tester.view.physicalSize = const Size(1000, 1200);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
await tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: Builder(
builder: (BuildContext context) => TextButton(
onPressed: () async {
dialogResult = await showSiteFormDialog(
context: context,
navNodes: _navNodes,
heading: heading,
initial: initial,
onSubmit: (SubmitSiteDraft draft) =>
repository.submitSite(draft),
);
},
child: const Text('打开'),
),
),
),
),
);
await tester.tap(find.text('打开'));
await tester.pumpAndSettle();
}
/// 按顺序填字段：0 名称、1 地址、2 描述、3 分组、4 子分组、5 称呼。
Future<void> fill(WidgetTester tester, int index, String value) async {
await tester.enterText(find.byType(TextField).at(index), value);
await tester.pump();
}
Future<void> fillValidForm(WidgetTester tester) async {
await fill(tester, 0, 'Hugging Face');
await fill(tester, 1, 'https://huggingface.co');
await fill(tester, 2, '开源模型与数据集社区');
await fill(tester, 3, 'AI 工具');
await fill(tester, 4, '模型社区');
await fill(tester, 5, '[email protected]');
}
testWidgets('空表单提交会逐项提示，且不发请求', (WidgetTester tester) async {
await openDialog(tester);
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(find.text('请填写网站名称'), findsOneWidget);
expect(find.text('请填写网站地址'), findsOneWidget);
expect(find.text('请填写分组名称'), findsOneWidget);
expect(repository.submitted, isEmpty);
expect(dialogResult, isNull, reason: '校验没过时对话框不关');
});
testWidgets('内网地址会被拦下来', (WidgetTester tester) async {
await openDialog(tester);
await fill(tester, 0, '内网');
await fill(tester, 1, 'http://192.168.1.10');
await fill(tester, 3, 'AI 工具');
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(find.text('不能填本机或内网地址'), findsOneWidget);
expect(repository.submitted, isEmpty);
});
testWidgets('合法内容提交给仓库，成功后关闭并返回 true', (WidgetTester tester) async {
await openDialog(tester);
await fillValidForm(tester);
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(repository.submitted, hasLength(1));
final SubmitSiteDraft draft = repository.submitted.single;
expect(draft.title, 'Hugging Face');
expect(draft.url, 'https://huggingface.co');
expect(draft.group, 'AI 工具');
expect(draft.subGroup, '模型社区');
expect(draft.submittedBy, '[email protected]');
expect(dialogResult, isTrue);
expect(find.text('取消'), findsNothing, reason: '对话框已经关掉');
});
testWidgets('后端报错时留在表单里显示原因', (WidgetTester tester) async {
repository.failWith = 'url 不能是本机或内网地址：localhost';
await openDialog(tester);
await fillValidForm(tester);
await tester.tap(find.text('提交'));
await tester.pumpAndSettle();
expect(find.textContaining('不能是本机或内网地址'), findsOneWidget);
expect(repository.submitted, isEmpty);
expect(dialogResult, isNull);
expect(find.text('取消'), findsOneWidget, reason: '还能改了再提交');
});
testWidgets('提交中按钮变成「提交中…」且不可再点', (WidgetTester tester) async {
repository.gate = Completer<void>();
await openDialog(tester);
await fillValidForm(tester);
await tester.tap(find.text('提交'));
await tester.pump();
expect(find.text('提交中…'), findsOneWidget);
repository.gate!.complete();
await tester.pumpAndSettle();
expect(dialogResult, isTrue);
});
testWidgets('只给用户分组建议，点一下填进输入框', (WidgetTester tester) async {
await openDialog(tester);
// 内置分组不出现在建议里。
expect(find.text('AI 工具'), findsOneWidget, reason: '用户分组建议');
expect(find.text('常用推荐'), findsNothing, reason: '内置分组不可选');
await tester.tap(find.text('AI 工具'));
await tester.pumpAndSettle();
final TextField groupField = tester.widget<TextField>(
find.byType(TextField).at(3),
);
expect(groupField.controller!.text, 'AI 工具');
// 分组定了之后，它下面已有的子分组才出现。
expect(find.text('模型社区'), findsOneWidget);
});
testWidgets('编辑模式预填现有内容，且不显示提交者字段', (WidgetTester tester) async {
await openDialog(
tester,
heading: '编辑网站',
initial: const SubmitSiteDraft(
title: 'Hugging Face',
url: 'https://huggingface.co',
description: '开源模型与数据集社区',
group: 'AI 工具',
subGroup: '模型社区',
),
);
expect(find.text('编辑网站'), findsOneWidget);
expect(
tester.widget<TextField>(find.byType(TextField).at(0)).controller!.text,
'Hugging Face',
);
expect(
tester.widget<TextField>(find.byType(TextField).at(1)).controller!.text,
'https://huggingface.co',
);
expect(
tester.widget<TextField>(find.byType(TextField).at(3)).controller!.text,
'AI 工具',
);
// 后端 PATCH 不接受 submittedBy，编辑时就不显示这个字段。
expect(find.text('你的称呼或邮箱'), findsNothing);
// 分组已填好，它下面的子分组建议直接出来。
// （子分组输入框里也预填了同样的文字，所以这里用 findsWidgets。）
expect(find.text('模型社区'), findsWidgets);
});
}