# AlgoStruct

**Repository Path**: tianshuangming/algo-struct

## Basic Information

- **Project Name**: AlgoStruct
- **Description**: AlgoStruct：专注于算法结构与优化的开源项目，提供高效算法实现及学习资源，助力开发者提升算法能力。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-22
- **Last Updated**: 2025-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: TypeScript, tsx, 算法

## README

# AlgoStruct

AlgoStruct 是一个专注于数据结构与算法的开源项目，提供规范的 TypeScript 实现与交互式可视化应用，帮助你更高效地学习与验证算法行为。

## 特性总览

- 模块化源码：`src/data-structures`、`src/algorithms`、`src/utils`、`src/tests`
- 完整工程规范：ESLint、Prettier、TypeScript 严格模式、Jest 测试覆盖
- 可视化应用：基于 `Vite + React + Ant Design` 的交互式演示（位于 `visualizer/`）
- 跨目录别名：`@ds` 指向 `src/data-structures`，在可视化中直接复用源码

## 目录结构

- `src/data-structures/linked-list.ts`：链表实现
- `src/data-structures/tree/*`：二叉搜索树等树结构实现
- `visualizer/src/components/*`：各数据结构可视化组件
- `visualizer/vite.config.ts`：别名与跨目录访问配置

## 安装与开发

1. 安装依赖（根目录）：`npm install`
2. 进入可视化应用：`cd visualizer && npm install`
3. 启动开发服务：`npm run dev`
4. 打开浏览器：`http://localhost:5173/`

## 可视化子项目说明与链接

- 子项目路径：`visualizer/`
- 入口文档：`visualizer/README.md`（包含分组路由、页面模式与模块化结构说明）
- 运行与访问：
  - `cd visualizer && npm install`
  - `npm run dev`，浏览器访问 `http://localhost:5173/`
- 模块化结构（已更新）：
  - 路由入口：`visualizer/src/routes/index.tsx`（统一导出 `routeElements`、`navConfig`、`buildMenuItems`、`getOpenKeysFromPath`、`getBreadcrumb`、`segmentedOptions`）
  - 导航配置与工具函数：`visualizer/src/routes/navConfig.ts`
  - 路由元素：`visualizer/src/routes/routeElements.tsx`
- 导航分组（最新）：`树与二叉树`、`链式结构`、`栈与队列`
- 应用入口引用：`visualizer/src/App.tsx` 通过 `import { ... } from './routes'` 从目录入口加载路由与导航。
- 顶部辅助切换：使用 `Segmented`（User / Team / Files），置于 Header 右侧
- 面包屑：移至内容区顶部，降低 Header 信息密度
- 响应式：Sider 在宽度不足时自动折叠，内容区自适应

### 已接入的可视化组件

- `BSTVisualizer`：
  - URL 子视图：`/bst`（概览）`/bst/search`（搜索）`/bst/validate`（验证）
  - 输入解析加固：过滤 `NaN`，无效搜索值提示“请输入有效数字”
  - 搜索高亮：仅在搜索模式下对命中节点高亮
- `LinkedListVisualizer`：头插 `prepend`、尾插 `append`，`Tag + RightOutlined` 渲染节点
- `StackVisualizer`：`push / pop`，栈顶高亮
- `QueueVisualizer`：`enqueue / dequeue`，队头高亮与方向箭头

### 路由与导航映射

- 路由：
  - `/bst`、`/bst/search`、`/bst/validate`
  - `/list`、`/stack`、`/queue`
  - 顶部辅助：`/user`、`/team`、`/files`
- 侧边导航：受控 `openKeys`，基于当前路径自动展开到对应层级；侧边栏内置滚动容器以适应更多模块

## 截图与动图示例

- 建议资源路径：
  - 截图：`visualizer/public/screenshots/`
  - 动图：`visualizer/public/gifs/`
- 文件命名建议：`<模块>-<场景>.png|gif`（示例：`bst-overview.png`、`bst-search.gif`）
- Markdown 引用示例：
  - `![BST 概览](visualizer/public/screenshots/bst-overview.png)`
  - `![BST 搜索演示](visualizer/public/gifs/bst-search.gif)`
- 录制建议：
  - Windows 推荐使用 `ScreenToGif`；或使用 `ffmpeg`（示例命令：`ffmpeg -i input.mp4 -vf "fps=12,scale=1024:-1:flags=lanczos" output.gif`）
  - 尽量控制宽度在 `1024px` 内，帧率 `10–15 fps`，避免过大文件体积

## 新增模块 Checklist（精简版）

- 代码实现：在 `src/data-structures/<your-struct>.ts` 完成实现并导出 API
- 可视化接入：
  - `visualizer/src/components/` 新建 `<YourStruct>Visualizer.tsx`
  - 在 `visualizer/src/App.tsx`：
    - 侧边导航 `items` 中添加分组或子项（叶子 `key` = 路由）
    - `Routes` 中注册组件路由
    - 面包屑显示名称（若需定制）
- 别名联动：若路径更改，同步更新 `visualizer/vite.config.ts` 的 `alias` 与 `server.fs.allow`
- 文档与演示：在 README 中补充说明与截图/动图
- 测试与质量：补 `src/tests/...` 测试；运行 `npm run lint`、`npm test`、`npm run format`

## 代码质量与测试

- 代码规范检查：`npm run lint`
- 自动修复：`npm run lint:fix`
- TypeScript 检查：`npx tsc --noEmit`
- 格式化：`npm run format`
- 运行测试：`npm test`
- 覆盖率：`npm run test:coverage`

## 常见问题

- 若可视化无法加载源码，请检查 `visualizer/vite.config.ts` 的 `server.fs.allow` 是否包含项目根目录
- 若提交时 `husky` 提示旧版脚本失效，请移除历史遗留的 `husky.sh` 调用

## 参与贡献

1. Fork 本仓库
2. 新建 `feat_xxx` 分支
3. 提交代码（自动进行规范检查与相关测试）
4. 发起 Pull Request（见本仓库 `.github/PULL_REQUEST_TEMPLATE.md`）

感谢所有为项目做出贡献的开发者！