# anni

**Repository Path**: veetine/anni

## Basic Information

- **Project Name**: anni
- **Description**: 现代化的 3D 数据标注 Web 应用程序。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 完整目录与文件功说明

## 📂 根目录结构

```
├── public/              # 静态资源
├── src/                 # 源代码
├── package.json         # 项目配置
├── vite.config.ts       # Vite构建配置
├── tsconfig.json        # TypeScript配置
├── tailwind.config.js   # Tailwind CSS配置
├── .eslintrc.cjs        # ESLint代码检查配置
└── env-config.ts        # 环境变量验证
```

---

## 🎯 项目概述

现代化的 3D 数据标注 Web 应用程序，允许用户对 3D 网格模型(Mesh)和点云(Point Cloud)进行交互式标注。该项目是一个完整的前端应用，需要与后端 API 配合使用，主要用于机器学习、计算机视觉等领域的数据标注工作。

**项目版本**: 0.1.4

**主要特性**:

-   支持网格和点云标注
-   多种标注工具
-   撤销/重做功能
-   用户认证
-   项目管理
-   协作标注

---

## 🗂️ 一级目录详解

### 1️⃣ `public/` - 公共静态资源目录

**功能**: 存放不需要构建处理的静态文件

| 文件            | 功能                                         |
| --------------- | -------------------------------------------- |
| `manifest.json` | PWA 应用清单文件，定义应用名称、图标等元数据 |

---

### 2️⃣ `src/` - 源代码根目录

包含所有应用程序源代码，分为 8 个主要子目录：

```
src/
├── annotator/      # 标注引擎核心（最重要）
├── api/            # 后端API接口层
├── ui/             # React用户界面层
├── entity/         # 数据实体定义
├── util/           # 工具函数库
├── i18n/           # 国际化翻译
├── assets/         # 静态资源（图标、图片）
├── index.tsx       # 应用入口
├── env-config.ts   # 环境变量配置
└── setupTests.ts   # 测试环境配置
```

---

## 📁 核心目录深度剖析

---

## 🎨 `src/annotator/` - 标注引擎核心目录

**总体功能**: 整个 3D 标注系统的核心引擎，负责 3D 场景渲染、标注管理、工具系统等

### 📂 `src/annotator/` 根文件

| 文件                       | 核心功能                           | 关键类/接口                                               |
| -------------------------- | ---------------------------------- | --------------------------------------------------------- |
| **Annotator.ts**           | 抽象标注器基类，定义标注器生命周期 | `abstract class Annotator<T extends Model>`               |
| **MeshAnnotator.ts**       | 网格模型标注器实现                 | `class MeshAnnotator extends Annotator<Mesh>`             |
| **PointCloudAnnotator.ts** | 点云模型标注器实现                 | `class PointCloudAnnotator extends Annotator<PointCloud>` |

**Annotator.ts 详细说明**:

-   定义设置阶段枚举: `SetupStage` (READ_MODEL_FILES → INITIALIZE_MODEL → CHECK_ANNOTATION_FILE → READ_ANNOTATION_DATA → LOAD_TOOLS → FINISHED)
-   提供抽象方法: `setup()`, `createScene()`, `createToolManager()`, `dispose()`
-   管理核心组件: FileManager, AnnotationManager, LabelManager, UndoManager

---

### 📂 `src/annotator/annotation/` - 标注数据管理

**功能**: 管理所有标注数据、标签、撤销重做操作

| 文件                     | 功能           | 关键方法                                                                    |
| ------------------------ | -------------- | --------------------------------------------------------------------------- |
| **AnnotationManager.ts** | 标注数据管理器 | `annotate()`, `removeAnnotation()`, `loadAnnotations()`, `getAnnotations()` |
| **LabelManager.ts**      | 标签管理器     | `getLabels()`, `setActiveLabel()`, `getLabelById()`, `getActiveLabelId()`   |

**AnnotationManager.ts 核心逻辑**:

```typescript
- 存储结构: Uint16Array (存储每个顶点/点的标注类ID)
- 订阅者模式: 标注变化时通知所有观察者
- 中性标签: 使用NEUTRAL_LABEL表示未标注区域
```

#### 📂 `src/annotator/annotation/undo/` - 撤销重做系统

| 文件                     | 功能               | 特点                                |
| ------------------------ | ------------------ | ----------------------------------- |
| **UndoManager.ts**       | 撤销管理器接口定义 | 定义 `undo()`, `redo()`, `record()` |
| **HybridUndoManager.ts** | 混合撤销管理器实现 | 支持单次和批量操作的撤销            |

---

### 📂 `src/annotator/anno3d/` - 标注文件解析与序列化

**功能**: 处理标注数据的保存和加载（自定义 anno3d 格式）

