# 架构约定

## 1. 系统边界

梦畅AIGC 采用前后端分离的单仓库结构：

```text
Vue 3 主应用
└── React 子模块 ── HTTP/API ─┐
                              ├─ Java 主业务后端 ─ PostgreSQL
                              │                    ├─ Redis
                              │                    └─ MinIO
                              └─ 已认证的内部 HTTP 调用 ─ Python Agent
                                                   ├─ LangChain
                                                   └─ LangGraph
```

当前图仅描述已确认的系统边界，不代表最终部署拓扑。

## 2. 前端

- `apps/web-vue/` 是主要用户入口，也是 React 子模块的宿主应用。
- React 子模块位于 Vue 主应用内部，随主应用一起构建和部署。
- React 子模块与 Vue 主应用之间通过明确的挂载、输入、输出和事件契约交互。

## 3. 服务职责

- `services/api/` 是 Java 模块化单体主业务后端，负责认证授权、业务规则、业务数据持久化，以及对 PostgreSQL、Redis 和 MinIO 的受控访问。
- `services/agent/` 是 Python 3.11+ Agent 进程，使用 LangChain 组织模型、提示词和工具，使用 LangGraph 编排有状态、多步骤或可恢复的 Agent 流程。
- 前端请求必须先进入 `services/api/`；Java 完成用户认证和授权后，才可以通过内部 HTTP API 调用 Agent，并传递经过校验的用户和请求上下文。
- Agent 不拥有主业务数据的最终写入权，不直接连接主业务 PostgreSQL，也不建立独立的用户认证体系；业务数据读写通过 `services/api/` 完成。
- 模型供应商、提示词、工具权限和 Agent 状态属于 Agent 服务边界；业务实体、用户权限和业务审计属于 Java 主业务后端边界。

## 4. Java DDD 主业务后端

- 后端位于 `services/api/`，使用 Spring Boot、JDK 21 和 Maven。
- Maven 坐标使用 `mc:mcaigc`，Java 基础包名使用 `mc.mcaigc`。
- API、领域逻辑和基础设施访问应保持清晰边界；具体模块随真实业务出现后再建立。
- 数据库结构变更必须通过迁移管理，但迁移工具尚待选定。

Maven 多模块职责如下：

```text
mcaigc-boot
├── mcaigc-interfaces ── mcaigc-application ── mcaigc-domain
└── mcaigc-infrastructure ────────────────────┘
```

- `domain` 不依赖 Spring、数据库驱动或 Web 框架。
- `application` 只编排用例和事务边界，通过领域端口访问外部能力。
- `infrastructure` 实现领域端口，封装 PostgreSQL、Redis 和 MinIO 等技术细节。
- `interfaces` 负责 HTTP/DTO 等输入输出适配，不承载领域规则。
- `boot` 只负责启动和依赖组装，不承载业务逻辑。

当前骨架是一个模块化单体主业务服务内部的 DDD 多模块结构，暂不拆分为多个微服务。未来确需按限界上下文拆分时，各服务应复用相同的分层约束；服务发现、配置中心、网关和分布式事务等 Spring Cloud 基础设施不在本次骨架中预设。

Python Agent 已提供最小包骨架和无模型 LangGraph 自检流程；真实模型、内部 HTTP 服务、依赖锁定方式和部署形态仍需按业务场景确定。

### Java 与 Agent 的调用方式

- Java 与 Agent 作为独立进程运行，通过内部网络上的 HTTP API 通信；Agent 不直接暴露给浏览器或公网。
- Agent API 使用版本化路径，例如 `/internal/v1/`，请求和响应使用 JSON；具体资源名称、字段和错误格式在实现对应能力前单独确定。
- Java 负责校验用户身份、权限和业务参数，然后向 Agent 传递请求编号、用户/租户上下文、已授权能力和业务输入。Agent 不重复建立用户登录体系，只校验 Java 的服务间调用凭据和请求格式。
- 短时间内可完成的生成任务使用同步 HTTP 请求；较长任务仍通过 HTTP 创建任务并返回任务编号，状态查询或结果获取由 Java 负责对前端提供统一接口。
- Java 调用 Agent 必须设置连接和读取超时、有限重试和幂等请求编号；Agent 需要返回可区分的业务错误、参数错误和暂时不可用错误。
- 服务间认证方式（例如 mTLS 或内部服务令牌）、超时数值、流式输出方式和具体 API 契约在实现前确定。

## 5. 数据与基础设施

- PostgreSQL：持久化业务数据。
- Redis：缓存和适合其数据模型的短期状态；不得作为唯一持久化来源。
- MinIO：存储上传文件、生成内容等对象数据；数据库只保存必要的对象元数据和引用。
- Docker：用于本地开发依赖，不预设生产部署方式。

## 6. 待决策事项

下列事项应在相关实现开始前确定：

1. React 子模块的挂载、状态和事件通信契约。
2. Java 调用 Agent 的内部认证上下文和 HTTP API 契约。
3. Java 主业务后端的认证机制及 Agent 内部调用的信任方式。
4. Python 版本、Agent 依赖锁定方式和运行时隔离方式。
5. API 契约格式和版本策略。
6. PostgreSQL 数据库迁移工具。
7. MinIO 对象命名、生命周期和访问控制策略。
8. 本地 Docker 服务端口、卷和初始化流程。
