# 仓库共享配置

> 第二层级配置（权重: 75），作用于当前代码仓库。定义项目级技术栈、架构约定、构建命令和团队协作规范，优先于 L1 公司统一配置生效。
>
> **设计原则**：本文件声明项目的**技术事实**（用了什么、怎么组织）和**团队共识**（代码风格、架构决策）。L1 已覆盖的通用规则此处不重复。

---

## 一、项目技术栈

### 核心技术栈总览

| 层面 | 技术 | 版本要求 | 说明 |
|---|---|---|---|
| **后端语言** | Java | >= 17 (LTS) | 优先使用最新 LTS |
| **后端框架** | Spring Boot / Spring Cloud | Alibaba 2022.x / 3.x | 微服务架构 |
| **前端框架** | Vue 3 | ^3.3+ | Composition API |
| **UI 组件库** | Ant Design Vue | ^4.x | antdv |
| **前端语言** | TypeScript | strict 模式 | 新组件强制 TS |
| **构建工具（前端）** | Vite | ^5.x | — |
| **辅助语言** | Python | >= 3.10 | 脚本/工具/数据处理 |
| **数据库** | PostgreSQL / MySQL | — | 按项目选择 |
| **ORM** | MyBatis-Plus / JPA | — | 按项目选择 |
| **缓存** | Redis | — | — |
| **消息队列** | RabbitMQ / RocketMQ / Kafka | — | 按场景选择 |
| **容器化** | Docker + Docker Compose | — | 本地开发统一 |
| **CI/CD** | GitHub Actions / Jenkins | — | 按团队基础设施 |

### 项目依赖约束

#### 后端（Java）
- **JDK 版本**：>= 17，统一使用 LTS 版本
- **构建工具**：Maven（优先）或 Gradle
- **Spring Boot 版本**：团队统一版本，禁止自行升级 minor 版本
- **禁止引入**：已停止维护的库、与 Spring Boot BOM 版本冲突的依赖、未通过安全审计的第三方 SDK

#### 前端（Vue）
- **包管理器**：pnpm
- **Node 版本**：>= 18
- **禁止引入**：`lodash`（用 `lodash-es` 或原生替代）、`moment.js`（用 `dayjs`）、`jquery` 及其插件

#### Python
- **包管理**：pip / poetry / pdm（按项目选择）
- **虚拟环境**：必须使用 venv / conda / poetry env
- **禁止在全局环境安装项目依赖**

---

## 二、项目目录结构与架构约定

### Monorepo 目录规范（前后端分离）

```
project-root/
├── java/                    # Java 后端服务
│   ├── src/main/java/
│   │   └── com/company/project/
│   │       ├── config/         # 配置类
│   │       ├── controller/     # REST API 接口层
│   │       ├── service/        # 业务逻辑层（接口 + impl 分离）
│   │       ├── repository/     # 数据访问层
│   │       ├── entity/         # 数据库实体 / DO
│   │       ├── dto/            # 数据传输对象
│   │       ├── common/         # 公共模块（异常、常量、工具、枚举）
│   │       └── util/           # 工具类
│   ├── src/main/resources/
│   │   ├── mapper/             # MyBatis XML 映射文件
│   │   └── application*.yml   # 配置文件
│   └── pom.xml
│
├── web/                   # Vue 前端应用
│   ├── src/
│   │   ├── api/                # API 请求封装
│   │   ├── views/              # 页面视图
│   │   ├── components/         # 公共组件
│   │   ├── composables/        # 组合式函数
│   │   ├── stores/             # Pinia 状态管理
│   │   ├── router/             # 路由配置
│   │   ├── types/              # TypeScript 类型定义
│   │   ├── utils/              # 工具函数
│   │   ├── assets/             # 静态资源
│   │   ├── styles/             # 全局样式
│   │   ├── layout/             # 布局组件
│   │   └── App.vue
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
├── app/                   # Vue 前端应用
│   ├── src/
│   │   ├── api/                # API 请求封装
│   │   ├── views/              # 页面视图
│   │   ├── components/         # 公共组件
│   │   ├── composables/        # 组合式函数
│   │   ├── stores/             # Pinia 状态管理
│   │   ├── router/             # 路由配置
│   │   ├── types/              # TypeScript 类型定义
│   │   ├── utils/              # 工具函数
│   │   ├── assets/             # 静态资源
│   │   ├── styles/             # 全局样式
│   │   ├── layout/             # 布局组件
│   │   └── App.vue
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
│
├── scripts/                    # Python / Shell 脚本工具
├── docker-compose.yml
├── Dockerfile
└── docs/                       # 项目文档
```

### 架构原则

#### 后端（Spring Cloud 微服务）
1. **分层架构**：Controller → Service → Repository，严禁跨层调用
2. **服务间通信**：内部服务用 OpenFeign，对外暴露用 RESTful API
3. **统一返回格式**：所有接口使用统一的 `Result<T>` 包装
4. **异常处理**：`@ControllerAdvice` + 自定义异常体系，禁止 try-catch 吞掉异常
5. **配置管理**：敏感配置走 Nacos / Config Server，禁止硬编码
6. **API 版本管理**：URL 中携带版本号 `/api/v1/xxx`

