starRiverProperty/docs/superpowers/specs/2026-04-29-frontend-source-design.md

# frontend-source/ 反编译与重建方案设计

**日期**: 2026-04-29
**版本**: 1.0
**状态**: 待审查

## 1. 背景与目标

### 背景
- `frontend/` 目录包含 28 个 Vue 2 + Element UI 前端应用，均为 webpack 构建的 dist 产物
- 原始源码（.vue / webpack.config.js / package.json）已丢失，无法找到
- 当前迭代中前端工作被跳过，但长期需要恢复前端功能拓展能力

### 目标
创建 `frontend-source/` 同级目录，分两阶段将 dist 产物转化为可维护的源码：

| 阶段 | 范围 | 目标 | 输出质量 |
|------|------|------|----------|
| 阶段 1 | 全部 28 个应用 | 反编译为可读源码 | B 级：代码可理解、可修改 |
| 阶段 2 | 4 个核心应用 | 重建为可构建工程 | C 级：可 `npm run build` |

## 2. 目录结构

```
反编译/
├── frontend/                              # 现有 dist 产物（只读）
└── frontend-source/                       # 新建目标目录
    ├── AGENTS.md
    ├── .gitignore                         # node_modules/
    │
    ├── decompiled/                        # 阶段 1 产物（B 级反编译）
    │   ├── cwos-portal/
    │   ├── elevator-front/
    │   ├── alarm-front/
    │   ├── front_acs/
    │   ├── ...（其余 24 个）
    │   │
    │   └── [每个应用结构]:
    │       ├── README.md                  # API 清单 + 路由表 + 组件树
    │       ├── src/
    │       │   ├── views/                 # 页面级模块
    │       │   ├── components/            # 自定义组件
    │       │   ├── api/                   # API 端点清单
    │       │   └── router/                # 路由定义
    │       ├── static/                    # CSS/img/font 复用
    │       └── index.html                 # 原样
    │
    ├── projects/                          # 阶段 2 产物（C 级重建）
    │   ├── cwos-portal/                   # 物业管理门户
    │   │   ├── package.json
    │   │   ├── vue.config.js
    │   │   ├── src/
    │   │   │   ├── main.js
    │   │   │   ├── App.vue
    │   │   │   ├── views/
    │   │   │   ├── components/
    │   │   │   ├── api/
    │   │   │   ├── router/
    │   │   │   └── store/
    │   │   └── public/
    │   ├── elevator-front/                # 电梯管理
    │   ├── alarm-front/                   # 报警管理
    │   └── front_acs/                     # 门禁管理
    │
    └── scripts/                           # 反编译工具
        ├── unpack-webpack.js              # webpack bundle 解包
        ├── extract-api-calls.js           # API 端点提取
        ├── extract-router.js              # 路由表提取
        ├── beautify-all.sh                # 批量格式化
        └── compare-output.sh              # 产物对比
```

## 3. 阶段 1：B 级反编译（全部 28 个）

### 3.1 反编译流水线

```
frontend/<app>/*.js  ──► [1. 解包] ──►  modules/*.raw.js
                                     ──► [2. 格式化] ──►  modules/*.formatted.js
                                                         ──► [3. 分析] ──►  api-calls.json
                                                                            router-tree.json
                                                                            component-tree.json
                                                                            ──► [4. 组织] ──► decompiled/<app>/
```

### 3.2 各步骤详细说明

**步骤 1 — 解包**
- 识别 webpack bundle 的模块结构（`__webpack_modules__` 或 `__webpack_require__`）
- 按模块 ID 拆分为独立文件
- 处理 chunk 文件的异步加载引用

**步骤 2 — 格式化**
- 使用 `js-beautify` 处理缩进、换行
- 使用 `prettier` 统一代码风格
- 保留注释（如有）

**步骤 3 — AST 分析**
- 使用 `@babel/parser` 解析格式化后的 JS
- 提取：
  - **API 调用**：`axios.get/post`、`this.$http` 等 HTTP 请求模式
  - **路由定义**：`vue-router` 的 `routes` 数组和 `path/component` 映射
  - **组件注册**：`Vue.component()`、`components: {}` 局部注册
  - **Element UI 引用**：`this.$message`、`el-form` 等使用点

**步骤 4 — 组织**
- 根据分析结果归类文件到 views/components/api/router
- 编写每应用的 README.md（API 清单、路由表、组件树）
- 原样复制 static/ 下的 CSS/img/font

