# company-ai-rules

**Repository Path**: open_product/company-ai-rules

## Basic Information

- **Project Name**: company-ai-rules
- **Description**: 专注于企业级AI规则引擎开发的开源团队，提供灵活的规则管理与执行方案，支持多种业务场景，助力企业智能化转型。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2026-03-16
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 公司级 AI 编码规范仓库

本仓库包含了公司级 AI 辅助编码的完整规范体系，旨在确保代码质量、一致性和可维护性。

---

## 仓库结构

```
company-ai-rules/
├── README.md                       # 本文件
├── AGENT_RULES.md                  # 【核心】公司级通用 AI 指令文件
├── development_workflow.md         # 开发流程规范（分支管理、提交规范等）
├── dtcloud/
│   ├── __init__.py
│   ├── dtcloud_rules.md            # DTCloud 核心规范（模型、视图、模块）
│   ├── dtcloud_translation_mechanism.md # DTCloud 多语言翻译机制指南
│   └── js_xml_rules.md             # DTCloud 前端规范（JavaScript OWL、XML QWeb、CSS）
│   └── environment_setup_DTCloud.md    # DTCloud 开发环境搭建指南
├── python/
│   ├── __init__.py
│   └── python_rules.md             # Python 通用规范
├── fastapi/
│   ├── __init__.py
│   └── fastapi_rules.md            # FastAPI 框架专项规范
├── gin/
│   ├── __init__.py
│   └── gin_rules.md                # Go-GIN 框架专项规范
├── go/
│   ├── __init__.py
│   └── go_rules.md                 # Go 通用规范
├── vue3/
│   ├── __init__.py
│   └── vue3_rules.md               # Vue3 前端专项规范（对接 DTCloud、FastAPI）
└── dtcloud-project-examples/
    ├── PRD.md                      # DTCloud Swagger Tools 项目产品需求文档
    ├── swagger_tools_coding_standard.md  # 【示例】Swagger Tools 项目级编码规范
    ├── UI_design.md                # DTCloud Swagger Tools 项目 UI 设计文档
    ├── technical_implementation.md # DTCloud Swagger Tools 项目技术实施文档
    ├── development_plan.md         # DTCloud Swagger Tools 项目开发计划文档
    └── project_template.md         # 项目级编码规范模板
```

---

## 规范层次

### 1. 核心层 - AGENT_RULES.md
这是 AI 进入项目时首先读取的总纲领，定义了：
- AI 角色定位
- 通用技术栈
- 通用编码规范
- 禁止行为
- 性能优化规范
- 规范引用指引

**适用场景**: 所有 AI 辅助编码任务的起始点

### 2. 框架专项层 - dtcloud/
版本：dtcloud-v6

针对 DTCloud 框架的专项规范：

#### 2.1 dtcloud/dtcloud_rules.md
- 模块与文件结构
- 模型（Model）规范
- 视图（View）与 XML 规范
- 安全权限规范
- 最佳实践

**适用场景**: DTCloud 模块开发、模型定义、视图创建

#### 2.2 dtcloud/dtcloud_translation_mechanism.md
- 翻译机制概述
- 开发规则与最佳实践
- 常见问题与解决方案
- 完整实现示例

**适用场景**: DTCloud 多语言支持开发、翻译问题排查

#### 2.3 dtcloud/js_xml_rules.md
DTCloud 前端开发规范，涵盖：
- JavaScript (OWL) 规范
- XML (QWeb) 规范
- CSS 样式规范
- 性能优化
- 可访问性

**适用场景**: DTCloud 前端交互、视图模板、样式定义

### 3. 语言专项层 - python/python_rules.md
Python 编码语言规范，包括：
- 代码风格（PEP8）
- 导入顺序
- 代码注释规范
- 代码结构
- 异常处理
- 性能优化
- 类型提示

**适用场景**: 所有 Python 代码文件

### 4. 前端专项层 - dtcloud/js_xml_rules.md
DTCloud 前端开发规范，涵盖：
- JavaScript (OWL) 规范
- XML (QWeb) 规范
- CSS 样式规范
- 性能优化
- 可访问性

**适用场景**: DTCloud 前端交互、视图模板、样式定义