| 文件                               | 功能                         |
| ---------------------------------- | ---------------------------- |
| **AnnotationFileParser.ts**        | 标注文件解析器接口           |
| **AnnotationFileSerializer.ts**    | 标注文件序列化器接口         |
| **GenericAnnotationFileParser.ts** | 通用解析器，自动检测文件版本 |

#### 📂 `src/annotator/anno3d/UTF8v1/` - UTF8v1 格式实现

| 文件                                  | 功能                |
| ------------------------------------- | ------------------- |
| **AnnotationFileParserUTF8v1.ts**     | UTF8v1 格式解析器   |
| **AnnotationFileSerializerUTF8v1.ts** | UTF8v1 格式序列化器 |

**文件格式**: 自定义二进制格式，存储标注类 ID 数组

---

### 📂 `src/annotator/files/` - 文件系统管理

**功能**: 管理模型文件和标注文件的读写

| 文件                                  | 功能              | 核心技术                                  |
| ------------------------------------- | ----------------- | ----------------------------------------- |
| **FileManager.ts**                    | 文件管理器接口    | 定义文件 I/O 操作                         |
| **OriginPrivateFileSystemManager.ts** | OPFS 文件系统实现 | 使用浏览器 Origin Private File System API |

**OriginPrivateFileSystemManager 关键功能**:

-   本地缓存模型和标注文件
-   支持文件树导航
-   异步文件读写

---

### 📂 `src/annotator/scene/` - 3D 场景系统

**功能**: 管理 Three.js 3D 场景、渲染、相机、光照

#### 📂 `src/annotator/scene/` 根文件

| 文件                   | 功能         | 关键组件                                        |
| ---------------------- | ------------ | ----------------------------------------------- |
| **Scene.ts**           | 抽象场景基类 | 管理 Three.js Scene, Camera, Renderer, Lighting |
| **MeshScene.ts**       | 网格场景实现 | 渲染三角网格                                    |
| **PointCloudScene.ts** | 点云场景实现 | 渲染点云数据                                    |
| **SceneManager.ts**    | 场景管理器   | 统一管理场景、相机、渲染循环                    |
| **SceneSubject.ts**    | 场景主体接口 | 定义可更新对象                                  |
| **Camera.ts**          | 相机类型定义 | 透视/正交相机切换                               |

**Scene.ts 核心配置**:

```typescript
- 透视相机: FOV 30°, 裁剪范围 0.1 - 10000
- 正交相机: 视锥体大小 100, 裁剪范围 0.1 - 100000
- 背景颜色: #3C3C3C (深灰色)
- 渲染器: WebGLRenderer
```

---

#### 📂 `src/annotator/scene/model/` - 3D 模型系统

**功能**: 模型加载、构建、BVH 加速结构

##### 根文件

| 文件              | 功能         |
| ----------------- | ------------ |
| **Model.ts**      | 抽象模型基类 |
| **Mesh.ts**       | 三角网格模型 |
| **PointCloud.ts** | 点云模型     |

##### 📂 `src/annotator/scene/model/loader/` - 模型加载器

| 文件                 | 功能           | 支持格式         |
| -------------------- | -------------- | ---------------- |
| **Loader.ts**        | 加载器接口定义 | -                |
| **GenericLoader.ts** | 通用加载器     | 自动检测文件类型 |
| **TextureLoader.ts** | 纹理加载器     | 图片纹理         |

###### 📂 `src/annotator/scene/model/loader/obj/` - OBJ 文件加载

| 文件                        | 功能                        |
| --------------------------- | --------------------------- |
| **NonBlockingOBJLoader.ts** | 非阻塞 OBJ 加载器（主线程） |
| **BigFileOBJLoader.ts**     | 大文件 OBJ 加载器           |
| **OBJLoader.worker.ts**     | Web Worker 中的 OBJ 解析器  |

**支持**: `.obj` 文件，UTF8 编码，最大文件大小检测

###### 📂 `src/annotator/scene/model/loader/ply/` - PLY 文件加载

| 文件                        | 功能                        |
| --------------------------- | --------------------------- |
| **NonBlockingPLYLoader.ts** | 非阻塞 PLY 加载器（主线程） |
| **PLYLoader.worker.ts**     | Web Worker 中的 PLY 解析器  |

**支持**: `.ply` 文件，二进制和 ASCII 格式，大文件警告阈值

---

##### 📂 `src/annotator/scene/model/builder/` - 模型构建器

**功能**: 将加载的数据构建为 Three.js 可渲染对象

| 文件                     | 功能                                       |
| ------------------------ | ------------------------------------------ |
| **MeshBuilder.ts**       | 网格构建器，创建 BufferGeometry + Material |
| **PointCloudBuilder.ts** | 点云构建器，创建 Points 对象               |

###### 📂 `src/annotator/scene/model/builder/bvh/` - BVH 加速结构

