# TECH_STACK.md

## 1. 目的
本文件锁定当前项目技术栈与精确版本，避免生成代码时发生版本漂移。

关联文档：
- PRD.md
- IMPLEMENTATION_PLAN.md

## 2. 运行环境
- Node.js: `24.11.0`
- npm: `11.6.1`
- OS（当前开发环境）: macOS

## 3. Web 框架与构建
- Vue: `3.5.28`
- Vite: `7.3.1`
- @vitejs/plugin-vue: `6.0.4`
- TypeScript: `5.9.3`
- vue-tsc: `3.2.4`

## 4. 核心业务依赖
- echarts: `5.6.0`
- papaparse: `5.5.3`
- xlsx (SheetJS): `0.18.5`

## 5. 代码质量与测试
- vitest: `3.2.4`
- eslint: `8.57.1`
- @typescript-eslint/eslint-plugin: `8.55.0`
- @typescript-eslint/parser: `8.55.0`
- eslint-plugin-vue: `9.33.0`
- vue-eslint-parser: `9.4.3`
- eslint-config-prettier: `10.1.8`
- prettier: `3.8.1`

## 6. 类型依赖
- @types/node: `24.10.13`
- @types/papaparse: `5.5.2`

## 7. NPM Scripts（唯一入口）
- `npm run dev`: 启动开发服务器
- `npm run build`: 类型检查 + 生产构建
- `npm run preview`: 预览构建产物
- `npm run type-check`: 仅类型检查
- `npm run lint`: ESLint 检查
- `npm run test`: Vitest 单测
- `npm run format`: Prettier 检查

## 8. 目录与模块边界
- `src/core/*`: 纯业务逻辑（解析、聚合、类型）
- `src/App.vue`: Web 页面与交互
- `src/styles.css`: 全局样式
- `src/theme-presets.ts`: 主题色预设
- `miniapp/pages/index/*`: 小程序页面与交互
- `miniapp/utils/sankey.js`: 小程序解析与聚合逻辑（含 xlsx 分流）
- `miniapp/README.md`: 小程序端能力与限制说明

## 9. 小程序运行时能力
- 运行平台：微信小程序原生运行时（非浏览器 DOM 环境）
- 文件读写：`wx.getFileSystemManager()`
- 图表绘制：`canvas` + `wx.createCanvasContext`
- 导出：
  - PNG：`wx.canvasToTempFilePath` + `wx.saveImageToPhotosAlbum`
  - SVG：生成 XML 字符串后写本地文件（`writeFile`）
- npm 依赖：小程序端 xlsx 解析依赖 `xlsx@0.18.5`，需在开发者工具执行“构建 npm”

## 10. 开发服务器约束
`vite.config.ts` 当前使用本地 HTTPS 证书路径：
- `~/mac.biboer.cn_ecc/fullchain.cer`
- `~/mac.biboer.cn_ecc/mac.biboer.cn.key`

若本机无该证书，`npm run dev` 需要先调整 Vite 配置。

## 11. 依赖治理规则
- 生产依赖新增/升级必须先确认。
- 版本锁定以 `package-lock.json` + 本文档为准。
- 未在本文档出现的库，默认不可在实现中使用。

## 12. 后端说明
当前无后端服务、无数据库、无认证（详见 BACKEND_STRUCTURE.md）。