后端框架初始化

6a898afb · 郭腾飞 · cdefdd78 · 6a898afb · 6a898afb · 6a898afb
Commit 6a898afb authored Aug 13, 2026 by 郭腾飞
62 changed files
--- a/.editorconfig
+++ b/.editorconfig
@@ -11,5 +11,8 @@ trim_trailing_whitespace = true
 [*.java]
 indent_size = 4

+[*.py]
+indent_size = 4
+
 [*.md]
 trim_trailing_whitespace = false
--- a/.gitignore
+++ b/.gitignore
@@ -35,5 +35,19 @@ coverage/
 .eslintcache
 .stylelintcache

+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+
+# Python tooling
+.python-version
+
 # Local infrastructure data
 infra/docker/data/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,23 +11,40 @@
 ## 技术约束

 - `apps/web-vue/`：Vue 3 + TypeScript 主前端，内嵌 React + TypeScript 子模块。
- `services/api/`：Spring Boot 后端，JDK 21，Maven。
+- `services/api/`：Spring Boot 模块化单体主业务后端，JDK 21，Maven。
+- `services/agent/`：Python 3.11+ Agent 进程，使用 LangChain 和 LangGraph，由 Java 主业务后端调用。
 - Maven 坐标约定：`groupId=mc`、`artifactId=mcaigc`。
 - Java 基础包名约定：`mc.mcaigc`。
 - PostgreSQL 是主数据库，Redis 用于缓存，MinIO 用于对象存储。
 - `infra/docker/` 只承载本地开发环境相关文件。

+### Java DDD 模块
+
+- `services/api/mcaigc-domain/`：领域模型和领域端口，不依赖 Spring。
+- `services/api/mcaigc-application/`：应用服务和用例编排，依赖领域层。
+- `services/api/mcaigc-infrastructure/`：数据库、缓存、对象存储等技术适配，依赖领域层。
+- `services/api/mcaigc-interfaces/`：HTTP 接口、DTO 和参数适配，依赖应用层。
+- `services/api/mcaigc-boot/`：Spring Boot 启动模块，组装各层并提供可运行入口。
+
+具体业务服务出现后，应在此骨架内按业务边界拆分模块，不跨领域直接引用内部实现。
+
 ## 修改原则

 1. 目录、源代码标识符和配置键使用英文；项目文档使用中文。
 2. React 子模块与 Vue 主应用之间通过明确的公开契约交互，不直接依赖彼此的内部实现。
-3. 后端模块不得绕过既定分层直接访问其他模块内部实现。
-4. 原始资料只追加、不覆盖，按 `resources/raw/YYYY/YYYY-MM-DD/` 归档。
-5. 不为尚未确认的需求预建模块、依赖或抽象。
-6. 修改项目结构、核心技术选型或跨模块契约时，同步更新 `docs/` 中的相关文档。
+3. Java 主业务后端负责认证授权、业务 API、业务规则和持久化；Python Agent 负责智能体编排、工具调用和模型交互。
+4. 用户和前端不得直接调用 Agent；请求必须先经过 Java 主业务后端认证和授权，再由 Java 调用 Agent。
+5. Agent 不建立独立的用户认证体系，不直接修改主业务数据库；需要读写业务数据时通过 Java 主业务后端的公开 HTTP API 完成。
+6. Java 与 Agent 通过内部、版本化的 HTTP/JSON 契约通信；用户和前端不得绕过 Java 直接访问 Agent。
+7. 后端模块不得绕过既定分层直接访问其他模块内部实现。
+8. 原始资料只追加、不覆盖，按 `resources/raw/YYYY/YYYY-MM-DD/` 归档。
+9. 不为尚未确认的需求预建模块、依赖或抽象。
+10. 修改项目结构、核心技术选型或跨模块契约时，同步更新 `docs/` 中的相关文档。

 ## 验证要求

 - 只运行与改动范围相匹配的最小验证。
 - 新增业务代码后，应为关键分支、数据转换和边界条件补充自动化测试。
 - 在工具链尚未初始化前，不编造不可执行的构建或测试命令。
+- Java 骨架验证：`cd services/api && mvn verify`。
+- Agent 骨架验证：安装开发依赖后运行 `cd services/agent && python -m pytest`。
--- a/README.md
+++ b/README.md
 # 梦畅AIGC