**功能**: 为网格构建 Bounding Volume Hierarchy，加速射线检测

| 文件                         | 功能                     |
| ---------------------------- | ------------------------ |
| **NonBlockingBVHBuilder.ts** | 非阻塞 BVH 构建器        |
| **BVHBuilder.worker.ts**     | Web Worker 中的 BVH 构建 |
| **WorkerTypes.ts**           | Worker 通信类型定义      |

**性能优化**: 使用 three-mesh-bvh 库，在后台线程构建，不阻塞 UI

---

#### 📂 `src/annotator/scene/controls/` - 相机控制

**功能**: 用户交互控制相机视角

| 文件                         | 功能           |
| ---------------------------- | -------------- |
| **CameraControls.ts**        | 相机控制接口   |
| **ArcballCameraControls.ts** | 轨迹球控制实现 |

**控制方式**: 鼠标拖动旋转、滚轮缩放、右键平移

---

#### 📂 `src/annotator/scene/lighting/` - 场景光照

**功能**: 管理场景光源

| 文件                  | 功能             | Three.js 对象    |
| --------------------- | ---------------- | ---------------- |
| **SceneLighting.ts**  | 光照接口         | -                |
| **GlobalLighting.ts** | 全局环境光       | AmbientLight     |
| **SunLighting.ts**    | 平行光（太阳光） | DirectionalLight |

---

#### 📂 `src/annotator/scene/visualizer/` - 标注可视化

**功能**: 将标注数据可视化显示在 3D 模型上

| 文件                                  | 功能                       |
| ------------------------------------- | -------------------------- |
| **AnnotationVisualizer.ts**           | 可视化器接口               |
| **MeshAnnotationVisualizer.ts**       | 网格标注可视化（顶点着色） |
| **PointCloudAnnotationVisualizer.ts** | 点云标注可视化（点着色）   |

**可视化方式**: 根据标注类修改顶点/点的颜色属性

---

#### 📂 `src/annotator/scene/image/` - 图像渲染

**功能**: 将 3D 场景渲染为 2D 图像

| 文件                       | 功能               |
| -------------------------- | ------------------ |
| **ImageRenderer.ts**       | 图像渲染器接口     |
| **SimpleImageRenderer.ts** | 简单图像渲染器实现 |

---

### 📂 `src/annotator/tools/` - 标注工具系统

**功能**: 提供各种标注工具（笔刷、套索、多边形等）

#### 根文件

| 文件              | 功能           |
| ----------------- | -------------- |
| **Tool.ts**       | 抽象工具基类   |
| **ToolManger.ts** | 工具管理器基类 |

**Tool.ts 生命周期**:

```
load() → onLoad()         (加载资源)
select() → onSelected()   (激活工具，注册事件监听器)
update() → onUpdate()     (每帧更新，处理标注逻辑)
unselect() → onUnselected() (取消激活，移除监听器)
dispose() → onDispose()   (清理资源)
```

---

#### 📂 `src/annotator/tools/mesh/` - 网格标注工具

**功能**: 专门用于三角网格的标注工具

| 文件                   | 功能           |
| ---------------------- | -------------- |
| **MeshToolManager.ts** | 网格工具管理器 |

##### 📂 `src/annotator/tools/mesh/brush_3D/` - 网格 3D 笔刷

| 文件                                 | 功能                |
| ------------------------------------ | ------------------- |
| **MeshBrush3D.ts**                   | 3D 球形笔刷工具逻辑 |
| **MeshBrush3DButton.tsx**            | 工具按钮 UI 组件    |
| **MeshBrush3DQuickSettingsView.tsx** | 快速设置面板        |

**功能**: 基于 3D 球体范围标注网格顶点

##### 📂 `src/annotator/tools/mesh/lasso/` - 网格套索

| 文件                               | 功能         |
| ---------------------------------- | ------------ |
| **MeshLasso.ts**                   | 套索工具逻辑 |
| **MeshLassoButton.tsx**            | 工具按钮     |
| **MeshLassoQuickSettingsView.tsx** | 设置面板     |

**功能**: 绘制自由轮廓选择网格区域

##### 📂 `src/annotator/tools/mesh/polygon/` - 网格多边形

| 文件                                 | 功能           |
| ------------------------------------ | -------------- |
| **MeshPolygon.ts**                   | 多边形工具逻辑 |
| **MeshPolygonButton.tsx**            | 工具按钮       |
| **MeshPolygonQuickSettingsView.tsx** | 设置面板       |
| **MeshPolygonHelpContent.tsx**       | 帮助内容       |

**功能**: 点击创建多边形顶点，闭合后填充标注

---

#### 📂 `src/annotator/tools/point_cloud/` - 点云标注工具

**功能**: 专门用于点云的标注工具

| 文件                         | 功能           |
| ---------------------------- | -------------- |
| **PointCloudToolManager.ts** | 点云工具管理器 |

