### AI 编程代码编写规范（基于“单体 + 技术分层 + 业务垂直 + 文件三层”）

规范定位

适用于桌面自动化工具、数据处理脚本等**单体 Python 项目**，采用“技术分层目录 + 业务垂直文件 + 文件内三层隔离”的架构。

---

## 一、项目目录结构（技术分层）

```

项目根目录/

├── main.py # 程序入口

├── modules/ # 核心业务代码（所有 .py 放在此）

│ ├── dedup.py # 去重业务

│ ├── audit.py # 审计入库业务

│ ├── publish.py # 标题/刊登业务

│ └── ... # 其他业务文件

├── config/ # 配置文件（json, yaml, ini, toml）

├── assets/ # 静态资源（图片、样式、帮助文档）

├── tools/ # 第三方工具或辅助脚本

├── temp/ # 运行时临时文件（可被 gitignore）

├── dist/ # 打包输出目录

├── build/ # 编译中间目录

└── requirements.txt # Python 依赖清单

```

命名规则

- 目录名全部小写，单词用下划线分隔（如 `input_files` 而非 `inputFiles`）。

- 文件名清晰表达用途（如 `color_config.json`，而非 `conf1.json`）。

---

## 二、业务文件组织（垂直拆分）

原则：一个 `.py` 文件只负责一个完整的业务功能。

命名：`动词_名词.py` 或 `业务名.py`，如 `check_duplicate.py`、`upload_task.py`。

大小：单个文件不超过 500 行（超过则考虑进一步拆分）。

示例

`modules/dedup.py` —— 只包含去重相关的所有逻辑。

`modules/audit.py` —— 只包含审计入库相关的所有逻辑。

---

## 三、单个文件内部三层结构（强制隔离）

每个业务文件必须按以下顺序组织，**不允许跨层调用**（界面只能调逻辑，逻辑只能调数据）。

```python

# ========== 1. 数据层 ==========

# 定义数据结构、常量、配置加载、文件读写等

CONFIG_PATH = "config/dedup_config.json"

class DuplicateRecord:

def init(self, id, name):

self.id = id

self.name = name

def load_existing_records():

# 从数据库或文件加载数据

pass

# ========== 2. 逻辑层 ==========

# 核心业务算法、判断规则、计算等

def find_duplicates(records):

# 业务逻辑

return duplicates

def filter_by_rule(records, rule):

# 纯逻辑，无输入输出交互

pass

# ========== 3. 界面/接口层 ==========

# 处理用户输入、打印输出、GUI事件、API接口等

def run_dedup_cli():

# 从命令行获取参数，调用逻辑层，打印结果

records = load_existing_records() # 调用数据层

result = find_duplicates(records) # 调用逻辑层

print(result)

def run_dedup_gui(parent_frame):

# 供 GUI 调用的入口

pass

```

每条规则

- 数据层：可以 import 标准库（如 json、csv），不 import 界面库（如 tkinter）。

- 逻辑层：纯 Python 计算，不依赖外部 I/O（数据库、网络、文件）。

- 界面层：可以调用数据层和逻辑层，但不在界面层写复杂算法。

---

## 四、配置与资源管理

- 配置：统一放在 `config/` 下，使用 `config.py` 封装加载逻辑。

- 资源：图片/字体/文档放 `assets/`，路径通过 `os.path.join(ROOT_DIR, "assets/...")` 获取。

- 第三方工具：放 `tools/` 或 `bin/`，程序运行时使用 `subprocess` 调用，路径用 `shutil.which()` 或绝对路径。

---

## 五、AI 编程特别提示

当使用 AI（如 Copilot、ChatGPT）生成代码时，遵循以下规范提示词：

> “按以下规范生成 Python 代码：

> 1. 项目采用单体架构，技术分层目录（`config`、`assets`、`modules`）。

> 2. 业务功能垂直拆分，每个 `.py` 文件只做一件事。

> 3. 文件内严格按数据层、逻辑层、界面层顺序组织，禁止跨层调用。

> 4. 只输出该文件的核心代码，不输出整个项目结构。”

---

## 六、规范记忆口诀

**目录三层技术分，业务垂直单文件；

文件内部三明治，数据逻辑界面清；

配置资源各归位，AI 编程有准绳。**

---

## 总结（一张表）

| 层级 | 组织方式 | 例子 |

|------|---------|------|

| 架构级 | 单体架构 | 一个 `main.py` 启动所有功能 |

| 目录级 | 技术分层 | `config/`、`modules/`、`assets/` |

| 文件级 | 业务垂直 | `dedup.py`、`audit.py` |

| 代码级 | 三层隔离 | 数据区 → 逻辑区 → 界面区 |

这套规范让 AI 生成的代码结构稳定、易于人类审阅和维护。