《基于知识图谱和智能推荐的养老志愿服务系统》开发日志

基于现阶段系统架构的升级模块下一步开发--全景图

开发环境重新配置

完成了开发环境的搭建与配置：
- 后端环境： JDK1.8、Maven3.6.3、SpringBoot框架配置
- 前端环境： Node.js、Vue.js脚手架搭建
- 数据库环境： Neo4j图数据库安装与基础配置
- AI环境： 大语言模型相关依赖库准备

一、原系统核心模块挑战映射表

挑战序号	挑战名称	需改造的核心模块	改造深度	创新价值
挑战1	知识图谱本体设计	`dict`, `old`, `volunteer`, `activity`	颠覆性重构	从标签树到网络本体
挑战2	多源异构数据融合	所有`entity`, `param`, `service/impl`	流程再造	从清洗到知识抽取
挑战3	GraphRAG算法重构	`activity/service/impl`, `volunteer/service/impl`	算法革命	从相似度到图推理
挑战4	LLM协同机制	新增`llm`模块,改造`controller`层	架构扩展	从规则推荐到生成式推荐
挑战5	实时动态更新	`useractivityaction`, `activityrec`	性能跃迁	从日级批处理到秒级流处理
挑战6	可解释性溯源	新增`explainability`模块	功能新增	从黑盒到白盒推荐
挑战7	系统架构升级	`core`配置层,数据库层	基础设施升级	从单体到混合存储

二、各模块的具体更改与创新方向

模块1：`dict`模块 → 知识图谱本体管理中心

原功能：存储静态数据字典（活动类型、技能分类）

面临挑战：挑战1（本体设计）

改造创新：

实体类型定义 ：将原BizDictEnum扩展为OntologyClass，定义老人、志愿者、活动、技能、地点、时间等本体类
关系类型定义 ：新增RelationTypeEnum，定义需要服务、具备技能、可服务、地理位置邻近、时间冲突、社交信任等20+种关系
约束规则引擎 ：在dict模块中新增ConstraintRuleService，将原论文的硬约束/软约束转化为SWRL规则（如老人( ?x ) ^ 需求技能( ?x, ?s ) ^ 志愿者( ?y ) ^ 具备技能( ?y, ?s ) ^ 距离( ?x, ?y, ?d ) ^ swrlb:lessThan( ?d, 5 ) → 可推荐志愿者( ?x, ?y )）

技术突破 ：从扁平枚举到层级本体，支持推理机自动推导隐含关系（如"医护服务"是"医疗服务"的子类）

✅已完成任务：

1、dict模块→ 知识图谱本体管理中心

改造项	完成情况	说明
实体类型定义	✅ 已完成	扩展BizDictEnum为OntologyClass，定义老人、志愿者、活动、技能、地点、时间等本体类
关系类型定义	✅ 已完成	新增RelationTypeEnum，定义20+种关系（需要服务、具备技能、可服务、地理位置邻近、时间冲突、社交信任等）
约束规则引擎	✅ 已完成	新增ConstraintRuleService，将硬约束/软约束转化为SWRL规则

技术突破：实现基于SWRL的推荐规则引擎，示例规则：

复制代码

老人(?x) ∧ 需求技能(?x, ?s) ∧ 志愿者(?y) ∧ 具备技能(?y, ?s) ∧ 
距离(?x, ?y, ?d) ∧ swrlb:lessThan(?d, 5) → 可推荐志愿者(?x, ?y)

2、数据库本体化改造（核心基础设施）

2. 模块2：old实体层 → 知识图谱实体节点（已完成）

2.1 核心改造内容

文件清单（共10个文件）：

复制代码

/Users/like/Desktop/FYP/Code/newvolunteer-master 2/snowy-plugin/snowy-plugin-biz/src/main/java/vip/xiaonuo/biz/modular/old/
├── entity/BizOld.java                    # 核心实体类改造
├── enums/DataSourceTypeEnum.java         # 数据源类型枚举（新增）
├── enums/BizOldEnum.java                 # 扩展现有枚举
├── controller/BizOldController.java      # 控制器更新
├── param/BizOldAddParam.java             # 添加参数更新
├── param/BizOldEditParam.java            # 编辑参数更新
├── param/BizOldPageParam.java            # 分页参数更新
├── param/BizOldMergeParam.java           # 多源融合参数（新增）
├── service/BizOldService.java            # 服务接口更新
└── service/impl/BizOldServiceImpl.java   # 服务实现更新

模块2：`old`, `volunteer`, `activity`实体层 → 知识图谱实体节点

原功能：Java Bean映射MySQL表字段

面临挑战：挑战2（多源异构融合）

改造创新：

实体链接能力 ：为每个BizOld, BizVolunteer, BizActivity新增kgId字段（知识图谱全局唯一ID）
多版本管理 ：在entity包中新增EntityVersion嵌套类，记录同一实体在不同数据源（政务平台、社区登记、爬虫）的原始值，支持知识融合时的冲突检测
动态属性容器 ：将原固定字段（如serviceSkills）改造为Map<String, Object> dynamicProperties，容纳图谱中动态添加的属性（如老人"血压趋势"时序数据）

技术突破 ：从关系型表的"行"到知识图谱的"节点"，支持同一实体的多态性表达（志愿者既是"服务者"也是"社区邻居"）

模块3：`param`参数层 → Cypher查询构造器

原功能 ：封装前端请求参数（如BizActivityGetRecListParam）

面临挑战：挑战3（GraphRAG算法）

改造创新：

参数语义化 ：将oldId扩展为GraphQueryParam，包含主体实体ID、关系类型集合、筛选条件（距离<5km）、排序策略（按信任度）

