package com.example.demo.controller;

import com.example.demo.model.*;
import com.example.demo.service.BusinessService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * 核心业务控制器。
 *
 * <p>提供信息管理系统（IMS）所有业务模块的 RESTful API 接口，包括用户管理、
 * 角色管理、部门管理、业务数据全生命周期管理、日志审计、系统配置等。</p>
 *
 * <p>所有接口返回统一格式 {@link ApiResult}。</p>
 */
@RestController
@RequestMapping("/api")
@Tag(name = "业务管理", description = "信息管理系统核心业务接口")
public class BusinessController {

    private final BusinessService businessService;

    public BusinessController(BusinessService businessService) {
        this.businessService = businessService;
    }

    // ==================== 用户管理 ====================

    /**
     * 分页查询用户列表。
     *
     * @param keyword 模糊搜索关键字
     * @param page    页码
     * @param size    每页条数
     * @return 分页结果
     * @requirement(name="用户管理", id="SRS-IMS_F-001")
     */
    @GetMapping("/user")
    @Operation(summary = "分页查询用户", description = "支持关键字模糊查询用户列表")
    public ApiResult<PageResult<User>> queryUsers(
            @RequestParam(required = false) @Parameter(description = "搜索关键字") String keyword,
            @RequestParam(defaultValue = "1") @Parameter(description = "页码") int page,
            @RequestParam(defaultValue = "10") @Parameter(description = "每页条数") int size) {
        return ApiResult.success(businessService.queryUsers(keyword, page, size));
    }

    /**
     * 根据 ID 获取用户详情。
     *
     * @param id 用户ID
     * @return 用户信息
     * @requirement(name="用户管理", id="SRS-IMS_F-001")
     */
    @GetMapping("/user/{id}")
    @Operation(summary = "获取用户详情", description = "根据用户ID获取用户详细信息")
    public ApiResult<User> getUser(@PathVariable @Parameter(description = "用户ID") Long id) {
        User user = businessService.getUserById(id);
        return user != null ? ApiResult.success(user) : ApiResult.error(404, "用户不存在");
    }

    /**
     * 新增用户。
     *
     * @param user 用户信息
     * @return 创建后的用户
     * @requirement(name="用户管理", id="SRS-IMS_F-001")
     */
    @PostMapping("/user")
    @Operation(summary = "新增用户", description = "创建新的系统用户")
    public ApiResult<User> createUser(@Valid @RequestBody @Parameter(description = "用户信息") User user) {
        return ApiResult.success("创建成功", businessService.createUser(user));
    }

    /**
     * 编辑用户。
     *
     * @param id      用户ID
     * @param user 更新后的用户信息
     * @return 更新后的用户
     * @requirement(name="用户管理", id="SRS-IMS_F-001")
     */
    @PutMapping("/user/{id}")
    @Operation(summary = "编辑用户", description = "更新指定用户的信息")
    public ApiResult<User> updateUser(@PathVariable @Parameter(description = "用户ID") Long id,
                                      @RequestBody @Parameter(description = "更新信息") User user) {
        User updated = businessService.updateUser(id, user);
        return updated != null ? ApiResult.success("更新成功", updated) : ApiResult.error(404, "用户不存在");
    }

    /**
     * 删除用户。
     *
     * @param id 用户ID
     * @return 操作结果
     * @requirement(name="用户管理", id="SRS-IMS_F-001")
     */
    @DeleteMapping("/user/{id}")
    @Operation(summary = "删除用户", description = "删除指定用户")
    public ApiResult<Void> deleteUser(@PathVariable @Parameter(description = "用户ID") Long id) {
        return businessService.deleteUser(id) ? ApiResult.success() : ApiResult.error(404, "用户不存在");
    }

    // ==================== 角色管理 ====================

    /**
     * 分页查询角色列表。
     *
     * @param keyword 搜索关键字
     * @param page    页码
     * @param size    每页条数
     * @return 分页结果
     * @requirement(name="角色管理", id="SRS-IMS_F-002")
     */
    @GetMapping("/role")
    @Operation(summary = "分页查询角色", description = "支持关键字模糊查询角色列表")
    public ApiResult<PageResult<Role>> queryRoles(
            @RequestParam(required = false) @Parameter(description = "搜索关键字") String keyword,
            @RequestParam(defaultValue = "1") @Parameter(description = "页码") int page,
            @RequestParam(defaultValue = "10") @Parameter(description = "每页条数") int size) {
        return ApiResult.success(businessService.queryRoles(keyword, page, size));
    }

