一、项目概述

1.1项目背景与建设目标

重庆明珠果苑农业开发有限公司主营哈密瓜品种“玉露明珠”的种植与销售，走的是基地智慧化、数字化、精细化管理这条路。从种下去到卖出去，中间有基地档案、生产记录、渠道合作、库存出入、财务结算、内部审批一大堆事，靠人和表格撑不长久。为此我们自己搭了一套数字平台，并配套建了对外内容管理系统：对内把经营管理搬进系统，对外把品牌和内容展示出去。

本说明书讲清楚这套东西现在长成什么样、用了什么技术、哪些是我们自己设计的、以后怎么维护和扩展。它是后续接手、升级、交接的依据。

1.2建设范围

1.3设计原则

• 自主可控：业务代码全部独立成模块，与底层基座解耦。基座以后升级，我们的业务代码一行不用动；业务改需求，也不牵连基座。这是这套系统能长期维护的根本；
• 贴合业务，基地、渠道这些业务对象按我们自己的流程建模，表单、流程、报表都是照着真实经营场景做的；
• 表扩展而非新建：业务字段在已有主表上扩展，不重复造平行主表，数据一处维护、处处可用；
• 可回滚：所有配置改动都留 .bak 备份，出问题能逐项退回去。

二、总体架构

2.1技术栈总览

前后端源码的处理路径不一样，交付物也不一样。前端没有 Java 那种独立编译步骤，但打包本身就在承担编译：.vue、.ts 浏览器不认，必须经 Vite 转成 .js、.css 才能上线。两边对照如下：

2.2技术基座与命名沿革

我们这套系统不是从零写起的，底子是开源后台脚手架，一层一层继承下来。因此代码、文档、界面里会同时出现三个名字——若依、芋道、宇擎，它们不是三套系统，而是同一套东西的三代前身。若依（RuoYi）是 2018 年发布的开源地基，国内大量后台系统都由它长出来；芋道（yudao，原名 ruoyi-vue-pro）在若依之上重构成 Spring Boot 3 + JDK 17 + Vue 3 的模块化骨架，把单体拆成可插拔模块；宇擎（RuoYi Office）再在芋道之上封装成带业务模块的发行版，2026 年 2 月改成现在这个名字。我们是从宇擎这一代接过来用的。

记一条原则就够用：名字越往下越管底层，越往上越管业务。多租户、权限、工作流、代码生成这些框架机制，按芋道去找；业务模块怎么用、菜单怎么配，按宇擎去找；碰到 sys_ 开头的表、老式后台写法这类底层细节，才回到若依。版本号只认芋道那条线（2026.01-SNAPSHOT），若依时代的写法不能套在现在的代码上。

三者的身份，以及各自在本系统里留下的痕迹，对照如下：

工程目录也留着历史痕迹：后端在 H:\Ruoyi Office\ruoyi-office（目录名带 Ruoyi，编译产物却是 yudao-server.jar），前端在 H:\Ruoyi Office\ruoyi-office-vben。目录名不影响使用，不必改；备份、部署、找文件时认这两个路径就对了。

2.3前端技术体系

前端采用 Vue 3 全家桶，Vite 做构建，TypeScript 全程类型约束，组件库用 Ant Design Vue v4.2.6。工程上走 Monorepo，pnpm 管理依赖，实际应用在 apps/web-antd。

工程目录分三层，各管各的：apps 装可以跑起来的产品外壳，packages 装框架内核，internal 装构建工具链。apps 下面有五个应用，分别是 web-antd、web-ele、web-naive、web-tdesign、web-antdv-next，对应不同的 UI 组件库；真正编译部署的只有 web-antd，其余四个是框架自带的示例，留着备查。三者职责和升级时的处置方式如下表：

依赖是单向的：apps/web-antd 调 packages/effects/layouts，packages/effects/layouts 再调 packages/@core，一层比一层底层。升级的方向正好相反，只替换下游的框架包，apps 里的业务代码不在升级包内——vben 官方发布的升级内容只含 packages、internal 和根配置，不含各应用的 src/views、src/layouts 这些业务页面。所以框架升完级，我们在 apps 层写的东西还在；反过来，改在 packages 里的东西会被整体还原，一行都不留。