### 3.3 28 个应用处理顺序

| 优先级 | 应用数 | 说明 |
|--------|--------|------|
| P0 | cwos-portal | 先跑通工具链验证 |
| P1 | elevator-front, alarm-front, front_acs | 阶段 2 目标 |
| P2 | canoe-account, canoe-car, canoe-device, canoe-person | Canoe 系列 |
| P3 | 其余 20 个 | 批量处理 |

## 4. 阶段 2：C 级重建（4 个核心）

### 4.1 技术栈

| 项 | 选用 | 理由 |
|----|------|------|
| 框架 | Vue 2.6 | 与原始一致（chunk-elementUI 确认） |
| UI 库 | Element UI 2.15 | 原始使用 Element UI |
| 构建 | Vue CLI 4.5 | 稳定版本 |
| HTTP | axios 0.21 | 与 V1 时代匹配 |
| 路由 | vue-router 3.x | 与 Vue 2 配套 |
| 状态管理 | vuex 3.x | 仅使用到的应用引入 |

### 4.2 重建流程（每个应用）

1. **工程脚手架**：`vue create` 或手动搭建 Vue 2 + Element UI 项目结构
2. **路由重建**：根据阶段 1 提取的 router-tree.json 还原 `router/index.js`
3. **API 层**：根据 api-calls.json 建立 `api/` 模块（axios 封装）
4. **页面重建**：逐页面创建 `.vue` SFC，参考原 dist 的 CSS 样式
5. **组件重建**：抽取可复用组件为独立 `.vue` 文件
6. **构建验证**：`npm run build` 并对比产物与原 dist

### 4.3 四个核心应用的重建重点

| 应用 | 预计页面数 | 核心功能 |
|------|-----------|----------|
| cwos-portal | 15-20 | 主框架布局、菜单树、仪表板、项目管理 |
| elevator-front | 10-15 | 电梯派梯、设备管理、楼层配置、通行规则 |
| alarm-front | 8-12 | 报警列表、规则配置、实时推送、统计 |
| front_acs | 10-15 | 门禁权限、区域管理、通行日志、人员管理 |

## 5. 工具脚本设计

### 5.1 `unpack-webpack.js`
```
输入: <app>/static/js/app.xxx.js
处理: 解析 webpack bundle 结构，按模块 ID 拆分
输出: modules/<module-id>.js
```

### 5.2 `extract-api-calls.js`
```
输入: modules/*.formatted.js
处理: AST 遍历查找 HTTP 调用模式
输出: api-calls.json (端点、方法、参数)
```

### 5.3 `extract-router.js`
```
输入: modules/*.formatted.js
处理: 查找 vue-router 的 routes 定义
输出: router-tree.json (path → component 映射)
```

### 5.4 `beautify-all.sh`
```
输入: modules/*.js
处理: 批量 js-beautify + prettier
输出: modules/*.formatted.js
```

## 6. 质量验证

### 阶段 1 验证
- [ ] 每个应用产出 README.md（含 API 清单、路由表）
- [ ] 代码通过 js-beautify 格式化
- [ ] 无原始混淆变量残留（至少重命名为有语义的名称）
- [ ] 与原 dist 的 CSS/img 完整对应

### 阶段 2 验证
- [ ] `npm install` 成功
- [ ] `npm run build` 成功
- [ ] 构建产物与原 dist 的页面数量一致
- [ ] API 端点覆盖与原一致

## 7. 风险与限制

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 变量名无法完全还原 | 代码可读性下降 | 通过上下文推断 + 手工标注语义名 |
| Vue SFC 无法自动还原 | 阶段 1 产物为 .js 而非 .vue | 阶段 2 手工重建为 .vue |
| webpack 配置不可知 | 构建配置需猜测 | 参考 Vue CLI 默认配置，按需调整 |
| 部分 Chunk 为第三方库 | 浪费分析时间 | 用文件名规则（chunk-libs、chunk-elementUI）过滤 |

## 8. 与现有仓库的集成

- `frontend-source/` 为新建独立目录，不修改 `frontend/`
- 加入根 `.gitignore` 白名单（类似 `frontend/` 的显式 `!` 规则）
- 产出 `frontend-source/AGENTS.md` 作为本目录说明
- 产出 `docs/superpowers/specs/` 下的本设计文档