    /**
     * 根据 ID 获取角色详情。
     *
     * @param id 角色ID
     * @return 角色信息
     * @requirement(name="角色管理", id="SRS-IMS_F-002")
     */
    @GetMapping("/role/{id}")
    @Operation(summary = "获取角色详情", description = "根据角色ID获取角色详细信息")
    public ApiResult<Role> getRole(@PathVariable @Parameter(description = "角色ID") Long id) {
        Role role = businessService.getRoleById(id);
        return role != null ? ApiResult.success(role) : ApiResult.error(404, "角色不存在");
    }

    /**
     * 新增角色。
     *
     * @param role 角色信息
     * @return 创建后的角色
     * @requirement(name="角色管理", id="SRS-IMS_F-002")
     */
    @PostMapping("/role")
    @Operation(summary = "新增角色", description = "创建新的系统角色")
    public ApiResult<Role> createRole(@Valid @RequestBody @Parameter(description = "角色信息") Role role) {
        return ApiResult.success("创建成功", businessService.createRole(role));
    }

    /**
     * 编辑角色。
     *
     * @param id   角色ID
     * @param role 更新后的角色信息
     * @return 更新后的角色
     * @requirement(name="角色管理", id="SRS-IMS_F-002")
     */
    @PutMapping("/role/{id}")
    @Operation(summary = "编辑角色", description = "更新指定角色的信息")
    public ApiResult<Role> updateRole(@PathVariable @Parameter(description = "角色ID") Long id,
                                      @RequestBody @Parameter(description = "更新信息") Role role) {
        Role updated = businessService.updateRole(id, role);
        return updated != null ? ApiResult.success("更新成功", updated) : ApiResult.error(404, "角色不存在");
    }

    /**
     * 删除角色（超级管理员角色不可删除）。
     *
     * @param id 角色ID
     * @return 操作结果
     * @requirement(name="角色管理", id="SRS-IMS_F-002")
     */
    @DeleteMapping("/role/{id}")
    @Operation(summary = "删除角色", description = "删除指定角色，超级管理员角色不可删除")
    public ApiResult<Void> deleteRole(@PathVariable @Parameter(description = "角色ID") Long id) {
        Boolean result = businessService.deleteRole(id);
        if (result == null) return ApiResult.error(404, "角色不存在");
        if (!result) return ApiResult.error(403, "超级管理员角色不可删除");
        return ApiResult.success();
    }

    // ==================== 角色权限分配 ====================

    /**
     * 为角色分配权限。
     *
     * @param roleId          角色ID
     * @param permissionCodes 权限标识列表
     * @return 更新后的角色
     * @requirement(name="角色权限分配", id="SRS-IMS_F-006")
     */
    @PostMapping("/role/{roleId}/permissions")
    @Operation(summary = "角色权限分配", description = "为指定角色分配权限标识列表")
    public ApiResult<Role> assignPermissions(@PathVariable @Parameter(description = "角色ID") Long roleId,
                                             @RequestBody @Parameter(description = "权限标识列表") List<String> permissionCodes) {
        Role role = businessService.assignPermissions(roleId, permissionCodes);
        return role != null ? ApiResult.success("权限分配成功", role) : ApiResult.error(404, "角色不存在");
    }

    // ==================== 部门管理 ====================