##### 📂 `src/annotator/tools/point_cloud/brush/` - 点云 2D 笔刷

| 文件                                     | 功能            |
| ---------------------------------------- | --------------- |
| **PointCloudBrush.ts**                   | 2D 圆形笔刷工具 |
| **PointCloudBrushButton.tsx**            | 工具按钮        |
| **PointCloudBrushQuickSettingsView.tsx** | 设置面板        |

**功能**: 基于屏幕空间 2D 圆形笔刷标注点云

##### 📂 `src/annotator/tools/point_cloud/brush_3D/` - 点云 3D 笔刷

| 文件                                       | 功能            |
| ------------------------------------------ | --------------- |
| **PointCloudBrush3D.ts**                   | 3D 球形笔刷工具 |
| **PointCloudBrush3DButton.tsx**            | 工具按钮        |
| **PointCloudBrush3DQuickSettingsView.tsx** | 设置面板        |

**功能**: 基于 3D 球体范围标注点云

##### 📂 `src/annotator/tools/point_cloud/lasso/` - 点云套索

| 文件                                     | 功能         |
| ---------------------------------------- | ------------ |
| **PointCloudLasso.ts**                   | 套索工具逻辑 |
| **PointCloudLassoButton.tsx**            | 工具按钮     |
| **PointCloudLassoQuickSettingsView.tsx** | 设置面板     |

---

#### 📂 `src/annotator/tools/common/` - 工具通用组件

**功能**: 工具系统共享的 UI 组件、数学工具、事件监听器

##### 📂 `src/annotator/tools/common/components/` - UI 组件

| 文件                     | 功能         |
| ------------------------ | ------------ |
| **Button.tsx**           | 通用按钮组件 |
| **DropDown.tsx**         | 下拉选择器   |
| **NumberInput.tsx**      | 数字输入框   |
| **PercentInput.tsx**     | 百分比输入框 |
| **RadioButtonGroup.tsx** | 单选按钮组   |
| **ToggleButton.tsx**     | 切换按钮     |

##### 📂 `src/annotator/tools/common/elements/` - 工具元素

###### 📂 `circle/` - 圆形元素

| 文件                   | 功能            |
| ---------------------- | --------------- |
| **Circle.ts**          | 2D 圆形绘制逻辑 |
| **CircleSettings.tsx** | 圆形参数设置 UI |

###### 📂 `sphere/` - 球体元素

| 文件                   | 功能            |
| ---------------------- | --------------- |
| **Sphere.ts**          | 3D 球体绘制逻辑 |
| **SphereSettings.tsx** | 球体参数设置 UI |

##### 📂 `src/annotator/tools/common/listener/` - 事件监听器

| 文件                         | 功能                    |
| ---------------------------- | ----------------------- |
| **Listener.ts**              | 监听器注册/注销工具函数 |
| **PointerListenerBundle.ts** | 鼠标/指针事件监听器包   |

##### 📂 `src/annotator/tools/common/math/` - 数学工具

| 文件             | 功能             |
| ---------------- | ---------------- |
| **MathUtils.ts** | 数学计算工具函数 |

##### 📂 `src/annotator/tools/common/undo/` - 撤销处理

| 文件                      | 功能               |
| ------------------------- | ------------------ |
| **PointerUndoHandler.ts** | 指针操作撤销处理器 |

---

### 📂 `src/annotator/three/` - Three.js 配置

| 文件                         | 功能                  |
| ---------------------------- | --------------------- |
| **three-mesh-bvh.config.ts** | three-mesh-bvh 库配置 |

---

### 📂 `src/annotator/__test__/` - 标注器单元测试

**功能**: 标注引擎的单元测试

#### 结构

```
__test__/
├── anno3d/
│   ├── AnnotationFileSerializer.test.ts
│   └── UTF8v1/
│       ├── AnnotationFileParserUTF8v1.test.ts
│       └── AnnotationFileSerializerUTF8v1.test.ts
└── annotation/
    ├── AnnotationManager.test.ts
    ├── LabelManager.test.ts
    └── undo/
        └── HybridUndoManager.test.ts
```

---

## 🌐 `src/api/` - API 接口层

**功能**: 与后端服务器通信的 API 层

### 根文件

| 文件          | 功能             |
| ------------- | ---------------- |
| **API.ts**    | API 接口定义     |
| **Errors.ts** | API 错误类型定义 |

---

### 📂 `src/api/v1/` - API v1 实现

**功能**: API 版本 1 的具体实现

| 文件         | 功能                      |
| ------------ | ------------------------- |
| **APIv1.ts** | API v1 主类，集成所有端点 |

**APIv1.ts 核心结构**:

```typescript
class APIv1 implements API {
	auth: Auth; // 用户认证
	users: Users; // 用户管理
	projects: Projects; // 项目管理
	models: Models; // 模型管理
	labels: Labels; // 标签管理
	files: Files; // 文件上传下载
}
```