这里有两条要记牢。第一，不被覆盖是约定，不是机制保证：如果有人图省事整仓覆盖（git checkout 上游分支 — . 或整包解压），apps 一样会被冲掉，升级只能按目录挑选着替换。第二，apps/web-antd 里混着一批上游模板文件，src/views/_core、src/layouts、src/adapter、src/router/routes/core.ts 这些文件虽然在我们的目录里，内容却是框架自带的，我们只在上面改过一部分；升级时若上游也动了它们，git 合并会报冲突，必须逐个手工确认，不能一律取上游，也不能一律取本地。

按这条边界，我们自己的东西一律落在 apps 层。自定义配色板 mzgy-palette.ts 放在 apps/web-antd/src/，登录页改版也按这个走——整块舞台在 apps/web-antd/src/layouts/auth.vue 里自己实现，不去动 packages/effects/layouts 下的认证布局。需要改框架行为时，优先用插槽、覆盖配置、运行时替换来解决；确实非改 packages 不可的，改完要在这里补一笔，并在升级检查单里加一条“升级后需重新应用”。

主题不是简单换个色值：我们把整套莫兰迪绿做成 CSS 变量，侧边导航和顶栏统一深色，内容区浅灰绿底，登录页是独立舞台，样式和配色自成一套，不受后台布局主题影响。全局行为（比如官方文档提示条开关）通过 .env.production 环境变量控制，构建时一键切换，不用改代码。

权限菜单是登录后动态下发的：登录拿到身份，后端按角色返回可见菜单，前端据此渲染路由和按钮，不在前端写死权限表。

2.4后端技术体系

后端是 Java 17 + Spring Boot 单体服务，Maven 多模块组织，我们的业务代码放在独立模块里。多租户靠拦截器在请求层统一处理，每个租户看到自己的数据。Redis 8 做缓存，会话、字典、热点数据都走它，数据库压力小很多。

定时任务执行器内嵌在后端服务里，和调度中心之间走令牌鉴权，不开放裸端口。

整个系统代码规模：后端约 4680 个文件、40.5 万行（Java/XML/SQL/配置），前端约 4908 个文件、61.9 万行（Vue/TypeScript/样式），定时任务调度中心约 149 个文件、1.6 万行；合计约 9700 个源文件、104 万行代码。其中我们的业务代码在独立模块和前端应用目录里，框架自带模块不改动。

2.5数据与存储

业务库 PostgreSQL 16，库名 pgsql_mzgy，94 张业务表一次导入到位，跑在本机 Docker 容器里。Redis 8 同样容器化。两个库都只绑定本机回环地址，外网直接摸不到。

2.6域名与访问规划

中文域名转 punycode 后用于服务器配置和证书申请。平台租户 ID = 1（明珠果苑），超管账号 yanghsia（id=1）。

三、数字平台开发说明

3.1功能模块清单

3.2核心设计方法：业务对象映射

这是我们整套业务建模最关键的一个判断：现实中的“基地”映射成供应商对象，“渠道”映射成客户对象。这么做的好处是，采购、库存、销售、财务那套流程不用重写，天然就能跑通基地和渠道的业务。我们要做的是在这些对象上按自己的需求扩字段、加页面，而不是从零造一套主数据。

比如渠道管理，就是把渠道当客户经营：渠道档案、合作申请、资质审核、跟进记录、考核五个页面，加上原有的采购入库、销售出库、库存盘点、往来财务，正好拼成我们要的“产品—采购—库存—销售—财务”链路。需求长什么样，页面就长成什么样，没有为了通用而通用的多余功能。

接口上也有两条我们自己踩出来的规矩：下拉、选择类数据走不分页接口（/simple-list），不拿分页接口硬塞大 pageSize（后端单页上限 200）；批量查询先判空，列表空了就别生成 WHERE id IN () 这种非法 SQL。

3.3玉露明珠经营分析模型

这是我们围绕“玉露明珠”哈密瓜自己搭的一套经营分析模型，从田间数据一直通到利润决策。整体分四层，一层喂一层：

• 数据采集层：种植计划、茬次记录、生产日志、环境监测、病虫害、收购入库、销售出库，全量进系统，不事后补台账；
• 复盘看板层：单基地、单茬次一屏看全——投入多少、产量多少、卖了多少、剩多少；
• 横向对比层：多基地、多茬次放一起比，哪个基地成本高、哪个茬次卖得好，数字说话；
• 情景模拟层：两个我们自己设计的核心模型——盈亏平衡分析，算清楚一亩地、一茬瓜做到什么产量什么价才不亏；价格×产量敏感性矩阵，价格和产量两个变量一动，利润怎么变一眼看出来。

