12 KiB
12 KiB
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 个坑
- 改了 JS 页面没反应（最高频） — 老前端不是实时编译。你改的是
wwwroot/Scripts/源文件，必须经rebuild-bundles重新打包成bundles/*.js，浏览器再靠?v=JsVersion缓存戳刷新。没重跑构建 = 跑的还是旧 bundle。 - jQuery 直接操作 Vue 管理的 DOM — 灾难。
el:'#vueDiv'挂载后那块 DOM 归 Vue 管，别用$(el).html()改；反之 jQuery 控制的区域也别挂 Vue。 - Vue2 响应式陷阱（和 Vue3 完全不同，无 Composition API）：给
data对象新增属性必须this.$set(form,'x',val)；数组按索引赋值不更新，用splice/push；v-for与v-if同元素时 v-for 优先级更高；组件data必须是函数。 - Razor /
ViewBag运行时炸 — 如RiskDailyReportLimit data = ViewBag.Data;若后端没塞值，服务端直接 500。这是dynamic无编译期检查，Java 的 Optional/类型安全在这里没有。 - script 加载顺序 + iframe — jQuery/Vue 在
_Layout.cshtml里先以 bundle 加载，业务脚本用@section JS注入；顺序错就$ is not defined。很多页面嵌在 iframe 里（见window.parent.location.reload()）。 - 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 处）。
里程碑顺序：
- 打通「改→构建→生效」闭环：本地
start.dev.sh起服 → 改一个 cshtml 里的小 JS → 跑rebuild-bundles→ 浏览器看生效。（解决 80% 卡点） - 精读 3 个典型页对照：一个纯 jQuery、一个
new Vue(、一个 FastVue。 - 通读
fastVue.base.js / components.js / form.js三个封装文件。 - jQuery 核心：选择器、
$().on事件委托（动态元素必须委托）、$.ajax/Deferred、layer.open/confirm。 - Vue2 Options API：
data/methods/computed/watch/components/$set/$emit。 - 后端侧：读一个 Controller + 对应 ViewBag 数据来源，闭环理解契约。
- 进阶（仅新模块）：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/、定价与估值/、数据库/、业务处理/各子目录
本文件为统一入口，专项细节请点上面的索引。若发现本文件与代码不符，以代码为准并回来更新这一份。