-梦畅AIGC 是一个用于 AIGC 内容生成的 Web 平台。本仓库采用单仓库结构，包含 Vue 3 主前端（内嵌 React 子模块）、Spring Boot 后端、本地开发基础设施，以及项目文档和原始资料。
+梦畅AIGC 是一个用于 AIGC 内容生成的 Web 平台。本仓库采用单仓库结构，包含 Vue 3 主前端（内嵌 React 子模块）、Spring Boot 主业务后端、Python Agent 服务、本地开发基础设施，以及项目文档和原始资料。

-当前仓库仅完成目录与项目规范初始化，尚未生成任何业务代码或运行配置。
+当前仓库已生成 Java 主业务后端和 Python Agent 的项目骨架，尚未实现具体业务功能或生产运行配置。

 ## 技术基线

 - 主前端：Vue 3 + TypeScript
 - 内嵌子模块：React + TypeScript，位于 Vue 主应用内部
 - 后端：Spring Boot、JDK 21、Maven
+- Agent：Python 3.11+、LangChain、LangGraph
 - 数据库：PostgreSQL
 - 缓存：Redis
 - 对象存储：MinIO
@@ -21,7 +22,8 @@
 ├── apps/
 │   └── web-vue/             # Vue 3 主前端，内嵌 React 子模块
 ├── services/
-│   └── api/                 # Spring Boot 后端
+│   ├── api/                 # Spring Boot 模块化单体主业务后端，DDD 多模块骨架
+│   └── agent/               # Python LangChain/LangGraph Agent 进程骨架
 ├── infra/
 │   └── docker/              # 本地开发基础设施
 ├── resources/
@@ -44,7 +46,9 @@

 - Node.js 版本和前端包管理器
 - React 子模块与 Vue 主应用的通信契约
+- Java 主业务后端调用 Agent 的内部 HTTP API 契约（认证、版本、错误格式等）
+- Python Agent 依赖锁定方式
 - 数据库迁移工具
 - 开发环境服务端口和容器编排细节