Cypher生成器 ：在param包中新增CypherQueryBuilder类，将业务参数（如"需要医护服务、距离5km内、评分4.5以上"）自动转换为：

复制代码

MATCH (old:Old {id:$oldId})-[:HAS_NEED]->(s:Skill)
MATCH (v:Volunteer)-[:HAS_SKILL]->(s)
MATCH (v)-[:LOCATED_AT]->(loc:Location)
WITH old, v, point.distance(old.location, loc.coordinate) AS dist
WHERE dist < $distance AND v.rating > $minRating
RETURN v ORDER BY dist ASC LIMIT 10

技术突破 ：从SQL参数传递到Cypher动态生成，实现"业务意图→图查询"的自动转换

2月8日进度汇报：

系统启动成功 - Snowy框架已正常启动，端口82
数据库连接正常 - MySQL通过Druid连接池工作正常
Neo4j驱动已加载 - neo4j-java-driver/4.2.9 在classpath中
本体数据已初始化 - 养老领域本体（ONTOLOGY类别）已存在，系统提示"已初始化，跳过"
用户登录成功 -

模块4：`service/impl`业务实现层 → GraphRAG引擎

原功能：实现EVUP/EAUP算法（余弦相似度+约束条件）

面临挑战：挑战3（算法重构）、挑战4（LLM协同）

改造创新：

检索器-生成器分离 ：将原BizActivityServiceImpl拆分为：
- GraphRetrieverService（负责从Neo4j检索候选子图）
- LlmReasoningService（负责调用LLM生成推荐理由）
- RerankService（负责基于约束条件重排序）
混合检索策略 ：实现Hybrid Retrieval Strategy接口，支持：
- 向量检索：用Neo4j Vector Index找相似活动（原TF-IDF/BERT相似度升级）
- 图遍历检索：用Cypher找2跳关系内的志愿者（创新）
- 标签过滤检索：用硬约束快速剪枝（原功能保留）

LLM Prompt工程 ：在service/impl中新增PromptTemplateManager，将知识图谱子图序列化为自然语言：

复制

复制代码

老年人王奶奶的需求：{需求标签}，家住{住址}，健康状况{健康状态}。
候选志愿者信息：
- 志愿者A：{技能}，距离{距离}km，评分{评分}，历史服务{次数}次
- 志愿者B：...
请根据以上信息，推荐最合适的志愿者并解释原因。

技术突破 ：从单一相似度计算到"检索-生成-排序"三阶段流水线，推荐质量从"匹配"升级到"推理"

模块5：`useractivityaction`模块 → 实时事件流处理器

原功能：记录浏览/收藏/参与行为，日级更新画像

面临挑战：挑战5（实时动态更新）

改造创新：

事件驱动架构 ：将原有的MyBatis批量插入改造为Kafka消息队列，每个行为产生事件UserActionEvent
流式计算引擎 ：新增Flink Stream Processor模块，订阅行为事件，实时计算：
- 兴趣权重衰减：W_new = W_old * exp(-λ*(now - last_time))
- 标签热度更新：tag_heat = count_actions_in_window / time_window

增量图谱更新 ：在useractivityaction/service/impl中新增Neo4jIncrementalUpdater，行为发生后立即执行：

复制代码

MATCH (old:Old {id:$oldId})
MERGE (t:Tag {name:$tagName})
MERGE (old)-[r:INTERESTED_IN]->(t)
SET r.weight = r.weight + $delta, r.lastUpdate = timestamp()

技术突破 ：从"日级定时任务"到"秒级实时反馈"，老人刚浏览3个医疗活动，下一秒推荐列表即刷新

模块6：新增`explainability`模块 → 可解释性引擎

原功能缺失：原系统无专门解释模块，推荐结果黑盒

面临挑战：挑战6（可解释性溯源）

创新设计：

溯源服务层 ：新增TraceabilityService接口，实现两个核心方法：
- traceRetrievalPath(recommendationId): 返回从知识图谱检索到的所有路径
- generateExplanation(userId, itemId): 调用LLM生成自然语言解释

证据链存储 ：在activityrec模块的BizActivityRec实体中新增evidenceChain字段，JSON格式存储：

JSON

复制

复制代码

{
  "reasoningPaths": [
    "老人(.id) -[需要]-> 医护服务 -[匹配]-> 志愿者(3年经验) -[距离过滤]-> 3.2km"
  ],
  "constraintChecks": {
    "硬约束_地理距离": "通过(3.2km < 5km)",
    "软约束_文化水平": "不匹配(老人初中 vs 志愿者本科)"
  },
  "llmGeneratedReason": "推荐志愿者C因其3年护理经验且距离最近"
}

前端解释组件：在小程序端新增"为什么推荐"按钮，点击后弹出卡片，展示图谱路径可视化（节点-边-节点）+ 文字解释

技术突破 ：从"只给结果"到"展示推理过程"，满足老人对AI的信任需求，符合《算法推荐管理规定》的透明性要求

模块7：`core`配置层 + 数据存储层 → 混合架构底座

原功能：SpringBoot通用配置 + MySQL单库存储

面临挑战：挑战7（架构升级）

改造创新：

多模态数据库配置 ：在core/config中新增PolyglotPersistenceConfig
- Neo4j图数据库：存储本体、实体关系、动态兴趣边
- MySQL关系数据库：保留（存储用户账号、交易记录等强事务数据）
- Redis缓存：存储热点画像、推荐结果、会话Token
- MinIO对象存储：存储志愿者/活动图片、行为日志
分布式事务管理 ：新增DistributedTransactionManager，使用Seata框架保证跨库事务一致性（如预约时同时扣减活动名额+锁定志愿者时间+创建订单）
服务网关增强 ：在core中集成Spring Cloud Gateway，实现：
- 限流熔断（保护LLM接口）
- 请求染色（标记哪些是GraphRAG请求，便于监控）
- 响应脱敏（自动屏蔽老人隐私信息）

