Domovská stránka Prehľadávať Pomoc
Prihlásiť sa
lrj
/
PAS
1
0
Fork 0
Súbory Issues 0 Pull requesty 0 Wiki
Strom: b92a372910
Branche Tagy
PAS
/
.qoder
/
repowiki
/
zh
/
content
/
API端点参考
/
系统管理API
/
系统管理API.md

系统管理API.md 23 KB
História Raw

系统管理API

本文引用的文件

  • CustomFieldController.java
  • PermissionRecordController.java
  • PersonFieldController.java
  • Constants.java
  • BusinessFactory.java
  • CustomFieldService.java
  • PermissionRecordService.java
  • PersonFieldService.java
  • SystemDict.java
  • SystemDictService.java
  • SystemDictMapper.java
  • ConfigDTO.java
  • CustomFieldDTO.java
  • UpdateCustomFieldDTO.java
  • PermissionRecordDTO.java
  • PermissionRecordVO.java
  • AllCustomFieldVO.java
  • PersonSelfFieldVO.java
  • AddSelfFieldDTO.java
  • EsCustomFieldDTO.java
  • EsCustomFieldBatchVO.java
  • EsQueryPatentFieldsDTO.java
  • EsPatentFieldsVO.java
  • QueryEsCustomFieldDTO.java
  • AllFieldOrderDTO.java
  • StringRequest.java
  • OtherPatentInfoDTO.java
  • QueryFieldsDTO.java
  • QueryFieldsVO.java
  • GetTabelColumDTO.java
  • GetAllPatentCountDTO.java
  • GetAllPatentCountVO.java
  • AddPatentCountDTO.java
  • Response.java
  • Records.java

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向系统管理员与开发人员，系统性梳理“系统管理”相关API，覆盖以下三大模块：

  • 自定义字段管理：提供自定义字段的创建、更新、删除、排序、批量标引、按专利批量查询字段值等能力。
  • 权限记录管理：提供许可历史的新增/更新、查询与删除能力，支持按专利号分页查询与人员信息装载。
  • 个人字段配置：提供检索字段、表格列、导出列、统计列的获取与设置，支持证据与理由相关表格列的个性化配置。

同时，文档补充了系统字典（SystemDict）与配置管理（ConfigDTO）的相关使用说明，并给出实际配置更新示例路径，帮助快速落地。

项目结构

系统管理API位于后端控制器层，统一通过常量前缀拼接形成REST路径；控制器通过业务工厂模式调用具体业务服务，业务服务再与持久层交互，最终返回统一响应封装。

graph TB
subgraph "控制器层"
CF["CustomFieldController"]
PR["PermissionRecordController"]
PF["PersonFieldController"]
end
subgraph "业务层"
BF["BusinessFactory"]
CFS["CustomFieldService"]
PRS["PermissionRecordService"]
PFS["PersonFieldService"]
end
subgraph "数据访问层"
CFD["CustomFieldMapper"]
PRM["PermissionRecordMapper"]
SDM["SystemDictMapper"]
end
subgraph "领域模型与DTO/VO"
SD["SystemDict"]
CFG["ConfigDTO"]
PRDTO["PermissionRecordDTO"]
PRVO["PermissionRecordVO"]
ACF["AllCustomFieldVO"]
PSF["PersonSelfFieldVO"]
end
CF --> BF
PR --> BF
PF --> BF
BF --> CFS
BF --> PRS
BF --> PFS
CFS --> CFD
PRS --> PRM
PFS --> SDM
PRS --> PRDTO
PRS --> PRVO
CFS --> ACF
PFS --> PSF
PFS --> CFG

图表来源

  • CustomFieldController.java
  • PermissionRecordController.java
  • PersonFieldController.java
  • BusinessFactory.java
  • CustomFieldService.java
  • PermissionRecordService.java
  • PersonFieldService.java

章节来源

  • Constants.java