### 5. FastAPI 专项层 - fastapi/fastapi_rules.md
FastAPI 框架开发规范，涵盖：
- 项目结构规范
- API 设计规范
- 路由定义规范
- 依赖注入规范
- 数据验证规范
- 异常处理规范
- 文档注释规范

**适用场景**: FastAPI 服务开发、REST API 设计

### 6. Go-GIN 专项层 - gin/gin_rules.md
Go-GIN 框架开发规范，涵盖：
- 项目结构规范
- 路由定义规范
- 中间件使用规范
- 数据绑定规范
- 错误处理规范
- 数据验证规范

**适用场景**: Go-GIN 服务开发、REST API 设计

### 7. Vue3 前端专项层 - vue3/vue3_rules.md
Vue3 前端开发规范，涵盖：
- 项目结构规范
- API 对接规范（DTCloud、FastAPI）
- TypeScript 类型定义规范
- 组件开发规范（Composition API）
- 状态管理规范（Pinia）
- 路由配置规范
- 错误处理规范
- 认证授权规范
- 样式编写规范

**适用场景**: Vue3 前端项目开发，与 DTCloud 或 FastAPI 后端对接

### 8. 项目示例层 - dtcloud-project-examples/
展示如何在具体项目中应用公司级规范，每个示例文件包含：
- 项目特有约定（与公司级规范不重复）
- 项目架构设计
- 最佳实践案例
- 常见问题解答

**示例**:
- `PRD.md` - DTCloud Swagger Tools 项目产品需求文档
- `swagger_tools_coding_standard.md` - Swagger Tools 项目编码规范
- `UI_design.md` - Swagger Tools 项目 UI 设计文档
- `technical_implementation.md` - Swagger Tools 项目技术实施文档
- `development_plan.md` - Swagger Tools 项目开发计划文档
- `project_template.md` - 项目级编码规范通用模板

**适用场景**: 新项目启动时参考，建立项目级规范

---

## 使用指南

### 对于 AI 助手

1. **首次任务**: 首先阅读 `AGENT_RULES.md` 了解整体规范
2. **任务分类**: 根据任务类型查阅对应的专项规范
   - DTCloud 后端 → `dtcloud/dtcloud_rules.md`
   - DTCloud 前端（OWL + QWeb）→ `dtcloud/js_xml_rules.md`
   - FastAPI 服务 → `fastapi/fastapi_rules.md`
   - Go-GIN 服务 → `gin/gin_rules.md`
   - Vue3 前端 → `vue3/vue3_rules.md`
   - Python 通用 → `python/python_rules.md`
3. **项目参考**: 如果是具体项目开发，参考 `dtcloud-project-examples/` 下的项目级规范
4. **交叉参考**: 涉及多个领域时，交叉参考相关规范
5. **代码审查**: 在提交代码前，使用各规范中的代码审查清单

### 对于开发人员

1. **团队协作**: 在 Pull Request 中引用相关规范条款
2. **代码审查**: 使用各规范中的代码审查清单进行评审
3. **项目规范**: 为项目建立项目级编码规范（参考 `dtcloud-project-examples/project_template.md`）
4. **环境搭建**: 参考 `environment_setup.md` 搭建开发环境
5. **流程规范**: 参考 `development_workflow.md` 遵循开发流程
6. **持续改进**: 根据实际情况提出规范改进建议

---

## 📖 快速开始

### 1. 新手入门

```bash
# 1. 阅读核心规范
阅读 AGENT_RULES.md 了解整体技术栈和编码原则

# 2. 搭建开发环境
按照 environment_setup.md 搭建开发环境

# 3. 学习开发流程
阅读 development_workflow.md 了解分支管理和提交规范

# 4. 查看项目示例
参考 dtcloud-project-examples/ 了解具体项目应用
```

### 2. 创建新项目规范

```bash
# 1. 复制项目模板
cp dtcloud-project-examples/project_template.md dtcloud-project-examples/your_project.md

# 2. 填写项目信息
# 根据项目实际情况填写模板中的占位符

# 3. 添加项目特有约定
# 只记录与公司级规范不重复的特有约定
```

### 3. 代码审查检查