---

#### 📂 `src/api/v1/endpoints/` - API 端点

**功能**: 各模块的 HTTP 请求实现

| 文件            | 端点功能 | 主要方法                                                                                         |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ |
| **Auth.ts**     | 用户认证 | `signIn()`, `signUp()`, `signOut()`, `getCurrentUser()`                                          |
| **Users.ts**    | 用户管理 | `getAll()`, `getById()`, `update()`                                                              |
| **Projects.ts** | 项目管理 | `getAll()`, `getById()`, `create()`, `update()`, `delete()`, `addUser()`, `removeUser()`         |
| **Models.ts**   | 模型管理 | `getAll()`, `getById()`, `create()`, `update()`, `delete()`, `lock()`, `unlock()`                |
| **Labels.ts**   | 标签管理 | `getAll()`, `getById()`, `create()`, `update()`, `delete()`                                      |
| **Files.ts**    | 文件操作 | `downloadModelData()`, `uploadModelData()`, `downloadAnnotationFile()`, `uploadAnnotationFile()` |

---

#### 📂 `src/api/v1/errors/` - 错误处理

| 文件                | 功能             |
| ------------------- | ---------------- |
| **ErrorHandler.ts** | Axios 错误处理器 |
| **ErrorTypes.ts**   | 错误类型枚举     |

**错误类型**:

-   `NETWORK` - 网络错误
-   `ABORTED` - 请求中止
-   `INVALID_CREDENTIALS` - 认证失败
-   `LOCKED` - 资源被锁定
-   `NO_ANNOTATION_FILE` - 标注文件不存在

---

#### 📂 `src/api/v1/logger/` - 日志系统

| 文件                   | 功能                     |
| ---------------------- | ------------------------ |
| **Logger.ts**          | HTTP 请求/响应日志记录器 |
| **ConsoleLogUtils.ts** | 控制台日志工具           |

---

#### 📂 `src/api/v1/resources/` - 资源转换

| 文件                   | 功能                    |
| ---------------------- | ----------------------- |
| **Resources.ts**       | 后端资源类型定义        |
| **Transformations.ts** | 后端数据 ↔ 前端实体转换 |

**关键转换**: 日期字符串 → Date 对象，用户/项目/模型数据格式转换

---

#### 📂 `src/api/v1/validation/` - 数据验证

| 文件              | 功能                            |
| ----------------- | ------------------------------- |
| **Validation.ts** | Zod 模式验证，验证 API 响应数据 |

---

### 📂 `src/api/__test__/` - API 测试

```
__test__/v1/
├── endpoints/
│   ├── Labels.test.ts
│   ├── Models.test.ts
│   ├── Projects.test.ts
│   └── Users.test.ts
├── resources/
│   └── Transformations.test.ts
└── validation/
    └── Validation.test.ts
```

---

## 🎨 `src/ui/` - 用户界面层

**功能**: React 组件、页面、上下文

### 根文件

| 文件            | 功能       |
| --------------- | ---------- |
| **App.tsx**     | 应用根组件 |
| **Routing.tsx** | 路由配置   |

**Routing.tsx 路由表**:

```
/ → ProjectOverviewPage (项目列表)
/project/:projectId → ProjectPage (项目详情)
/annotate/:annotatorId → AnnotatorPage (标注编辑器)
/login → SignInPage (登录)
/register → SignUpPage (注册)
```

---

### 📂 `src/ui/contexts/` - React 上下文

**功能**: 全局状态管理

| 文件                | 功能           |
| ------------------- | -------------- |
| **AuthContext.tsx** | 用户认证上下文 |
| **APIContext.tsx**  | API 实例上下文 |

---

### 📂 `src/ui/components/` - 通用组件

**功能**: 跨页面复用的 UI 组件

| 文件                       | 功能               |
| -------------------------- | ------------------ |
| **Header.tsx**             | 页面头部组件       |
| **StandardContainer.tsx**  | 标准容器布局       |
| **InnerItemContainer.tsx** | 内部条目容器       |
| **ElementList.tsx**        | 元素列表           |
| **LabelItem.tsx**          | 标签条目（只读）   |
| **LabelItemEditable.tsx**  | 标签条目（可编辑） |
| **UserItem.tsx**           | 用户条目（只读）   |
| **UserItemEditable.tsx**   | 用户条目（可编辑） |
| **ToolButton.tsx**         | 工具按钮           |
| **LanguageSelector.tsx**   | 语言选择器         |

---

### 📂 `src/ui/pages/` - 页面组件

**功能**: 完整页面视图

#### 📂 `src/ui/pages/projectOverview/` - 项目概览页

