项目组装方式

如何使用 mldong 框架组件组装一个业务项目。

核心思路

业务项目不直接修改框架源码，而是通过 git submodule 引用框架仓库，上层只放业务代码和配置。

如果仓库已包含子模块（backend/、admin-web/ 等目录已存在），直接使用即可，无需重新初始化。

标准布局

一个典型的业务项目目录结构：

mldong-{biz}/
├── AGENTS.md                      # AI 协作须知（契约参见[AI 智能体](./agents.html#assembly-contract)）
├── .gitmodules                    # 子模块定义
├── backend/                       # git submodule → 后端框架（可选）
├── admin-web/                     # git submodule → 前端框架（可选）
├── app/                           # git submodule → App 框架（可选）
├── docs/                          # 文档中心（知识沉淀统一入口）
│   ├── {biz}-requirements.md      #   PRD
│   ├── {biz}-architecture.md      #   技术架构
│   ├── {biz}-tasks.md             #   任务拆分
│   ├── issues/                    #   Issue 协作
│   │   └── _archived_issues/      #   已归档
│   ├── backend/                   #   后端研发文档
│   ├── front/                     #   前端研发文档
│   ├── app/                       #   App 研发文档
│   └── sql/                       #   DDL SQL
├── e2e/                           # E2E 测试（pytest）
│   ├── conftest.py                 # 共享 fixture
│   ├── helpers/                    # 工具函数
│   ├── tests/                      # 测试用例 test_*.py
│   ├── pytest.ini                  # pytest 配置
│   ├── requirements.txt
│   └── .env.example
├── .github/
│   ├── agents/                    # Copilot 自定义智能体
│   └── skills/                    # 项目级 skill
└── .claude/
    ├── agents/                    # Claude Code 自定义智能体
    └── settings.local.json        # 本地配置

.gitmodules 配置（参考）

以下是 mldong 框架的参考地址，实际使用时替换为你的仓库地址：

[submodule "backend"]
    path = backend
    url = https://gitee.com/mldong/mldong.git
    branch = boot3

[submodule "admin-web"]
    path = admin-web
    url = https://gitee.com/mldong/mldong-vben5.git
    branch = master

子模块地址和分支以实际使用的为准，甚至可能只有一个 master 分支。如果已有子模块，直接使用现有的 .gitmodules 配置即可。

子模块操作

首次 clone

# 新仓库：clone 时同时拉取子模块
git clone --recurse-submodules <repo-url>

# 已存在的仓库：初始化子模块
git submodule update --init --recursive

拉取子模块最新代码

git submodule update --remote

在子模块内开发后提交，以 `.gitmodules` 中 `branch` 配置为准，不是硬编码某个分支：

cd backend
# ... 写代码、commit、push（当前分支已在 .gitmodules 中指定） ...
cd ..
git add backend
git commit -m "bump: backend - <说明>"
git push

父仓只记录子模块的 commit hash（gitlink），不存子模块的实际内容。

多智能体协作

业务项目采用多角色协作模式，跨角色沟通通过 docs/issues/ 目录进行。完整流程、5 件套真值表、状态 emoji、Issue 文档模板见AI 智能体 → 多智能体协作契约。

项目根目录的 AGENTS.md 是 AI 协作的入口文档（在 AI 智能体页面打开"多智能体协作契约"弹窗，复制内容到 AGENTS.md 并替换 {biz} 即可使用）。

常用智能体初始化（可选）

项目初始化时可选用以下智能体，将对应 prompt 保存到 .claude/agents/ 或 .github/agents/ 目录即可激活：

智能体	角色	职责	prompt 来源
产品经理	输出 PRD 需求文档	业务流程、功能清单、验收标准	AI 智能体→产品经理
架构师	数据库设计、接口清单	表结构、ER 图、接口功能清单	AI 智能体→架构师
boot3 后端工程师	Spring Boot 3 后端开发	CRUD 生成、业务接口、编码规范	AI 智能体→boot3 后端
vben5 前端工程师	Vben5 管理端前端开发	页面开发、路由注册、Schemas 调整	AI 智能体→vben5 前端

每个智能体的 prompt 在 AI 智能体页面点击对应卡片弹窗查看并复制，保存为 .claude/agents/{name}.md 即可在 Claude Code 中用 /agent {name} 调用。

# 示例：初始化产品经理智能体
# 1. 访问 AI 智能体页面 → 点击"产品经理"→ 复制提示词
# 2. 保存到项目
mkdir -p .claude/agents
# 将复制的内容粘贴到 .claude/agents/product-manager.md
# 然后在 Claude Code 中使用
# /agent product-manager

这 4 个智能体覆盖了从需求到上线的完整链路：产品经理出 PRD → 架构师出设计 → 后端开发 API → 前端开发页面。

E2E 测试

项目使用 pytest 做接口级 E2E 测试，脚本统一放在 e2e/ 目录下。

初始化

cd e2e
python -m venv venv
source venv/bin/activate      # Linux/Mac
venv\Scripts\activate         # Windows
pip install -r requirements.txt
cp .env.example .env          # 编辑 .env 填入实际配置

运行

cd e2e
source venv/bin/activate      # 先激活虚拟环境
pytest                          # 运行所有
pytest -m smoke                 # 冒烟测试
pytest tests/test_xxx.py        # 指定文件

编写规范

文件：e2e/tests/test_{模块}_{功能}.py
后端自测 / 前端验证 / Issue 验证的脚本统一落盘到 e2e/tests/
标记：@pytest.mark.smoke（冒烟）、@pytest.mark.regression（回归）

启动方式

子模块各自有独立的启动脚本，在子模块目录内执行：

子模块	启动方式	端口
`backend/`	`start-admin.local.sh` / `start-admin.local.bat`	18080
`admin-web/`	`pnpm dev:antd`	5666

本地定制脚本（如 start-admin.local.sh）被 .gitignore 忽略，不入仓。