#### 前端（Vue 3 + Ant Design Vue）
1. **Composition API 优先**：新组件统一使用 `<script setup lang="ts">`
2. **状态管理**：Pinia，按业务域拆分 store
3. **组件设计**：容器展示分离（Smart-Dumb Components），公共组件放 `components/`
4. **API 层**：统一在 `api/` 封装请求方法，组件中直接调用
5. **权限控制**：路由级别（动态路由）+ 按钮级别（自定义指令 v-auth）
6. **TypeScript 覆盖**：新增组件/工具/类型定义必须使用 TS

---

## 三、构建与开发命令

### 后端（Maven）

```bash
mvn clean compile              # 编译
mvn clean package -DskipTests  # 打包（跳过测试）
mvn clean install              # 安装到本地仓库
mvn test                       # 运行单元测试
mvn verify                     # 运行集成测试
mvn checkstyle:check           # 代码风格检查
mvn spring-boot:run            # 启动应用
```

### 前端（pnpm + Vite）

```bash
pnpm --filter frontend dev          # 启动开发服务器
pnpm --filter frontend build        # 生产构建
pnpm --filter frontend lint         # ESLint 检查
pnpm --filter frontend typecheck    # TypeScript 类型检查
pnpm --filter frontend test         # 单元测试
pnpm --filter frontend test:coverage # 覆盖率报告
```

### Docker（本地开发环境）

```bash
docker compose up -d postgres redis rabbitmq  # 启动基础中间件
docker compose down                           # 停止并清理
docker compose logs -f [service]              # 查看日志
```

> AI 执行任务后，若涉及代码变更：
> - **后端变更**：应确认 Maven 编译通过（`mvn compile`）
> - **前端变更**：应运行 `lint` + `typecheck` 验证

---

## 四、Git 协作补充（项目级）

> 基础 Git 规范（提交格式、分支命名）已在 **L1 §四** 中定义，以下为本仓库的**补充约定**。

### 分支策略（Git Flow 简化版）

| 分支 | 命名 | 说明 | 合入目标 |
|---|---|---|---|
| 主分支 | `main` | 生产环境代码 | — |
| 开发分支 | `develop` | 开发集成分支 | → main（发布时） |
| 功能分支 | `feature/xxx` | 新功能开发 | → develop |
| 修复分支 | `fix/xxx` | Bug 修复 | → develop（普通）/ main（紧急） |
| 发布分支 | `release/x.x.x` | 发版准备 | → main + develop |

### PR/MR 要求
- **标题格式**：`[type] 简短描述`
- **描述模板**需包含：关联 issue/ticket、变更概述、测试说明
- **CI 必须通过**后方可合并
- **单次 PR 改动量**建议不超过 500 行（不含生成文件）

---

## 五、测试约定

### 后端测试（JUnit 5 + Mockito）

| 测试类型 | 工具 | 要求 |
|---|---|---|
| 单元测试 | JUnit 5 + Mockito | Service 层核心逻辑必须有单测 |
| 集成测试 | Spring Boot Test + Testcontainers | 关键 API 端点需集成测试 |
| 覆盖率目标 | JaCoCo | 行覆盖率 >= 60%（新增代码） |

### 前端测试

| 测试类型 | 工具 | 要求 |
|---|---|---|
| 单元测试 | Vitest | composables / utils 必须有单测 |
| 组件测试 | @testing-library/vue | 核心业务组件需组件测试 |
| 测试文件命名 | `*.test.ts` | 与源文件同目录 |
| Mock 策略 | vitest.mock | 优先 mock API 请求层，不 mock 内部实现 |

---

## 六、项目特定知识库

### 文档资源
- 项目 Wiki：_待填写_
- API 文档（Swagger/OpenAPI）：_http://localhost:8080/doc.html_ （Knife4j）
- 数据库 ER 图：_待填写_
- Nacos 配置中心地址：_待填写_

### 关键业务概念
<!-- 记录项目中特有的业务术语和领域模型 -->

### 常见坑点 & 经验教训
<!-- 记录项目中容易出错的地方，AI 可主动规避 -->

---

## 七、与 L1/L3 的关系

```
公司统一配置 (L1, 权重25)  ← 安全红线、技术选型、编码底线
    ↓ 被覆盖
仓库共享配置 (L2, 权重75)  ← 本文件（项目技术栈、架构约定、构建命令）
    ↓ 被覆盖
本地私有配置 (L3, 权重100)  ← 最高优先级，本地环境 + 个人偏好
```

### 本文件的独特价值（L1 不包含的内容）

| 内容 | 为什么只在 L2 |
|---|---|
| 具体技术栈声明（Java 17 / Vue 3 / Spring Cloud / antdv） | 这是**项目事实**，非通用规则 |
| 分层架构约定（Controller→Service→Repository） | 项目特定的架构决策 |
| 多语言构建命令（Maven + pnpm + Docker） | 项目特定的工具链 |
| PR/MR 的项目级补充要求 | 团队协作特定约定 |
| 测试约定和覆盖率目标 | 项目级质量要求 |
| 业务领域知识和常见坑点 | 项目独有上下文 |

- 本文件的规则适用于**当前仓库的所有协作者**
- 当本地私有配置有冲突规则时，**L3 优先**

---

*最后更新：2026-04-18*
*版本：4.0.0（3层架构版）*