| 文件                        | 功能               |
| --------------------------- | ------------------ |
| **ProjectOverviewPage.tsx** | 项目列表页面主组件 |
| **AddProjectModal.tsx**     | 添加项目模态框     |

**功能**: 显示所有项目、创建新项目

---

#### 📂 `src/ui/pages/project/` - 项目详情页

| 文件                         | 功能               |
| ---------------------------- | ------------------ |
| **ProjectPage.tsx**          | 项目详情页面主组件 |
| **ModelDataItem.tsx**        | 模型数据条目       |
| **UpdateAnnotationFile.tsx** | 更新标注文件       |

##### 📂 `src/ui/pages/project/modals/` - 项目模态框

| 文件                         | 功能         |
| ---------------------------- | ------------ |
| **UpdateProjectModal.tsx**   | 编辑项目信息 |
| **UpdateMembersModal.tsx**   | 管理项目成员 |
| **LabelModal.tsx**           | 标签管理     |
| **UpdateModelDataModal.tsx** | 编辑模型数据 |

##### 📂 `src/ui/pages/project/addModel/` - 添加模型

| 文件                                | 功能           |
| ----------------------------------- | -------------- |
| **AddModelDataModalController.tsx** | 添加模型控制器 |
| **ModelDataPreviewItem.tsx**        | 模型预览条目   |

---

#### 📂 `src/ui/pages/userManagement/` - 用户管理页

| 文件                  | 功能     |
| --------------------- | -------- |
| **SignInPage.tsx**    | 登录页面 |
| **SignUpPage.tsx**    | 注册页面 |
| **SignOutButton.tsx** | 登出按钮 |

---

#### 📂 `src/ui/pages/notFound/` - 404 页面

| 文件                 | 功能         |
| -------------------- | ------------ |
| **NotFoundPage.tsx** | 404 错误页面 |

---

### 📂 `src/ui/annotator/` - 标注器页面

**功能**: 标注编辑器的 UI 层

#### 根文件

| 文件              | 功能             |
| ----------------- | ---------------- |
| **Annotator.tsx** | 标注器页面主组件 |

---

#### 📂 `src/ui/annotator/contexts/` - 标注器上下文

| 文件                     | 功能             |
| ------------------------ | ---------------- |
| **AnnotatorContext.tsx** | 标注器实例上下文 |

---

#### 📂 `src/ui/annotator/hooks/` - 标注器钩子

| 文件           | 功能              |
| -------------- | ----------------- |
| **Setup.tsx**  | 标注器初始化 Hook |
| **Tools.tsx**  | 工具管理 Hook     |
| **Labels.tsx** | 标签管理 Hook     |
| **Cursor.tsx** | 光标管理 Hook     |

**Setup.tsx 流程**: 初始化标注器 → 监听设置进度 → 处理错误 → 返回标注器实例

---

#### 📂 `src/ui/annotator/components/` - 标注器 UI 组件

| 文件                      | 功能               |
| ------------------------- | ------------------ |
| **LeftSidebar.tsx**       | 左侧工具栏         |
| **LabelMenu.tsx**         | 标签菜单           |
| **HeaderSettings.tsx**    | 顶部设置栏         |
| **CameraSettings.tsx**    | 相机参数设置       |
| **CameraPerspective.tsx** | 相机视角切换       |
| **LightingSettings.tsx**  | 光照强度调节       |
| **PointSettings.tsx**     | 点大小调节（点云） |
| **UndoRedo.tsx**          | 撤销/重做按钮      |
| **Eraser.tsx**            | 橡皮擦工具         |
| **SaveButton.tsx**        | 保存按钮           |
| **RenderButton.tsx**      | 渲染按钮           |
| **LoadingState.tsx**      | 加载状态显示       |
| **Stats.tsx**             | FPS 统计信息       |
| **Help.tsx**              | 帮助面板           |
| **ModelName.tsx**         | 模型名称显示       |

---

## 📊 `src/entity/` - 数据实体定义

**功能**: 应用程序的数据模型

| 文件                    | 定义的实体                                         |
| ----------------------- | -------------------------------------------------- |
| **User.ts**             | `User` - 用户信息                                  |
| **Project.ts**          | `Project`, `FullProject` - 项目信息                |
| **ModelInformation.ts** | `ModelInformation`, `FileInformation` - 模型元数据 |
| **Annotation.ts**       | `Label`, `Color`, `AnnotationData` - 标注相关      |
| **Types.ts**            | `Observer`, `Disposable`, `Updatable` - 通用接口   |
| **Language.ts**         | `Language` - 语言枚举                              |
| **Perspective.ts**      | `Perspective` - 相机视角枚举                       |

**核心实体关系**:

```
Project
  ├─ owner: User
  ├─ users: User[]
  ├─ labels: Label[]
  └─ models: ModelInformation[]
      ├─ modelFile: FileInformation
      └─ annotationFile: FileInformation
```

