PAS/.qoder/repowiki/zh/content/API端点参考/系统管理API/系统管理API.md

系统管理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