-以上事项应在开始对应代码开发前确定，不在本次初始化中预设。
+以上事项应在实现对应能力前确定；当前骨架只提供本地构建和自检入口。
--- a/apps/web-vue/index.html
+++ b/apps/web-vue/index.html
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>金水流域闸站联合调度数据支撑系统</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
--- a/apps/web-vue/package-lock.json
+++ b/apps/web-vue/package-lock.json
--- a/apps/web-vue/package.json
+++ b/apps/web-vue/package.json
+{
+  "name": "jinshui-water-dashboard",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0"
+  },
+  "dependencies": {
+    "@vitejs/plugin-vue": "latest",
+    "vite": "latest",
+    "vue": "latest"
+  },
+  "devDependencies": {}
+}
--- a/apps/web-vue/public/assets/header/headon.png
+++ b/apps/web-vue/public/assets/header/headon.png
--- a/apps/web-vue/public/assets/header/menu_on.png
+++ b/apps/web-vue/public/assets/header/menu_on.png
--- a/apps/web-vue/public/assets/header/new_tops.png
+++ b/apps/web-vue/public/assets/header/new_tops.png
--- a/apps/web-vue/public/assets/home-map.jpg
+++ b/apps/web-vue/public/assets/home-map.jpg
--- a/apps/web-vue/public/assets/img1.png
+++ b/apps/web-vue/public/assets/img1.png
--- a/apps/web-vue/public/assets/img2.png
+++ b/apps/web-vue/public/assets/img2.png
--- a/apps/web-vue/public/assets/map/down.png
+++ b/apps/web-vue/public/assets/map/down.png
--- a/apps/web-vue/public/assets/map/left.png
+++ b/apps/web-vue/public/assets/map/left.png
--- a/apps/web-vue/public/assets/map/map-flow.png
+++ b/apps/web-vue/public/assets/map/map-flow.png
--- a/apps/web-vue/public/assets/map/map-gate-disable.png
+++ b/apps/web-vue/public/assets/map/map-gate-disable.png
--- a/apps/web-vue/public/assets/map/map-gate-enable.png
+++ b/apps/web-vue/public/assets/map/map-gate-enable.png
--- a/apps/web-vue/public/assets/map/map-pump.png
+++ b/apps/web-vue/public/assets/map/map-pump.png
--- a/apps/web-vue/public/assets/map/map-rainfall-station.png
+++ b/apps/web-vue/public/assets/map/map-rainfall-station.png
--- a/apps/web-vue/public/assets/map/map-river-water-level.png
+++ b/apps/web-vue/public/assets/map/map-river-water-level.png
--- a/apps/web-vue/public/assets/map/map-video.png
+++ b/apps/web-vue/public/assets/map/map-video.png
--- a/apps/web-vue/public/assets/map/map1.png
+++ b/apps/web-vue/public/assets/map/map1.png
--- a/apps/web-vue/public/assets/map/map2.png
+++ b/apps/web-vue/public/assets/map/map2.png
--- a/apps/web-vue/public/assets/map/map3.png
+++ b/apps/web-vue/public/assets/map/map3.png
--- a/apps/web-vue/public/assets/map/position.png
+++ b/apps/web-vue/public/assets/map/position.png
--- a/apps/web-vue/public/assets/map/position_green.png
+++ b/apps/web-vue/public/assets/map/position_green.png
--- a/apps/web-vue/public/assets/map/right.png
+++ b/apps/web-vue/public/assets/map/right.png
--- a/apps/web-vue/public/assets/map/up.png
+++ b/apps/web-vue/public/assets/map/up.png
--- a/apps/web-vue/public/assets/mapbox-background.jpg
+++ b/apps/web-vue/public/assets/mapbox-background.jpg
--- a/apps/web-vue/public/assets/newlogin_bg.jpg
+++ b/apps/web-vue/public/assets/newlogin_bg.jpg
--- a/apps/web-vue/public/assets/njsw.png
+++ b/apps/web-vue/public/assets/njsw.png
--- a/apps/web-vue/public/assets/weather/104.png
+++ b/apps/web-vue/public/assets/weather/104.png
--- a/apps/web-vue/public/assets/wjsw.png
+++ b/apps/web-vue/public/assets/wjsw.png
--- a/apps/web-vue/src/App.vue
+++ b/apps/web-vue/src/App.vue
--- a/apps/web-vue/src/main.ts
+++ b/apps/web-vue/src/main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import './styles.css'
+
+createApp(App).mount('#app')
--- a/apps/web-vue/src/styles.css
+++ b/apps/web-vue/src/styles.css
--- a/apps/web-vue/vite.config.ts
+++ b/apps/web-vue/vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  base: './',
+})
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -6,10 +6,13 @@

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

 当前图仅描述已确认的系统边界，不代表最终部署拓扑。
@@ -20,26 +23,64 @@ Vue 3 主应用
 - React 子模块位于 Vue 主应用内部，随主应用一起构建和部署。
 - React 子模块与 Vue 主应用之间通过明确的挂载、输入、输出和事件契约交互。

-## 3. 后端
+## 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、领域逻辑和基础设施访问应保持清晰边界；具体模块随真实业务出现后再建立。
 - 数据库结构变更必须通过迁移管理，但迁移工具尚待选定。

-## 4. 数据与基础设施
+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：用于本地开发依赖，不预设生产部署方式。

-## 5. 待决策事项
+## 6. 待决策事项

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

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

 - Java：JDK 21
 - 后端构建：Maven
+- Agent：Python 3.11+、LangChain、LangGraph
 - 前端：Vue 3 + TypeScript、React + TypeScript
 - 本地依赖：Docker 中运行 PostgreSQL、Redis 和 MinIO

-Node.js 版本、前端包管理器和具体框架版本尚未确定。初始化前端代码时必须一次性选定并提交锁文件。
+Node.js 版本、前端包管理器和 Agent 依赖锁定方式尚未确定。初始化对应工程时必须一次性选定并提交锁文件。

 ## 2. 分支与提交

@@ -21,6 +22,10 @@ Node.js 版本、前端包管理器和具体框架版本尚未确定。初始化
 - 各应用初始化时建立可执行的格式化、静态检查、测试和构建命令。
 - 新增依赖前确认标准库、平台能力或现有依赖不能满足需求。
 - 跨模块调用使用公开契约，不依赖另一个模块的内部文件结构。
