Environment-Monitoring-System/Report/目前内容.md

1. 实践目的

1.1 项目概述与个人贡献

1.1.1 项目概述

本项目旨在解决传统环保监督渠道反馈不畅、处理流程不透明、以及公众参与度不高等痛点，开发一个高效、透明的环保公众监督平台。作为《东软环保应急》系统的重要子模块，它不仅是技术上的实现，更是业务流程上的一次重要创新。

系统的核心目标是打通从"问题发现"到"问题解决"的全链路。它通过提供便捷的移动端/网页端入口，鼓励公众随时随地上传图文并茂的环境问题反馈。系统接收到反馈后，将自动触发一系列内部流程：首先通过AI服务进行初步的智能分类与严重性评估；随后，经由主管人员审核确认后，反馈将自动转化为一个结构化的处理任务；最后，系统基于智能分配算法，综合考量网格员的实时位置、当前负载等因素，将任务精准派发给最优的执行者。整个过程的状态（待处理、执行中、已完成、已归档）对管理者和反馈者全程可见，极大地提升了环保工作的透明度与处理效率。

1.1.2 个人贡献

在本次实践中，本人担任核心的系统设计与后端开发角色，全面负责了从技术选型到项目落地的完整技术实现。我的工作不仅是代码的编写者，更是整个后端架构的设计者和构建者。具体贡献如下：

• 架构设计与技术决策：在项目初期，我主导了技术栈的选型，力主采用Spring Boot + Vue.js的前后端分离架构，以应对未来快速迭代和功能扩展的需求。同时，我独立设计了后端Controller-Service-Repository的三层应用架构，并规划了项目的整体模块（如安全、事件、仓储等），为整个项目的稳固开发奠定了基础。

• 核心难题攻关：面对"所有数据需以文件形式存储"这一核心且棘手的约束，我没有采取简单的文件读写，而是独立设计并实现了一套模拟JPA规范的泛型JSON仓储层。这个创新方案不仅完美地解决了数据持久化问题，其遵循的"依赖倒置原则"也使得代码高度解耦，极大地提升了系统的可维护性和可测试性，是本次项目中技术含量最高的突破之一。

• 全栈功能实现：我负责了全部后端模块的编码实现，包括但不限于基于Spring Security和JWT的用户认证与授权系统、任务全生命周期的状态机管理、以及基于A*算法的智能任务分配模型等。此外，我也参与了部分前端页面的开发，并利用Swagger和Postman完成了所有API的设计、文档化与测试工作，确保了前后端的顺畅联调。

1.2 个人能力培养

通过本次实践，本人将软件工程理论与开发实践深度结合，在设计与开发复杂问题的解决方案方面获得了显著提升。

• 软件工程全周期掌控能力：通过完整地参与从需求分析、系统设计、编码实现到测试部署的全过程，深刻掌握了现代软件开发的生命周期要素和方法。能够运用面向对象的思想，通过UML对系统进行建模，合理地划分模块，确保了系统设计的高内聚、低耦合。

• 复杂问题解决方案的设计与创新能力：

  • 面对"数据以文件格式保存"的核心约束，没有采用简单的序列化读写，而是创新性地设计并实现了一套基于JSON的泛型仓储层（Repository Pattern）。该方案遵循了依赖倒置原则，不仅满足了功能要求，更保证了代码的可维护性与未来向数据库迁移的可行性。
  • 针对任务分配场景，设计了基于多维因素（地理位置、负载）的智能调度算法，并集成了A*寻路算法进行路径规划，展现了运用科学算法解决实际工程问题的能力。
  • 在系统中有效运用了事件驱动模型，将耗时的AI分析流程解耦为异步操作，提升了系统的响应速度和健壮性。

• 技术沟通与文档化能力：能够通过撰写系统设计方案、绘制UML图表等方式，系统、清晰地阐述项目的技术架构与实现细节，并具备良好的口头技术交流能力。

2. 相关技术基础

本项目综合运用了业界主流的开发技术与环境，构建了一个现代化Web应用。整体技术体系由以下五部分构成：

• 理论基础：遵循面向对象编程(OOP)、SOLID设计原则(尤其是DIP)、MVC分层架构及RESTful API设计规范。
• 后端技术栈：以 Spring Boot 3 为核心，整合 Spring Security 与 JWT 进行安全控制，并创新性地设计了自定义的泛型JSON仓储层作为持久化方案。
• 前端技术栈：采用 Vue 3 作为核心框架，配合 Vite 进行构建，使用 Pinia 进行状态管理，Element Plus 作为UI组件库，并对 Axios 进行了封装。
• 测试技术：后端采用 JUnit 5 和 Mockito 进行单元/集成测试；接口层使用 Swagger UI 和 Postman 进行测试与调试。
• 开发工具与环境：使用 IntelliJ IDEA 和 VS Code 作为主力IDE，通过 Maven 和 npm 管理项目，并利用 Git 进行版本控制。