---

## 🛠️ `src/util/` - 工具函数库

**功能**: 通用工具函数

| 文件              | 功能                |
| ----------------- | ------------------- |
| **FileUtils.ts**  | 文件扩展名检查等    |
| **Three.ts**      | Three.js 工具函数   |
| **Timeout.ts**    | 超时处理            |
| **TypeScript.ts** | TypeScript 类型工具 |
| **Util.ts**       | 通用工具函数        |

---

### 📂 `src/util/streams/` - 流处理工具

**功能**: ReadableStream/WritableStream 处理

| 文件                                    | 功能                    |
| --------------------------------------- | ----------------------- |
| **StreamUtils.ts**                      | 流工具函数              |
| **BufferedLineReader.ts**               | 缓冲行读取器接口        |
| **ReadableStreamBufferedLineReader.ts** | ReadableStream 行读取器 |
| **BufferedWriter.ts**                   | 缓冲写入器接口          |
| **WritableStreamBufferedWriter.ts**     | WritableStream 写入器   |
| **ZIPUtils.ts**                         | ZIP 压缩工具            |

---

## 🌍 `src/i18n/` - 国际化

**功能**: 多语言支持

| 文件/目录              | 功能         |
| ---------------------- | ------------ |
| **formatters.ts**      | 格式化函数   |
| **vanilla-context.ts** | 国际化上下文 |
| **en/index.ts**        | 英语翻译     |
| **de/index.ts**        | 德语翻译     |

**支持语言**: 英语 (en), 德语 (de)

---

## 🎨 `src/assets/` - 静态资源

**功能**: 图标、图片等静态资源

### 📂 `src/assets/icons/` - 图标组件

| 文件                | 图标         |
| ------------------- | ------------ |
| **BritishFlag.tsx** | 英国国旗     |
| **GermanFlag.tsx**  | 德国国旗     |
| **Delete.tsx**      | 删除图标     |
| **Edit.tsx**        | 编辑图标     |
| **Help.tsx**        | 帮助图标     |
| **HelpFilled.tsx**  | 填充帮助图标 |
| **LockClosed.tsx**  | 锁定图标     |
| **LockOpen.tsx**    | 解锁图标     |
| **ModelName.tsx**   | 模型名称图标 |

### 📂 `src/assets/icons/perspective/` - 相机视角图标

存放透视/正交相机切换图标

---

## 🔧 配置文件详解

### 根目录配置文件

| 文件                   | 功能                | 关键配置                            |
| ---------------------- | ------------------- | ----------------------------------- |
| **package.json**       | NPM 项目配置        | 依赖、脚本、版本                    |
| **vite.config.ts**     | Vite 构建配置       | React 插件、路径别名、Worker 支持   |
| **tsconfig.json**      | TypeScript 编译配置 | 严格模式、路径别名(`~/*` → `src/*`) |
| **tailwind.config.js** | Tailwind CSS 配置   | DaisyUI 主题、Winter/Dark 主题      |
| **.eslintrc.cjs**      | ESLint 代码检查     | TypeScript 规则、命名规范           |
| **env-config.ts**      | 环境变量验证        | Zod 验证 API_BASE_URL 等            |

---

## 📝 其他重要文件

| 文件                       | 功能                            |
| -------------------------- | ------------------------------- |
| **src/index.tsx**          | 应用入口文件，ReactDOM.render() |
| **src/setupTests.ts**      | Vitest 测试环境配置             |
| **src/env.ts**             | 环境变量导出                    |
| **src/augmentations.d.ts** | TypeScript 类型增强             |

---

## 🧪 测试文件分布

```
src/
├── annotator/__test__/      # 标注引擎测试
├── api/__test__/            # API层测试
├── entity/__test__/         # 实体测试
└── util/__test__/           # 工具函数测试
```

---

## 📊 目录统计总结

| 目录             | 文件数 | 核心功能        |
| ---------------- | ------ | --------------- |
| `src/annotator/` | ~80    | 3D 标注引擎核心 |
| `src/api/`       | ~20    | 后端 API 通信   |
| `src/ui/`        | ~40    | React 用户界面  |
| `src/entity/`    | ~8     | 数据模型定义    |
| `src/util/`      | ~10    | 工具函数        |
| `src/i18n/`      | ~4     | 国际化          |
| `src/assets/`    | ~10    | 静态资源        |

---

## 🔑 关键技术流程图

### 用户交互流程

```
浏览器
  → React UI (src/ui/)
    → API Context (src/api/)
      → 后端服务器
```

### 标注流程

```
AnnotatorPage
  → Setup Hook (初始化)
    → Annotator (src/annotator/)
      → Scene (Three.js 3D渲染)
      → Tools (标注工具)
      → AnnotationManager (标注数据)
    → FileManager (文件I/O)
      → OPFS (本地存储)
```

