ai_soc_sw/.ai/prompts/coding/code-style.md

Dev AI 代码风格规范

适用技术栈

层	技术	语言
前端	Taro 4 + React 18	TypeScript 5.x
样式	Tailwind CSS 4	—
后端	NestJS 10	TypeScript 5.x
训练	PyTorch 2.0	Python 3.10+

---

1. 文件命名

类型	规则	示例
页面组件	kebab-case	error-detail.tsx
UI 组件	kebab-case	button.tsx
工具函数	kebab-case	format-date.ts
类型定义	kebab-case	error-entry.d.ts
NestJS 模块	kebab-case	auth.module.ts
Python 模块	snake_case	data_loader.py

2. 目录组织（前端）

src/
├── pages/{page-name}/     # 页面 —— 一个目录一个页面
│   ├── index.tsx
│   ├── index.config.ts
│   └── index.css
├── components/            # 通用组件
│   └── {component-name}/
│       └── index.tsx
├── lib/                   # 工具函数、hooks
├── types/                 # 全局类型声明
├── server/                # NestJS 后端
└── config/                # Taro 构建配置

3. 目录组织（NestJS 后端）

src/server/src/
├── modules/{name}/        # 一个模块一个目录
│   ├── {name}.module.ts
│   ├── {name}.controller.ts
│   ├── {name}.service.ts
│   ├── dto/
│   └── entities/
├── common/                # 共享：拦截器、守卫、管道
└── main.ts

4. 命名风格

TypeScript：

• 组件：PascalCase —— ErrorCard
• 函数/变量：camelCase —— getUserProfile
• 常量：UPPER_SNAKE —— MAX_PAGE_SIZE
• 接口/类型：PascalCase —— ErrorEntry

Python：

• 类：PascalCase —— DataLoader
• 函数/变量：snake_case —— load_dataset
• 常量：UPPER_SNAKE —— BATCH_SIZE

5. 导入顺序（TypeScript）

1. 第三方库
2. Taro 相关
3. 项目内部（@/ 别名）
4. 相对路径
5. 样式文件

示例：

import { useState } from 'react';
import Taro from '@tarojs/taro';
import { Button } from '@/components/ui/button';
import { formatDate } from './lib/date';
import './index.css';

6. 组件规范

• 优先使用函数组件，不用 class 组件
• 一个文件只有一个 export default 组件
• 组件 props 必须声明类型接口
• 跨端兼容：避免使用 document、window（用 Taro API 代替）

7. API 调用规范

• 前端统一使用 @/network.ts 中的 Network.request，不要直接调用 Taro.request
• 后端Controller 只做参数校验和路由，业务逻辑放在 Service
• API 响应统一使用 Envelope 格式 { code, msg, data }

8. 不能做的事

• 不要在 src/ 下写测试文件（测试在 tests/）
• 不要引入未经 package.json 声明的依赖
• 不要在组件中硬编码后端地址（用 PROJECT_DOMAIN 全局变量）