以下是各部分的详细介绍。

2.1 理论基础

项目的架构和代码设计遵循了下述成熟的软件工程理论，以确保系统的可维护性和扩展性。

• 面向对象编程 (OOP): 项目的核心编程思想，其封装、继承、多态特性在后端代码设计中得到了深入应用。

  • 封装 (Encapsulation): 核心业务实体（如User, Task）被抽象为Java类，其属性私有化，仅通过公共方法暴露，保证了对象状态的完整性。
  • 继承 (Inheritance) 与多态 (Polymorphism): 在自定义的JSON仓储层设计中，通过定义泛型接口JsonRepository<T, ID>和实现该接口的泛型基类JsonRepositoryImpl<T, ID>，使得具体的实体仓储（如JsonUserRepositoryImpl）能自动获得通用的数据操作能力。业务逻辑层依赖于抽象接口而非具体实现，实现了"面向接口编程"，提高了代码的灵活性。

• SOLID设计原则，尤其是依赖倒置原则 (DIP): 项目架构遵循SOLID原则，特别是依赖倒置原则，即"高层模块不应依赖于低层模块，两者都应依赖于抽象"。

  • 实践应用: Service层（高层模块）依赖的是UserRepository等抽象接口，而不是JsonRepositoryImpl这样的具体实现（低层模块）。这种设计倒置了传统的依赖关系，极大提升了系统的可替换性和可测试性。未来更换数据源或进行单元测试时，只需更换实现或模拟接口，上层代码无需改动。

• 模型-视图-控制器 (MVC) 分层架构: 项目遵循MVC分层思想，并扩展为更精细的四层架构：Controller -> Service -> Repository -> Entity。

  • Controller (控制器层): 作为HTTP请求的入口，负责解析请求参数，调用Service层执行业务逻辑，并返回响应。
  • Service (业务逻辑层): 包含所有业务规则和处理流程，通过依赖注入（DI）调用Repository层。
  • Repository (数据访问层): 数据持久化的抽象，负责与数据源（本项目中为JSON文件）交互，实现业务与数据的解耦。
  • Entity/DTO (模型层): POJO对象，Entity映射数据存储结构，DTO（Data Transfer Object）用于各层之间的数据传输，避免持久化实体直接暴露给外部。

• RESTful API 设计原则: 前后端通信完全基于RESTful风格的API进行。

  • 统一接口 (Uniform Interface): 使用HTTP标准方法（GET, POST, PUT, DELETE）表达对资源的操作。
  • 无状态 (Stateless): 服务端不保存客户端会话状态，每次请求都包含所有必要信息（如JWT），提高了系统的可伸缩性。
  • 资源导向 (Resource-Oriented): API围绕"资源"展开，使用名词（如/api/users）标识资源，而非动词。

2.2 后端技术栈

• 核心框架 - Spring Boot 3.x: 作为后端应用基石，它通过自动配置、起步依赖和内嵌服务器等特性，极大地简化了Spring应用的开发、配置和部署。其强大的生态整合能力，使得集成Spring Security、Lombok、Swagger等第三方库变得非常简单。

• 安全框架 - Spring Security 6.x & JWT: 采用Spring Security结合JSON Web Tokens (JWT)，构建无状态的认证与授权体系。

  • Spring Security Filter链: 自定义JwtAuthenticationFilter过滤器，用于在每个请求中校验JWT并设置安全上下文。
  • 声明式权限控制: 使用@PreAuthorize注解对Service方法进行方法级别的权限声明，实现了安全逻辑与业务逻辑的解耦。
  • 无状态会话 (Stateless Session): 配置会话管理策略为STATELESS，使后端服务成为真正的无状态服务，提升了系统的可伸缩性。

• 持久化方案 - 自定义泛型JSON仓储层: 为满足"数据存储在JSON文件中"的需求，设计并实现了一套模拟Spring Data JPA接口规范的、可复用的泛型JSON仓储层。

  • JsonStorageService: 将所有文件I/O操作封装在此服务中，并使用synchronized块确保并发写操作的线程安全。
  • JsonRepositoryImpl<T, ID>: 泛型基类，实现了通用的CRUD功能，具体的实体仓储通过继承该类来复用代码。
  • 该方案遵循依赖倒置原则，业务层仅依赖抽象接口，为未来平滑迁移持久化方案提供了便利。

