# 代码规范文档

**项目代号**: A00  
**项目名称**: TJFS集团官方网站及Web服务器  
**文档类型**: 代码规范文档  
**创建日期**: 2026-03-05  
**编制人**: TBs  
**文档版本**: V1.0  
**文档状态**: 已批准

---

## 目录

1. [概述](#一概述)
2. [通用规范](#二通用规范)
3. [HTML规范](#三html规范)
4. [CSS规范](#四css规范)
5. [JavaScript规范](#五javascript规范)
6. [Python规范](#六python规范)
7. [Git提交规范](#七git提交规范)
8. [代码审查规范](#八代码审查规范)

---

## 一、概述

### 1.1 规范目的

1. 提高代码可读性和可维护性
2. 统一团队编码风格
3. 减少代码缺陷
4. 提高开发效率
5. 便于代码审查

### 1.2 适用范围

本文档适用于TJFS集团官方网站及Web服务器项目（A00）的所有代码开发工作，包括HTML、CSS、JavaScript和Python代码。

### 1.3 规范原则

1. **一致性**: 整个项目保持统一的编码风格
2. **可读性**: 代码应该易于阅读和理解
3. **简洁性**: 避免过度复杂的实现
4. **可维护性**: 便于后续维护和扩展

---

## 二、通用规范

### 2.1 文件编码

- 所有源代码文件统一使用 **UTF-8** 编码
- 文件末尾保留一个空行
- 不使用BOM头

### 2.2 缩进与空格

| 语言 | 缩进方式 | 缩进大小 |
|------|----------|----------|
| HTML | 空格 | 2空格 |
| CSS | 空格 | 2空格 |
| JavaScript | 空格 | 2空格 |
| Python | 空格 | 4空格 |

### 2.3 行长度限制

| 文件类型 | 最大行长度 |
|----------|------------|
| HTML | 120字符 |
| CSS | 120字符 |
| JavaScript | 120字符 |
| Python | 120字符 |
| 文档/注释 | 80字符 |

### 2.4 命名规范

#### 2.4.1 通用命名规则

| 类型 | 命名风格 | 示例 |
|------|----------|------|
| 文件名 | 小写连字符 | style.css, main.js |
| 类名 | 小写连字符 | nav-container, btn-primary |
| ID名 | 小写连字符 | main-content, contact-form |
| 变量名 | 小驼峰 | userName, itemCount |
| 常量名 | 全大写下划线 | MAX_COUNT, API_BASE_URL |
| 函数名 | 小驼峰 | getUserById, initNavbar |

#### 2.4.2 命名原则

1. **有意义**: 名称应表达其用途和含义
2. **可读性**: 易于阅读和发音
3. **可搜索**: 便于代码搜索
4. **避免缩写**: 除非是通用缩写（如ID, URL）

```javascript
// 好的命名
var userName = 'John';
var maxConnectionCount = 100;
function calculateTotalPrice(items) { }

// 不好的命名
var n = 'John';
var mcc = 100;
function calc(items) { }
```

### 2.5 注释规范

#### 2.5.1 注释原则

1. 代码应该自解释，注释补充说明"为什么"而非"是什么"
2. 保持注释与代码同步更新
3. 避免无意义的注释

#### 2.5.2 文件头注释

```html
<!--
  文件名称: index.html
  功能描述: TJFS集团官网首页
  创建日期: 2026-03-05
  创建人: TBs
  修改记录:
    - 2026-03-10: 添加粒子背景动画
-->
```

```javascript
/**
 * 文件名称: main.js
 * 功能描述: 网站主要交互逻辑
 * 创建日期: 2026-03-05
 * 创建人: TBs
 * 修改记录:
 *   - 2026-03-10: 添加导航栏滚动效果
 */
```

```python
"""
文件名称: start-server.py
功能描述: TJFS Web服务器启动脚本
创建日期: 2026-03-05
创建人: TBs
修改记录:
    - 2026-03-10: 添加CORS支持
"""
```

#### 2.5.3 函数注释

```javascript
/**
 * 根据用户ID获取用户信息
 * @param {number} userId - 用户ID
 * @returns {Object|null} 用户对象，不存在返回null
 * @example
 * var user = getUserById(1);
 * console.log(user.name);
 */
function getUserById(userId) {
  // 实现代码
}
```

---

## 三、HTML规范

### 3.1 基本规范

- 使用HTML5文档类型声明
- 使用语义化标签
- 属性值使用双引号
- 自闭合标签不加斜杠

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>页面标题</title>
</head>
<body>
  <!-- 内容 -->
</body>
</html>
```

### 3.2 语义化标签

| 场景 | 推荐标签 |
|------|----------|
| 页面头部 | `<header>` |
| 导航 | `<nav>` |
| 主要内容 | `<main>` |
| 章节 | `<section>` |
| 文章 | `<article>` |
| 侧边栏 | `<aside>` |
| 页脚 | `<footer>` |

### 3.3 属性规范

```html
<!-- 好的写法 -->
<img src="image.jpg" alt="描述文字" width="100" height="100">
<a href="https://example.com" target="_blank" rel="noopener">链接</a>
<input type="text" name="username" required>

<!-- 不好的写法 -->
<img src='image.jpg' alt='描述文字'>
<a href=https://example.com>链接</a>
```

### 3.4 可访问性

```html
<!-- 图片添加alt属性 -->
<img src="logo.png" alt="TJFS集团Logo">

<!-- 表单添加label -->
<label for="email">邮箱</label>
<input type="email" id="email" name="email">

<!-- 按钮有明确的文字 -->
<button type="submit">提交</button>
```

---

## 四、CSS规范

### 4.1 基本规范

- 使用CSS变量管理颜色和尺寸
- 使用Flexbox和Grid进行布局
- 避免使用!important
- 选择器尽量简洁

### 4.2 文件组织

```css
/* 1. CSS变量 */
:root {
  --primary-color: #1a1a2e;
  --accent-color: #A8FCF3;
}

/* 2. 重置样式 */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

/* 3. 基础样式 */
body {
  font-family: 'Noto Sans SC', sans-serif;
}

/* 4. 布局样式 */
.container {
  max-width: 1200px;
  margin: 0 auto;
}

/* 5. 组件样式 */
.btn {
  padding: 12px 24px;
  border-radius: 8px;
}

/* 6. 工具类 */
.text-center {
  text-align: center;
}

/* 7. 媒体查询 */
@media (max-width: 768px) {
  /* 移动端样式 */
}
```

### 4.3 命名规范（BEM）

使用BEM命名规范：Block__Element--Modifier

```css
/* Block */
.card { }

/* Element */
.card__title { }
.card__content { }

/* Modifier */
.card--featured { }
.btn--primary { }
```

### 4.4 属性顺序

```css
.selector {
  /* 定位 */
  position: relative;
  top: 0;
  left: 0;
  z-index: 1;
  
  /* 盒模型 */
  display: flex;
  width: 100%;
  height: auto;
  margin: 0;
  padding: 20px;
  
  /* 视觉 */
  background: #fff;
  border: 1px solid #ddd;
  border-radius: 8px;
  
  /* 文字 */
  font-size: 16px;
  color: #333;
  
  /* 其他 */
  transition: all 0.3s ease;
}
```

---

## 五、JavaScript规范

### 5.1 基本规范

- 使用ES6+语法
- 使用const和let，不使用var
- 使用严格模式
- 使用模板字符串

```javascript
'use strict';

// 好的写法
const userName = 'John';
let count = 0;

const message = `Hello, ${userName}!`;

// 不好的写法
var name = 'John';
var msg = 'Hello, ' + name + '!';
```

### 5.2 函数定义

```javascript
// 箭头函数
const getUserById = (id) => {
  return users.find(user => user.id === id);
};

// 函数表达式
const initNavbar = function() {
  // 实现
};

// 默认参数
function greet(name = 'Guest') {
  return `Hello, ${name}!`;
}
```

### 5.3 对象和数组

```javascript
// 对象简写
const name = 'John';
const user = { name };  // { name: 'John' }

// 解构赋值
const { id, name, email } = user;
const [first, second] = items;

// 展开运算符
const newUser = { ...user, age: 30 };
const newArray = [...array1, ...array2];
```

### 5.4 异步处理

```javascript
// 使用async/await
const fetchData = async () => {
  try {
    const response = await fetch('/api/data');
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
};
```

### 5.5 DOM操作

```javascript
// 查询元素
const navbar = document.getElementById('navbar');
const buttons = document.querySelectorAll('.btn');

// 事件监听
button.addEventListener('click', (e) => {
  e.preventDefault();
  // 处理逻辑
});

// 创建元素
const div = document.createElement('div');
div.className = 'new-element';
div.textContent = '内容';
```

### 5.6 错误处理

```javascript
try {
  const result = riskyOperation();
  processResult(result);
} catch (error) {
  console.error('Operation failed:', error.message);
  showErrorMessage('操作失败，请稍后重试');
}
```

---

## 六、Python规范

### 6.1 基本规范

遵循 **PEP 8** 规范。

### 6.2 导入规范

```python
# 标准库
import os
import sys
from pathlib import Path

# 第三方库（本项目无）

# 本地模块
from .utils import helper
```

### 6.3 函数定义

```python
def create_user(username: str, email: str, is_admin: bool = False) -> dict:
    """
    创建用户
    
    Args:
        username: 用户名
        email: 邮箱地址
        is_admin: 是否为管理员，默认False
        
    Returns:
        用户对象字典
        
    Raises:
        ValueError: 当参数无效时
    """
    if not username:
        raise ValueError('用户名不能为空')
    
    return {
        'username': username,
        'email': email,
        'is_admin': is_admin
    }
```

### 6.4 类定义

```python
class CustomHTTPRequestHandler(http.server.SimpleHTTPRequestHandler):
    """自定义HTTP请求处理器"""
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._cache = {}
    
    def end_headers(self):
        """添加CORS头"""
        self.send_header('Access-Control-Allow-Origin', '*')
        super().end_headers()
```

### 6.5 异常处理

```python
try:
    with socketserver.TCPServer(("", PORT), handler) as httpd:
        httpd.serve_forever()
except PermissionError:
    print(f'错误: 无法绑定端口 {PORT}')
    sys.exit(1)
except KeyboardInterrupt:
    print('\n服务器已停止')
    sys.exit(0)
```

---

## 七、Git提交规范

### 7.1 提交信息格式

```
<type>: <subject>

<body>

<footer>
```

### 7.2 提交类型

| 类型 | 说明 | 示例 |
|------|------|------|
| feat | 新功能 | feat: 添加导航栏滚动效果 |
| fix | Bug修复 | fix: 修复移动端菜单无法关闭问题 |
| docs | 文档更新 | docs: 更新README文档 |
| style | 代码格式 | style: 格式化CSS代码 |
| refactor | 重构 | refactor: 重构动画模块 |
| test | 测试 | test: 添加表单验证测试 |
| chore | 构建/工具 | chore: 更新服务器端口配置 |

### 7.3 提交示例

```
feat: 添加粒子背景动画

- 实现动态粒子生成
- 添加浮动动画效果
- 优化移动端性能

Closes #5
```

### 7.4 分支命名

| 分支类型 | 命名规则 | 示例 |
|----------|----------|------|
| 功能分支 | feature/功能描述 | feature/navbar-animation |
| 修复分支 | fix/问题描述 | fix/mobile-menu |
| 文档分支 | docs/文档描述 | docs/api-docs |

---

## 八、代码审查规范

### 8.1 审查清单

#### 代码质量

- [ ] 代码是否符合编码规范
- [ ] 命名是否清晰有意义
- [ ] 是否有冗余代码
- [ ] 是否有复杂度过高的代码
- [ ] 是否有重复代码

#### 功能正确性

- [ ] 是否实现了需求要求的功能
- [ ] 边界条件是否处理正确
- [ ] 异常情况是否处理
- [ ] 是否有安全漏洞

#### 可访问性

- [ ] 图片是否有alt属性
- [ ] 表单是否有label
- [ ] 颜色对比度是否足够
- [ ] 是否支持键盘导航

#### 性能

- [ ] 是否有性能瓶颈
- [ ] 动画是否流畅
- [ ] 资源加载是否优化

#### 文档

- [ ] 是否有必要的注释
- [ ] 是否更新了相关文档
- [ ] 函数是否有文档字符串

### 8.2 审查流程

```
提交代码 → 自动检查 → 人工审查 → 修改完善 → 合并代码
    │           │           │           │           │
    ▼           ▼           ▼           ▼           ▼
 创建PR     代码检查    审查者审查   作者修改    完成合并
```

### 8.3 审查反馈

#### 反馈级别

| 级别 | 说明 | 处理方式 |
|------|------|----------|
| 必须修改 | 影响功能或有严重问题 | 必须修改后才能合并 |
| 建议修改 | 可以改进的地方 | 建议修改 |
| 讨论问题 | 需要讨论的问题 | 可以讨论后决定 |

---

## 附录

### 附录A: 推荐工具

| 工具 | 用途 | 配置 |
|------|------|------|
| VS Code | 代码编辑 | 安装ESLint、Prettier插件 |
| Chrome DevTools | 调试 | 内置 |
| W3C Validator | HTML验证 | https://validator.w3.org/ |
| Prettier | 代码格式化 | 配置.prettierrc |

### 附录B: 推荐阅读

- MDN Web Docs
- Google HTML/CSS Style Guide
- Airbnb JavaScript Style Guide
- PEP 8 -- Style Guide for Python Code

### 附录C: 变更记录

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| V1.0 | 2026-03-05 | 初始版本 | TBs |

---

**文档编制日期**: 2026-03-05  
**编制单位**: SG Studio - 松果工作室  
**文档版本**: V1.0