# 后端模块总览

## 1. 当前代码边界

当前后端已有 `common`、`rag`、`modelprovider`、`agent` 包。后续重新实现时，可以保留这些包作为技术分层落点，但业务文档按产品域拆分。

## 2. 后端实现原则

- Controller 不直接暴露实体。
- 请求使用 `XxxRequest`，响应使用 `XxxResponse`。
- 统一返回 `RequestResult<T>`。
- 实体继承 `BaseEntity`，保持审计字段和乐观锁字段。
- Mapper 继续使用 MyBatis-Plus `BaseMapper<T>`。
- Service 负责业务校验、状态流转和跨表协调。

## 3. 模块落点建议

| 产品域 | 后端包建议 |
|--------|------------|
| 系统基础 | `com.bruce.common` |
| 知识资产与文件解析 | `com.bruce.rag` |
| 模型与路由 | `com.bruce.modelprovider` |
| Workflow 编排 | `com.bruce.workflow` |
| Agent 会话 | `com.bruce.agent` |
| MCP 能力接入 | `com.bruce.mcp` |
| Skill 编辑 | `com.bruce.skill` |
| 运行观测 | `com.bruce.observability` 或复用运行来源模块 |

## 4. 枚举实现约束

新增结构化枚举时，继续实现 `PersistableSysEnumDefinition`，并同步：

- Java 枚举定义。
- `sys_enum` 初始化测试。
- `script/sql/studio_enum.sql` 或对应模块枚举脚本。
- 前端枚举常量或字典接口。