# 00 · 项目接手总览（技术栈 / 避坑 / 文档复核 统一入口）

> 本文是 zszq-trs 项目的**唯一接手入口文档**。所有"技术栈怎么学、哪里容易踩坑、现有文档准不准"都先读这一份。
> 模块级细节（某个字段互算、某个改进方案）见末尾「专项文档索引」，不要本文件里展开。
> 所有结论均来自对代码库的实际扫描（2026-07-29 核实），非凭印象。

---

## 一、一句话定位

这是一个 **ASP.NET Core (C#) 后端 + 老前端（jQuery 3.5.1 / Vue 2.6.14 / 内部 FastVue）+ 新前端（TypeScript + qiankun 微前端 V3）三栈并存** 的项目。
你以为要啃"古老"，其实主力是 **jQuery + Vue2 + FastVue**，且新模块已经走 **Vue3 微前端（otcdms-ui）**。约 **494 个存量页面**仍是 Razor 服务端渲染 + 老前端。

---

## 二、技术栈真实地图（实测）

| 层 | 真实技术 | 备注 |
|---|---|---|
| 后端 | ASP.NET Core (C#) | 146 个 Controllers/WebAPI；YLErpDAL 数据层；SignalR Hubs 实时推送 |
| 老前端（存量 ~494 页） | jQuery **3.5.1** + Vue **2.6.14** + 内部 **FastVue** | 以 bundle 全局加载；无 webpack/HMR |
| 后台管理区（Areas/Admin） | jQuery + Vue2 + **bootstrap-table** + toastr，打包为 `bundleV2.js` | 与主站 bundle **不同栈**：无 FastVue、无 jqGrid；仅 `Areas/Admin/_Layout.cshtml` 及其子页引用（如 OwnerInfo）。**与微前端无关** |
| 新前端微前端 | **qiankun 2.10.5** 加载子应用 **otcdms-ui**（Vue3） | 源码/构建在**另一仓库**；本仓库仅 `Views/V3/Index.cshtml` 宿主页经 `qiankun.registerMicroApps/start()` 加载 `/otcdms-ui/` |
| 控件 | layer(弹窗) / chosen / flatpickr / ueditor / bootstrap-table | layer 最高频 |
| 构建 | `bundleconfig.json` + `rebuild-bundles.py/ps1/sh` 手工打包 | 浏览器用 `?v=HtmlUtil.JsVersion` 缓存戳 |

> ⚠️ 常见误判：**不是 Vue 1.x，是 Vue 2.6.14；jQuery 也不是 1.x，是 3.5.1。** 另外项目已经用上 qiankun 微前端，别把它当纯古老项目。

---

## 三、高频技术优先级（按本项目真实文件数排序）

数字 = 在 `Views`/`wwwroot/Scripts` 中出现该技术的文件数，直接决定你把精力放哪。

| 技术 | 文件数 | 角色 | 学习优先级 |
|---|---:|---|---|
| Razor / `ViewBag` / `@section` / `HtmlUtil.JsVersion` | **494** | 服务端模板，几乎每页 | 🔴 必学 |
| jQuery（含 `$.ajax` **113**） | 全页 bundle | DOM 操作 + 数据请求 | 🔴 必学 |
| `layer` 弹窗 | **355** | 弹层/确认框，最高频控件 | 🔴 必学 |
| Vue 2.6（`new Vue(` **84**） + 内部 **FastVue**（**73**） | 84 / 73 | 表单与组件 | 🔴 必学（用 FastVue，不是裸 Vue） |
| `chosen`(40) / `flatpickr`(26) / `ueditor`(17) / `bootstrap-table`(14) | — | 下拉/日期/富文本/表格 | 🟡 按需 |
| SignalR Hubs | 后端 | 实时推送 | 🟡 后端侧 |
| qiankun / TS V2（otcdms-ui） | **2**（V3 宿主页） | 新微前端 | 🟢 只做新模块才碰 |

**结论**：别把时间砸在"现代前端工具链"上。老前端没有 webpack、没有 npm 打包、没有 HMR；你 80% 的活在 **jQuery + layer + Vue2(FastVue) + Razor** 这四样。

---

## 四、Java 老兵最易踩的 6 个坑

1. **改了 JS 页面没反应（最高频）** — 老前端不是实时编译。你改的是 `wwwroot/Scripts/` 源文件，必须经 `rebuild-bundles` 重新打包成 `bundles/*.js`，浏览器再靠 `?v=JsVersion` 缓存戳刷新。**没重跑构建 = 跑的还是旧 bundle。**
2. **jQuery 直接操作 Vue 管理的 DOM** — 灾难。`el:'#vueDiv'` 挂载后那块 DOM 归 Vue 管，别用 `$(el).html()` 改；反之 jQuery 控制的区域也别挂 Vue。
3. **Vue2 响应式陷阱**（和 Vue3 完全不同，无 Composition API）：给 `data` 对象**新增属性**必须 `this.$set(form,'x',val)`；**数组按索引赋值**不更新，用 `splice/push`；`v-for` 与 `v-if` 同元素时 **v-for 优先级更高**；组件 `data` 必须是函数。
4. **Razor / `ViewBag` 运行时炸** — 如 `RiskDailyReportLimit data = ViewBag.Data;` 若后端没塞值，服务端直接 **500**。这是 `dynamic` 无编译期检查，Java 的 Optional/类型安全在这里没有。
5. **script 加载顺序 + iframe** — jQuery/Vue 在 `_Layout.cshtml` 里先以 bundle 加载，业务脚本用 `@section JS` 注入；顺序错就 `$ is not defined`。很多页面嵌在 iframe 里（见 `window.parent.location.reload()`）。
6. **FastVue ≠ 原生 Vue** — 项目封了 `FastVue`（autocomplete / numberInput / Form 等）。新人常照原生 Vue 写而踩坑：**先读 `fastVue.base.js`/`components.js`/`form.js` 吃透约定**（表单绑定、组件注册），别裸写。

---

## 五、20 年 Java 老兵速成路径（借力优势）

你的优势很强，别从"前端小白"视角学，从"工程老手"视角映射：

- **强类型 → 直奔 V2 的 TypeScript**（`.mts/.mjs` 有类型，你最舒服，也最保值）。
- **OOP/分层 → 理解 FastVue 组件化**（本质是 Options API 封装，组件 = 数据/方法/生命周期，和写 Java Bean+方法没两样）。
- **后端经验 → 读契约**：直接看 `Controllers/WebAPI`（146 个）和 `Hubs`，搞清请求/响应字段，前端只是渲染。

**不要浪费时间**：别学 webpack 现代打包（老前端用不上）、别学 Vue3 Composition API（项目是 Vue2 Options API）、qiankun 只在新子应用出现（2 处）。

**里程碑顺序**：
1. 打通「改→构建→生效」闭环：本地 `start.dev.sh` 起服 → 改一个 cshtml 里的小 JS → 跑 `rebuild-bundles` → 浏览器看生效。（解决 80% 卡点）
2. 精读 3 个典型页对照：一个纯 jQuery、一个 `new Vue(`、一个 FastVue。
3. 通读 `fastVue.base.js / components.js / form.js` 三个封装文件。
4. jQuery 核心：选择器、`$().on` 事件委托（动态元素必须委托）、`$.ajax`/`Deferred`、`layer.open/confirm`。
5. Vue2 Options API：`data/methods/computed/watch/components/$set/$emit`。
6. 后端侧：读一个 Controller + 对应 ViewBag 数据来源，闭环理解契约。
7. 进阶（仅新模块）：TS + qiankun 接入方式。

---

## 六、现有文档准确性复核（踩坑指南 / 长期改进方案）

> 复核对象：《互换债券三字段互算踩坑总结与测试指南》《互换模块长期改进方案》（均已读，并与代码库逐项核对）。

### 6.1 经代码核实「准确」的部分（可放心照做）

| 项 | 核实结果 |
|---|---|
| 5 个根因（`.native` 被 jQuery 拦截 / 非 `data()` 属性不响应 / `$set` 同引用不触发 / `main.post` reject 不走 `.done` / 构建缓存路径） | ✅ 全部属实，且有代码佐证（`fastVue.base.js:488` 用 jQuery 绑 keydown；`swapTradeEdit.js:380` `$set`；`base/main.js:384` `deferred.reject`，且代码里已有 `⚠️【全局陷阱/接手必读】__post 的成败路由` 注释——文档结论已反哺代码） |
| `bundle.js` 体积 | ✅ 实测 800.8KB（文档 801KB） |
| `swapTradeEdit.js` 行数 | ✅ 实测 1963 行 |
| `FastVue.autocomplete(el,options,context)` / `numberInput(append/precision/negative)` 签名 | ✅ 与代码一致 |

### 6.2 需要修正的数字与一处自相矛盾

| 文档说法 | 实测（排除 node_modules） | 修正建议 |
|---|---|---|
| `new Vue` 组件 **67 个** | **88 文件 / 115 处** | 更新数字或注明统计口径（如"仅互换模块"） |
| JS 单测 **22 个文件** | **9 个 `.test.js`**（fe-tests） | 更新；当前远不到 22 |
| C# 单测 **133 文件 / 37933 行** | **261 个 `*Test*.cs`**（排除 obj/bin） | 重数并更新，注明统计范围 |
| `289 个 JS 文件` | 准确，但 = `wwwroot/Scripts` 自有脚本；全量（含 libs）是 **553** | 注明口径，避免与全量混淆 |

**内部矛盾**：《长期改进方案》2.3 写"前端组件测试 `@vue/test-utils` ✗ 缺失"，但同系列《踩坑总结》5.1 明确列了 `fastVue.enter.test.js` / `numberInput.paste.test.js` 已存在且全绿。两文档自相矛盾——实际上组件测试**已部分存在**，缺的是页面级集成测试。

### 6.3 最关键的补充：文档漏掉了真实的现代化路径（otcdms-ui / V3 微前端）

- 代码里已有一个**在跑的 Vue3 微前端**：`Views/V3/Index.cshtml:60-85` 有 `window.qiankun.registerMicroApps([{name:'vue3', entry:'/otcdms-ui/', activeRule:'/v3'}])` + `initGlobalState` + `start()`。
- 即 **otcdms-ui 是 Vue3 子应用，经 qiankun 嵌入 C# 主站**；跨应用通信用 `initGlobalState`/`actions.onGlobalStateChange`（见 V3 页 67-84 行）。
- 但《长期改进方案》把终态设为"纯 Vue2 组件化 + 去 jQuery + esbuild"，对 qiankun/V3/otcdms-ui/Vue3 **零提及**（grep 整个项目文档，仅《估值模块重构》在"否决方案"表里顺带提了 otcdms-ui 一句）。

**影响**：阶段 2/3 的目标与代码实际演进方向不一致。新人按文档会以为"还技术债 = 把老页面重写成 Vue2 原生"，但团队真实做法是「**新模块写 otcdms-ui(Vue3) 微前端，老模块只做稳定 + 补测试**」。

**建议修订动作**：
- [ ] 补一节「前端战略：otcdms-ui(Vue3) 微前端」——V3 宿主页、子应用接入规范、全局状态通信约定、独立构建与 C# 主站版本协同。
- [ ] 阶段 0/1（测试 + CI + 构建现代化）依然正确且最高优先级，但应明确"**仅用于老栈止血**"；阶段 2/3 改写为"老栈只做稳定+测试，新功能一律 otcdms-ui"。
- [ ] 另补一篇《V3/otcdms-ui 微前端接入与避坑》：qiankun JS 沙箱/样式隔离、public-path、全局变量污染、jQuery 全局 `$` 与沙箱冲突、子应用独立部署与缓存版本协同（当前完全无文档）。

### 6.4 其他建议

- [ ] 量化指标脚本化（如 `grep -rl "new Vue(" | wc -l`），避免再陈旧。
- [ ] 核实 CI 是否真接 jest：文档自己说"有 Jenkins 但不跑前端测试"。若仍如此，阶段 0 第一件事就是接 `npm test`。
- [ ] 后端解耦未覆盖：《估值模块重构》透露 otcdms-ui 仍"数据来自 C#，未实现解耦"，走 otcdms-ui 还需"Java 中转层"。微前端目前只是 UI 隔离，建议补一节 BFF/网关等后端解耦讨论。

---

## 七、专项文档索引（细节去这里，不要在本文件展开）

**踩坑 / 根因类**
- `互换债券三字段互算踩坑总结与测试指南.md` — EQD-6838 七次提交的根因全记录（本文 6.1 的根因均出自此）
- `互换模块长期改进方案.md` — 5 阶段改进路线（注意本文 6.2/6.3 的修正点）
- `互换模块可测性改造Seam实践指南.md` — 可测性改造手法
- `JS组件/FastVue.txt` — FastVue API（autocomplete / numberInput 签名）
- `JS组件/OTC项目Layer弹窗机制.docx` — layer 弹窗机制
- `JS组件/宽表格的水平滚动条处理.txt`、`JS组件/组合标的价格控件.docx`

**字段语义 / 命名类（最易引入新 bug）**
- `互换价格字段命名规范决策文档.md` — PosiNetPrice 名为 Net 实为含费全价，命名坑
- `MarkClosePnl字段语义统一决策文档.md`
- `互换交易价格字段存储与显示规范.md`
- `互换分红损益字段语义与重复计算分析.md`

**模块方案类**
- `互换模块独立化最终方案.md`
- `估值模块重构-前端改造说明.md` — 提及 otcdms-ui（见 6.3）
- `互换重收盘误删手动互换资金记录问题分析.md`、`互换收益结算审核后状态卡死阻止收盘问题分析.md`、`互换部分平仓后利息端预付金默认盈亏偏大问题分析.md`

**其他**
- `readme.txt` — 项目说明入口
- `API测试/`、`Python/`、`定价与估值/`、`数据库/`、`业务处理/` 各子目录

---

> 本文件为统一入口，专项细节请点上面的索引。若发现本文件与代码不符，以代码为准并回来更新这一份。