技术突破 ：从单一MySQL到"图+关系+缓存+对象"混合存储，支撑大规模知识图谱与高并发推荐

三、模块间协作流程的颠覆性变化

复制代码

老人点击"获取推荐" 
→ Controller调用Service计算相似度 
→ 返回List<BizVolunteer> 
→ 前端渲染

特点：线性、同步、无外部知识

新系统流程（GraphRAG+LLM）：

复制代码

老人语音输入"我血压高，想找会量血压的志愿者" 
→ Controller调用LlmIntentParser解析意图 
   （提取：需求=医护服务，症状=高血压） 
→ GraphRetrieverService在Neo4j中执行多跳查询：
   MATCH (old:Old) WHERE old.id=$userId 
   OPTIONAL MATCH (old)-[:HAS_HISTORY]->(d:Disease {name:"高血压"}) 
   MATCH (v:Volunteer)-[:CERTIFIED]->(c:Certification {skill:"量血压"}) 
   RETURN v, c.certificateLevel, point.distance(old.home, v.home) as dist 
→ RerankService按硬约束（距离<5km）+软约束（证书等级优先）排序 
→ LlmReasoningService调用文心一言生成解释：
   "为您推荐志愿者王医生，他持有高级护理证书，擅长高血压患者护理，
    距离您家3.2公里，历史服务评价4.8分"
→ EvidenceChainService记录所有推理路径到activityrec 
→ 前端展示推荐结果 + 可解释卡片

特点：异步、多阶段、融合符号推理（图）与神经网络（LLM）

四、创新总结：从"推荐系统"到"养老志愿认知服务平台"

维度	原系统（论文）	升级后系统（你的目标）	技术标志
知识表示	标签化的画像向量	网络化知识图谱（亿级三元组）	Neo4j图数据库
推荐逻辑	相似度计算 + 约束过滤	图遍历 + LLM推理 + 证据链	GraphRAG架构
数据更新	日级定时任务	秒级事件驱动	Kafka + Flink
用户交互	点击按钮获取列表	语音/自然语言对话式推荐	LLM意图理解
结果可信度	黑盒输出	白盒可追溯的推理过程	溯源服务层
系统边界	单个App应用	可对接社区、医院、政务平台的开放服务	API网关 + 微服务

【一】、newvolunter-master---Snowy 后端架构分析

一、架构设计理念

核心思想：插件化微内核架构

snowy-web-app 是轻量级主启动模块（微内核），仅负责加载和管理插件
业务功能完全插件化：每个功能模块独立成插件，可热插拔、独立升级
前后端分离：前端(Vue)与后端(SpringBoot)通过API解耦

1. snowy-common（基础通用层）

工具箱和基础设施，包含：

公共实体类、枚举、常量定义
统一异常处理、响应封装
通用工具类（如日期、加密、文件操作）
基础配置（Swagger、MyBatis、Neo4j连接等）
对你很重要：Neo4j客户端、LLM调用封装、分页组件等应放这里

2. **snowy-plugin-*（业务插件层）**

插件	养老系统适用场景	你可能的实现
`snowy-plugin-auth`	志愿者/管理员登录、JWT鉴权	手机号+验证码登录、实名认证
`snowy-plugin-sys`	系统管理（用户、部门、权限）	志愿者档案管理、社区组织架构
`snowy-plugin-biz`	核心业务	活动发布、服务记录、智能推荐 ⭐
`snowy-plugin-client`	C端小程序/APP接口	志愿者移动端：活动报名、服务时长查询
`snowy-plugin-gen`	代码生成器	快速生成CRUD：活动表、评价表
`snowy-plugin-dev`	开发辅助	知识图谱数据导入工具、测试数据生成

业务插件（snowy-plugin-biz）的模块化架构

bash 复制代码

snowy-plugin-biz/
├── core/                      # 插件级核心配置（如数据字典、业务常量）
└── modular/                   # 业务模块隔离层（微服务化的单体架构）
    ├── activity/              # 志愿活动管理（CRUD、推荐、预约）
    ├── activityrec/           # 活动推荐记录（历史推荐日志）
    ├── activityreserve/       # 活动预约管理（老人预约活动）
    ├── dict/                  # 数据字典（活动类型、状态等枚举）
    ├── old/                   # 老人档案管理
    ├── org/                   # 组织机构（社区、服务站）
    ├── position/              # 地理位置（活动地址、服务范围）
    ├── user/                  # 用户模块（登录用户扩展）
    ├── useractivityaction/    # 用户行为（收藏、点赞、报名）
    └── volunteer/             # 志愿者管理（技能、服务时长）

1、activity