核心组件

  • 控制器层：分别暴露三组REST端点，均以“/api/xiaoshi/{module}”为前缀。
  • 业务工厂：通过名称映射获取对应业务Bean，解耦控制器与具体服务实现。
  • 业务服务层：封装业务逻辑，处理参数校验、分页、人员信息装载等。
  • 数据访问层：MyBatis-Plus Mapper负责数据库交互。
  • 领域模型与DTO/VO：承载请求/响应数据结构，保证前后端契约清晰。

章节来源

  • CustomFieldController.java
  • PermissionRecordController.java
  • PersonFieldController.java
  • BusinessFactory.java

架构总览

系统管理API采用“控制器-业务工厂-业务服务-持久层”的分层架构，控制器仅负责路由与参数透传，业务工厂根据字符串键选择具体业务Bean，业务服务完成数据转换、校验与调用Mapper，最终统一返回Response封装的数据载体。

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "控制器"
participant Fac as "业务工厂"
participant Svc as "业务服务"
participant Mapper as "Mapper"
participant DB as "数据库"
Client->>Ctrl : "HTTP 请求"
Ctrl->>Fac : "getClass(业务键)"
Fac-->>Ctrl : "返回业务Bean"
Ctrl->>Svc : "调用业务方法(参数)"
Svc->>Mapper : "持久化/查询"
Mapper->>DB : "SQL执行"
DB-->>Mapper : "结果集"
Mapper-->>Svc : "实体/列表"
Svc-->>Ctrl : "业务结果"
Ctrl-->>Client : "Response 封装"

图表来源

  • CustomFieldController.java
  • PermissionRecordController.java
  • PersonFieldController.java
  • BusinessFactory.java

详细组件分析

