Strona główna Odkrywaj Pomoc
Zaloguj się
zenghaiyang
/
ylsw-bw
1
0
Forkuj 0
Pliki Problemy 0 Oczekujące zmiany 0 Wiki
Gałąź: dev-ai
Gałęzie Tagi
ylsw-bw
/
.cursor
/
skills
/
tofly-memory-system
/
warehouse_shared_config.md

warehouse_shared_config.md 10 KB
Bezpośredni odnośnik Historia Czysty

仓库共享配置

第二层级配置（权重: 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）

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

前端（pnpm + Vite）

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（本地开发环境）

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 配置中心地址：待填写

关键业务概念

常见坑点 & 经验教训

七、与 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层架构版）