# 开发约定

## 1. 环境基线

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

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

## 2. 分支与提交

- 新功能和修复在独立分支完成，分支名使用英文并体现目的。
- 一次提交只处理一个清晰主题，提交信息说明“做了什么”。
- 不提交构建产物、依赖目录、本地数据、日志和真实环境配置。
- 原始资料的新增或修订应在提交信息中说明来源和日期。

## 3. 代码质量

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

## 4. 配置管理

- 本地默认值和必要变量写入 `.env.example` 或应用对应的示例配置。
- 密钥只通过本地环境变量或安全的密钥管理方式提供。
- Docker 编排加入后，应为 PostgreSQL、Redis 和 MinIO 配置健康检查及持久化卷。

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

当前业务骨架已生成，但前端和具体业务能力尚未初始化。后续扩展各应用时，应在根 `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
```