```markdown
## 代码审查清单

### 通用检查
- [ ] 所有导入语句符合顺序规范
- [ ] 所有类、函数、方法都有中文 Docstring
- [ ] 没有硬编码的数值或字符串
- [ ] 没有直接使用 SQL 语句（Python）
- [ ] 错误处理完善

### 框架专项检查
- [ ] 代码符合框架特定规范（DTCloud/FastAPI/Go-GIN/Vue3）
- [ ] 使用正确的API和方法
- [ ] 权限配置正确
```

---

## ❓ 常见问题

### Q1: 如何使用这些规范？
**A**:
1. AI助手在生成代码时会自动查阅相关规范
2. 开发人员可使用规范进行代码审查
3. 新项目可参考项目模板创建规范文档

### Q2: 规范更新频率？
**A**:
- 规范会根据团队实践和反馈定期更新
- 重大变更会在本README的版本历史中记录
- 建议订阅仓库通知获取更新

### Q3: 如何贡献规范？
**A**:
1. Fork本仓库
2. 创建分支进行修改
3. 提交Pull Request并说明变更原因
4. 团队审核通过后合并

### Q4: 规范冲突如何处理？
**A**:
- 核心原则: 通用规范优先于项目规范
- 安全规范优先级最高
- 具体问题可咨询团队负责人

### Q5: 如何快速上手？
**A**:
1. 阅读本README和 `AGENT_RULES.md`
2. 按照 `environment_setup.md` 搭建环境
3. 查看 `dtcloud-project-examples/` 中的示例项目
4. 参考 `development_workflow.md` 开始开发

---

## 规范引用流程

```mermaid
graph TD
    A[AI 开始任务] --> B[阅读 AGENT_RULES.md]
    B --> C{任务类型判断}
    C -->|DTCloud 后端| D[阅读 dtcloud/dtcloud_rules.md]
    C -->|DTCloud 前端| E[阅读 dtcloud/js_xml_rules.md]
    C -->|Python 通用| F[阅读 python/python_rules.md]
    C -->|Go 通用| G[阅读 go/go_rules.md]
    C -->|FastAPI 服务| H[阅读 fastapi/fastapi_rules.md]
    C -->|Go-GIN 服务| I[阅读 gin/gin_rules.md]
    C -->|Vue3 前端| J[阅读 vue3/vue3_rules.md]
    C -->|综合任务| K[阅读多个专项规范]
    D --> L[生成/修改代码]
    E --> L
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M[使用代码审查清单]
    M --> N[完成任务]
```

---

## 核心原则

### 1. 分层清晰
- 通用规范与专项规范分离
- 便于管理和继承
- 支持不同项目定制

### 2. 可操作性
- 提供详细的代码示例
- 包含正反对比
- 附带代码审查清单

### 3. 持续演进
- 根据实际使用反馈优化
- 定期更新技术栈信息
- 补充新的最佳实践

---

## 联系与反馈

如有问题或建议，请联系团队负责人或提交 Issue。

---

## 🔄 版本历史

### v1.3.0 (2026-03-20)
- ✅ 新增 `dtcloud/dtcloud_translation_mechanism.md` - DTCloud 多语言翻译机制指南
- ✅ 更新 README.md，完善 DTCloud 框架专项规范结构

### v1.2.0 (2026-03-17)
- ✅ 新增 `development_workflow.md` - 开发流程规范（分支管理、提交规范、代码审查）
- ✅ 新增 `environment_setup.md` - 开发环境搭建指南
- ✅ 新增 `dtcloud-project-examples/project_template.md` - 项目级编码规范模板
- ✅ 重命名 `project-examples` → `dtcloud-project-examples`
- ✅ 完善README，添加快速开始和FAQ部分

### v1.1.0 (2026-03-17)
- 新增 Go 通用规范目录（`go/go_rules.md`）
- 优化 AGENT_RULES.md 结构，移除详细框架规范
- 完善代码审查清单，增加 Go 相关检查项
- 更新 DTCloud 多语言支持规范（非必须）

### v1.0.0 (2026-03-16)
- 初始版本发布
- 包含核心层、DTCloud 层、Python 层、前端层规范
- 提供完整的代码示例和审查清单