模块名称	核心功能	Controller职责	Entity映射	Service业务逻辑	关键API端点	GraphRAG关联度
activity	志愿活动全生命周期管理	接收CRUD与推荐请求	`BizActivity`（活动表）	活动发布、智能推荐算法	`/recList`, `/page`, `/add`	⭐⭐⭐⭐⭐
activityrec	活动推荐历史记录	查询推荐日志	`BizActivityRec`（推荐记录表）	推荐效果追踪、日志存储	`/page`, `/add`	⭐⭐⭐
activityreserve	活动预约与报名	处理预约请求	`BizActivityReserve`（预约表）	库存锁定、状态流转	`/add`, `/edit`, `/myActivityReserve`	⭐⭐
dict	数据字典与枚举	提供下拉选项	`BizDict`（字典表）	常量管理、缓存	`/list`	⭐
old	老人档案管理	老人信息CRUD	`BizOld`（老人表）	档案维护、标签提取	`/page`, `/add`, `/detail`	⭐⭐⭐⭐
org	组织机构管理	社区/服务站CRUD	`BizOrg`（机构表）	层级管理、权限范围	`/page`, `/tree`	⭐⭐
position	地理位置服务	地址与坐标	`BizPosition`（位置表）	附近活动计算	`/nearby`	⭐⭐⭐
user	用户扩展信息	用户档案补充	`BizUser`（用户扩展表）	关联老人/志愿者身份	`/bind`, `/info`	⭐⭐
useractivityaction	用户行为追踪	记录交互事件	`BizUserActivityAction`（行为表）	行为分析、偏好学习	`/collect`, `/like`, `/view`	⭐⭐⭐⭐
volunteer	志愿者管理	志愿者CRUD	`BizVolunteer`（志愿者表）	技能认证、时长统计	`/page`, `/recList`, `/getListBySkill`	⭐⭐⭐⭐⭐

1. activity（志愿活动核心模块）

模块定位 ：系统的心脏，直接承载你的毕业设计创新点------基于知识图谱的智能推荐

类文件职责分层：

Controller层 ：BizActivityController
- getActivityRecList()：接收老人ID，调用Service的GraphRAG推荐算法
- 权限控制：原为@SaCheckPermission，现改为无条件开放（开发阶段）
- 日志记录：@CommonLog记录每次推荐请求，用于论文"系统测试"章节的数据来源

Entity层 ：BizActivity

复制代码

public class BizActivity {
    private String title;          // 活动标题（用于语义匹配）
    private String labels;         // 标签（知识图谱中的Skill节点）
    private String address;        // 地址（地理位置计算）
    private String publishTime;    // 发布时间（推荐排序因子）
    private String images;         // 图片（前端展示）
    // ...其他字段
}

Service层 ：BizActivityServiceImpl（你的算法主战场）
- GraphRAG查询 ：执行Cypher查询 MATCH (old:Old {id:?})-[:NEEDS]->(s:Skill)<-[:HAS_SKILL]-(v:Volunteer)-[:JOINED]->(a:Activity) RETURN a
- LLM调用：调用OpenAI/文心一言生成推荐理由："根据您的健康需求，推荐志愿者小李的义诊服务"
- 排序策略：综合地理位置（3km内优先）、技能匹配度（Neo4j关系权重）、发布时间（新活动加分）
Mapper层 ：BizActivityMapper.xml
- 基础CRUD：MyBatis-Plus自动生成
- 复杂推荐：在XML中编写Neo4j原生查询（如果通过JDBC连接）

数据流转示例：

复制代码

老人点击"获取推荐" 
→ Controller接收oldId=2018980167187218434 
→ Service调用Neo4j查询匹配活动 
→ 返回List<BizActivity> 
→ Controller封装为CommonResult 
→ 前端渲染活动卡片

论文价值：在"系统实现"章节，重点描述此模块如何结合Neo4j和LLM实现GraphRAG，体现技术创新。

2. volunteer（志愿者管理模块）

模块定位 ：推荐算法的关键参与者 ，志愿者是活动的供给方

核心设计：

Entity层 ：BizVolunteer
- skills：技能标签（知识图谱核心节点），如["医护", "陪伴", "家政"]
- serviceTime：累计服务时长（推荐排序因子：时长越高越可信）
- location：常驻位置（与老人地理位置匹配）
- rating：评分（老人评价影响推荐权重）
Service层 ：BizVolunteerServiceImpl
- 技能匹配算法 ：将BizActivity.labels与BizVolunteer.skills做交集，计算Jaccard相似度
- 可用性检查 ：查询志愿者空闲时间（通过activityreserve模块）
- 信誉计算：综合评分、服务完成率、投诉率生成信誉分
关键API：
- getVolunteerRecList(BizVolunteerGetRecListParam param)：为老人推荐志愿者
- getListBySkill(BizVolunteerGetListBySkillParam param)：根据活动技能需求查询匹配志愿者（调度用）

与GraphRAG关联：

复制代码

// 在Mapper.xml中
MATCH (v:Volunteer {id: ?})
OPTIONAL MATCH (v)-[:HAS_SKILL]->(s:Skill)
RETURN v, collect(s.name) as skills

毕业设计场景：当老人需要"上门义诊"时，系统通过此模块匹配具有"医护"技能的志愿者，并通过位置过滤3km内的服务者。

3. useractivityaction（用户行为分析模块）

模块定位 ：隐式反馈数据源，为推荐算法提供持续优化依据

核心功能：

行为类型枚举：
- VIEW：浏览活动（轻度兴趣）
- COLLECT：收藏活动（中度兴趣）
- LIKE：点赞活动/志愿者（强烈兴趣）
- RESERVE：预约活动（转化行为）
行为权重设计（用于协同过滤）：
- VIEW：权重1
- COLLECT：权重3
- LIKE：权重5
- RESERVE：权重10

API设计：

复制代码

@PostMapping("/biz/useractivityaction/add")
public CommonResult<String> addAction(@RequestBody BizUserActivityActionAddParam param) {
    // 参数：userId, actionType, targetId(活动ID), timestamp
    // 存储后触发推荐算法重算
}

GraphRAG增强：每次行为记录后，在Neo4j中创建关系：

复制代码

MATCH (old:Old {id: ?}), (a:Activity {id: ?})
CREATE (old)-[:VIEWED {weight: 1, timestamp: ?}]->(a)

后续推荐时，高权重关系优先展示。

