OpenOBA 开源代码规范

1. 开源协议

OpenOBA 核心引擎使用 MIT 协议 开源。你可以自由使用、修改、分发代码，用于个人和商业项目。详见项目根目录下的 LICENSE 文件。

2. 技术栈

层级	技术选型
后端	Node.js + TypeScript
前端	Vue 3 + TypeScript
数据库	关系型数据库 + 缓存
协议层	ERDL（YAML 超集）
容器化	Docker + Docker Compose

3. 代码风格

3.1 TypeScript

• 严格模式（strict: true）
• 优先使用 interface 而非 type（API 定义除外）
• 禁止 any，使用 unknown 或具体类型
• 文件命名：kebab-case.ts
• 类命名：PascalCase；方法/变量：camelCase

3.2 后端框架

• 每个模块独立目录：module-name/ 包含 controller、service、dto、entity
• 使用 DTO 类 + class-validator 进行参数校验
• Service 层不直接操作 Response 对象
• 使用全局 TransformInterceptor 统一响应格式

3.3 Vue 3

• Composition API（<script setup>）
• 使用 ref / reactive 进行状态管理
• 组件命名：PascalCase.vue
• Props 使用 TypeScript 类型声明

4. 命名规范

对象	规范	示例
数据库表	snake_case，复数	product_spus
数据库列	snake_case	spu_name
Entity 类	PascalCase，单数	ProductSpu
DTO 类	PascalCase + 后缀	CreateProductDto
API 路由	kebab-case，复数	/api/products
Vue 组件	PascalCase.vue	ProductList.vue

5. Git 提交规范

使用 Conventional Commits 格式：

<type>(<scope>): <description>

# 类型
feat:     新功能
fix:      Bug 修复
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 重构
perf:     性能优化
test:     测试
chore:    构建/工具变更

# 示例
feat(erdl): 添加 Hot Reload 机制
fix(order): 修复支付状态未更新问题
docs(api): 更新 API 对接文档

6. 提交 PR 前检查清单

• npm run lint 无错误
• npm run typecheck（tsc --noEmit）通过
• npm run test 全部通过
• 新功能已包含单元测试
• 数据库迁移已生成（如有 schema 变更）
• CHANGELOG 已更新
• 文档已同步更新（如涉及 API 变更）

7. 目录结构

openoba-erp/
├── backend/
│   ├── src/
│   │   ├── modules/          # 业务模块
│   │   ├── common/           # 公共工具
│   │   └── config/           # 配置
│   ├── erdl/                 # ERDL 文件
│   ├── migrations/           # 数据库迁移
│   └── test/                 # 后端测试
├── frontend/
│   ├── src/
│   │   ├── views/            # 页面组件
│   │   ├── components/       # 通用组件
│   │   └── composables/      # 组合式函数
│   └── test/                 # 前端测试
├── docs/                     # 项目文档
├── docker-compose.yml
└── README.md

8. 交流与贡献

欢迎通过以下方式参与 OpenOBA 开源社区：

• GitHub Issues：提交 Bug 报告和 Feature Request
• Pull Requests：贡献代码（请先阅读本规范）
• 文档贡献：完善文档、翻译、编写教程
• ERDL 贡献：提交新的行业 ERDL 文件到社区市场