+- 前端只调用 Java 主业务后端；Java 完成认证授权后通过内部 HTTP API 调用 Python Agent，Agent 不直接接受用户请求。
+- Agent 不直接访问主业务数据库，也不建立独立的用户认证体系。
+- Java 调用 Agent 时必须使用版本化 JSON 契约，并传递请求编号和经过授权的用户上下文；HTTP 超时、有限重试和幂等性应在客户端统一处理。
+- 长时间 Agent 任务通过 HTTP 创建任务并异步查询结果，前端仍只访问 Java 提供的业务接口。
 - 数据库、缓存和对象存储访问必须处理超时、失败和资源释放。

 ## 4. 配置管理
@@ -31,10 +36,18 @@ Node.js 版本、前端包管理器和具体框架版本尚未确定。初始化

 ## 5. 初始化后的命令维护

-当前没有业务工程，因此不提供不可执行的占位命令。后续初始化各应用时，应在根 `README.md` 补充以下真实命令：
+当前业务骨架已生成，但前端和具体业务能力尚未初始化。后续扩展各应用时，应在根 `README.md` 补充以下真实命令：

 - 安装依赖
 - 启动本地基础设施
 - 启动前端和后端
+- 启动 Agent 服务
 - 运行测试与静态检查
 - 构建发布产物
+
+当前骨架可执行的最小验证：
+
+```bash
+cd services/api && mvn verify
+cd services/agent && python -m venv .venv && .venv/bin/python -m pip install -e '.[dev]' && .venv/bin/python -m pytest
+```
--- a/docs/project-conventions.md
+++ b/docs/project-conventions.md
@@ -9,7 +9,8 @@
 | 路径 | 用途 | 主要内容 |
 | --- | --- | --- |
 | `apps/web-vue/` | 主 Web 应用 | Vue 3、TypeScript 源码，以及内嵌 React 子模块 |
-| `services/api/` | 后端 API | Spring Boot、JDK 21、Maven 工程 |
+| `services/api/` | 模块化单体主业务 API | Spring Boot、JDK 21、Maven DDD 多模块工程，负责认证授权、业务规则和持久化 |
+| `services/agent/` | Agent 进程 | Python 3.11+、LangChain、LangGraph，负责智能体编排和模型交互，由 Java 主业务后端调用 |
 | `infra/docker/` | 本地基础设施 | PostgreSQL、Redis、MinIO 的本地编排与初始化配置 |
 | `resources/raw/` | 原始资料 | Excel、Markdown、产品原型源文件及其他输入资料 |
 | `docs/product/` | 产品资料 | 已整理、持续维护的需求和产品说明 |
@@ -30,7 +31,12 @@

 - React 子模块随 Vue 主应用一起维护依赖、构建配置和测试。
 - React 子模块不得被设计为独立部署的前端应用；其挂载、状态和通信方式应通过 Vue 主应用的公开契约实现。
- 前后端通过版本化 API 契约交互，不共享运行时内部实现。
+- Java 主业务后端与 Python Agent 分别维护依赖、运行时和测试；Java 主业务后端当前按模块化单体部署，不拆分为多个微服务。
+- Java 主业务后端按 `domain`、`application`、`infrastructure`、`interfaces`、`boot` 分层；依赖方向由外向内，不得由领域层反向依赖技术实现。
+- Java 主业务后端负责认证授权、业务 API、业务规则和数据库写入；Agent 负责智能体流程、工具调用和模型交互。
+- 用户和前端不得直接访问 Agent；Java 完成认证授权后，才可调用 Agent 的内部 HTTP API。
+- Agent 不建立独立用户认证体系，也不直接访问主业务数据库；业务数据读写通过 Java 主业务后端完成。
+- Java 与 Agent 通过公开、版本化的内部 HTTP/JSON 契约交互，不共享运行时内部实现。短任务可同步调用，长任务通过 HTTP 任务接口异步处理。

 ## 5. 配置与安全