论文价值 ：在"系统优化"章节，说明如何通过用户行为数据实现在线学习，持续优化推荐精度。

二、支撑模块（保障业务运行）

4. old（老人档案管理模块）

模块定位 ：推荐算法的"用户画像"来源

核心字段：

healthStatus：健康状况（高血压、糖尿病等）→ 匹配医疗类活动
hobbies：兴趣爱好（书法、太极）→ 匹配文化类活动
location：家庭地址 → 地理围栏推荐
emergencyContact：紧急联系人 → 安全审核

标签提取Service：

复制代码

public List<String> extractLabels(Long oldId) {
    // 根据健康状态、爱好生成标签
    // 如：老人有"高血压" → 生成"医疗"标签
    return labelList; // 存入Neo4j作为Skill节点
}

5. activityrec（推荐记录模块）

模块定位 ：推荐效果评估与审计

核心功能：

召回记录：存储每次推荐的结果集（用于离线评估）
点击流：老人是否点击查看详情
转化率：是否预约成功
性能指标：推荐耗时、LLM调用耗时

论文价值 ：在"实验结果"章节，通过查询此模块数据，计算准确率（Precision） 、召回率（Recall） 、覆盖率（Coverage） 等指标。

6. position（地理位置模块）

模块定位 ：LBS（基于位置的服务）核心

关键技术：

存储经纬度坐标
GeoHash编码（快速查询附近）
与腾讯地图/高德API对接

推荐算法集成：

复制代码

// 在Service中
double distance = calculateDistance(
    old.getLatitude(), old.getLongitude(),
    activity.getLatitude(), activity.getLongitude()
);
if (distance > 5.0) continue; // 过滤5km外的活动

三、基础设施模块（通用能力）

7. dict（数据字典模块）

模块定位 ：系统常量管理中心

管理内容：

活动类型：医疗服务、生活照料、文化娱乐
活动状态：草稿、已发布、已结束、已取消
标签库：技能标签、健康标签（与Neo4j节点同步）

设计优势：

前端下拉框动态加载
修改字典无需改代码
多语言支持（配合snowy-common的i18n）

8. org（组织机构模块）

模块定位 ：多租户与权限隔离

典型场景：

不同社区（orgId）只能看自己发布的活动
Service层自动添加过滤条件：
复制代码
```
queryWrapper.eq("org_id", user.getOrgId());
```

🔄 跨模块协作流程（以"老人预约活动"为例）

3. snowy-plugin-api（插件接口层）

定义插件暴露的接口：其他插件通过API调用本模块服务
实现插件间通信 ：如推荐插件需调用志愿者插件获取用户标签
对你很关键：知识图谱查询服务、推荐算法接口应在此定义

4. snowy-web-app（主启动模块）

极简入口 ：仅含main启动类和基础配置
插件扫描与加载：通过SpringBoot自动配置加载所有插件
多端适配：可打包为Jar/Docker镜像，部署到社区服务器

二、`snowy-web-app` 主启动模块：系统的入口和全局配置中心

2.1 `src/main/java/vip/xiaonuo/` ------ 主代码目录

1、`Application.java`（核心启动类）

功能：

启动整个后端服务 ：唯一包含 main 方法的类，运行即启动内嵌 Tomcat
组件自动扫描 ：scanBasePackages 会加载所有插件（auth/biz/sys）的 Spring Bean
注册插件 ：通过依赖引入的 snowy-plugin-* 被自动发现并加载
养老系统启动

2、`core/` 目录 ------ 应用生命周期管理

存放与启动、关闭、运行时相关的核心组件

3、`config/` 目录 ------ 全局通用配置

存放跨插件共用 的基础配置类，优先级高于插件内配置。

DruidConfigure.java

功能：配置 Druid 数据库连接池（如果用到 MySQL 存业务数据）

养老系统场景：管理志愿者基本信息、活动报名记录等 MySQL 数据。

GlobalConfigure.java

功能：全局通用参数配置，通过 @ConfigurationProperties 注入

养老系统场景：统一配置志愿者头像上传路径、推荐服务超时时间等。

`4、handler/` 目录 ------ 全局异常与错误处理器

中央化错误处理中心 ，捕获所有插件抛出的异常，统一返回友好格式，是系统健壮性的关键。

**GlobalExceptionHandler.java **（核心）

** 功能 **：统一捕获 Controller 层抛出的业务异常和技术异常

当 GraphRAG 推荐失败时，前端收到结构化错误响应，体现 系统容错能力 **。

**GlobalExceptionUtil.java **（工具类）

** 功能 **：提供异常处理辅助方法

**GlobalErrorAttributesHandler.java **

** 功能 **：自定义 SpringBoot 错误属性，控制 /error 端点返回的 JSON 结构

**GlobalErrorViewHandler.java & GlobalErrorViewController.java **

** 功能 **：处理浏览器访问时的错误页面（非 JSON 接口）

GlobalErrorViewHandler：配置错误页面模板（如 404.html、500.html）
GlobalErrorViewController：控制错误页面跳转逻辑

** 养老系统场景 **：当志愿者访问不存在的活动页面时，显示友好的 404 页面，引导返回首页。

2.2 `resources/` ------ 资源配置目录

1、`application.properties/yml` ------ 主配置文件

** 全局配置总入口 **，所有插件共享的配置优先

`2、logback-spring.xml` ------ 日志框架配置

精细化控制日志输出格式、级别、存储策略。

关键配置（推荐日志分离）

2.3 `_sql/` 目录 **（你之前提到的）

存放 ** 数据库初始化脚本 **，如：

neo4j_init.cypher：创建志愿者、活动、技能等节点和关系
mysql_init.sql：创建用户表、角色表（如果用 MySQL）