模型要准，靠数据“喂”。明年春茬开始录入真实生产数据，每一茬的单产、成本构成、损耗率、收购价都进库，模型参数随之校准。录得越全、茬次越多，模型越接近真实经营，往后是早种晚种、扩不扩基地、定价定多少，都拿它当尺子。

另外，平台物联管理模块已预留设备接入、告警中心、规则引擎，等基地环境监测设备上线，温湿度、土壤数据直接进库，模型的数据采集层还能再自动一截。

3.4哈密瓜病虫害识别辅助模型

这是我们给基层技术人员做的一件实事：在田间遇到病瓜病叶，掏出手机就能知道是什么病、该用什么药。模型围绕“玉露明珠”主栽品种和重庆本地气候建，不是通用识别工具，只认我们这块地常见的那些病。

分两步走：

• 第一步，特征知识库：先把常见病害（茎腐病、蔓枯病、白粉病、霜霉病、蚜虫等）整理成特征卡——病斑颜色、形状、位置（茎杆流油还是叶片发黄）、发生条件，基层人员按症状勾选或描述，模型给出候选病害、典型特征对照和防治用药方案；
• 第二步，图像识别：积累足够多田间照片后，再上拍照识别，拍病斑直接出结果，识别结果带置信度，拿不准的转人工复核。

每次诊断都和生产记录联动：自动落到对应基地、茬次、地块，形成“哪块地哪茬容易生什么病”的历史台账。诊断结果经技术人员复核后回流成样本，越用越准。

目前先把特征知识库跑起来，明年春茬边用边攒照片，为后续图像识别打基础。

3.5权限与多租户模型

平台是多租户架构，明珠果苑自己是租户 ID = 1。权限设计我们想清楚了两件事：什么样的关系用“租户”，什么样的关系用“部门树”。

• 平级隔离用租户：每个基地、每个伙伴一个独立租户，数据按 tenant_id 硬隔离，基地之间、伙伴之间互不可见；租户配独立套餐（menuIds），套餐里有什么菜单，这个租户才能看见什么；
• 上下级用部门树：渠道体系有一、二、三级，上级要看下级的数。这套不走租户，走系统租户里的部门树加数据权限——渠道角色数据权限设为“本部门及以下”，一级渠道能看自己加所有下级，二级、三级层层收敛，同级之间天然互不可见，这是原生能力，零开发；
• C 端与后台分离：游客和商城会员走会员体系（member_user），不给 C 端建后台账号；员工、渠道人员都在系统租户内，靠角色分菜单、靠部门分数据；
• 超管看全局：明珠果苑作为系统租户，admin 跨租户汇总看全部数据，出汇总报表。

角色已按业务配好：技术总监、人事总监、市场总监、访客等五套角色，菜单批量授权，分别约 315、246、500、473 项，该看的能看、不该看的摸不着。后续新增菜单要同步进租户套餐，租户才看得见。

3.6定时任务平台化

定时任务以前是散在服务器 crontab 里的，看不见、管不着。我们把 XXL-Job 2.4.0 调度中心部署在本机，9090 端口只绑回环地址，systemd 托管，单独一个 xxl_job 库，跟业务库物理隔离。

管理后台是我们自己集成进数字平台的：任务列表、手动执行、启停、执行日志（时长、状态、结果）全在平台页面上完成，不用再登录调度中心。执行器内嵌在后端服务里，端口 9999，走令牌鉴权。对接过程中我们修了三个坑：分页接口返回 DataTables 格式解析错误、执行时长显示 null、多租户结果把原始 JSON 直接吐出来。现在这套东西在平台里已经能用了。

3.7菜单配置与占位页规范

平台的菜单不是写死在前端，也不在后端源码里，而是由数据库 system_menu 表驱动：登录后后端按角色查表下发，前端据此渲染路由和按钮。所以增删改菜单只改库，不用重新打包后端，也不用动前端源码。菜单分三类：目录只做分组、菜单对应一个页面、按钮对应一个权限点。

落库后现状：一级菜单 8 个，全部条目 1307 条，其中目录 90、菜单 322、按钮 895；322 个页面里有 62 个挂的是统一占位组件，6 个是外链。完整结构见附录 A，落库的执行步骤见《部署手册》5.6。

图标统一用 Element Plus 的 ep: 前缀，当前 185 条在用。补图标前先核对图标名在当前版本里真实存在——ep:storage、ep:code 在现用版本中并不存在，已分别换成 ep:files、ep:magic-stick，凭印象写只会留下空白。按钮不需要图标，留空字符串即可；空值不渲染，比写“#”干净。

