2026-04-28-22-55-15 - 建立代码编纂工作流

2026-04-28 23:01:41 +08:00
parent 071ebf4b2a
commit cb0b99b4ca
7 changed files with 1013 additions and 0 deletions
--- a/工程分析/项目整体分析.md
+++ b/工程分析/项目整体分析.md
@@ -0,0 +1,187 @@
+# 项目整体分析 — 语义分割系统（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 助手根据项目实际内容生成。当项目结构或技术栈发生重大变化时，应同步更新本文档。