    /**
     * 获取部门树形结构。
     *
     * @return 树形部门列表
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @GetMapping("/dept/tree")
    @Operation(summary = "获取部门树", description = "获取部门树形结构数据")
    public ApiResult<List<Dept>> getDeptTree() {
        return ApiResult.success(businessService.getDeptTree());
    }

    /**
     * 获取部门列表（扁平）。
     *
     * @return 部门列表
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @GetMapping("/dept")
    @Operation(summary = "获取部门列表", description = "获取扁平结构的部门列表")
    public ApiResult<List<Dept>> getAllDepts() {
        return ApiResult.success(businessService.getAllDepts());
    }

    /**
     * 根据 ID 获取部门详情。
     *
     * @param id 部门ID
     * @return 部门信息
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @GetMapping("/dept/{id}")
    @Operation(summary = "获取部门详情", description = "根据部门ID获取部门详细信息")
    public ApiResult<Dept> getDept(@PathVariable @Parameter(description = "部门ID") Long id) {
        Dept dept = businessService.getDeptById(id);
        return dept != null ? ApiResult.success(dept) : ApiResult.error(404, "部门不存在");
    }

    /**
     * 新增部门。
     *
     * @param dept 部门信息
     * @return 创建后的部门
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @PostMapping("/dept")
    @Operation(summary = "新增部门", description = "创建新的部门")
    public ApiResult<Dept> createDept(@Valid @RequestBody @Parameter(description = "部门信息") Dept dept) {
        return ApiResult.success("创建成功", businessService.createDept(dept));
    }

    /**
     * 编辑部门。
     *
     * @param id   部门ID
     * @param dept 更新后的部门信息
     * @return 更新后的部门
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @PutMapping("/dept/{id}")
    @Operation(summary = "编辑部门", description = "更新指定部门的信息")
    public ApiResult<Dept> updateDept(@PathVariable @Parameter(description = "部门ID") Long id,
                                      @RequestBody @Parameter(description = "更新信息") Dept dept) {
        Dept updated = businessService.updateDept(id, dept);
        return updated != null ? ApiResult.success("更新成功", updated) : ApiResult.error(404, "部门不存在");
    }

    /**
     * 删除部门。
     *
     * @param id 部门ID
     * @return 操作结果
     * @requirement(name="部门管理", id="SRS-IMS_F-003")
     */
    @DeleteMapping("/dept/{id}")
    @Operation(summary = "删除部门", description = "删除指定部门")
    public ApiResult<Void> deleteDept(@PathVariable @Parameter(description = "部门ID") Long id) {
        return businessService.deleteDept(id) ? ApiResult.success() : ApiResult.error(404, "部门不存在");
    }

    // ==================== 业务数据管理 ====================

    /**
     * 分页查询业务数据（多条件组合筛选）。
     *
     * @param keyword 关键字
     * @param type    业务类型
     * @param status  业务状态
     * @param page    页码
     * @param size    每页条数
     * @return 分页结果
     * @requirement(name="查询筛选", id="SRS-IMS_F-017")
     */
    @GetMapping("/business")
    @Operation(summary = "分页查询业务数据", description = "多条件组合查询业务数据列表")
    public ApiResult<PageResult<BusinessItem>> queryBusiness(
            @RequestParam(required = false) @Parameter(description = "关键字") String keyword,
            @RequestParam(required = false) @Parameter(description = "业务类型") String type,
            @RequestParam(required = false) @Parameter(description = "业务状态") String status,
            @RequestParam(defaultValue = "1") @Parameter(description = "页码") int page,
            @RequestParam(defaultValue = "10") @Parameter(description = "每页条数") int size) {
        return ApiResult.success(businessService.queryBusinessItems(keyword, type, status, page, size));
    }