目录已建、页面未开发的，统一挂 common/coming-soon/index 占位页：莫兰迪绿、文案“功能建设中·敬请期待”，并关闭缓存。页面开发完成后，把该菜单的 component 改指真实页面即可，不必新建目录、不必调整层级。这 62 个菜单点开看到占位页是预期，不是故障。

四、内容管理系统开发说明

4.1部署与目录

内容管理系统跑在 WordPress 上，站点根目录是服务器 /www/wwwroot/明珠果苑.com，主题是我们自己写的 mzgy01。前后台都按莫兰迪品牌色系定制。我们不直接动生产目录的文件，成品在独立目录做好，确认无误再覆盖上去。

4.2主题开发 mzgy01

前期前台顶部管理栏，视觉不佳，还跟主题导航抢层级，导致注销按钮看得见点不着。我们干脆把前台管理栏整个关掉，头部模板做成两套分支：没登录显示注册/登录按钮；登录后显示圆形头像、用户名和下拉菜单（个人资料、进入后台、退出登录），菜单支持点击展开、点空白和 Esc 关闭。退出链接专门的函数生成，带校验参数，安全上有保障。

后台也历经修改：管理栏通栏拉通，侧栏退到顶栏下面；顶栏高度收敛成一个样式变量，全站（侧栏定位、内容区偏移、按钮尺寸）都认这一个数，移动端只改变量就行，不再各处硬编码。这个改动顺手把编辑文章时工具条被顶栏压住的毛病也治了。

后台界面的样式——标徽、侧栏、一级与二级菜单、悬停态——全部收在一个文件里：wp-content/themes/mzgy01/assets/css/admin.css，前台样式各管各的，改后台不影响前台。样式表版本号改用 filemtime() 取文件修改时间，改完保存即生效，不用手动改版本号，也不用让访客强刷缓存。

