# REASONIX.md

## 项目概述

**microapp-vue3** — 基于 Vue 3 + TypeScript + Vite 的微前端子应用，使用 `@micro-zoe/micro-app` 框架集成到主应用中。同时集成了高德地图 JSAPI，提供地图展示、地理围栏、路径轨迹等功能。

- **类型**: 前端微应用（子应用）
- **运行环境**: 浏览器（支持独立运行 & micro-app 微前端环境）
- **默认端口**: `3001`

---

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Vue 3 (Composition API) | ^3.5 |
| 语言 | TypeScript | ~6.0 |
| 构建 | Vite | ^8.0 |
| 路由 | Vue Router | ^4.6 |
| 微前端 | @micro-zoe/micro-app | ^1.0.0-rc.31 |
| 地图 | @amap/amap-jsapi-loader | ^1.0.1 |

---

### 环境变量

在 `.env` 中配置高德地图 Key（以 `VITE_` 为前缀暴露给客户端）：

```
VITE_AMAP_JSAPI_KEY=<your-key>
VITE_AMAP_WEB_KEY=<your-web-key>
VITE_AMAP_SECURITY_CODE=<your-security-code>
```

---

## 架构设计

### 微前端生命周期

`src/main.ts` 中实现了 `mount()` / `unmount()` 两个生命周期函数：

- **微前端环境** (`window.__MICRO_APP_ENVIRONMENT__` 为 truthy)：导出 `{ mount, unmount }` 到 `window['micro-app-<appName>']`，由 micro-app 框架调用
- **独立运行**：直接调用 `mount()` 挂载到 `#microapp-vue3-root`

### 路由

- 使用 `createWebHistory`，`baseroute` 动态适配：
  - 微前端环境：使用 `window.__MICRO_APP_BASE_ROUTE__`
  - 独立运行：使用 `/`
- 所有路由均使用懒加载 (`() => import(...)`)
- 挂载点使用独立 id `#microapp-vue3-root`（避免与主应用 `#app` 冲突）

### 跨应用通信

通过 micro-app 的 `globalData` 机制实现：

- **发送**: `window.microApp.setGlobalData({ key: value })`
- **接收**: `window.microApp.addGlobalDataListener(callback, autoTrigger)`
- 示例见 `src/views/Home.vue` 中的共享计数器

### 高德地图集成

- **单例加载**: `loadAMap()` 确保 JSAPI 全局只加载一次，所有地图实例共享
- **Composable 模式**: `useAmap()` 返回 `containerRef`、`mapInstance`、`loading`、`error`、`initMap`、`destroyMap`
- **配置集中管理**: 所有 AMap 配置（Key、版本、插件列表）在 `src/config/amap.ts` 中统一维护
- **MapPanel 组件**: 每个 MapPanel 有独立的 DOM 容器和地图实例，可多个同时存在

---

## 编码规范

### Vue 组件

- 使用 `<script setup lang="ts">` 语法
- 样式默认 `scoped`，避免样式泄漏到主应用
- 全局样式使用 `#microapp-vue3-container` 选择器前缀隔离
- 组件命名：PascalCase 文件名（如 `MapPanel.vue`）

### TypeScript

- 启用严格检查：`noUnusedLocals`、`noUnusedParameters`、`noFallthroughCasesInSwitch`
- 使用 `erasableSyntaxOnly`（TS 6.0 特性）
- 路径别名：`@/` 映射到 `./src/`
- 环境变量类型通过 `vite-env.d.ts` 扩展

### Composable

- 文件命名：`use<Name>.ts`，放在 `src/composables/`
- 返回响应式状态 + 操作方法
- 使用 `onUnmounted` 清理资源（如销毁地图实例）

### 注释

- 使用中文注释，区块使用分隔线标记
- 重要配置项附带说明和官方文档链接

---

## 微前端注意事项

1. **挂载点命名**: 子应用挂载点不能使用 `#app`，必须使用独立命名的 id
2. **自定义元素**: 子应用中嵌套 `<micro-app>` 标签时，需要在 `vite.config.ts` 的 `vue.template.compilerOptions.isCustomElement` 中注册
3. **CORS**: 开发服务器需设置 `Access-Control-Allow-Origin: *` 允许主应用跨域请求
4. **base 路径**: 构建时需设置与主应用 `baseroute` 一致的 `base`（当前注释掉，独立运行时使用默认 `/`）
5. **样式隔离**: 全局样式使用子应用容器选择器前缀，组件样式使用 `scoped`


## 重要

在回答了用户问题，如果这个问题与项目相关，就要整理成面试题，在帮用户回答完问题之后，整理成面试题写入到docs/AMap面试题.md 中去，每个回答最好100行以内就能说明清楚。

尽量少出现源码，用文字说明清楚就可以了。

在原有的Q1，Q2的基础上累加问题，这个是用户最关心的内容，非常重要，请务必认真写。