--- a/mise.toml
+++ b/mise.toml
+[tools]
+python = "3.11"
--- a/services/agent/.gitkeep
+++ b/services/agent/.gitkeep
+
--- a/services/agent/pyproject.toml
+++ b/services/agent/pyproject.toml
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcaigc-agent"
+version = "0.1.0"
+description = "梦畅AIGC Python Agent 服务"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "langchain>=0.3,<2",
+    "langgraph>=0.2,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+]
+
+[project.scripts]
+mcaigc-agent = "mcaigc_agent.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
--- a/services/agent/readme.md
+++ b/services/agent/readme.md
+# Python Agent 服务
+
+该目录是梦畅AIGC 的 Python Agent 进程骨架，使用 Python 3.11+、LangChain 和 LangGraph。它不是用户认证入口，必须由 Java 主业务后端在完成认证授权后调用。
+
+当前仅包含一个无模型的 LangGraph 回显流程，用于验证包结构和图编排入口。真实模型、工具、内部调用认证上下文、HTTP 服务协议和业务流程后续按需求接入。Agent 的 HTTP 接口只接受 Java 主业务后端的内部调用，不直接接受浏览器请求。
+
+## 本地验证
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/mcaigc-agent
+```
--- a/services/agent/src/mcaigc_agent/__init__.py
+++ b/services/agent/src/mcaigc_agent/__init__.py
+"""梦畅AIGC Python Agent 服务。"""
+
+__version__ = "0.1.0"
--- a/services/agent/src/mcaigc_agent/__main__.py
+++ b/services/agent/src/mcaigc_agent/__main__.py
+from .graph import build_graph
+
+
+def main() -> None:
+    result = build_graph().invoke({"input": "mcaigc-agent-ready", "output": ""})
+    print(result["output"])
+
+
+if __name__ == "__main__":
+    main()
--- a/services/agent/src/mcaigc_agent/graph.py
+++ b/services/agent/src/mcaigc_agent/graph.py
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+
+class AgentState(TypedDict):
+    input: str
+    output: str
+
+
+def _echo_node(state: AgentState) -> AgentState:
+    return {"input": state["input"], "output": state["input"]}
+
+
+def build_graph():
+    """Build the model-free graph used as the initial service self-check."""
+    graph = StateGraph(AgentState)
+    graph.add_node("echo", _echo_node)
+    graph.add_edge(START, "echo")
+    graph.add_edge("echo", END)
+    return graph.compile()
--- a/services/agent/tests/test_graph.py
+++ b/services/agent/tests/test_graph.py
+from mcaigc_agent.graph import build_graph
+
+
+def test_graph_echoes_input() -> None:
+    result = build_graph().invoke({"input": "hello", "output": ""})
+    assert result["output"] == "hello"
--- a/services/api/mcaigc-application/pom.xml
+++ b/services/api/mcaigc-application/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>mc</groupId>
+        <artifactId>mcaigc</artifactId>
+        <version>0.1.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcaigc-application</artifactId>
+    <name>mcaigc-application</name>
+    <dependencies>
+        <dependency>
+            <groupId>mc</groupId>
+            <artifactId>mcaigc-domain</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+    </dependencies>
+</project>
--- a/services/api/mcaigc-application/src/main/java/mc/mcaigc/application/shared/ApplicationMarker.java
+++ b/services/api/mcaigc-application/src/main/java/mc/mcaigc/application/shared/ApplicationMarker.java
+package mc.mcaigc.application.shared;
+
+/**
+ * Application module marker until the first use case is introduced.
+ */
+public final class ApplicationMarker {
+    private ApplicationMarker() {
+    }
+}
--- a/services/api/mcaigc-boot/pom.xml
+++ b/services/api/mcaigc-boot/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>mc</groupId>
+        <artifactId>mcaigc</artifactId>
+        <version>0.1.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcaigc-boot</artifactId>
+    <name>mcaigc-boot</name>
+    <dependencies>
+        <dependency>
+            <groupId>mc</groupId>
+            <artifactId>mcaigc-interfaces</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>mc</groupId>
+            <artifactId>mcaigc-infrastructure</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>
--- a/services/api/mcaigc-boot/src/main/java/mc/mcaigc/ApiApplication.java
+++ b/services/api/mcaigc-boot/src/main/java/mc/mcaigc/ApiApplication.java
+package mc.mcaigc;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication(scanBasePackages = "mc.mcaigc")
+public class ApiApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(ApiApplication.class, args);
+    }
+}
--- a/services/api/mcaigc-boot/src/test/java/mc/mcaigc/ApiApplicationTest.java
+++ b/services/api/mcaigc-boot/src/test/java/mc/mcaigc/ApiApplicationTest.java
+package mc.mcaigc;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+class ApiApplicationTest {
+    @Test
+    void contextLoads() {
+    }
+}
--- a/services/api/mcaigc-domain/pom.xml
+++ b/services/api/mcaigc-domain/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>mc</groupId>
+        <artifactId>mcaigc</artifactId>
+        <version>0.1.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcaigc-domain</artifactId>
+    <name>mcaigc-domain</name>
+</project>
--- a/services/api/mcaigc-domain/src/main/java/mc/mcaigc/domain/shared/DomainMarker.java
+++ b/services/api/mcaigc-domain/src/main/java/mc/mcaigc/domain/shared/DomainMarker.java
+package mc.mcaigc.domain.shared;
+
+/**
+ * Domain module marker until the first bounded context is introduced.
+ */
+public final class DomainMarker {
+    private DomainMarker() {
+    }
+}
--- a/services/api/mcaigc-infrastructure/pom.xml
+++ b/services/api/mcaigc-infrastructure/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>mc</groupId>
+        <artifactId>mcaigc</artifactId>
+        <version>0.1.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcaigc-infrastructure</artifactId>
+    <name>mcaigc-infrastructure</name>
+    <dependencies>
+        <dependency>
+            <groupId>mc</groupId>
+            <artifactId>mcaigc-domain</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-context</artifactId>
+        </dependency>
+    </dependencies>
+</project>
--- a/services/api/mcaigc-infrastructure/src/main/java/mc/mcaigc/infrastructure/configuration/InfrastructureConfiguration.java
+++ b/services/api/mcaigc-infrastructure/src/main/java/mc/mcaigc/infrastructure/configuration/InfrastructureConfiguration.java
+package mc.mcaigc.infrastructure.configuration;
+
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Technical adapters are registered here as bounded contexts are added.
+ */
+@Configuration
+public class InfrastructureConfiguration {
+}
--- a/services/api/mcaigc-interfaces/pom.xml
+++ b/services/api/mcaigc-interfaces/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>mc</groupId>
+        <artifactId>mcaigc</artifactId>
+        <version>0.1.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcaigc-interfaces</artifactId>
+    <name>mcaigc-interfaces</name>
+    <dependencies>
+        <dependency>
+            <groupId>mc</groupId>
+            <artifactId>mcaigc-application</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-web</artifactId>
+        </dependency>
+    </dependencies>
+</project>
--- a/services/api/mcaigc-interfaces/src/main/java/mc/mcaigc/interfaces/health/HealthController.java
+++ b/services/api/mcaigc-interfaces/src/main/java/mc/mcaigc/interfaces/health/HealthController.java
+package mc.mcaigc.interfaces.health;
+
+import java.util.Map;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/internal/health")
+public class HealthController {
+    @GetMapping
+    public Map<String, String> health() {
+        return Map.of("status", "UP");
+    }
+}
--- a/services/api/pom.xml
+++ b/services/api/pom.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.4.5</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>mc</groupId>
+    <artifactId>mcaigc</artifactId>
+    <version>0.1.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+    <name>mcaigc</name>
+    <description>梦畅AIGC 主业务后端</description>
+
+    <properties>
+        <java.version>21</java.version>
+    </properties>
+
+    <modules>
+        <module>mcaigc-domain</module>
+        <module>mcaigc-application</module>
+        <module>mcaigc-infrastructure</module>
+        <module>mcaigc-interfaces</module>
+        <module>mcaigc-boot</module>
+    </modules>
+</project>
--- a/services/api/readme.md
+++ b/services/api/readme.md
+# Java 主业务后端
+
+该目录是梦畅AIGC 的 Spring Boot 模块化单体主业务后端，使用 JDK 21 和 Maven 多模块 DDD 骨架。当前不拆分为多个微服务。
+
+## 模块
+
+- `mcaigc-domain/`：领域模型和领域端口
+- `mcaigc-application/`：应用服务和用例编排
+- `mcaigc-infrastructure/`：技术适配和基础设施实现
+- `mcaigc-interfaces/`：HTTP 接口和输入输出适配
+- `mcaigc-boot/`：启动入口和模块组装
+
+## 验证
+
+```bash
+mvn verify
+```
+
+启动类为 `mc.mcaigc.ApiApplication`。当前仅提供 `GET /internal/health` 骨架接口。后续由 Java 调用 Agent 的内部 HTTP API；相关入口必须在 Java 完成用户认证授权并补充服务间认证后开放。