# 项目规范

## 1. 目标

本规范定义梦畅AIGC 仓库的目录职责、命名方式和协作边界。当前阶段只建立规范，不提前生成业务代码、依赖配置或 Docker 编排文件。

## 2. 目录职责

| 路径 | 用途 | 主要内容 |
| --- | --- | --- |
| `apps/web-vue/` | 主 Web 应用 | Vue 3、TypeScript 源码，以及内嵌 React 子模块 |
| `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/` | 产品资料 | 已整理、持续维护的需求和产品说明 |
| `docs/decisions/` | 决策记录 | 影响多个模块或长期维护的重要架构决策 |

原始输入放在 `resources/raw/`；从原始输入提炼出的、需要持续维护的正式文档放在 `docs/`。同一文件不在两个目录重复维护。

## 3. 命名规范

- 除根目录文件外，目录和文件名使用英文小写，单词间使用连字符，例如 `content-review.md`。
- 根目录文件可以使用项目和工具约定的标准名称，例如 `README.md`、`AGENTS.md` 和 `.editorconfig`。
- Java 包名全小写；基础包名为 `mc.mcaigc`。
- TypeScript 代码命名遵循各前端项目后续确定的统一检查规则。
- 文档正文使用中文；技术名词、代码标识符和命令保留英文。
- 日期统一使用北京时间（Asia/Shanghai）对应的 `YYYY-MM-DD`。

## 4. 模块边界

- React 子模块随 Vue 主应用一起维护依赖、构建配置和测试。
- React 子模块不得被设计为独立部署的前端应用；其挂载、状态和通信方式应通过 Vue 主应用的公开契约实现。
- 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. 配置与安全

- 真实密钥和环境配置不得提交到 Git。
- 可提交的环境变量模板命名为 `.env.example`，只包含无敏感信息的示例值。
- 本地 Docker 数据卷落在 `infra/docker/data/` 时必须保持 Git 忽略。
- 大型资源当前允许直接提交 Git；当仓库体积或克隆时间明显影响协作时，再评估 Git LFS 或外部资产库。

## 6. 文档维护

- 代码行为、目录职责或技术选型发生变化时，同一变更中更新相关文档。
- 仅记录会影响实现和协作的约定，不为未知需求预写设计。
- 重要且难以逆转的决策在 `docs/decisions/` 单独记录背景、选择和后果。
