# 项目整体分析 — 语义分割系统（Seg_Server）

> 分析时间: 2026-04-28-22-55-15  
> 本文档面向代码编纂工作流，提供项目全景视图，用于快速理解项目结构和当前状态。

---

## 一、项目基本信息

| 属性 | 值 |
|------|-----|
| 项目名称 | react-example（package.json name） |
| 业务名称 | 语义分割系统（Semantic Segmentation System） |
| 部署目标 | Google AI Studio / Cloud Run |
| 应用链接 | https://ai.studio/apps/2707f0e1-d453-4594-a618-fba53cb937c4 |
| 业务文档 | `语义分割系统构建方案.docx`（未解析） |
| 代码仓库 | http://192.168.31.5:5002/admin/Seg_Server.git |

---

## 二、技术栈

| 层级 | 技术选型 | 版本 |
|------|----------|------|
| 前端框架 | React + TypeScript | React 19, TS 5.8 |
| 构建工具 | Vite | v6 |
| 样式方案 | TailwindCSS + 自定义深色主题 | v4 |
| 状态管理 | React useState（无外部状态库） | - |
| 路由 | 无路由库，基于 React 状态切换 | - |
| Canvas 渲染 | Konva + react-konva | - |
| 图标库 | lucide-react | - |
| 动画 | motion | - |
| AI SDK | @google/genai（Gemini API） | - |
| 后端 | Express | v4 |
| 运行时 | Node.js ES Modules | `"type": "module"` |

---

## 三、目录结构

```
Seg_Server/
├── server.ts                    # Express 服务端入口（开发服务器 + 生产静态文件服务）
├── index.html                   # SPA HTML 入口
├── vite.config.ts               # Vite 构建配置（含 DISABLE_HMR 逻辑）
├── tsconfig.json                # TypeScript 配置
├── package.json                 # 依赖与脚本
├── .env.example                 # 环境变量模板
├── metadata.json                # AI Studio 元数据（目前为空）
├── AGENTS.md                    # AI 助手项目指南
├── 语义分割系统构建方案.docx      # 业务方案文档
├── src/
│   ├── main.tsx                 # React 应用挂载点（StrictMode）
│   ├── App.tsx                  # 根组件：模块路由 + 登录鉴权
│   ├── index.css                # TailwindCSS 导入 + 自定义工具类
│   ├── lib/
│   │   └── utils.ts             # cn() 工具函数（clsx + tailwind-merge）
│   └── components/
│       ├── auth/
│       │   └── Login.tsx        # 登录页（admin / 123456）
│       ├── layout/
│       │   └── Sidebar.tsx      # 左侧导航栏（w-16），引用 /Logo.png（缺失）
│       ├── dashboard/
│       │   └── Dashboard.tsx    # 总体概况仪表盘
│       ├── projects/
│       │   └── ProjectLibrary.tsx  # 项目库列表
│       ├── workspace/
│       │   ├── VideoWorkspace.tsx  # 核心分割工作区布局（32 行）
│       │   ├── CanvasArea.tsx      # Konva 画布（缩放/平移/选点，140 行）
│       │   ├── ToolsPalette.tsx    # 左侧工具栏
│       │   ├── OntologyInspector.tsx  # 右侧本体/属性检查面板
│       │   └── FrameTimeline.tsx   # 底部时间轴
│       ├── ai/
│       │   └── AISegmentation.tsx  # AI 智能分割引擎界面
│       └── templates/
│           └── TemplateRegistry.tsx  # 模板库管理
```

---

## 四、模块与路由

`App.tsx` 中 `activeModule` 状态控制当前显示模块：

| 模块标识 | 组件 | 功能 |
|----------|------|------|
| `dashboard` | Dashboard.tsx | 总体概况仪表盘 |
| `projects` | ProjectLibrary.tsx | 项目库列表 |
| `ai` | AISegmentation.tsx | AI 智能分割引擎 |
| `workspace` | VideoWorkspace.tsx | 核心分割工作区（默认进入） |
| `templates` | TemplateRegistry.tsx | 模板库管理 |

**未登录时全局拦截**，显示 `Login` 组件。

---

## 五、后端 API

`server.ts` 提供以下端点（内存数据存储，无数据库）：

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | /api/login | 认证，固定用户名 admin / 密码 123456 |
| GET  | /api/projects | 返回项目列表 |
| GET  | /api/templates | 返回模板列表 |

---

## 六、已知问题与风险

| 问题 | 影响 | 状态 |
|------|------|------|
| `Sidebar.tsx` 引用 `/Logo.png`，文件不存在 | 运行时 404 | 待修复 |
| 硬编码登录凭据（admin/123456） | 安全风险 | 已知，需替换 |
| 使用 fake JWT token | 无实际签名验证 | 已知 |
| 内存数据存储 | 服务重启数据丢失 | 设计如此 |
| 未配置 CORS / Helmet | 安全头缺失 | 待评估 |
| 无测试框架 | 无自动化测试 | 待引入 |

---

## 七、构建与部署

### 可用命令

```bash
npm install    # 安装依赖
npm run dev    # 开发模式（Express + Vite 中间件，端口 3000）
npm run build  # 生产构建（输出到 dist/）
npm run preview  # 预览生产构建
npm start      # 生产模式启动（需先 build）
npm run lint   # 类型检查
npm run clean  # 清理构建产物
```

### 环境变量

```bash
GEMINI_API_KEY    # Gemini AI API 密钥
APP_URL           # 应用托管 URL
DISABLE_HMR       # 设为 true 关闭 HMR（AI Studio 环境）
```

---

## 八、关键依赖

### 生产依赖
- react, react-dom
- @google/genai
- express
- konva, react-konva
- use-image
- lucide-react
- motion
- clsx, tailwind-merge
- tailwindcss

### 开发依赖
- vite
- @vitejs/plugin-react
- typescript
- @types/react, @types/react-dom, @types/express, @types/node

---

## 九、代码风格要点

1. **深色主题**: 全局背景 `#0a0a0a`、`#111`、`#0d0d0d`、`#151515`、`#1e1e1e`
2. **强调色**: 青色 `cyan-400`/`cyan-500` 用于激活状态
3. **工具类优先**: TailwindCSS 工具类，`cn()` 合并条件类名
4. **中文界面**: 所有 UI 文本必须使用中文
5. **函数组件**: 全部使用函数组件 + Hooks，无类组件
6. **PascalCase**: 组件文件名（如 `AISegmentation.tsx`）
7. **路径别名**: `@/*` 映射项目根目录

---

## 十、历史变更记录

| 时间 | 变更内容 | 关联文档 |
|------|----------|----------|
| 2026-04-28-22-55-15 | 建立代码编纂工作流 | `代码编纂工作流.md` |

---

> 本文件由 AI 助手根据项目实际内容生成。当项目结构或技术栈发生重大变化时，应同步更新本文档。