188 lines
6.3 KiB
Markdown
188 lines
6.3 KiB
Markdown
# 项目整体分析 — 语义分割系统（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 助手根据项目实际内容生成。当项目结构或技术栈发生重大变化时，应同步更新本文档。
|