• 数据校验 - Jakarta Bean Validation (Hibernate Validator): 在DTO的字段上使用@NotNull, @Size等声明式注解，并配合Controller层的@Valid注解，实现对请求参数的自动化校验。

• 对象映射 - MapStruct: 一个编译期的代码生成器，通过定义@Mapper接口，自动生成Entity与DTO之间转换的高性能实现代码，提升了开发效率。

• 编程语言与辅助工具:

  • Java 17 (LTS): 使用其record、switch表达式等新特性编写更简洁的代码。
  • Lombok: 通过@Data, @Builder等注解，消除样板代码。
  • SLF4J & Logback: 灵活的日志系统，通过配置文件实现分环境、分级别的日志输出。

2.3 前端技术栈

采用Vue.js生态的最新技术，构建响应迅速、代码可维护的现代化单页应用（SPA）。

• 核心框架 - Vue.js 3.x: 利用其两大核心新特性：

  • Composition API (组合式API): 将相关逻辑组织在同一个setup函数内，提高了代码的可读性、可维护性和逻辑复用性。
  • Proxy-based Reactivity: 基于Proxy重写的响应式系统，解决了Vue 2中无法监听对象属性新增/删除等痛点。

• 构建工具 - Vite: 新一代前端构建工具，优势在于：

  • 利用浏览器原生ESM支持，实现开发环境下的极速冷启动和闪电般的热模块替换（HMR）。
  • 生产环境使用Rollup打包，生成高度优化的静态资源。

• 状态管理 - Pinia: Vue官方推荐的下一代状态管理库，特点是API直观、类型支持完美，且天生模块化。废除了Vuex中复杂的Mutations等概念，心智负担小。

• UI组件库 - Element Plus: Element UI的Vue 3版本，是一套高质量的企业级UI组件库，提供了丰富的组件，极大地加速了界面的开发进程。

• HTTP客户端 - Axios封装: 对流行的Axios库进行二次封装：

  • 创建实例: 为API服务设置不同的baseURL、timeout等。
  • 请求拦截器: 统一添加认证token。
  • 响应拦截器: 统一处理业务数据和错误状态码。

2.4 测试技术

• 后端单元与集成测试 (JUnit 5, Mockito, Spring Boot Test): 使用spring-boot-starter-test集成的测试套件保障业务逻辑正确性。

  • JUnit 5: 测试的基础框架。
  • Mockito: 在单元测试中用于模拟依赖对象（如Repository），实现测试隔离。
  • Spring Boot Test: 用于集成测试，加载完整应用上下文，测试跨层级的真实交互场景。

• API接口测试 (Postman / Swagger UI):

  • Swagger UI: 通过集成SpringDoc，根据代码注解自动生成交互式API文档，方便调试。
  • Postman: 用于执行更复杂的API测试场景、编写测试用例和自动化测试。

2.5 开发工具与环境

• IDE: 后端使用IntelliJ IDEA Ultimate，前端使用Visual Studio Code。
• 项目管理与构建: 后端使用Maven，前端使用npm。
• 版本控制: Git & GitHub，遵循Git Flow工作流。

3. 实践结果

此部分属报告的主要部分。包括：

3.1 需求定义

"系统分析"也可以看成是需求定义，包括对整个项目的介绍分析及本人工作内容的详细分析，如业务分析、功能分析（可使用例图、活动图来描述）、可行性分析等；

3.2 系统设计

"系统设计"包括总体设计和详细设计，"总体设计"包括系统架构设计、功能模块划分等，"详细设计"要围绕本人工作内容展开，包括功能模块详细设计、类和对象的设计、动态模型设计（时序图、状态图、协作图等）、算法设计、数据库设计等；

3.3 系统实现

"系统实现"也要围绕本人工作内容展开，从编码实现角度论述相应功能模块的实现细节，并展示自己所完成的主要成果及实际应用情况等。可通过"程序流程图"、"关键代码"和"界面"进行直观论述。

3.4 系统测试

"系统测试"包括测试方案设计、测试用例和测试结果、最终的测试结论或评价等。

4. 实践总结

简述你在实践过程中的内容完成情况，重点介绍创新点及不足（也就是可以再完善的部分，只是时间不允许了。不足不代表不好，也说明你思考了，但是来不及完成实现）

5. 参考资料

例： [1] 数据结构、算法与应用：C++语言描述 [Data Structures,Algorithms,and Applications in C++][M].机械工业出版社出版时间：2000-01-01. [2] 数据结构(C语言版) [M].北京: 中国铁道出版社, 2011-08-01.