2.4 `src/test/java/vip/xiaonuo/` ------ 测试代码

2.5`pom.xml ------ Maven 依赖管理（主模块）`

核心作用 ：声明式依赖管理 ，通过 <dependencyManagement> 统一控制所有插件版本

关键设计：

版本统一管理 ：所有插件版本在父 POM 的 <properties> 中定义
按需加载 ：注释掉某个插件的 <dependency>，该功能就被热移除（适合演示）
打包优化 ：spring-boot-maven-plugin 将所有依赖打入一个 Jar，部署时只需传一个文件

【二】、养老志愿服务小程序前端项目small-pension-program-master（基于 UniApp）

一、整体架构概览

技术栈

框架：UniApp（Vue3 + TypeScript）
目标平台：微信小程序（主要）、H5、App
网络请求 ：封装 request.js 对接 Snowy 后端
状态管理：Pinia（虽未列出，但通常会配合 Vue3 使用）
UI 组件 ：uni-ui（在 uni_modules 中）

项目结构模式

复制代码

common/          # 公共工具（API、请求封装、加密）
components/      # 可复用 Vue 组件
pages/           # 业务页面（登录 + 4个 TabBar 模块）
static/          # 静态资源（图片、字体）
uni_modules/     # UniApp 官方组件库

路径	类型	主要功能
`App.vue`	根组件	应用生命周期管理、全局样式、全局数据存储
`main.js`	入口脚本	注册全局组件/方法、初始化配置、挂载应用
`manifest.json`	应用配置	定义应用信息、平台设置、权限声明、AppID
`pages.json`	路由配置	页面路由注册、底部 tabBar、导航栏样式、分包配置
`package.json`	依赖管理	npm 包依赖、脚本命令、项目元信息
`uni.scss`	样式变量	全局 SCSS 变量、主题色、字体大小、间距规范
`index.html`	HTML 模板	应用 HTML 外壳、SEO 元标签、CDN 引入
`LICENSE`	协议文件	开源协议声明
`common/`	公共模块	API 接口封装、请求拦截器、工具函数、加密工具
`pages/`	页面目录	登录页、首页、养老服务页、个人中心、预约页
`components/`	组件目录	可复用 Vue 组件（活动卡片、志愿者头像等）
`static/`	静态资源	图片、图标、字体、mock 数据
`uni_modules/`	插件市场	第三方 uni-app 插件（UI 库、工具库）
`node_modules/`	npm 依赖	项目安装的 npm 包
`unpackage/`	编译输出	各平台编译后的代码（小程序、H5、App）
`.hbuilderx/`	开发工具	HBuilderX 编辑器配置
`.idea/`	IDE 配置	WebStorm/IDEA 项目配置
`.vite/`	构建缓存	Vite 构建工具缓存文件

二、核心目录与文件详解

一、隐藏配置目录（非项目核心，开发环境相关）

.hbuilderx/

HBuilderX IDE 的专用配置目录，存储编辑器的个性化设置，包括代码主题、快捷键映射、插件安装记录等。该目录仅在 HBuilderX 中打开项目时生成，不影响代码逻辑和团队协作，可被 .gitignore 忽略。

.idea/

JetBrains 系列 IDE（WebStorm、IDEA）的项目配置目录，包含代码索引、运行/调试配置、版本控制设置等。同样属于开发环境产物，不影响应用功能，建议加入版本控制忽略列表。

.vite/

Vite 构建工具在开发过程中生成的缓存目录，用于加速模块热更新和依赖预构建。内容自动生成，无需手动管理，删除后会自动重建，可显著提升二次编译速度。

二、核心功能目录

common/ ------ 公共资源层

整个前端的基础设施，所有业务模块依赖此目录。

api/ 子目录：

后端接口的唯一对接层，按业务模块划分文件，实现请求路径、参数、方法类型的集中管理。当后端接口变更时，只需修改此处，避免业务代码中硬编码 URL。

这是与 Snowy 后端通信的 唯一通道，每个文件对应一个业务模块：

文件	功能	对应后端接口	养老场景示例
`loginApi.js`	登录/注册/退出	`/auth/login`, `/auth/logout`	志愿者手机号+验证码登录
`bizActivityApi.js`	活动 CRUD 和推荐	`/biz/activity/list`, `/biz/activity/recList`	获取智能推荐的活动列表 ⭐
`bizActivityReserveApi.js`	活动预约	`/biz/activity/reserve`	志愿者报名"陪伴老人"活动
`bizUserActivityActionApi.js`	用户行为	`/biz/activity/action/collect`	收藏/点赞活动
`bizVolunteerApi.js`	志愿者信息	`/biz/volunteer/profile`	查看服务时长、技能标签

utils/request.js ：

HTTP 请求拦截器，统一处理 Token 注入、响应格式转换、错误码提示、重试机制。是前后端联调的关键节点，403/401 等权限问题需在此处理。

utils/tool.js ：

纯函数工具库，提供日期格式化、字符串脱敏、空值校验、数值计算等通用能力，与业务无耦合，可在任意页面调用。

utils/smCrypto.js ：

国密算法封装，用于身份证号、手机号等敏感字段的加密传输，满足等保合规要求。

components/ ------ Vue 公共组件

存放可复用 的 .vue 单文件组件，遵循高内聚低耦合原则。

典型组件包括：

活动卡片：展示活动标题、时间、地点、报名人数，点击跳转详情
志愿者头像：圆形头像 + 在线状态绿点，支持点击展开个人信息
技能标签：根据技能类型（医护、陪伴、家政）自动渲染不同颜色
空状态提示：无数据时的占位图和引导语