自定义字段管理 API

  • 基础路径：/api/xiaoshi/customField

  • 关键端点

    • POST /api/xiaoshi/customField/queryCustomField
    • 功能：查询自定义字段（内部通过业务工厂调用业务服务）
    • 请求体：StringRequest
    • 返回：Response.success(Records)
    • POST /api/xiaoshi/customField/addCustomField
    • 功能：新增自定义字段
    • 请求体：CustomFieldDTO
    • 返回：Response.success(新增ID)
    • 异常：参数为空或业务异常时返回错误码
    • POST /api/xiaoshi/customField/updateCustomField
    • 功能：更新自定义字段
    • 请求体：UpdateCustomFieldDTO
    • 返回：Response.success(更新ID)
    • 异常：参数为空或业务异常时返回错误码
    • POST /api/xiaoshi/customField/deleteCustomField
    • 功能：删除自定义字段（支持批量）
    • 请求体：List(ids)
    • 返回：Response.success("删除成功")
    • GET /api/xiaoshi/customField/getAllPatentCustomField
    • 功能：查询专题库/任务下的所有自定义字段
    • 查询参数：projectId 或 taskId（二选一）
    • 返回：Response.success(Records>)
    • POST /api/xiaoshi/customField/getCustomFieldValues
    • 功能：查询某自定义字段的取值集合
    • 请求体：QueryEsCustomFieldDTO
    • 返回：Response.success(Records)
    • POST /api/xiaoshi/customField/addAllPatentCustomFieldOrder
    • 功能：保存自定义字段顺序
    • 请求体：AllFieldOrderDTO
    • 返回：Response.success(Records)
    • POST /api/xiaoshi/customField/addCustomFieldValue
    • 功能：添加单个标引
    • 请求体：EsCustomFieldDTO
    • 返回：Response.success(Records)
    • POST /api/xiaoshi/customField/batchAddCustomField
    • 功能：批量添加标引
    • 请求体：EsCustomFieldBatchVO
    • 返回：Response.success(Records>)
    • POST /api/xiaoshi/customField/getPatentFields
    • 功能：批量获取专利的自定义字段及值
    • 请求体：EsQueryPatentFieldsDTO
    • 返回：Response.success(Records>)

    • 处理流程（新增/更新/删除）

      • 控制器接收请求后，通过业务工厂获取对应业务Bean
      • 业务Bean执行addMessage/updateMessage/deleteMessage等方法
      • 业务服务进行参数校验、异常捕获与数据转换
      • 最终统一返回Response.success或错误响应

    • 应用场景

      • 在专题库或任务中动态扩展字段类型（文本、数字、日期、树、选项等），并通过排序与批量标引提升检索与展示效率。

      • 章节来源

      • CustomFieldController.java
      • CustomFieldService.java
      • AllCustomFieldVO.java
      • EsCustomFieldDTO.java
      • EsCustomFieldBatchVO.java
      • EsQueryPatentFieldsDTO.java
      • EsPatentFieldsVO.java
      • QueryEsCustomFieldDTO.java
      • AllFieldOrderDTO.java
      • StringRequest.java

      权限记录查询 API

      • 基础路径：/api/xiaoshi/permissionRecord

      • 关键端点

        • POST /api/xiaoshi/permissionRecord/saveOrUpdate
        • 功能：新增或更新许可历史
        • 请求体：PermissionRecordDTO
        • 返回：Response.success(Records)，包含新增/更新后的ID
        • POST /api/xiaoshi/permissionRecord/query
        • 功能：按专利号分页查询许可历史
        • 请求体：OtherPatentInfoDTO（需包含专利号）
        • 返回：Response.success(Records>)
        • POST /api/xiaoshi/permissionRecord/delete
        • 功能：删除许可历史（支持批量）
        • 请求体：List(ids)
        • 返回：Response.success(Records>)

        • 处理流程（查询）

          • 控制器接收请求后，调用业务服务
          • 业务服务根据专利号分页查询，装载创建人姓名等信息
          • 返回统一响应封装

        • 审计要点

          • 支持按专利号过滤，按创建时间倒序排列
          • 通过外部服务加载创建人信息，增强可读性

          • 章节来源

          • PermissionRecordController.java
          • PermissionRecordService.java
          • PermissionRecordDTO.java
          • PermissionRecordVO.java
          • OtherPatentInfoDTO.java

          个人字段配置 API

          • 基础路径：/api/xiaoshi/personField

          • 关键端点

            • POST /api/xiaoshi/personField/getQueryFields
            • 功能：获取检索栏位
            • 请求体：List
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/getTableColumns
            • 功能：获取表格显示栏位
            • 请求体：GetTabelColumDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/getTableExportColumns
            • 功能：获取表格导出栏位
            • 请求体：GetTabelColumDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/getAllCountColumns
            • 功能：获取所有统计栏位
            • 请求体：GetAllPatentCountDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/setTableColumns
            • 功能：设置表格显示栏位
            • 请求体：AddSelfFieldDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/setShowCountColumns
            • 功能：设置显示的统计栏位
            • 请求体：AddPatentCountDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/getShowCountColumns
            • 功能：获取显示的统计栏位
            • 请求体：GetAllPatentCountDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/getEvidenceReasonTableColumns
            • 功能：获取无效理由和证据表格显示栏位
            • 请求体：GetTabelColumDTO
            • 返回：Response.success(Records>)
            • POST /api/xiaoshi/personField/setEvidenceReasonTableColumns
            • 功能：设置无效理由和证据表格显示栏位
            • 请求体：AddSelfFieldDTO
            • 返回：Response.success(Records>)

            • 处理流程（设置表格列）

              • 控制器接收请求后，调用业务服务
              • 业务服务根据用户登录信息与表名等参数，写入或更新个人字段配置
              • 返回统一响应封装

              • 章节来源

              • PersonFieldController.java
              • PersonFieldService.java
              • PersonSelfFieldVO.java
              • AddSelfFieldDTO.java
              • GetTabelColumDTO.java
              • GetAllPatentCountDTO.java
              • GetAllPatentCountVO.java
              • AddPatentCountDTO.java
              • QueryFieldsDTO.java
              • QueryFieldsVO.java

              配置管理与系统字典 API

              • 配置管理（ConfigDTO）

                • 字段：loginAccount、loginPassword、tenantId、webId
                • 使用场景：用于系统登录配置的参数传递，便于后续服务层进行配置更新或校验
                • 示例参考：ConfigDTO.java

              • 系统字典（SystemDict）

                • 字段：label、value、type、groupType、simpleLabel、remark
                • 用途：维护系统级枚举/字典项，如国家、法律状态、许可类型等
                • 服务方法：
                • 按类型列表获取字典项 Map>
                • 按类型与值获取标签值
                • 按类型获取场景顺序ID列表
                • 示例参考：
                • SystemDict.java
                • SystemDictService.java
                • SystemDictMapper.java

              • 实际配置更新示例

                • 登录配置更新：通过服务层接收ConfigDTO，进行参数校验与持久化，返回统一响应
                • 示例路径参考：
                • ConfigDTO.java
                • Response.java

                • 章节来源

                • ConfigDTO.java
                • SystemDict.java
                • SystemDictService.java
                • SystemDictMapper.java

                依赖关系分析

                • 控制器与业务工厂
                  • 控制器通过业务工厂按名称获取业务Bean，避免直接依赖具体实现类，降低耦合度
                • 控制器与业务服务
                  • 控制器仅负责参数接收与响应封装，业务逻辑集中在服务层
                • 业务服务与Mapper
                  • 业务服务通过Mapper执行数据库操作，支持分页、条件查询与数据装载
                • 统一响应封装
                  • 所有控制器返回统一的Response封装，包含状态码、消息与数据载体Records
                classDiagram
