项目整体分析 — 语义分割系统（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	安全头缺失	待评估
无测试框架	无自动化测试	待引入

七、构建与部署

可用命令

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

环境变量

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

九、代码风格要点

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

十、历史变更记录

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

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

6.3 KiB Raw Blame History Unescape Escape

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

一、项目基本信息

二、技术栈

三、目录结构

四、模块与路由

五、后端 API

六、已知问题与风险

七、构建与部署

可用命令

环境变量

八、关键依赖

生产依赖

开发依赖

九、代码风格要点

十、历史变更记录

6.3 KiB

Raw Blame History