这些组件通过 props 接收数据，emit 触发事件，实现参数化配置，提升页面开发效率。

node_modules/ ------ npm 依赖包

通过 npm install 自动下载的第三方库集合，包括：

UI 框架 ：uview-plus 提供按钮、表单、弹窗等基础组件
路由管理 ：uni-simple-router 实现页面跳转封装
HTTP 库 ：luch-request 增强 uni.request 功能
图标库 ：uni-icons 内置千余个矢量图标

该目录体积庞大，必须加入 .gitignore，通过 package-lock.json 保证团队依赖版本一致。

pages/ ------ 业务页面集合

按功能模块组织的页面目录，每个子目录对应一个业务场景。

login/ ：

身份认证入口，包含三种模式：密码登录、短信验证码登录、微信一键登录。登录成功后需将 Token 写入本地存储，并跳转首页。

文件	功能	关键代码
`login.vue`	手机号+验证码登录、微信登录	`handleLogin() { loginApi.login().then(saveToken) }`
`register.vue`	志愿者注册表单（姓名、技能、区域）	`submitForm() { bizVolunteerApi.register() }`
`forget.vue`	忘记密码（短信验证重置）	`resetPassword() { loginApi.reset() }`

tabbar/ ：

底部导航栏对应的三个核心页面：

pages/tabbar/my/ ------ ** 个人中心 **

** 功能 **：志愿者个人信息、服务时长、我参与的活动

pages/reserve/ ------ ** 活动预约页 **

** 功能 **：活动详情 + 立即报名

pension/ ：

养老服务详情页，展示服务项目、老人需求、注意事项，支持在线预约。

reserve/ ：

预约确认页，选择服务时间、填写备注、支付积分，提交后生成订单。

static/ ------ 静态资源

不经过编译的资源文件，直接复制到打包目录。

资源路径在代码中通过 /static/xxx.png 绝对路径引用，注意小程序对图片大小有限制（通常 < 2MB）。

uni_modules/ ------ uni-app 插件市场

通过 npm 或 HBuilderX 插件市场安装的高品质组件，与普通 npm 包的区别是：

典型插件：uni-icons、uview-plus、luch-request。

unpackage/ ------ 编译输出目录

执行 npm run dev:mp-weixin 或 npm run build 后自动生成，包含：

该目录绝对禁止 手动修改，每次编译会覆盖，必须加入 .gitignore。

三、根目录核心文件

App.vue

uni-app 应用的根实例，具有以下职责：

index.html

Web 端编译时的 HTML 模板，uni-app 会将 Vue 代码编译后的 JS/CSS 注入其中。可自定义：

小程序端会忽略此文件，使用平台自带的模板。

LICENSE

项目开源协议的法律文本，声明代码的使用、修改、分发权限。常见协议：

main.js

JavaScript 入口文件，职责包括：

manifest.json

uni-app 最重要的配置文件，控制应用全生命周期：

package-lock.json

npm 自动生成的依赖版本锁定文件，记录每个包的精确版本号、下载地址、哈希值。作用：

package.json

功能：npm 依赖管理

pages.json

uni-app 页面路由总控，功能包括：

uni.scss

功能：全局样式变量定义

重点文件

优先级	文件名	论文相关章节	重点内容
⭐⭐⭐	`pages/tabbar/frontpage/index.vue`	系统实现（推荐算法展示）	调用 recList，展示 GraphRAG 推荐结果
⭐⭐⭐	`common/api/bizActivityApi.js`	系统设计（接口设计）	与后端的 GraphRAG 接口对接
⭐⭐	`pages/login/login.vue`	系统实现（登录模块）	多角色登录（志愿者/老人）
⭐⭐	`manifest.json`	系统设计（小程序配置）	权限声明、AppID
⭐	`common/utils/request.js`	系统实现（请求封装）	Token 拦截、403 处理

首页：推荐算法展示页，调用 /biz/activity/recList 获取个性化活动
养老服务：分类浏览页，支持按服务类型、时间、地点筛选
个人中心：志愿者档案页，展示服务时长、积分、参与记录

pages/tabbar/frontpage/ ------ 首页（核心）

** 功能 **：智能推荐活动列表、搜索、轮播图
pages/tabbar/pension/ ------ ** 养老服务页 **

** 功能 **：分类浏览所有养老活动（陪护、家政、医疗）
顶部 Tab 切换分类
筛选条件：时间、地点、所需技能
头像、姓名、服务总时长
"我的报名"、"历史服务"、"技能证书"
展示活动详情（时间、地点、老人需求、所需技能）
志愿者报名：选择服务时间、留言
- 设置：消息通知、隐私设置
- images/：启动图、轮播图、空状态插画
- icons/：tabBar 图标、功能入口图标（要求尺寸精确，如 81x81px）
- mock/：开发阶段的模拟 JSON 数据，用于接口未完成时的页面调试
- 遵循 uni-app 规范：自动注册组件、自动引入样式
- 版本锁定 ：在 manifest.json 中记录版本号
- 即插即用 ：无需手动 import，可在任何页面直接使用
- dist/dev/：开发版，含 SourceMap，体积大，用于真机调试
- dist/build/：生产版，代码压缩混淆，体积小，用于发布上线
- 应用级生命周期：监听小程序启动、切前台、切后台，可用于统计用户活跃度
- 全局样式：定义页面背景色、字体族、基础动画
- 全局数据 ：通过 globalData 存储跨页面共享状态（如用户角色、未读消息数）
- 错误捕获 ：监听 onError 捕获未处理的异常，上报监控平台
- <meta> 标签：设置字符集、视口、Theme-Color
- <title>：Web 端页面标题
- 统计脚本：注入百度统计、友盟等第三方监控代码
- MIT：最宽松，可商用，需保留版权声明
- GPL：传染性，衍生代码必须开源
- Apache-2.0：可商用，需注明修改
- Vue 实例化 ：创建 createApp(App)，挂载到 #app
- 插件注册：全局注册 UI 组件库、工具函数
- 拦截器初始化 ：调用 request.js 的 setupRequestInterceptors
- 全局混入：注入全局方法或数据，需谨慎使用以避免污染
- 基础信息：应用名称、版本号、appid、描述
- 图标启动图 ：icon、splashScreen 配置
- 平台差异配置：
  - 小程序 ：mp-weixin 单独配置，包括 appid、setting（是否检查安全域名）、permission（位置、摄像头权限）
  - H5 ：h5 配置路由模式、template 模板、optimization 树摇优化
