新增基础数据服务配置

2026-08-05 16:26:35 +08:00
parent ac59397968
commit 6a076c9588
21 changed files with 1489 additions and 0 deletions
--- a/consumers/data_service.php
+++ b/consumers/data_service.php
@@ -0,0 +1,50 @@
+<?php
+
+return  [
+    // 对应消费者类的 $serviceName
+    'name' => 'DataService',
+    // 服务接口名，可选，默认值等于 name 配置的值，如果 name 直接定义为接口类则可忽略此行配置，如 name 为字符串则需要配置 service 对应到接口类
+    'service' => Dhd\Micro\Interface\DataService\DataService::class,
+    // 服务提供者的服务协议，可选，默认值为 jsonrpc-http
+    // 可选 jsonrpc-http jsonrpc jsonrpc-tcp-length-check
+    'protocol' => 'jsonrpc-http',
+    // 负载均衡算法，可选，默认值为 random
+    'load_balancer' => 'random',
+    // 这个消费者要从哪个服务中心获取节点信息，如不配置则不会从服务中心获取节点信息
+    'registry' => [
+        'protocol' => env("CONSUMERS_PROTOCOL", "consul"),
+        'address' => env("CONSUMERS_ADDRESS", "http://127.0.0.1:8500"),
+    ],
+    // 'nodes' => [
+    //     ['host' => '172.18.0.4', 'port' => 9502],
+    // ],
+    // 配置项，会影响到 Packer 和 Transporter
+    'options' => [
+        'connect_timeout' => 5.0,
+        'recv_timeout' => 5.0,
+        'settings' => [
+            // 根据协议不同，区分配置
+            'open_eof_split' => true,
+            'package_eof' => "\r\n",
+            // 'open_length_check' => true,
+            // 'package_length_type' => 'N',
+            // 'package_length_offset' => 0,
+            // 'package_body_offset' => 4,
+        ],
+        // 重试次数，默认值为 2，收包超时不进行重试。暂只支持 JsonRpcPoolTransporter
+        'retry_count' => 2,
+        // 重试间隔，毫秒
+        'retry_interval' => 100,
+        // 使用多路复用 RPC 时的心跳间隔，null 为不触发心跳
+        'heartbeat' => 30,
+        // 当使用 JsonRpcPoolTransporter 时会用到以下配置
+        'pool' => [
+            'min_connections' => 1,
+            'max_connections' => 32,
+            'connect_timeout' => 10.0,
+            'wait_timeout' => 3.0,
+            'heartbeat' => -1,
+            'max_idle_time' => 60.0,
+        ],
+    ],
+];
--- a/src/DataService/AgreementInterface.php
+++ b/src/DataService/AgreementInterface.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface AgreementInterface
+{
+    /**
+     * 获取协议列表
+     * @param string $platform 平台类型
+     */
+    public function getAgreementList(string $platform = 'app'): array;
+
+    /**
+     * 获取协议详情
+     * @param int $type 协议类型
+     * @param string $platform 平台类型
+     */
+    public function getAgreementDetail(int $type, string $platform = 'app'): array;
+
+    /***
+     * 根据协议ID获取协议详情
+     * @param int $id 协议ID
+     */
+    public function getAgreementDetailById(int $id): array;
+
+    /**
+     * 编辑协议
+     */
+    public function editAgreement(array $params);
+}
--- a/src/DataService/AppVersionInterface.php
+++ b/src/DataService/AppVersionInterface.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface AppVersionInterface
+{
+    /**
+     * 获取APP版本列表
+     * @param array $params 分页参数
+     */
+    public function getAppVersionList(array $params);
+
+
+    /**
+     * 获取APP版本详情
+     * @param int $id 版本ID
+     */
+    public function getAppVersionDetail(int $id);
+
+    /**
+     * 新增、编辑APP版本发布
+     */
+    public function editAppVersion(array $params);
+
+    /**
+     * 删除APP发布
+     */
+    public function deleteAppVersion(int $id);
+
+    /**
+     * 获取APP最新版本
+     */
+    public function getAppNewVersion(string $code = 'default', int $isTest = 0);
+}
--- a/src/DataService/CampusRelationInterface.php
+++ b/src/DataService/CampusRelationInterface.php
@@ -0,0 +1,185 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface CampusRelationInterface
+{
+    /**
+     * 获取关联关系列表
+     * @param array $params 筛选参数
+     * @return array
+     */
+    public function getRelations(array $params): array;
+
+    /**
+     * 创建关联关系
+     * @param array $data 关联数据
+     * @return int 新创建的关联ID
+     */
+    public function createRelation(array $data): int;
+
+    /**
+     * 批量创建关联关系
+     * @param array $relations 关联数据数组
+     * @return array 创建成功的ID数组
+     */
+    public function batchCreateRelations(array $relations): array;
+
+    /**
+     * 更新关联关系
+     * @param int $id 关联ID
+     * @param array $data 要更新的数据
+     * @return bool 是否更新成功
+     */
+    public function updateRelation(int $id, array $data): bool;
+
+    /**
+     * 删除关联关系
+     * @param int $id 关联ID
+     * @return bool 是否删除成功
+     */
+    public function deleteRelation(int $id): bool;
+
+    /**
+     * 批量删除关联关系
+     * @param array $ids 关联ID数组
+     * @return bool 是否删除成功
+     */
+    public function batchDeleteRelations(array $ids): bool;
+
+    /**
+     * 根据条件获取分类ID列表
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @param int $subjectId 科目ID
+     * @return array 分类ID列表
+     */
+    public function getCategoryIdsByRelation(int $campusId, int $examTypeId, int $subjectId): array;
+
+    /**
+     * 获取指定校区下的所有考试类型
+     * @param int $campusId 校区ID
+     * @return array 考试类型列表
+     */
+    public function getExamTypesByCampus(int $campusId): array;
+
+    /**
+     * 获取指定考试类型下的所有科目
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @return array 科目列表
+     */
+    public function getSubjectsByExamType(int $campusId, int $examTypeId): array;
+
+    /**
+     * 获取指定科目下的所有分类
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @param int $subjectId 科目ID
+     * @return array 分类列表
+     */
+    public function getCategoriesBySubject(int $campusId, int $examTypeId, int $subjectId): array;
+
+    /**
+     * 批量更新关联排序
+     * @param array $sorts 格式：[{id: 1, sort: 5}, {id: 2, sort: 10}]
+     * @return bool
+     */
+    public function batchUpdateSort(array $sorts): bool;
+
+    /**
+     * 批量校验关联数据合法性（用于导入）
+     * @param array $relations 待校验的关联数组
+     * @return array 校验结果，格式：[{id: 索引, valid: true/false, message: 错误信息}]
+     */
+    public function batchValidateRelations(array $relations): array;
+
+    /**
+     * 检查关联是否被引用
+     * @param int $id 关联ID
+     * @return array {is_referenced: bool, references: array 引用列表}
+     */
+    public function checkRelationReference(int $id): array;
+
+    /**
+     * 获取指定校区的考试类型（含已关联/未关联状态）
+     * @param int $campusId 校区ID
+     * @return array 考试类型列表，每个元素含is_related标识
+     */
+    public function getExamTypeWithRelationStatus(int $campusId): array;
+
+    /**
+     * 获取指定校区+考试类型的科目（含已关联/未关联状态）
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @return array 科目列表，每个元素含is_related标识
+     */
+    public function getSubjectWithRelationStatus(int $campusId, int $examTypeId): array;
+
+    /**
+     * 获取指定校区+考试类型+科目的分类（含已关联/未关联状态）
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @param int $subjectId 科目ID
+     * @return array 分类列表，每个元素含is_related标识
+     */
+    public function getCategoryWithRelationStatus(int $campusId, int $examTypeId, int $subjectId): array;
+
+    /**
+     * 获取智能组卷科目列表（筛选is_smart_paper=1）
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @return array 科目列表
+     */
+    public function getSmartPaperSubjectsByExamType(int $campusId, int $examTypeId): array;
+
+    /**
+     * 获取智能组卷科目对应的分类列表
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 考试类型ID
+     * @param int $subjectId 科目ID
+     * @return array 分类列表
+     */
+    public function getSmartPaperCategoriesBySubject(int $campusId, int $examTypeId, int $subjectId): array;
+
+    /**
+     * 根据ID获取关联关系详情
+     * @param int $id 关联ID
+     * @return array 关联关系详情（包含关联的校区、考试类型、科目、分类完整信息）
+     */
+    public function getRelationById(int $id): array;
+
+    /**
+     * 批量更新关联关系状态
+     * @param array $ids 关联ID数组
+     * @param int $status 状态值（1-启用，0-禁用）
+     * @return bool 是否更新成功
+     */
+    public function batchUpdateStatus(array $ids, int $status): bool;
+
+    /**
+     * 批量更新智能组卷标识
+     * @param array $ids 关联ID数组
+     * @param int $isSmartPaper 智能组卷标识（1-是，0-否）
+     * @return bool 是否更新成功
+     */
+    public function batchUpdateSmartPaper(array $ids, int $isSmartPaper): bool;
+
+    /**
+     * 批量更新考试使用标识
+     * @param array $ids 关联ID数组
+     * @param int $isUsedExam 考试使用标识（1-是，0-否）
+     * @return bool 是否更新成功
+     */
+    public function batchUpdateUsedExam(array $ids, int $isUsedExam): bool;
+
+    /**
+     * 批量更新公告类型使用标识
+     * @param array $ids 关联ID数组
+     * @param int $isUsedNoticeType 公告类型使用标识（1-是，0-否）
+     * @return bool 是否更新成功
+     */
+    public function batchUpdateUsedNoticeType(array $ids, int $isUsedNoticeType): bool;
+}
--- a/src/DataService/CityInterface.php
+++ b/src/DataService/CityInterface.php
@@ -0,0 +1,42 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface CityInterface
+{
+    /**
+     * 城市下拉列表
+     * @param int $level 级别
+     * @param bool $onlyShow 是否只获取显示的数据
+     * @return array
+     */
+    public function citySelectList(int $level = 0, bool $onlyShow = true): array;
+
+    /**
+     * 获取城市详情
+     * @param int $cityId
+     * @return array
+     */
+    public function getCityDetail(int $cityId): array;
+
+    /**
+     * 根据城市id获取城市列表
+     * @param array $ids
+     * @return array
+     */
+    public function getCityListByIds(array $ids): array;
+
+    /**
+     * 获取城市下拉树
+     * @param int $level 级别
+     * @return array
+     */
+    public function getCitySelectTree(int $level = 0, int $parentId = 0, int $noZhi = 0): array;
+
+    /**
+     * 根据城市id获取城市下拉树,
+     * @param array $ids
+     * @return array
+     */
+    public function getCitySelectTreeByIds(array $ids, int $level = 0): array;
+}
--- a/src/DataService/ConfigInterface.php
+++ b/src/DataService/ConfigInterface.php
@@ -0,0 +1,62 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface ConfigInterface
+{
+    /**
+     * 管理后台获取配置列表
+     * @param array $params 查询参数
+     * @param string $platform 平台类型，app-APP，official-官网,wxmini微信小程序
+     * @param int $type 类型，1轮播图，2广告，3菜单。 0全部
+     */
+    public function adminGetConfigList(array $params, string $platform = 'app', int $type = 0): array;
+
+    /**
+     * 获取配置列表，前端使用
+     * @param string $platform 平台类型，app-APP，official-官网,wxmini微信小程序
+     * @param array $types 类型，1轮播图，2广告，3菜单。 0全部
+     */
+    public function getConfigList(string $platform = 'app', array $types = []): array;
+
+    /**
+     * 统一前端配置读取（平台可选）.
+     * @param string $platform 平台标识；空=不按平台过滤；非空命中对应平台
+     * @param array $types 类型集合，空=不限
+     * @param array $configNames config_name 集合，空=不限
+     */
+    public function getPublicConfigs(string $platform = '', array $types = [], array $configNames = []): array;
+
+    /**
+     * 获取配置列表
+     * @param string $platform 配置所属平台
+     * @param array $configName 配置名称
+     */
+    public function getCongifByName(string $platform = 'app', array $configName = []): array;
+
+    /**
+     * 获取图片配置详情
+     * @param int $id 配置ID
+     */
+    public function getConfigDetail(int $id): array;
+
+    /**
+     * 新增/编辑配置
+     */
+    public function editConfig(array $params);
+
+    /**
+     * 编辑配置的排序
+     */
+    public function editConfigSort(int $id, int $sort);
+
+    /**
+     * 编辑配置的显示
+     */
+    public function editConfigShow(int $id, int $isShow);
+
+    /**
+     * 删除配置项
+     */
+    public function deleteConfig(int $id);
+}
--- a/src/DataService/Course/CourseServiceInterface.php
+++ b/src/DataService/Course/CourseServiceInterface.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService\Course;
+
+/**
+ * 课程服务接口
+ */
+interface CourseServiceInterface
+{
+    /**
+     * 根据教师ID获取课程列表
+     * @param int $teacherId 教师ID
+     * @param string $platform 平台 admin-后台 app-APP
+     */
+    public function getCoursesByTeacherId(int $teacherId, string $platform = 'app'): array;
+}
--- a/src/DataService/DataService.php
+++ b/src/DataService/DataService.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * 基础数据服务
+ */
+
+namespace Dhd\Micro\Interface\DataService;
+
+use Dhd\Micro\Interface\DataService\Course\CourseServiceInterface;
+use Dhd\Micro\Interface\DataService\Exam\ExamServiceInterface;
+
+interface DataService extends
+    DataServiceInterface,
+    AgreementInterface,
+    ConfigInterface,
+    AppVersionInterface,
+    RecruitUnitInterface,
+    CampusRelationInterface,
+    RegionInterface,
+    RegionExamTypeInterface,
+    ExamTypeSubjectInterface,
+    SubjectCategoryInterface,
+    CityInterface,
+    ExcelHeaderFieldsInterface,
+    DictionaryInterface,
+    MajorsInterface,
+    GuideNavInterface,
+    CourseServiceInterface,
+    ExamServiceInterface {}
--- a/src/DataService/DataServiceInterface.php
+++ b/src/DataService/DataServiceInterface.php
@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface DataServiceInterface
+{
+    // 校区相关（考区、省份地市、分校）
+    public function getCampuses(array $data): array;
+    public function getCampusTree(int $regionId): array;
+    public function getCitiesByRegion(int $regionId): array;
+    public function getCampusBy(int $id): array;
+    public function getCampusByForAdmin(int $id): array;
+    public function createCampus(array $data): int;
+    public function updateCampus(int $id, array $data): int;
+    public function deleteCampus(int $id): bool;
+    // 获取省份列表
+    public function getProvinces(): array;
+    // 根据省份获取城市列表
+    public function getCitiesByProvince(string $province): array;
+    // 根据校区ID列表获取校区详情
+    public function getCampusByIds(array $ids): array;
+
+
+    // 教师相关
+    public function getTeachers(array $data): array;
+    public function getTeacherBy(int $id): array;
+    public function createTeacher(array $data): int;
+    public function updateTeacher(int $id, array $data): int;
+    public function deleteTeacher(int $id): bool;
+    /**
+     * 获取按首字母分组的教师列表
+     */
+    public function getTeachersByAlphabet(array $data = []): array;
+
+
+    // 招考类型相关
+    public function getExamTypes(array $data): array;
+    public function getExamTypeBy(int $id): array;
+    public function createExamType(array $data): int;
+    public function updateExamType(int $id, array $data): bool;
+    public function deleteExamType(int $id): bool;
+    public function getExamTypesByCampusId(int $campusId): array;
+
+
+    // 科目相关
+    public function getSubjects(array $data): array;
+    public function getSubjectBy(int $id): array;
+    public function createSubject(array $data): int;
+    public function updateSubject(int $id, array $data): bool;
+    public function deleteSubject(int $id): bool;
+    public function getSubjectsByExamTypeId(int $examTypeId): array;
+
+
+    // 关联关系相关
+    public function getRelations(array $params): array;
+    public function createRelation(array $data): int;
+    public function updateRelation(int $id, array $data): bool;
+    public function deleteRelation(int $id): bool;
+    public function getCategoryIdsByRelation(int $campusId, int $examTypeId, int $subjectId): array;
+
+    // 批量更新校区排序
+    public function batchUpdateCampusSort(array $sorts): bool;
+}
--- a/src/DataService/DictionaryInterface.php
+++ b/src/DataService/DictionaryInterface.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface DictionaryInterface
+{
+    /**
+     * 获取字典列表
+     * @param string $category 字典类别
+     * @return array
+     */
+    public function getDictionaryListByCategory(string $category): array;
+}
--- a/src/DataService/Exam/ExamServiceInterface.php
+++ b/src/DataService/Exam/ExamServiceInterface.php
@@ -0,0 +1,546 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService\Exam;
+
+interface ExamServiceInterface extends GufenPaperInterface
+{
+    // 练习相关
+    /**
+     * 获取练习列表.
+     * @param int $userId 用户ID
+     * @return array 练习列表
+     */
+    public function getPracticeList(int $userId): array;
+
+    /**
+     * 获取练习详情.
+     * @param int $userId 用户ID
+     * @param int $id 练习ID
+     * @return array 练习详情
+     */
+    public function getPracticeDetail(int $userId, int $id): array;
+
+    // 考试类型相关
+
+    /**
+     * 获取考试类型列表.
+     * @param array $params
+     * @return array
+     */
+    public function getExamTypeList(array $params): array;
+
+    /**
+     * 获取考试类型详情.
+     * @param int $id 考试类型ID
+     * @return array 考试类型详情
+     */
+    public function getExamTypeDetail(int $id): array;
+
+    /**
+     * 创建考试类型.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createExamType(array $params): bool;
+
+    /**
+     * 更新考试类型.
+     * @param int $id 考试类型ID
+     * @param array $params
+     * @return bool 更新结果
+     */
+    public function updateExamType(int $id, array $params): bool;
+
+    /**
+     * 删除考试类型.
+     * @param int $id 考试类型ID
+     * @return bool 删除结果
+     */
+    public function deleteExamType(int $id): bool;
+
+    // 题目素材相关
+
+    /**
+     * 获取素材列表.
+     * @param array $params
+     * @return array
+     */
+    public function getQuestionMaterialList(array $params): array;
+
+    /**
+     * 获取素材详情.
+     * @param int $id
+     * @return array
+     */
+    public function getQuestionMaterialDetail(int $id): array;
+
+    /**
+     * 创建素材.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createQuestionMaterial(array $params): bool;
+
+    /**
+     * 更新素材.
+     * @param int $id 素材ID
+     * @param array $params
+     * @return bool 更新结果
+     */
+    public function updateQuestionMaterial(int $id, array $params): bool;
+
+    /**
+     * 删除素材.
+     * @param int $id 素材ID
+     * @return bool 删除结果
+     */
+    public function deleteQuestionMaterial(int $id): bool;
+
+    // 题目相关
+
+    /**
+     * 获取题目列表.
+     * @param array $params
+     * @return array
+     */
+    public function getQuestionList(array $params): array;
+
+    /**
+     * 获取题目详情.
+     * @param int $id
+     * @return array
+     */
+    public function getQuestionDetail(int $id): array;
+
+    /**
+     * 创建题目.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createQuestion(array $params): bool;
+
+    /**
+     * 更新题目.
+     * @param int $id 题目ID
+     * @param array $params
+     * @return bool 更新结果
+     */
+    public function updateQuestion(int $id, array $params): bool;
+
+    /**
+     * 删除题目.
+     * @param int $id 素材ID
+     * @return bool 删除结果
+     */
+    public function deleteQuestion(int $id): bool;
+
+    /**
+     * 搜索题目.
+     * @param array $params
+     * @return array
+     */
+    public function searchQuestion(array $params): array;
+
+    // 题目选项相关
+
+    /**
+     * 批量创建题目选项.
+     * @param int $questionId
+     * @param array $options
+     * @return bool
+     */
+    public function batchCreateQuestionOptions(int $questionId, array $options): bool;
+
+    /**
+     * 调整题目选项排序.
+     * @param int $questionId
+     * @param array $sortData
+     * @return bool
+     */
+    public function adjustQuestionOptionSort(int $questionId, array $sortData): bool;
+
+    /**
+     * 删除题目选项.
+     * @param int $questionId
+     * @return bool
+     */
+    public function deleteQuestionOptionsByQuestionId(int $questionId): bool;
+
+    // 题库相关
+
+    /**
+     * 获取题库列表.
+     * @param array $params
+     * @return array
+     */
+    public function getQuestionStoreList(array $params): array;
+
+    /**
+     * 获取题库详情.
+     * @param int $id
+     * @return array
+     */
+    public function getQuestionStoreDetail(int $id): array;
+
+    /**
+     * 创建题库.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createQuestionStore(array $params): bool;
+
+    /**
+     * 更新题库.
+     * @param int $id 题库ID
+     * @param array $params
+     * @return bool 更新结果
+     */
+    public function updateQuestionStore(int $id, array $params): bool;
+
+    /**
+     * 删除题库.
+     * @param int $id 题库ID
+     * @return bool 删除结果
+     */
+    public function deleteQuestionStore(int $id): bool;
+
+    // 题型相关
+
+    /**
+     * 获取题型列表.
+     * @param array $params
+     * @return array
+     */
+    public function getQuestionTypeList(array $params): array;
+
+    /**
+     * 获取题型详情.
+     * @param int $id
+     * @return array
+     */
+    public function getQuestionTypeDetail(int $id): array;
+
+    /**
+     * 创建题型.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createQuestionType(array $params): bool;
+
+    /**
+     * 删除题型.
+     * @param int $id 题型ID
+     * @return bool 删除结果
+     */
+    public function updateQuestionType(int $id, array $params): bool;
+
+    /**
+     * 删除题型.
+     * @param int $id 题型ID
+     * @return bool 删除结果
+     */
+    public function deleteQuestionType(int $id): bool;
+
+    // 科目相关
+
+    /**
+     * 获取科目列表.
+     * @param array $params
+     * @return array
+     */
+    public function getSubjectList(array $params): array;
+
+    /**
+     * 获取科目详情.
+     * @param int $id
+     * @return array
+     */
+    public function getSubjectDetail(int $id): array;
+
+    /**
+     * 创建科目.
+     * @param array $params
+     * @return bool 创建结果
+     */
+    public function createSubject(array $params): bool;
+
+    /**
+     * 更新科目.
+     * @param int $id 科目ID
+     * @return bool 更新结果
+     */
+    public function updateSubject(int $id, array $params): bool;
+
+    /**
+     * 删除科目.
+     * @param int $id 科目ID
+     * @return bool 删除结果
+     */
+    public function deleteSubject(int $id): bool;
+
+    // 用户试卷记录相关
+
+    /**
+     * 开始考试（创建试卷记录）.
+     * @param array $params
+     *                      - user_id: 用户ID
+     *                      - paper_id: 试卷ID
+     * @return array 试卷记录信息
+     */
+    public function startExam(array $params): array;
+
+    /**
+     * 提交试卷.
+     * @param array $params
+     *                      - record_id: 试卷记录ID
+     *                      - user_id: 用户ID（验证权限）
+     * @return array 考试结果
+     */
+    public function submitExam(array $params): array;
+
+    /**
+     * 获取用户试卷记录列表.
+     * @param array $params
+     *                      - user_id: 用户ID
+     *                      - page: 页码
+     *                      - size: 每页条数
+     *                      - status: 状态筛选
+     * @return array 分页记录
+     */
+    public function getUserRecords(array $params): array;
+
+    /**
+     * 获取试卷记录详情.
+     * @param int $recordId 记录ID
+     * @param int $userId 用户ID（验证权限）
+     * @return array 详情信息
+     */
+    public function getRecordDetail(int $recordId, int $userId): array;
+
+    /**
+     * 获取用户考试记录列表.
+     * @param array $params
+     * @return array
+     */
+    public function getUserExamRecords(array $params): array;
+
+    /**
+     * 获取考试记录详情.
+     * @param int $recordId 考试记录ID
+     * @param int $userId 用户ID（验证权限）
+     * @return array 详情信息
+     */
+    public function getExamRecordDetail(int $recordId, int $userId): array;
+
+    // 试卷相关
+
+    // 试卷相关
+    /**
+     * 创建试卷.
+     * @param array $params
+     * @return bool
+     */
+    public function createPaper(array $params): bool;
+
+    /**
+     * 更新试卷.
+     * @param int $id 试卷ID
+     * @param array $params
+     * @return bool
+     */
+    public function updatePaper(int $id, array $params): bool;
+
+    /**
+     * 添加题目到试卷.
+     * @param int $paperId
+     * @param array $questionData
+     * @return bool
+     */
+    public function addQuestionsToPaper(int $paperId, array $questionData): bool;
+
+    /**
+     * 从试卷中移除题目.
+     * @param int $paperId
+     * @param array $questionIds
+     * @return bool
+     */
+    public function removeQuestionsFromPaper(int $paperId, array $questionIds): bool;
+
+    /**
+     * 获取试卷详情.
+     * @param int $id
+     * @return array
+     */
+    public function getPaperDetail(int $id): array;
+
+    // 试卷生成相关
+
+    /**
+     * 根据策略生成试卷.
+     * @param array $params
+     * @return array
+     */
+    public function generateByStrategy(array $params): array;
+
+    /**
+     * 手动生成试卷.
+     * @param array $params
+     * @return array
+     */
+    public function generateManual(array $params): array;
+
+    // 素材相关
+
+    /**
+     * 获取素材列表.
+     * @param array $params
+     * @return array
+     */
+    public function getMaterialList(array $params): array;
+
+    /**
+     * 获取素材详情.
+     * @param int $id
+     * @return array
+     */
+    public function getMaterialDetail(int $id): array;
+
+    /**
+     * 创建素材.
+     * @param array $params
+     * @return bool
+     */
+    public function createMaterial(array $params): bool;
+
+    /**
+     * 更新素材.
+     * @param int $id 素材ID
+     * @param array $params
+     * @return bool
+     */
+    public function updateMaterial(int $id, array $params): bool;
+
+    /**
+     * 删除素材.
+     * @param int $id 素材ID
+     * @return bool
+     */
+    public function deleteMaterial(int $id): bool;
+
+    // 题目标签关联相关
+
+    /**
+     * 添加题目标签.
+     * @param int $questionId
+     * @param array $tagIds
+     * @return bool
+     */
+    public function attachQuestionTags(int $questionId, array $tagIds): bool;
+
+    /**
+     * 删除题目标签.
+     * @param int $questionId
+     * @param array $tagIds
+     * @return bool
+     */
+    public function detachQuestionTags(int $questionId, array $tagIds = []): bool;
+
+    /**
+     * 获取题目标签.
+     * @param int $questionId
+     * @return array
+     */
+    public function getQuestionTags(int $questionId): array;
+
+    /**
+     * 获取用户错题列表.
+     * @param array $params
+     *                      - user_id: 用户ID
+     *                      - page: 页码
+     *                      - size: 每页条数
+     *                      - subject_id: 科目筛选
+     * @return array 分页错题列表
+     */
+    public function getUserWrongQuestions(array $params): array;
+
+    /**
+     * 标记错题为已掌握
+     * @param int $userId 用户ID
+     * @param int $wrongId 错题ID
+     * @return bool 操作结果
+     */
+    public function markAsMastered(int $userId, int $wrongId): bool;
+
+    /**
+     * 添加错题笔记.
+     * @param array $params
+     *                      - wrong_id: 错题ID
+     *                      - user_id: 用户ID
+     *                      - note: 笔记内容
+     * @return bool 操作结果
+     */
+    public function addNote(array $params): bool;
+
+    /**
+     * 获取题目错误统计
+     * @param int $userId 用户ID
+     * @param int $questionId 题目ID
+     * @return array 统计信息
+     */
+    public function getErrorStats(int $userId, int $questionId): array;
+
+
+    /**
+     * 保存用户答题记录.
+     * @param array $params
+     *                      - user_id: 用户ID
+     *                      - record_id: 试卷记录ID
+     *                      - question_id: 题目ID
+     *                      - user_answer: 用户答案
+     * @return bool 操作结果
+     */
+    public function saveAnswer(array $params): bool;
+
+    /**
+     * 获取试卷内用户答题记录.
+     * @param int $userId 用户ID
+     * @param int $recordId 试卷记录ID
+     * @return array 答题记录列表
+     */
+    public function getByRecordId(int $userId, int $recordId): array;
+
+    /**
+     * 批量更新题目得分.
+     * @param array $params
+     *                      - record_id: 试卷记录ID
+     *                      - scores: 得分数据 [{question_id: 1, score: 5, is_correct: true}, ...]
+     * @return bool 操作结果
+     */
+    public function batchUpdateScores(array $params): bool;
+
+
+    public function getCategoryList(array $params): array;
+
+    public function getSubQuestionCategoryList(array $data): array;
+
+    public function getCategoryDetail(int $id): array;
+
+    public function getCategoriesByIds(array $ids): array;
+
+    public function createCategory(array $params): array;
+
+    public function updateCategory(int $id, array $params): array;
+
+    public function deleteCategory(int $id): array;
+
+    public function getCategoryTree(array $ids = []): array;
+
+    public function getCategoryOptions(): array;
+
+    /**
+     * 查询指定分类下的题库数量
+     * @param int $categoryId 分类ID
+     * @return int 题库数量
+     */
+    public function getQuestionCountByCategory(int $categoryId): int;
+}
--- a/src/DataService/Exam/GufenPaperInterface.php
+++ b/src/DataService/Exam/GufenPaperInterface.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService\Exam;
+
+interface GufenPaperInterface
+{
+    //更新估分职位信息
+    public function editGufenPosition(array $params): array;
+}
--- a/src/DataService/ExamTypeSubjectInterface.php
+++ b/src/DataService/ExamTypeSubjectInterface.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface ExamTypeSubjectInterface
+{
+    public function getExamTypeSubjects(array $params): array;
+
+    public function getExamTypeSubjectBy(int $id): array;
+
+    public function createExamTypeSubject(array $data): int;
+
+    /**
+     * 批量新增科目关联（多选地区一次性追加，已存在的地区跳过不报错）
+     * @param array $data ['exam_type_id' => int, 'subject_id' => int, 'region_ids' => int[], 'is_smart_paper' => ?int, 'sort' => ?int, 'status' => ?int]
+     * @return int[] 本次批量涉及的关联记录 id
+     */
+    public function batchCreateExamTypeSubject(array $data): array;
+
+    public function updateExamTypeSubject(int $id, array $data): bool;
+
+    public function deleteExamTypeSubject(int $id): bool;
+
+    public function batchUpdateExamTypeSubjectSort(array $sorts): bool;
+
+    public function batchUpdateExamTypeSubjectStatus(array $ids, int $status): bool;
+
+    public function batchUpdateExamTypeSubjectSmartPaper(array $ids, int $isSmartPaper): bool;
+
+    /**
+     * 获取指定地区+招考类型下的科目列表（通用科目 region_id=0）
+     * @param int $regionId    招考地区ID（0=不限地区，返回全部）
+     * @param int $examTypeId  招考类型ID
+     * @return array
+     */
+    public function getSubjectsByRegionExamType(int $regionId, int $examTypeId): array;
+
+    /**
+     * 获取多个适用地区共同可用的科目，避免调用方分别查询后自行求交集。
+     * @param int[] $regionIds
+     */
+    public function getCommonSubjectsByRegions(array $regionIds, int $examTypeId): array;
+
+    /**
+     * 覆盖设置科目在指定招考类型下的适用地区
+     * @param int   $examTypeId
+     * @param int   $subjectId
+     * @param array $regionIds  地区ID列表（[0]=全国通用，[]=清空）
+     */
+    public function setSubjectRegions(int $examTypeId, int $subjectId, array $regionIds): bool;
+}
--- a/src/DataService/ExcelHeaderFieldsInterface.php
+++ b/src/DataService/ExcelHeaderFieldsInterface.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface ExcelHeaderFieldsInterface
+{
+    /**
+     * 获取表头映射列表
+     * @param string $sceneName 场景名称
+     * @return array
+     */
+    public function getExcelHeaderFields(string $sceneName): array;
+}
--- a/src/DataService/GuideNavInterface.php
+++ b/src/DataService/GuideNavInterface.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface GuideNavInterface
+{
+    /** 官网用：启用导航树 [{name,icon,children:[{name,nav_key}]}] */
+    public function getGuideNavTree(): array;
+
+    /** 后台用：含隐藏的全量树 */
+    public function adminGetGuideNavTree(): array;
+
+    /** 新增/编辑节点，返回节点 id */
+    public function saveGuideNav(array $params): int;
+
+    /** 删除节点 */
+    public function deleteGuideNav(int $id): bool;
+
+    /** 批量排序 [{id,sort}] */
+    public function batchSortGuideNav(array $items): bool;
+
+    /** 显隐切换 */
+    public function toggleGuideNavShow(int $id, int $status): bool;
+}
--- a/src/DataService/MajorsInterface.php
+++ b/src/DataService/MajorsInterface.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface MajorsInterface
+{
+    /**
+     * 获取专业分类列表
+     * @return array
+     */
+    public function getMajorsCategories(): array;
+
+    /**
+     * 获取专业树形列表
+     * @param string $category 分类
+     * @return array
+     */
+    public function getMajorsTreeList(string $category): array;
+
+    /**
+     * 获取子级列表
+     * @param string $category 分类
+     * @param int $parentId 父级ID
+     * @return array
+     */
+    public function getMajorsChildList(string $category, int $parentId = 0): array;
+
+    /**
+     * 获取专业详情
+     * @param int $majorsId
+     * @return array
+     */
+    public function getMajorsDetail(int $majorsId): array;
+}
--- a/src/DataService/RecruitUnitInterface.php
+++ b/src/DataService/RecruitUnitInterface.php
@@ -0,0 +1,81 @@
+<?php
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface RecruitUnitInterface
+{
+    /**
+     * 获取招聘单位列表
+     * @param array $params 查询参数,分页参数
+     */
+    public function getRecruitUnitList(array $params): array;
+
+    /**
+     * 获取招聘单位详情
+     */
+    public function getRecruitUnitDetail(int $unitId): array;
+
+    /**
+     * 新增/编辑招聘单位
+     */
+    public function editRecruitUnit(array $params);
+
+    /**
+     * 编辑单位的显示
+     */
+    public function editRecruitUnitShow(int $id, int $isShow);
+
+    /**
+     * 删除招聘单位
+     */
+    public function deleteRecruitUnit(int $id);
+
+    /**
+     * 获取单位职位列表
+     * @param array $params 查询参数,分页参数
+     */
+    public function getUnitPositionList(array $params): array;
+
+    /**
+     * 获取招聘岗位详情
+     */
+    public function getUnitPositionDetail(int $positionId): array;
+
+    /**
+     * 新增、编辑招聘岗位
+     */
+    public function editUnitPosition(array $params);
+
+    /**
+     * 删除招聘岗位
+     */
+    public function deleteUnitPosition(int $positionId);
+
+    /**
+     * 导入招聘岗位及职位
+     */
+    public function importUnitPosition(array $data);
+
+    /**
+     * 根据岗位ID获取岗位列表
+     */
+    public function getUnitPositionListWithIds(array $ids): array;
+
+    /**
+     * 获取单位职位树
+     * @param int $campusId 校区ID
+     * @param int $examTypeId 招考类型
+     */
+    public function getUnitPositionTree(int $campusId, int $examTypeId): array;
+
+    /**
+     * 解析职位文件
+     * @param array $data
+     */
+    public function parsePositionFile(array $data): array;
+
+    /**
+     * 根据单位ID获取单位列表
+     */
+    public function getRecruitUnitListByIds(array $ids): array;
+}
--- a/src/DataService/RegionExamTypeInterface.php
+++ b/src/DataService/RegionExamTypeInterface.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface RegionExamTypeInterface
+{
+    public function getRegionExamTypes(array $params): array;
+
+    public function getRegionExamTypeBy(int $id): array;
+
+    public function createRegionExamType(array $data): int;
+
+    /**
+     * 批量新增地区关联（多选地区一次性追加，已存在的地区跳过不报错，不影响该类型已有的其他地区关联）
+     * @param array $data ['exam_type_id' => int, 'region_ids' => int[], 'alias' => ?string, 'sort' => ?int, 'status' => ?int]
+     * @return int[] 本次批量涉及的关联记录 id
+     */
+    public function batchCreateRegionExamType(array $data): array;
+
+    public function updateRegionExamType(int $id, array $data): bool;
+
+    public function deleteRegionExamType(int $id): bool;
+
+    public function batchUpdateRegionExamTypeSort(array $sorts): bool;
+
+    public function batchUpdateRegionExamTypeStatus(array $ids, int $status): bool;
+
+    /**
+     * 获取指定地区可用的招考类型列表
+     * @param int $regionId 招考地区ID
+     * @return array 招考类型列表，region_specific 类型含 display_name 字段
+     */
+    public function getExamTypesByRegion(int $regionId): array;
+
+    /**
+     * 覆盖设置招考类型的适用地区（多选地区一次性写入）
+     * @param int   $examTypeId 招考类型ID
+     * @param array $regionIds  地区ID列表（传 [0] 表示全国通用，传 [] 表示清空）
+     */
+    public function setExamTypeRegions(int $examTypeId, array $regionIds): bool;
+
+    /**
+     * 获取已关联指定招考类型的考区列表
+     * - is_national=1 的类型返回全部启用地区
+     * - 其他类型返回 da_region_exam_type 中关联的地区
+     */
+    public function getRegionsByExamType(int $examTypeId): array;
+}
--- a/src/DataService/RegionInterface.php
+++ b/src/DataService/RegionInterface.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface RegionInterface
+{
+    public function getRegions(array $params): array;
+
+    public function getAllRegions(): array;
+
+    public function appGetRegions(array $params): array;
+
+    public function appGetRegionCampus(int $id): array;
+
+    public function getRegionBy(int $id): array;
+
+    public function createRegion(array $data): int;
+
+    public function updateRegion(int $id, array $data): bool;
+
+    public function deleteRegion(int $id): bool;
+
+    public function batchUpdateRegionSort(array $sorts): bool;
+
+    public function batchUpdateRegionStatus(array $ids, int $status): bool;
+
+    public function getRegionsByIds(array $ids): array;
+}
--- a/src/DataService/StudentScoreInterface.php
+++ b/src/DataService/StudentScoreInterface.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+/**
+ * 学生成绩弹幕接口
+ */
+interface StudentScoreInterface
+{
+    /**
+     * 获取成绩弹幕列表（后台管理）
+     * @param array $params 查询参数
+     * @return array
+     */
+    public function getStudentScoreList(array $params): array;
+
+    /**
+     * 获取成绩弹幕列表（前端展示，仅显示is_show=1的数据）
+     * @param array $params 查询参数
+     * @return array
+     */
+    public function getStudentScoreBarrage(array $params): array;
+
+    /**
+     * 获取成绩弹幕详情
+     * @param int $id
+     * @return array
+     */
+    public function getStudentScoreDetail(int $id): array;
+
+    /**
+     * 新增/编辑成绩弹幕
+     * @param array $data
+     * @return int
+     */
+    public function editStudentScore(array $data): int;
+
+    /**
+     * 删除成绩弹幕
+     * @param int $id
+     * @return bool
+     */
+    public function deleteStudentScore(int $id): bool;
+
+    /**
+     * 批量删除成绩弹幕
+     * @param array $ids
+     * @return bool
+     */
+    public function batchDeleteStudentScore(array $ids): bool;
+
+    /**
+     * 修改显示状态
+     * @param int $id
+     * @param int $isShow
+     * @return bool
+     */
+    public function editStudentScoreShow(int $id, int $isShow): bool;
+
+    /**
+     * 修改排序
+     * @param int $id
+     * @param int $sort
+     * @return bool
+     */
+    public function editStudentScoreSort(int $id, int $sort): bool;
+}
--- a/src/DataService/SubjectCategoryInterface.php
+++ b/src/DataService/SubjectCategoryInterface.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhd\Micro\Interface\DataService;
+
+interface SubjectCategoryInterface
+{
+    public function getSubjectCategories(array $params): array;
+
+    public function getSubjectCategoryBy(int $id): array;
+
+    public function createSubjectCategory(array $data): int;
+
+    /**
+     * 批量新增分类关联（多选地区一次性追加，已存在的地区跳过不报错）
+     * @param array $data ['exam_type_id' => int, 'subject_id' => int, 'category_id' => int, 'region_ids' => int[], 'is_smart_paper' => ?int, 'sort' => ?int, 'status' => ?int]
+     * @return int[] 本次批量涉及的关联记录 id
+     */
+    public function batchCreateSubjectCategory(array $data): array;
+
+    public function updateSubjectCategory(int $id, array $data): bool;
+
+    public function deleteSubjectCategory(int $id): bool;
+
+    public function batchUpdateSubjectCategorySort(array $sorts): bool;
+
+    public function batchUpdateSubjectCategoryStatus(array $ids, int $status): bool;
+
+    public function batchUpdateSubjectCategorySmartPaper(array $ids, int $isSmartPaper): bool;
+
+    /**
+     * 获取指定地区+招考类型+科目下的分类ID列表（含通用分类 region_id=0）
+     * @param int $regionId   招考地区ID（0=不限）
+     * @param int $examTypeId
+     * @param int $subjectId
+     * @return array int[]
+     */
+    public function getCategoryIdsByRegionExamTypeSubject(int $regionId, int $examTypeId, int $subjectId): array;
+
+    /** @param int[] $regionIds */
+    public function getCommonCategoryIdsByRegions(array $regionIds, int $examTypeId, int $subjectId): array;
+
+    /**
+     * 覆盖设置分类在指定招考类型+科目下的适用地区
+     * @param int   $examTypeId
+     * @param int   $subjectId
+     * @param int   $categoryId
+     * @param array $regionIds  地区ID列表（[0]=全国通用，[]=清空）
+     */
+    public function setCategoryRegions(int $examTypeId, int $subjectId, int $categoryId, array $regionIds): bool;
+}