这套皮肤有三处要留意，都是 WordPress 核心自带的装饰和我们自己的样式叠在一起造成的。一是菜单右侧的三角：7.x 起核心不再输出 .wp-menu-arrow 元素，改用纯 CSS 边框画三角，分别落在 a::after（当前项，浅色）和 li::after（悬停态，深色）上，而主题又用 a::after 放自己的「>」箭头，两者会叠；凡自绘箭头的主题都要把这两层 border 清零，并把 position、top、right、margin-top 复位，否则箭头会被核心的 absolute 加 right:0 加 margin-top:-8px 挪出正常位置。二是子菜单悬停时左侧会出现一撇白色「(」：核心 #adminmenu a:hover 带 box-shadow: inset 4px 0 0 0 currentColor，是 WP 原生的悬停亮条，它本要求直角，但主题给子菜单设了 9px 圆角，4px 竖条两端被裁成圆弧，就成了括号；子菜单项必须显式写 box-shadow:none。三是侧栏滚动条滑块：4px 宽、白色半透明、带圆角，贴在侧栏最右缘，很容易被当成菜单上的杂色符号，现已隐藏滚动条本身，滚轮照常可滚。

4.3插件体系

主题管外观，插件管行为。我们自己增写了三个插件：

内容卫士这套设计的好处是换主题也不会把权限控制弄丢——判断逻辑在插件钩子里，不在主题文件里。以后要按角色细分（比如只让订阅者以上看文章），把登录判断换成权限判断就行，改动很小。

4.4内容访问控制

内容以“是否登录”划线：列表页谁都能看标题，文章详情必须登录。正文上叠了全屏水印又禁了复制，外面想扒内容不容易。管理员账号不受这套限制，日常编辑不受影响。

4.5维护模式操作说明

• 开启：后台 → 设置 → 明珠果苑维护，勾选“网站维护中”保存，访客即见维护页；
• 关闭：取消勾选即恢复；
• 页面切换：插件目录有“建设中maintenance.php”“维护中maintenance.php”两个候选，把要用的那个重命名为 maintenance.php（去掉中文前缀）即生效，同目录只能有一个 maintenance.php，是重命名切换、不是覆盖；
• 改文案：直接编辑对应候选文件（维护中maintenance.php / 建设中maintenance.php），配色已按 #5B7B5E 配好；
• 如果以前用过静态 index.html 维护页，启用插件后把 Nginx index 顺序改回 index.php 优先，静态页改名留存，别让两套机制打架。

4.6后台界面与菜单机制

后台的视觉与交互都收在 admin.css 一个文件里，改后台不会牵动前台。侧栏顶部留出一块放标徽，正常状态 64×64、圆角 18 像素，侧栏折成图标条时缩到 50×50，侧栏内容整体下移到 104 像素处，标徽不压第一条菜单。一级菜单悬停只做背景与文字的颜色过渡，0.18 秒完成，不做位移——早先试过向右挪 3 像素的跳动效果，鼠标沿菜单往下扫时整列文字来回晃，眼睛累，已去掉。侧栏滚动条本身隐藏，滚轮照常可滚。

一级菜单的开合由两个类名区分：mzgy-open 是点开的，mzgy-collapsed 是点收的，两个都不带的是没动过的。没动过的菜单里，只有当前页所在的那一条默认展开，判定用 WordPress 自带的 wp-has-current-submenu。除此之外不再有别的规则，系统不会因为“你到了某个页面”去替你展开或收起已经点过的菜单。

点击的规则按当下是否展开分两种。收着的父菜单，点一下先展开，再照常跳到它的第一个子菜单——父菜单的链接地址本来就是第一个子项的地址，不需要另外计算；已经展开的父菜单，点一下就是收起，停在原地不跳转。每次点击的结果写进浏览器本地（localStorage，键名 mzgyAdminMenuStateV1，按菜单 id 记 1 或 0），刷新页面、跳到别的菜单页都按记忆还原。因此展开的菜单不会因为换了页面就自己合上，点开另一条也不会把这条收掉，多条菜单可以同时展开。要恢复成默认状态（只展开当前页那一条），在后台按 F12 打开控制台，执行 localStorage.removeItem('mzgyAdminMenuStateV1') 后刷新即可。

这套开合机制改过四轮，两次偏差值得记下。一次只按“当前页”展开，跳转到子菜单后父项自己弹开，想合上却合不了，因为它在那一页仍然被判定为当前页；另一次补上了“点一下收起”的类名，样式表里却没有对应的规则，页面看着毫无反应——实际是脚本和样式没有同一批上线。凡是“点了没反应”的交互，先确认类名有没有加上去，再确认那个类名在样式表里有没有对应规则，两件事都成立才谈得上生效。

分类目录页由自制插件 mzgy-category-order 接管，当前版本 1.9。有下级的分类行前有一个 20×20 的方块按钮，点一下收起它全部子孙，再点展开；没有下级的行补一个同尺寸的隐形占位，保证同一列的分类名左右对齐，不补会差出 35 像素。列表顶部有“全部折叠 / 全部展开”，并显示“共 N 个分类，当前显示 M 个”。每页条数放到 999，避免父子分类被分页切开、上下级分在两页。

五、开发规范与约束

5.1操作规范

• 命令单行、简短、一次一条；临时文件用完就删，要新建先打招呼；
• 文件一律本地交付（.docx/.xlsx 等），不用在线协作文档；
• 工作日志命名 工作日志YYYYMMDD.docx，成品拿到手就能用。

5.2凭证与账号管理

数据库、Redis、调度中心这些敏感凭证专人保管，这份文档里不落明文。接环境用最小权限账号，定期轮换。超管账号 yanghsia 属明珠果苑租户（tenant_id=1）。

六、建设历程与里程碑

七、当前状态

7.1已完成并验证

平台搭建与上线、基地管理、渠道管理（购销存财闭环）、工作流 BPM、权限与多租户模型、定时任务平台内管理、系统性安全加固、全量备份体系、内容管理系统及配套插件体系。

附录 A平台菜单结构（八个一级菜单）

平台菜单按八个一级菜单组织，依次为管理首页、内容管理、商城管理、公司管理、基地管理、渠道管理、系统管理、平台运维。下表为 2026 年 10 月 26 日菜单重构落库后的实际结构，以生产库 system_menu 为准；表中“三级菜单”即挂在二级目录下的页面，标“—”的表示该二级项本身就是一个页面，不再分层。

附录 B软件与依赖清单

本附录列出本地开发机实际安装的软件、版本与用途，以及前后端的关键框架依赖。版本以实际安装为准，升级前请对照本表确认兼容性。生产环境的软件清单见《明珠果苑网站部署手册》附录 C。

（一）本地开发环境

（二）关键框架与依赖

附录 C菜单结构规划（交互式页面）

本附录为《数字管理平台菜单规划》交互式页面入口，文件位于 H:\系统备忘\常用\。该页面以独立 HTML 维护，作规划依据；实际结构以生产库 system_menu 为准，落库后回文档更新，双击下方链接可用浏览器打开。

数字管理平台菜单规划.html