class CustomFieldController
class PermissionRecordController
class PersonFieldController
class BusinessFactory
class CustomFieldService
class PermissionRecordService
class PersonFieldService
class Response
class Records
CustomFieldController --> BusinessFactory : "获取业务Bean"
PermissionRecordController --> BusinessFactory : "获取业务Bean"
PersonFieldController --> BusinessFactory : "获取业务Bean"
BusinessFactory --> CustomFieldService : "按名称映射"
BusinessFactory --> PermissionRecordService : "按名称映射"
BusinessFactory --> PersonFieldService : "按名称映射"
CustomFieldController --> Response : "返回统一响应"
PermissionRecordController --> Response : "返回统一响应"
PersonFieldController --> Response : "返回统一响应"
Response --> Records : "封装数据"

                图表来源

                • CustomFieldController.java
                • PermissionRecordController.java
                • PersonFieldController.java
                • BusinessFactory.java
                • Response.java
                • Records.java

                性能考量

                • 批量操作
                  • 自定义字段批量标引与批量删除可显著减少网络往返次数，建议优先使用批量接口
                • 分页查询
                  • 权限记录查询支持分页，建议前端传入合理的页码与大小，避免一次性加载过多数据
                • 缓存与装载
                  • 业务服务在装载人员信息时可能涉及外部服务调用，建议结合缓存策略优化性能
                • 字典查询
                  • 系统字典按类型批量查询，建议前端按需请求，减少冗余数据传输

                故障排查指南

                • 参数为空或格式错误
                  • 控制器与业务服务对空参数进行显式校验，返回相应错误码
                  • 参考路径：
                  • CustomFieldController.java
                  • PermissionRecordService.java
                • 未登录或权限不足
                  • 控制器捕获未登录异常并返回统一未登录响应
                  • 参考路径：
                  • CustomFieldController.java
                • 数据库异常
                  • 删除自定义字段时可能抛出IO异常，控制器捕获并返回错误信息
                  • 参考路径：
                  • CustomFieldController.java
                • 统一响应
                  • 所有接口返回统一的Response封装，便于前端统一处理
                  • 参考路径：
                  • Response.java

                章节来源

                • CustomFieldController.java
                • PermissionRecordService.java
                • Response.java

                结论

                本文件系统性梳理了系统管理相关的三大API模块，明确了各端点的功能、请求/响应结构与典型使用场景。通过业务工厂模式与统一响应封装，系统具备良好的可扩展性与一致性。配合系统字典与配置管理，可进一步完善系统的配置与枚举治理。

                附录

                • 常量前缀
                  • API前缀：/api/xiaoshi
                  • 参考路径：
                  • Constants.java