    /**
     * 根据 ID 获取业务数据详情。
     *
     * @param id 业务数据ID
     * @return 业务数据
     * @requirement(name="查询筛选", id="SRS-IMS_F-017")
     */
    @GetMapping("/business/{id}")
    @Operation(summary = "获取业务数据详情", description = "根据ID获取业务数据详细信息")
    public ApiResult<BusinessItem> getBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id) {
        BusinessItem item = businessService.getBusinessItemById(id);
        return item != null ? ApiResult.success(item) : ApiResult.error(404, "业务数据不存在");
    }

    /**
     * 新增业务数据。
     *
     * @param item 业务数据
     * @return 创建后的业务数据
     * @requirement(name="业务新增", id="SRS-IMS_F-010")
     */
    @PostMapping("/business")
    @Operation(summary = "新增业务数据", description = "创建新的业务数据（状态为草稿）")
    public ApiResult<BusinessItem> createBusiness(@Valid @RequestBody @Parameter(description = "业务数据") BusinessItem item) {
        return ApiResult.success("创建成功", businessService.createBusinessItem(item));
    }

    /**
     * 编辑业务数据。
     *
     * @param id   业务数据ID
     * @param item 更新后的业务数据
     * @return 更新后的业务数据
     * @requirement(name="业务编辑", id="SRS-IMS_F-011")
     */
    @PutMapping("/business/{id}")
    @Operation(summary = "编辑业务数据", description = "更新指定业务数据（仅草稿或驳回状态可编辑）")
    public ApiResult<BusinessItem> updateBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id,
                                                   @RequestBody @Parameter(description = "更新信息") BusinessItem item) {
        BusinessItem updated = businessService.updateBusinessItem(id, item);
        if (updated == null) {
            return ApiResult.error(400, "仅草稿或驳回状态的业务数据可编辑");
        }
        return ApiResult.success("更新成功", updated);
    }

    /**
     * 删除业务数据。
     *
     * @param id 业务数据ID
     * @return 操作结果
     * @requirement(name="业务删除", id="SRS-IMS_F-012")
     */
    @DeleteMapping("/business/{id}")
    @Operation(summary = "删除业务数据", description = "删除指定业务数据")
    public ApiResult<Void> deleteBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id) {
        return businessService.deleteBusinessItem(id) ? ApiResult.success() : ApiResult.error(404, "业务数据不存在");
    }

    /**
     * 提交业务数据至审核流程。
     *
     * @param id 业务数据ID
     * @return 提交后的业务数据
     * @requirement(name="业务提交", id="SRS-IMS_F-013")
     */
    @PostMapping("/business/{id}/submit")
    @Operation(summary = "提交业务审核", description = "将指定业务数据提交至审核流程（仅草稿或驳回状态可提交）")
    public ApiResult<BusinessItem> submitBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id) {
        BusinessItem item = businessService.submitBusinessItem(id);
        if (item == null) {
            return ApiResult.error(400, "仅草稿或驳回状态的业务数据可提交审核");
        }
        return ApiResult.success("提交审核成功", item);
    }

    /**
     * 审核通过业务数据。
     *
     * @param id      业务数据ID
     * @param request 请求体（含审核意见）
     * @return 审核后的业务数据
     * @requirement(name="业务审核", id="SRS-IMS_F-014")
     */
    @PostMapping("/business/{id}/approve")
    @Operation(summary = "审核通过", description = "审核通过已提交的业务数据")
    public ApiResult<BusinessItem> approveBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id,
                                                    @RequestBody(required = false) @Parameter(description = "审核意见") Map<String, String> request) {
        String comment = request != null ? request.get("comment") : null;
        BusinessItem item = businessService.approveBusinessItem(id, comment);
        if (item == null) {
            return ApiResult.error(400, "仅已提交状态的业务数据可审核");
        }
        return ApiResult.success("审核通过", item);
    }

    /**
     * 驳回业务数据。
     *
     * @param id      业务数据ID
     * @param request 请求体（含驳回原因）
     * @return 驳回后的业务数据
     * @requirement(name="业务驳回", id="SRS-IMS_F-015")
     */
    @PostMapping("/business/{id}/reject")
    @Operation(summary = "驳回业务", description = "驳回已提交的业务数据，需填写驳回原因")
    public ApiResult<BusinessItem> rejectBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id,
                                                   @RequestBody @Parameter(description = "驳回原因") Map<String, String> request) {
        String comment = request != null ? request.get("reason") : "驳回";
        BusinessItem item = businessService.rejectBusinessItem(id, comment);
        if (item == null) {
            return ApiResult.error(400, "仅已提交状态的业务数据可驳回");
        }
        return ApiResult.success("驳回成功", item);
    }

    /**
     * 归档业务数据。
     *
     * @param id 业务数据ID
     * @return 归档后的业务数据
     * @requirement(name="业务归档", id="SRS-IMS_F-016")
     */
    @PostMapping("/business/{id}/archive")
    @Operation(summary = "归档业务", description = "归档已审核通过的业务数据")
    public ApiResult<BusinessItem> archiveBusiness(@PathVariable @Parameter(description = "业务数据ID") Long id) {
        BusinessItem item = businessService.archiveBusinessItem(id);
        if (item == null) {
            return ApiResult.error(400, "仅已通过状态的业务数据可归档");
        }
        return ApiResult.success("归档成功", item);
    }

    // ==================== 数据统计分析 ====================

    /**
     * 数据汇总：按业务类型统计数量。
     *
     * @return 汇总数据
     * @requirement(name="数据汇总", id="SRS-IMS_F-018")
     */
    @GetMapping("/business/summary")
    @Operation(summary = "数据汇总", description = "按业务类型统计业务数据数量")
    public ApiResult<Map<String, Long>> getBusinessSummary() {
        return ApiResult.success(businessService.getBusinessSummary());
    }

    /**
     * 图表展示：按业务状态统计数量。
     *
     * @return 图表数据
     * @requirement(name="图表展示", id="SRS-IMS_F-019")
     */
    @GetMapping("/business/chart")
    @Operation(summary = "图表数据", description = "按业务状态统计数量，用于可视化图表渲染")
    public ApiResult<Map<String, Long>> getChartData() {
        return ApiResult.success(businessService.getChartData());
    }

    /**
     * 自定义查询：根据自定义条件过滤业务数据。
     *
     * @param conditions 查询条件
     * @return 符合条件的业务数据列表
     * @requirement(name="自定义查询", id="SRS-IMS_F-020")
     */
    @PostMapping("/business/custom-query")
    @Operation(summary = "自定义查询", description = "根据自定义条件灵活查询业务数据")
    public ApiResult<List<BusinessItem>> customQuery(@RequestBody(required = false) @Parameter(description = "查询条件") Map<String, String> conditions) {
        return ApiResult.success(businessService.customQuery(conditions));
    }

    /**
     * 报表导出（模拟数据源）。
     *
     * @return 业务数据列表
     * @requirement(name="报表导出", id="SRS-IMS_F-021")
     */
    @GetMapping("/business/export")
    @Operation(summary = "报表导出", description = "导出业务数据报表（模拟数据源）")
    public ApiResult<List<BusinessItem>> exportReport() {
        return ApiResult.success(businessService.exportReport());
    }

    /**
     * 数据台账生成。
     *
     * @return 台账数据
     * @requirement(name="数据台账生成", id="SRS-IMS_F-022")
     */
    @GetMapping("/business/ledger")
    @Operation(summary = "数据台账生成", description = "按类型分组生成结构化台账数据")
    public ApiResult<Map<String, List<BusinessItem>>> generateLedger() {
        return ApiResult.success(businessService.generateLedger());
    }

    // ==================== 日志审计管理 ====================

    /**
     * 记录登录日志。
     *
     * @param request 请求体（含用户名、IP）
     * @return 操作结果
     * @requirement(name="登录日志记录", id="SRS-IMS_F-023")
     */
    @PostMapping("/log/login")
    @Operation(summary = "记录登录日志", description = "记录用户登录行为日志")
    public ApiResult<Void> recordLoginLog(@RequestBody @Parameter(description = "登录信息") Map<String, String> request) {
        String username = request.getOrDefault("username", "unknown");
        String ip = request.getOrDefault("ip", "127.0.0.1");
        String result = request.getOrDefault("result", "SUCCESS");
        businessService.recordLoginLog(username, ip, result);
        return ApiResult.success();
    }

    /**
     * 日志溯源查询。
     *
     * @param logType  日志类型
     * @param username 操作用户
     * @param keyword  关键字
     * @param page     页码
     * @param size     每页条数
     * @return 分页日志
     * @requirement(name="日志溯源查询", id="SRS-IMS_F-026")
     */
    @GetMapping("/log")
    @Operation(summary = "日志溯源查询", description = "多条件组合查询各类日志，用于审计追溯")
    public ApiResult<PageResult<LogRecord>> queryLogs(
            @RequestParam(required = false) @Parameter(description = "日志类型(LOGIN/OPERATION/EXCEPTION)") String logType,
            @RequestParam(required = false) @Parameter(description = "操作用户") String username,
            @RequestParam(required = false) @Parameter(description = "关键字") String keyword,
            @RequestParam(defaultValue = "1") @Parameter(description = "页码") int page,
            @RequestParam(defaultValue = "10") @Parameter(description = "每页条数") int size) {
        return ApiResult.success(businessService.queryLogs(logType, username, keyword, page, size));
    }

    // ==================== 菜单/按钮/数据权限 ====================

    /**
     * 获取完整权限树（用于权限分配页面）。
     *
     * @return 完整权限树
     * @requirement(name="角色权限分配", id="SRS-IMS_F-006")
     */
    @GetMapping("/permission/tree")
    @Operation(summary = "获取权限树", description = "获取完整的菜单/按钮权限树，用于权限分配")
    public ApiResult<List<TreeNode>> getPermissionTree() {
        return ApiResult.success(businessService.getFullPermissionTree());
    }

    /**
     * 根据角色ID获取动态菜单。
     *
     * @param roleId 角色ID
     * @return 菜单树
     * @requirement(name="菜单权限管理", id="SRS-IMS_F-007")
     */
    @GetMapping("/menu/{roleId}")
    @Operation(summary = "获取角色菜单", description = "根据角色ID动态加载菜单项")
    public ApiResult<List<TreeNode>> getMenusByRole(@PathVariable @Parameter(description = "角色ID") Long roleId) {
        return ApiResult.success(businessService.getMenusByRole(roleId));
    }

    /**
     * 根据角色ID获取按钮权限。
     *
     * @param roleId 角色ID
     * @return 按钮权限标识列表
     * @requirement(name="按钮权限管理", id="SRS-IMS_F-008")
     */
    @GetMapping("/button/{roleId}")
    @Operation(summary = "获取按钮权限", description = "根据角色ID获取按钮级权限标识列表")
    public ApiResult<List<String>> getButtonPermissions(@PathVariable @Parameter(description = "角色ID") Long roleId) {
        return ApiResult.success(businessService.getButtonPermissions(roleId));
    }

    /**
     * 获取用户数据权限范围。
     *
     * @param userId 用户ID
     * @return 可访问的部门ID列表
     * @requirement(name="数据权限分级管控", id="SRS-IMS_F-009")
     */
    @GetMapping("/data-scope/{userId}")
    @Operation(summary = "获取数据权限", description = "根据用户ID获取数据权限范围（可访问的部门ID列表）")
    public ApiResult<List<Long>> getDataScope(@PathVariable @Parameter(description = "用户ID") Long userId) {
        return ApiResult.success(businessService.getDataScope(userId));
    }

    // ==================== 字典管理 ====================

    /**
     * 查询字典列表。
     *
     * @param dictType 字典类型
     * @param keyword  关键字
     * @return 字典列表
     * @requirement(name="字典管理", id="SRS-IMS_F-004")
     */
    @GetMapping("/dict")
    @Operation(summary = "查询字典", description = "查询数据字典项，可按类型和关键字过滤")
    public ApiResult<List<DictItem>> queryDict(
            @RequestParam(required = false) @Parameter(description = "字典类型") String dictType,
            @RequestParam(required = false) @Parameter(description = "关键字") String keyword) {
        return ApiResult.success(businessService.queryDictItems(dictType, keyword));
    }

    /**
     * 新增字典项。
     *
     * @param item 字典项
     * @return 创建后的字典项
     * @requirement(name="字典管理", id="SRS-IMS_F-004")
     */
    @PostMapping("/dict")
    @Operation(summary = "新增字典项", description = "创建新的数据字典项")
    public ApiResult<DictItem> createDict(@Valid @RequestBody @Parameter(description = "字典项") DictItem item) {
        return ApiResult.success("创建成功", businessService.createDictItem(item));
    }

    /**
     * 编辑字典项。
     *
     * @param id   字典ID
     * @param item 更新后的字典项
     * @return 更新后的字典项
     * @requirement(name="字典管理", id="SRS-IMS_F-004")
     */
    @PutMapping("/dict/{id}")
    @Operation(summary = "编辑字典项", description = "更新指定字典项的信息")
    public ApiResult<DictItem> updateDict(@PathVariable @Parameter(description = "字典ID") Long id,
                                           @RequestBody @Parameter(description = "更新信息") DictItem item) {
        DictItem updated = businessService.updateDictItem(id, item);
        return updated != null ? ApiResult.success("更新成功", updated) : ApiResult.error(404, "字典项不存在");
    }

    /**
     * 删除字典项。
     *
     * @param id 字典ID
     * @return 操作结果
     * @requirement(name="字典管理", id="SRS-IMS_F-004")
     */
    @DeleteMapping("/dict/{id}")
    @Operation(summary = "删除字典项", description = "删除指定字典项")
    public ApiResult<Void> deleteDict(@PathVariable @Parameter(description = "字典ID") Long id) {
        return businessService.deleteDictItem(id) ? ApiResult.success() : ApiResult.error(404, "字典项不存在");
    }

    // ==================== 参数配置 ====================

    /**
     * 查询所有系统参数配置。
     *
     * @return 配置列表
     * @requirement(name="参数配置", id="SRS-IMS_F-005")
     */
    @GetMapping("/config")
    @Operation(summary = "查询参数配置", description = "获取所有系统运行参数配置")
    public ApiResult<List<SystemConfig>> getAllConfigs() {
        return ApiResult.success(businessService.getAllConfigs());
    }

    /**
     * 新增系统参数配置。
     *
     * @param config 配置信息
     * @return 创建后的配置
     * @requirement(name="参数配置", id="SRS-IMS_F-005")
     */
    @PostMapping("/config")
    @Operation(summary = "新增参数配置", description = "创建新的系统参数配置")
    public ApiResult<SystemConfig> createConfig(@Valid @RequestBody @Parameter(description = "配置信息") SystemConfig config) {
        return ApiResult.success("创建成功", businessService.createConfig(config));
    }

    /**
     * 编辑系统参数配置。
     *
     * @param id     配置ID
     * @param config 更新后的配置
     * @return 更新后的配置
     * @requirement(name="参数配置", id="SRS-IMS_F-005")
     */
    @PutMapping("/config/{id}")
    @Operation(summary = "编辑参数配置", description = "更新指定参数配置")
    public ApiResult<SystemConfig> updateConfig(@PathVariable @Parameter(description = "配置ID") Long id,
                                                 @RequestBody @Parameter(description = "更新信息") SystemConfig config) {
        SystemConfig updated = businessService.updateConfig(id, config);
        return updated != null ? ApiResult.success("更新成功", updated) : ApiResult.error(404, "配置不存在");
    }

    /**
     * 删除系统参数配置。
     *
     * @param id 配置ID
     * @return 操作结果
     * @requirement(name="参数配置", id="SRS-IMS_F-005")
     */
    @DeleteMapping("/config/{id}")
    @Operation(summary = "删除参数配置", description = "删除指定系统参数配置")
    public ApiResult<Void> deleteConfig(@PathVariable @Parameter(description = "配置ID") Long id) {
        return businessService.deleteConfig(id) ? ApiResult.success() : ApiResult.error(404, "配置不存在");
    }

    // ==================== 标准化接口与第三方对接 ====================

    /**
     * 获取标准 API 接口定义列表。
     *
     * @return 接口定义列表
     * @requirement(name="标准化接口预留", id="SRS-IMS_F-027")
     */
    @GetMapping("/external/apis")
    @Operation(summary = "标准接口定义", description = "获取系统对外提供的标准化API接口定义列表")
    public ApiResult<List<Map<String, String>>> getStandardApiDefinitions() {
        return ApiResult.success(businessService.getStandardApiDefinitions());
    }

    /**
     * 第三方数据导入。
     *
     * @param data 外部数据列表
     * @return 导入结果
     * @requirement(name="第三方数据对接", id="SRS-IMS_F-028")
     */
    @PostMapping("/external/import")
    @Operation(summary = "第三方数据导入", description = "从外部系统导入业务数据")
    public ApiResult<Map<String, Object>> importExternalData(@RequestBody @Parameter(description = "外部数据列表") List<Map<String, String>> data) {
        return ApiResult.success(businessService.importExternalData(data));
    }

    /**
     * 执行数据同步任务。
     *
     * @param request 请求体（含同步类型）
     * @return 同步结果
     * @requirement(name="数据同步", id="SRS-IMS_F-029")
     */
    @PostMapping("/external/sync")
    @Operation(summary = "数据同步", description = "执行定时或实时的数据同步任务")
    public ApiResult<Map<String, Object>> executeDataSync(@RequestBody @Parameter(description = "同步参数") Map<String, String> request) {
        String syncType = request != null ? request.getOrDefault("syncType", "PULL") : "PULL";
        return ApiResult.success(businessService.executeDataSync(syncType));
    }
}