- 依赖管理 ：uni_modules 版本锁定，确保团队协作一致性
- 构建一致性：保证所有成员、所有环境的依赖版本完全相同
- 安装加速 ：利用缓存提升 npm install 速度
- 安全审计 ：配合 npm audit 检测漏洞
- 项目名称版本 ：name: "small-pension-program"
- 依赖库 ：uni-simple-router（路由）、uview-plus（UI 组件库）
- 脚本命令 ：dev:mp-weixin（编译到小程序）
- 页面注册 ：所有 .vue 页面必须在 pages 数组中注册，否则无法跳转
- 路由模式 ：配置 path、style（导航栏标题、背景色、是否下拉刷新）
- 底部 tabBar ：list 数组定义最多 5 个一级入口，含图标、文字、选中态
- 分包加载 ：subPackages 配置可提升小程序启动速度，将不常用页面拆分到分包
- 全局样式 ：globalStyle 设置默认导航栏、标题颜色
- 主题色：主色、辅色、警告色
- 字体大小：标题、正文、提示文字
- 间距规范：统一边距和圆角

《基于知识图谱和智能推荐的养老志愿服务系统》开发日志

基于现阶段系统架构的升级模块下一步开发--全景图

一、原系统核心模块挑战映射表

二、各模块的具体更改与创新方向

模块1：dict模块 → 知识图谱本体管理中心

✅已完成任务：

1、dict模块→ 知识图谱本体管理中心

2. 模块2：old实体层 → 知识图谱实体节点（已完成）

模块2：old, volunteer, activity实体层 → 知识图谱实体节点

模块3：param参数层 → Cypher查询构造器

模块4：service/impl业务实现层 → GraphRAG引擎

模块5：useractivityaction模块 → 实时事件流处理器

模块6：新增explainability模块 → 可解释性引擎

模块7：core配置层 + 数据存储层 → 混合架构底座

三、模块间协作流程的颠覆性变化

新系统流程（GraphRAG+LLM）：

四、创新总结：从"推荐系统"到"养老志愿认知服务平台"

【一】、newvolunter-master---Snowy 后端架构分析

一、架构设计理念

核心思想：插件化微内核架构

1. snowy-common（基础通用层）

2. snowy-plugin-*（业务插件层）

二、支撑模块（保障业务运行）

三、基础设施模块（通用能力）

🔄 跨模块协作流程（以"老人预约活动"为例）

3. snowy-plugin-api（插件接口层）

4. snowy-web-app（主启动模块）

二、snowy-web-app 主启动模块： 系统的入口和全局配置中心

2.1 src/main/java/vip/xiaonuo/ ------ 主代码目录

1、Application.java（核心启动类）

2、core/ 目录 ------ 应用生命周期管理

3、config/ 目录 ------ 全局通用配置

4、handler/ 目录 ------ 全局异常与错误处理器

2.2 resources/ ------ 资源配置目录

1、application.properties/yml ------ 主配置文件

2、logback-spring.xml ------ 日志框架配置

2.3 _sql/ 目录 **（你之前提到的）

2.4 src/test/java/vip/xiaonuo/ ------ 测试代码

2.5pom.xml ------ Maven 依赖管理（主模块）

【二】、养老志愿服务小程序 前端项目small-pension-program-master（基于 UniApp）

一、整体架构概览

技术栈

项目结构模式

二、核心目录与文件详解

一、隐藏配置目录（非项目核心，开发环境相关）

二、核心功能目录

三、根目录核心文件

重点文件

模块1：`dict`模块 → 知识图谱本体管理中心

模块2：`old`, `volunteer`, `activity`实体层 → 知识图谱实体节点

模块3：`param`参数层 → Cypher查询构造器

模块4：`service/impl`业务实现层 → GraphRAG引擎

模块5：`useractivityaction`模块 → 实时事件流处理器

模块6：新增`explainability`模块 → 可解释性引擎

模块7：`core`配置层 + 数据存储层 → 混合架构底座

2. **snowy-plugin-*（业务插件层）**

二、`snowy-web-app` 主启动模块：系统的入口和全局配置中心

2.1 `src/main/java/vip/xiaonuo/` ------ 主代码目录

1、`Application.java`（核心启动类）

2、`core/` 目录 ------ 应用生命周期管理

3、`config/` 目录 ------ 全局通用配置

`4、handler/` 目录 ------ 全局异常与错误处理器

2.2 `resources/` ------ 资源配置目录

1、`application.properties/yml` ------ 主配置文件

`2、logback-spring.xml` ------ 日志框架配置

2.3 `_sql/` 目录 **（你之前提到的）

2.4 `src/test/java/vip/xiaonuo/` ------ 测试代码

2.5`pom.xml ------ Maven 依赖管理（主模块）`

【二】、养老志愿服务小程序前端项目small-pension-program-master（基于 UniApp）