### 标注器生命周期

```
构造 → Setup (多阶段)
  1. READ_MODEL_FILES (读取模型文件)
  2. INITIALIZE_MODEL (初始化3D模型)
  3. CHECK_ANNOTATION_FILE (检查标注文件)
  4. READ_ANNOTATION_DATA (读取标注数据)
  5. LOAD_TOOLS (加载工具)
  6. FINISHED (完成)
→ 运行 (渲染循环)
→ 保存 (保存标注)
→ 清理 (释放资源)
```

---

## 💡 技术栈总览

### 核心框架

-   **React 18.3.1** - UI 框架
-   **Three.js 0.169.0** - 3D 图形库
-   **TypeScript 5.6.2** - 类型系统
-   **Vite 4.4.4** - 构建工具

### 状态管理

-   **Zustand 4.5.5** - 轻量级状态管理
-   **React Context** - 全局状态共享

### 网络通信

-   **Axios 0.27.2** - HTTP 客户端
-   **neverthrow 8.0.0** - 函数式错误处理

### 样式与 UI

-   **Tailwind CSS 3.1.8** - Utility-first CSS
-   **DaisyUI 2.27.0** - 组件库
-   **lucide-react 0.446.0** - 图标库

### 3D 图形优化

-   **three-mesh-bvh 0.8.1** - BVH 加速结构
-   **Web Workers** - 后台线程处理

### 数据验证

-   **Zod 3.23.8** - 模式验证

### 国际化

-   **typesafe-i18n 5.26.2** - 类型安全的 i18n

### 测试

-   **Vitest 0.33.0** - 单元测试框架

### 代码质量

-   **ESLint 8.45.0** - 代码检查
-   **Prettier 2.8.8** - 代码格式化
-   **Husky 8.0.3** - Git 钩子

---

## 🚀 NPM 脚本命令

```bash
# 开发
pnpm start              # 启动开发服务器
pnpm build              # 构建生产版本
pnpm preview            # 预览生产构建

# 测试
pnpm test               # 运行测试
pnpm test:watch         # 监视模式运行测试
pnpm test:coverage      # 生成测试覆盖率报告

# 代码质量检查
pnpm checks:all         # 运行所有检查
pnpm checks:required    # 运行必需检查（TS、Lint、格式）
pnpm checks:optional    # 运行可选检查（Lint警告、拼写检查）

# TypeScript
pnpm ts                 # 类型检查
pnpm ts:watch           # 监视模式类型检查

# Lint
pnpm lint               # 代码检查
pnpm lint:warnings      # 检查警告（零警告策略）
pnpm lint:fix           # 自动修复

# 格式化
pnpm format             # 格式化代码
pnpm format:check       # 检查格式

# 国际化
pnpm i18n               # 生成i18n类型定义
pnpm i18n:watch         # 监视模式生成i18n类型

# 其他
pnpm spellcheck         # 拼写检查
pnpm prepare            # Husky安装
pnpm pre-commit         # Pre-commit钩子
```

---

## 🌟 项目特色与亮点

### 架构优势

1. **抽象设计** - 网格和点云通过共同接口支持
2. **组合模式** - 管理器组合实现功能模块化
3. **观察者模式** - 解耦数据和 UI 更新
4. **工厂模式** - 灵活的场景和工具创建

### 功能特性

1. **多类型支持** - 网格和点云两种 3D 数据类型
2. **灵活的工具系统** - 易于扩展新工具
3. **撤销/重做** - 完整的操作历史管理
4. **多用户协作** - 项目和模型共享
5. **国际化支持** - 多语言用户界面

### 性能优化

1. **WebGL 加速** - Three.js GPU 渲染
2. **BVH 加速结构** - 快速射线检测
3. **Web Workers** - 非阻塞文件加载和 BVH 构建
4. **OPFS** - 浏览器本地文件系统缓存
5. **流式处理** - 大文件处理

### 开发最佳实践

1. **类型安全** - TypeScript 严格模式
2. **函数式错误处理** - neverthrow Result 类型
3. **自动化测试** - Vitest 框架
4. **代码格式化** - Prettier 保证一致性
5. **Git 钩子** - Husky 自动化工作流

---

## 📚 环境变量配置

### 必需环境变量

```env
ANNOTATOR_3D_API_BASE_URL=http://127.0.0.1:8000/  # 后端API地址
```

### 可选环境变量

```env
ANNOTATOR_3D_DEBUG=false                    # 调试模式
ANNOTATOR_3D_LOGGING_LEVEL=0               # 日志级别(0-3)
ANNOTATOR_3D_SHOW_STATS=true               # 显示FPS统计
ANNOTATOR_3D_RESET_OPFS=false              # 清除本地文件系统
ANNOTATOR_3D_BACKEND_VERSION=0.1.0         # 版本信息
```