# Next_Edu 编码规范

> 版本：1.0（2026-06-17 适配当前项目）
> 依据：Google TypeScript Style + Airbnb React + Next.js 16 + Tailwind v4 最佳实践
> 适用范围：Next_Edu K12 智慧教务系统（单应用 + 模块化架构）
> 关联文档：
> - [项目规则](../../.trae/rules/project_rules.md)
> - [架构影响地图](../architecture/004_architecture_impact_map.md)
> - [解耦路线图](../architecture/audit/01_decoupling_roadmap.md)

---

## 目录

1. [项目原则与理念](#一项目原则与理念)
2. [项目结构](#二项目结构)
3. [命名规范](#三命名规范)
4. [TypeScript 强制规范](#四typescript-强制规范)
5. [React 与 Next.js 组件规范](#五react-与-nextjs-组件规范)
6. [Tailwind CSS 规范](#六tailwind-css-规范)
7. [数据获取与状态管理](#七数据获取与状态管理)
8. [路由、代理与安全](#八路由代理与安全)
9. [错误处理与可观测性](#九错误处理与可观测性)
10. [测试规范](#十测试规范)
11. [Git 工作流与提交规范](#十一git-工作流与提交规范)
12. [CI/CD 流水线](#十二cicd-流水线)
13. [可访问性（A11y）规范](#十三可访问性a11y规范)
14. [文档与交付物](#十四文档与交付物)
15. [统一工具配置](#十五统一工具配置)
16. [代码审查清单](#十六代码审查清单)

---

## 一、项目原则与理念

1. **可读性优先于机巧**：代码首先是写给队友看的
2. **显式优于隐式**：避免魔法值、隐式类型转换、隐式全局副作用
3. **单一职责**：每个文件、函数、组件只做一件事，衡量标准是"能否用一句话描述它"
4. **防御性编程**：永远假设输入可能是 null/undefined 或非法格式
5. **工具强制一致性**：风格、格式、类型由 ESLint、Prettier、TypeScript 自动保证
6. **架构图优先**：任何任务开始前先查阅 [004 架构影响地图](../architecture/004_architecture_impact_map.md)，按图索骥
7. **模块封装**：模块间不直接查询对方 DB 表，必须通过 data-access 函数

---

## 二、项目结构

### 2.1 顶层结构（单应用 + 模块化）

本项目**不是 Monorepo**，采用单 Next.js 应用 + 严格模块化架构：

```
root/
├─ src/
│  ├─ app/                    # App Router 路由层
│  │  ├─ (auth)/              # 路由组：认证页面
│  │  ├─ (dashboard)/         # 路由组：业务页面（admin/teacher/student/parent）
│  │  ├─ api/                 # REST API 路由
│  │  ├─ globals.css          # Tailwind v4 指令 + CSS 变量设计令牌
│  │  ├─ layout.tsx           # 根布局（Provider 组合）
│  │  └─ page.tsx             # 首页
│  ├─ modules/                # 业务模块层（26 个模块）
│  │  ├─ exams/               # 每个模块标准结构见 2.2
│  │  ├─ homework/
│  │  ├─ classes/
│  │  └─ ...
│  ├─ shared/                 # 基础设施层（被依赖方，不反向依赖）
│  │  ├─ components/          # 共享组件（ui/ + a11y/ + 顶层）
│  │  ├─ db/                  # Drizzle ORM（schema.ts + relations.ts + index.ts）
│  │  ├─ hooks/               # 全局自定义 Hook
│  │  ├─ lib/                 # 纯工具函数（auth-guard, ai, permissions, ...）
│  │  └─ types/               # 公共类型定义
│  ├─ auth.ts                 # NextAuth 配置（根模块）
│  ├─ proxy.ts                # Next.js 16 代理（原 middleware.ts）
│  └─ env.mjs                 # 环境变量校验（@t3-oss/env-nextjs + Zod）
├─ tests/                     # 测试目录
│  ├─ e2e/                    # Playwright E2E 测试
│  ├─ integration/            # 集成测试
│  ├─ visual/                 # 视觉回归测试
│  └─ setup/                  # 测试 setup
├─ scripts/                   # 运维脚本（db/backup/security/dr）
├─ docs/                      # 文档（架构/审查/专题/设计）
├─ drizzle/                   # 数据库迁移
└─ .gitea/workflows/          # CI/CD 流水线
```

### 2.2 模块标准结构

每个业务模块遵循**统一结构**，职责分离：

```
src/modules/[module]/
├─ actions.ts              # Server Actions（编排层：权限校验 + 调用 data-access + revalidate）
├─ data-access.ts          # 数据访问层（DB CRUD，仅服务端，可拆分为多个 data-access-*.ts）
├─ schema.ts               # Zod 验证 schema（可选，按需）
├─ types.ts                # 模块类型定义
├─ components/             # 模块专属组件
│  └─ [feature]/           # 复杂功能可分子目录
└─ hooks/                  # 模块专属 Hook（可选）
```

**分层规则**（严格单向依赖）：

```
app/  ──▶  modules/  ──▶  shared/
                              ▲
                              │
                       禁止反向依赖
```

- `app/` 只能调用 `modules/` 的 Server Actions 和 data-access 函数，**不直接访问 DB**
- `modules/` 之间通过对方 data-access 通信，**不直接查询对方 DB 表**
- `shared/` 是被依赖方，**不得反向依赖** `@/auth`、`@/proxy` 或任何 `modules/*`
- `src/auth.ts` 和 `src/proxy.ts` 位于根目录，属于应用层

**文件拆分规则**（当 data-access 过大时）：

```
src/modules/classes/
├─ data-access.ts              # 核心 CRUD
├─ data-access-stats.ts        # 统计查询
├─ data-access-schedule.ts     # 课表查询
└─ data-access-grades.ts       # 成绩汇总
```

### 2.3 路由组织

- 使用路由组 `(group)` 组织相同布局的页面，不影响 URL
- 动态路由 `[slug]`、捕获所有 `[...slug]`、可选捕获 `[[...slug]]` 按需使用
- 路由命名一律使用**小写与连字符**（`user-profile`）
- 每个路由段应提供 `loading.tsx`（骨架屏）和 `error.tsx`（错误边界）

### 2.4 核心原则

- 页面组件（`page.tsx`）必须使用**默认导出**；布局、加载、错误使用**具名导出**
- 每个路由段都必须提供 `error.tsx`，不得出现未捕获异常导致白屏
- `loading.tsx` 必须提供骨架屏或最小可感知的加载状态，**不得使用全局 spin 遮罩**
- 服务端数据获取通过模块的 `data-access.ts`，标记 `import "server-only"` 以防客户端误用

---

## 三、命名规范

### 3.1 文件与目录

| 对象 | 命名风格 | 示例 |
|------|---------|------|
| 目录 | kebab-case | `user-profile/`, `class-detail/` |
| 组件文件 | PascalCase | `UserProfile.tsx`, `ExamForm.tsx` |
| Hook 文件 | camelCase | `useAuth.ts`, `useExamPreview.ts` |
| 工具函数文件 | camelCase | `formatCurrency.ts`, `auditLogger.ts` |
| 类型定义文件 | camelCase | `user.ts`, `permissions.ts` |
| 测试文件 | `*.test.ts` / `*.spec.ts` | `utils.test.ts`, `auth.spec.ts` |
| Server Action | `actions.ts` 或 `xxx-actions.ts` | `actions.ts`, `actions-analytics.ts` |
| Data Access | `data-access.ts` 或 `data-access-*.ts` | `data-access.ts`, `data-access-stats.ts` |
| 代理（Next.js 16） | `proxy.ts` | `src/proxy.ts` |
| 常量文件 | camelCase | `navigation.ts`, `permissions.ts` |
| 环境变量 | UPPER_SNAKE_CASE | `DATABASE_URL`, `NEXTAUTH_SECRET` |

### 3.2 变量、函数、类

- **变量**：camelCase。布尔值用 `is/has/can/should` 前缀（`isVisible`, `hasError`）
- **函数**：camelCase，动词开头（`fetchUser`, `handleSubmit`, `validateForm`）
- **常量**：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`, `API_BASE_URL`）
- **类与接口**：PascalCase。接口**不加** `I` 前缀（Google 风格）
- **类型别名**：PascalCase，如 `type UserId = string`
- **泛型参数**：使用描述性名称，如 `TData`, `TResponse`（避免单字母 `T`）
- **枚举**：推荐联合类型 + 字符串字面量（tree-shaking 友好）。如必须用枚举，成员名 PascalCase

### 3.3 组件与 Props

- 组件名必须为**多词**（`UserProfile` 而非 `Profile`），以免与 HTML 元素冲突
- Props 类型命名为 `组件名Props`（`UserProfileProps`），定义在组件文件顶部
- 事件回调 Props 使用 `on` 前缀（`onSave`, `onClose`）
- `children` 必须显式声明类型 `React.ReactNode`
- **不使用 `React.FC`**，直接用函数声明 + 显式标注 props 类型（Google 风格）

```tsx
// 推荐方式
interface UserCardProps {
  user: User;
  onSelect: (id: string) => void;
  children?: React.ReactNode;
}

export function UserCard({ user, onSelect, children }: UserCardProps): JSX.Element {
  // ...
}
```

---

## 四、TypeScript 强制规范

### 4.1 配置（tsconfig.json）

当前项目配置需升级以符合规范。**目标配置**：

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "ES2022"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "jsx": "react-jsx",
    "incremental": true,
    "noEmit": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

**当前差异**（需逐步升级）：
- `target`: `ES2017` → `ES2022`
- 缺失 `noUncheckedIndexedAccess`（数组/对象索引返回 `T | undefined`）
- 缺失 `noImplicitReturns`（函数所有分支必须返回）
- 缺失 `noFallthroughCasesInSwitch`

### 4.2 类型规则

1. **禁止 `any`**：未知类型用 `unknown` 并做类型守卫。若极特殊情况必须使用，需 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` 并注释原因

2. **优先 `interface` 描述对象形状**，`type` 用于联合、交叉、映射类型

3. **不使用 `as` 断言**，除非从 `unknown` 强制转换或在测试中（需注释原因）。可用 `satisfies` 保持类型推导

4. **函数返回值必须显式标注**，特别是 `Promise<T>`

5. **可选链后禁止跟非空断言 `!`**（`x?.y!` 是矛盾的）

6. **所有仅用于类型的导入必须使用 `import type`**

```typescript
import type { User, Permission } from "@/shared/types/permissions";
```

7. **避免 `object` 或 `{}` 作为类型**，使用 `Record<string, unknown>` 或具体接口

8. **泛型使用有意义的名称**；若函数只有一处使用，不一定需要泛型

### 4.3 导入顺序（强制执行）

```typescript
// 1. React 相关
import React from "react";
// 2. 第三方库
import { z } from "zod";
import { useQuery } from "@tanstack/react-query";
// 3. 内部绝对路径（使用别名 @/）
import { Button } from "@/shared/components/ui/button";
import { requirePermission } from "@/shared/lib/auth-guard";
// 4. 相对路径导入
import { formatDate } from "../utils";
import { getExams } from "./data-access";
// 5. 类型导入
import type { User } from "@/shared/types/permissions";
```

使用 `eslint-plugin-import` 规则 `import/order` 自动排序，分组间空一行。

---

## 五、React 与 Next.js 组件规范

### 5.1 组件定义

- 组件必须为**纯函数**，使用 `function` 声明（非箭头函数，Google 风格）
- 页面组件（`page.tsx`）使用**默认导出**；其余所有组件使用**具名导出**
- **禁止在渲染期间**修改外部变量、执行网络请求、读取/写入 DOM（除 ref 初始化）

### 5.2 服务端组件 vs 客户端组件

- **默认服务端组件**。只有需要交互（事件处理）、状态（`useState`/`useReducer`）、效果（`useEffect`）或浏览器 API 时，才在文件顶部添加 `"use client"` 指令
- `"use client"` 必须位于文件**第一行**，之后空一行再写代码
- 客户端组件应尽可能小而聚焦。将需要交互的局部提取为客户端组件，外层容器保持服务端渲染
- **禁止在服务端组件中使用** `useState`, `useEffect`, `onClick` 等客户端特性

```tsx
// 容器页面（服务端）
import { UserList } from "@/modules/users/components/user-list";
import { getUsers } from "@/modules/users/data-access";

export default async function UsersPage(): Promise<JSX.Element> {
  const users = await getUsers();
  return <UserList users={users} />;
}
```

### 5.3 组件拆分指南

本项目采用**企业级行数规范**（见 [项目规则](../../.trae/rules/project_rules.md)）：

| 文件类型 | 建议行数 | 硬性上限 |
|---------|---------|---------|
| 配置/常量/类型定义文件 | 无限制 | 无限制 |
| React 组件 | ≤ 500 行 | 800 行（复杂表单/大型表格） |
| Server Actions / Data Access | ≤ 800 行 | 1000 行 |
| 工具函数 | ≤ 40 行 | - |
| 自定义 Hook | ≤ 80 行 | - |

**超过建议行数时的拆分信号**：
1. **语义边界**：子模块能用一个明确名称独立描述其作用
2. **状态边界**：有独立的 `useState`/`useEffect` 逻辑，或生命周期明显不同
3. **复用潜力**：某段 UI 或逻辑可能在另一页面使用
4. **复杂度预警**：Hook 调用超过 3 个，或 JSX 嵌套层级超过 4 层
5. **可测试性**：若要对组件的一部分逻辑编写单元测试，说明该部分应该独立

### 5.4 Hook 规范

- 命名以 `use` 开头，驼峰式
- **单一职责**：一个 Hook 只做一件事
- 返回值使用**对象形式**（非数组），方便使用者按需提取

```ts
const { data, isLoading, error } = useUser(userId);
```

- 必须编写 JSDoc，描述用途、参数、返回值和可能副作用
- 所有 `useEffect` 必须提供**清理函数**（如订阅、定时器）
- `useEffect` 依赖数组必须**完整**，不得遗漏响应式变量。若确实需要忽略，用 `// eslint-disable-next-line react-hooks/exhaustive-deps` 并注释原因

---

## 六、Tailwind CSS 规范

### 6.1 核心策略

本项目使用 **Tailwind v4**，采用 **CSS 变量设计令牌**（在 `globals.css` 中定义），而非传统的 `tailwind.config.ts` 扩展。

- **移动优先**：所有类名从无前缀（移动端）开始，逐步通过 `sm:`, `md:`, `lg:`, `xl:`, `2xl:` 增强
- **类名组织顺序**：布局 → 盒模型 → 排版 → 背景 → 边框 → 效果 → 状态
- **可读性**：当单个元素类名超过 10 个时，考虑提取为组件

### 6.2 类名编写最佳实践

使用 `cn()` 工具函数（基于 `clsx` + `tailwind-merge`）管理条件类名：

```tsx
import { cn } from "@/shared/lib/utils";

<button
  className={cn(
    "inline-flex items-center rounded px-4 py-2",
    "text-sm font-medium text-white",
    variant === "primary" && "bg-primary hover:bg-primary/90",
    disabled && "cursor-not-allowed opacity-50"
  )}
/>
```

**禁止模式**：
- ❌ 禁止字符串拼接动态类名（`bg-${color}-500`），Tailwind 无法静态分析
- ❌ 禁止使用 `!important`（Tailwind 的 `!` 前缀在必须覆盖第三方样式时可使用，但需谨慎）
- ❌ 禁止使用任意值（`w-[137px]`），除非有充分理由并注释说明

### 6.3 设计令牌配置

本项目在 `src/app/globals.css` 中使用 CSS 变量定义设计令牌：

```css
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 240 5.9% 10%;
  --primary-foreground: 0 0% 98%;
  --destructive: 0 84.2% 60.2%;
  --border: 240 5.9% 90%;
  --radius: 0.5rem;
  /* ... */
}
```

**所有视觉设计决策**（颜色、字号、间距）必须体现在设计令牌中，组件中不使用硬编码值。

---

## 七、数据获取与状态管理

### 7.1 数据获取分层

本项目采用**模块化 data-access 层**（替代传统 `services/`）：

| 层级 | 位置 | 职责 | 标记 |
|------|------|------|------|
| 服务端数据 | `modules/[module]/data-access.ts` | DB CRUD + 查询 | `import "server-only"` |
| 客户端动态数据 | TanStack Query | 缓存、重试、乐观更新 | `"use client"` |
| Server Actions | `modules/[module]/actions.ts` | 编排：权限 + 调用 data-access + revalidate | `"use server"` |

**规则**：
- 服务端数据获取通过模块的 `data-access.ts` 函数
- 客户端动态数据统一使用 **TanStack Query v5+**，**禁止在 `useEffect` 中手写 fetch**
- 缓存策略：服务端请求必须显式设置 `next.revalidate` 或使用 `unstable_cache`，并注释缓存时长理由

### 7.2 Server Actions

**文件命名**：`actions.ts` 或 `xxx-actions.ts`（如 `actions-analytics.ts`），置于对应模块目录

**强制规则**：
1. 每个 Action 函数必须使用 `"use server"`（文件顶部或函数级）
2. **权限校验**：函数体内必须调用 `requirePermission()`，绝不信任客户端参数
3. **输入验证**：使用 Zod 定义 schema，在 Action 入口解析，验证失败返回结构化错误
4. **返回值**：统一采用 `ActionState<T>` 类型（已定义于 `@/shared/types/action-state`）

```typescript
// 当前 ActionState 定义
export type ActionState<T = void> = {
  success: boolean;
  message?: string;
  errors?: Record<string, string[]>;
  data?: T;
};
```

5. **错误处理**：Action 内所有错误必须捕获并转为 `ActionState` 返回，客户端不得捕获到未处理异常
6. **缓存刷新**：使用 `revalidatePath` 或 `revalidateTag` 精确刷新相关缓存，避免全站重新验证

**标准 Action 模板**：

```typescript
"use server";

import { revalidatePath } from "next/cache";
import { z } from "zod";
import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard";
import { Permissions } from "@/shared/types/permissions";
import { createExam } from "./data-access";
import type { ActionState } from "@/shared/types/action-state";

const ExamCreateSchema = z.object({
  title: z.string().min(1),
  // ...
});

export async function createExamAction(
  _prev: ActionState,
  formData: FormData
): Promise<ActionState<{ id: string }>> {
  try {
    const ctx = await requirePermission(Permissions.EXAM_CREATE);
    const parsed = ExamCreateSchema.safeParse(Object.fromEntries(formData));
    if (!parsed.success) {
      return {
        success: false,
        message: "表单校验失败",
        errors: parsed.error.flatten().fieldErrors,
      };
    }
    const exam = await createExam(ctx.userId, parsed.data);
    revalidatePath("/teacher/exams");
    return { success: true, data: { id: exam.id }, message: "创建成功" };
  } catch (error) {
    if (error instanceof PermissionDeniedError) {
      return { success: false, message: "权限不足" };
    }
    return { success: false, message: "创建失败，请重试" };
  }
}
```

### 7.3 状态管理

| 场景 | 方案 |
|------|------|
| 局部 UI 状态 | `useState` / `useReducer` |
| 跨组件共享（小范围） | React Context |
| 跨组件共享（大范围） | Zustand（轻量、可选择订阅） |
| 全局状态 | 仅存放真正全局必要数据（认证信息、主题、通知列表） |
| URL 状态 | `nuqs`（已集成） |

**规则**：
- Context 拆分：一个 Context 只负责一类数据，避免无关状态变化引发不必要的渲染
- 业务数据一律通过路由参数或 TanStack Query 获取，**不存入全局状态**
- Zustand 的 `persist` 中间件必须处理版本迁移和敏感数据加密

---

## 八、路由、代理与安全

### 8.1 路由组织

- 使用路由组 `(group)` 组织相同布局的页面，不影响 URL
- 动态路由 `[slug]`、捕获所有 `[...slug]`、可选捕获 `[[...slug]]` 按需使用
- 路由命名一律使用**小写与连字符**（`user-profile`）

### 8.2 代理（proxy.ts）

> **Next.js 16 重要变更**：`middleware.ts` 已重命名为 `proxy.ts`。本项目使用 `src/proxy.ts`。

- 集中处理**身份验证**、**权限路由**、**API 权限**
- 代理逻辑必须**轻量**（执行时间 < 50ms），复杂逻辑委托给 API 或服务端组件
- 使用 `NextResponse` 提供统一错误响应，**不做重型数据库操作**

当前 `proxy.ts` 实现：
- 路由前缀 → 最低权限映射（`/admin` → `school:manage`，`/teacher` → `exam:read`，等）
- API 路由前缀 → 权限映射（`/api/ai/chat` → `ai:chat`）
- 未认证 → 重定向登录；权限不足 → 重定向默认页

### 8.3 安全规范

1. **XSS 防护**：JSX 默认转义，**禁止 `dangerlySetInnerHTML`**。如必须使用，必须先用 DOMPurify 清洗

2. **CSRF 防护**：所有状态变更操作（POST/PUT/DELETE）必须校验 Origin/Referer 头。Next.js Server Actions 默认通过 POST 发送，仍需应用层校验

3. **认证令牌**：JWT/session ID 存储在 `httpOnly`、`Secure`、`SameSite=Strict` 的 Cookie 中，前端不可读

4. **环境变量**：
   - 服务端变量**不加** `NEXT_PUBLIC_` 前缀
   - 客户端变量**必须加** `NEXT_PUBLIC_` 前缀，且仅暴露非敏感信息
   - 使用 `@t3-oss/env-nextjs` + Zod 在应用启动时验证环境变量（已实现于 `src/env.mjs`）

5. **权限校验**：
   - Server Action 必须使用 `requirePermission()` 进行权限校验
   - 前端组件**禁止使用** `role === "xxx"` 硬编码，统一使用 `usePermission().hasPermission()`

6. **依赖扫描**：CI 中集成 `npm audit` + Snyk + Trivy，高危漏洞阻断合并

---

## 九、错误处理与可观测性

1. **错误边界**：每个路由段必须有 `error.tsx`；全局兜底 `global-error.tsx`

2. **结构化日志**：服务端日志使用 `shared/lib/audit-logger.ts`、`change-logger.ts`、`login-logger.ts`，记录关键操作

3. **性能监控**：通过 `web-vitals` 库上报 CLS、FID、LCP 到监控平台；生产环境开启 Next.js 内置分析

4. **API 速率限制**：对公开 API 或 Server Action 实施速率限制（`shared/lib/rate-limit.ts`），防止滥用

5. **审计日志**：
   - 登录日志：`login-logger.ts` 记录所有登录尝试（成功/失败）
   - 数据变更日志：`change-logger.ts` 记录所有数据变更操作
   - 审计日志：`audit-logger.ts` 记录关键业务操作

---

## 十、测试规范

### 10.1 测试分层

| 层级 | 工具 | 覆盖率目标 | 位置 |
|------|------|-----------|------|
| 单元测试 | Vitest | 100%（工具函数） | 同目录 `*.test.ts` |
| 组件测试 | React Testing Library + Vitest | ≥ 80% | 同目录 `*.test.tsx` |
| 集成测试 | Vitest + jsdom | 关键流程 | `tests/integration/` |
| E2E 测试 | Playwright | 核心业务路径 | `tests/e2e/` |
| 视觉回归 | Playwright（visual-chromium 项目） | 关键页面 | `tests/visual/` |

### 10.2 编写规范

- 测试文件与源文件**同目录**，命名为 `*.test.ts(x)` 或 `*.spec.ts(x)`
- 使用 `describe`/`it` 结构，描述应说明预期行为：`it("should disable button while loading")`
- 查询元素优先使用 `byRole`（符合无障碍），其次 `byLabelText`；避免 `byTestId` 除非必要
- 异步交互必须用 `waitFor` 或 `findBy*`，**禁止固定 `setTimeout`**
- Mock 仅用于外部边界（API、数据库）；组件自身逻辑须真实运行

### 10.3 测试命令

```bash
npm run test:unit          # 单元测试
npm run test:integration   # 集成测试
npm run test:e2e           # E2E 测试
npm run test:visual        # 视觉回归测试
npm run test               # 全部测试
```

---

## 十一、Git 工作流与提交规范

### 11.1 分支策略

- `main` 分支受保护，禁止直接推送
- 功能分支：`feat/JIRA-123-add-user-avatar`
- 修复分支：`fix/JIRA-456-correct-total`
- 发布分支：`release/v1.2.0`
- 热修复：`hotfix/security-patch`

### 11.2 提交信息（Conventional Commits）

```
feat(dashboard): add revenue chart
fix(cart): handle empty cart on checkout
chore(deps): update next to 16.0.0
docs(readme): add local setup guide
style(button): adjust hover color
refactor(utils): extract date formatting
test(checkout): cover discount edge cases
```

- 类型必须是 `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `perf`, `ci` 之一
- 范围可选但推荐（小写，与功能域对应）
- 提交信息使用**中文或英文**均可，但需与项目现有风格一致

### 11.3 质量门禁

- **提交前**：必须运行 `npm run lint` 和 `npx tsc --noEmit` 确保零错误
- **pre-commit**（推荐配置 Husky + lint-staged）：对暂存文件执行 `eslint --fix`, `prettier --write`
- **commit-msg**（推荐配置 commitlint）：检查提交信息格式

---

## 十二、CI/CD 流水线

当前项目使用 **Gitea Actions**（`.gitea/workflows/`）：

| 工作流 | 文件 | 用途 |
|--------|------|------|
| CI | `ci.yml` | Lint + 类型检查 + 单元测试 + 集成测试 + 构建 + 安全扫描 |
| 安全扫描 | `security.yml` | 每周深度扫描（npm audit + Snyk + Trivy + OWASP ZAP） |
| 灾备演练 | `dr-drill.yml` | 每周灾备演练 |

**CI 必须包含**：
1. 安装依赖（`npm ci`，利用缓存）
2. Lint 检查（ESLint）
3. 类型检查（`tsc --noEmit`）
4. 单元测试（Vitest + 覆盖率报告）
5. 构建（`next build`，确保 standalone 输出）
6. 安全审计（`npm audit` + Snyk + Trivy）
7. E2E 测试（仅主分支，部署 staging 后运行 Playwright）

---

## 十三、可访问性（A11y）规范

**目标**：WCAG 2.2 AA 合规

### 13.1 强制规则

1. **ESLint 插件**：`eslint-plugin-jsx-a11y` 设置为 `error`（待集成）
2. **键盘导航**：所有交互元素可用 Tab 访问，Enter/Space 激活，Escape 关闭弹层。焦点管理必须合理（弹窗打开时焦点移入，关闭后复原）
3. **语义化 HTML**：使用 `<header>`, `<main>`, `<nav>`, `<footer>`，按钮必须是 `<button>`（非 `div`）
4. **图片**：必须提供 `alt` 属性；装饰性图片用 `alt=""`
5. **表单**：每个输入元素关联 `<label>`，必填项明确标识
6. **色彩对比度**：文本与背景至少 4.5:1（普通文本）或 3:1（大文本）
7. **动态内容**：使用 `aria-live` 区域通知屏幕阅读器

### 13.2 已实现的 A11y 工具

- `src/shared/lib/a11y.ts`：`useA11yId`, `mergeA11yProps`, `describeInput`, `loadingAria`
- `src/shared/hooks/use-aria-live.ts`：aria-live 区域管理 Hook
- `src/shared/components/a11y/`：`skip-link`, `visually-hidden`, `focus-trap`, `aria-status`
- UI 组件（table, dialog）已增强系统性 ARIA role

### 13.3 工具检查

- CI 中可集成 `@axe-core/playwright` 做自动化检查
- 视觉回归测试（`tests/visual/`）覆盖关键页面的渲染一致性

---

## 十四、文档与交付物

### 14.1 项目必写文档

| 文档 | 位置 | 状态 |
|------|------|------|
| README.md | 根目录 | ✅ 待更新（当前为默认模板） |
| 架构文档 | `docs/architecture/` | ✅ 已完善（001-007） |
| 文档索引 | `docs/README.md` | ✅ 已创建 |
| 工作日志 | `docs/work_log.md` | ✅ 持续维护 |
| CONTRIBUTING.md | 根目录 | ❌ 待创建 |
| CHANGELOG.md | 根目录 | ❌ 待创建 |

### 14.2 架构文档维护规则

**任何源码修改后，必须同步更新架构文档**：

| 修改场景 | 需更新文档 |
|---------|-----------|
| 新增/删除/重命名导出函数、组件、Hook、类型 | 004 + 005 |
| 修改函数签名（参数、返回类型） | 004 + 005 |
| 修改权限点或角色-权限映射 | 004 + 005 |
| 新增/删除数据库表 | 004 + 005 |
| 新增/删除路由页面或 API 路由 | 004 + 005 |
| 修改模块间依赖关系 | 004 + 005 |
| 新增模块 | 004 + 005 + 006 |

### 14.3 可交付物清单

- 源代码仓库（完整提交历史）
- CI/CD 配置文件（`.gitea/workflows/`）
- 数据库迁移脚本（`drizzle/`）
- 环境配置模板（`.env.example`）
- 测试报告与覆盖率数据
- 安全扫描报告（`scripts/security-scan.sh`）
- 运维手册（`docs/dr/`、`scripts/backup-*.sh`）

---

## 十五、统一工具配置

### 15.1 ESLint（当前配置 + 建议增强）

**当前配置**（`eslint.config.mjs`）：

```javascript
import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTs from "eslint-config-next/typescript";

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  {
    rules: {
      "react-hooks/incompatible-library": "off",
    },
  },
  // ...
]);

export default eslintConfig;
```

**建议增强**（待逐步集成）：

```javascript
{
  extends: [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:jsx-a11y/recommended",
    "prettier"
  ],
  rules: {
    "@typescript-eslint/no-explicit-any": "error",
    "react/react-in-jsx-scope": "off",
    "react/function-component-definition": [2, { "namedComponents": "function-declaration" }],
    "import/order": ["error", {
      "groups": ["builtin", "external", "internal", "parent", "sibling", "index", "type"],
      "newlines-between": "always"
    }]
  }
}
```

### 15.2 Prettier

**当前配置**（`.prettierrc`）：

```json
{
  "semi": false,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "arrowParens": "always",
  "plugins": ["prettier-plugin-tailwindcss"]
}
```

### 15.3 lint-staged（建议配置）

```json
{
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,scss}": ["prettier --write"]
}
```

---

## 十六、代码审查清单

审查者必须逐一确认：

### 16.1 架构与设计

- [ ] 命名表意清晰，无歧义
- [ ] 类型安全：无 `any`，无多余断言
- [ ] 组件拆分合理，无巨型组件（>500 行需讨论，>800 行必须拆分）
- [ ] 单一职责：每个文件/函数/组件只做一件事
- [ ] 模块封装：无跨模块直接 DB 查询（通过 data-access 通信）

### 16.2 实现质量

- [ ] 使用 Tailwind 正确，设计令牌符合主题，无任意值
- [ ] 数据获取：客户端用 TanStack Query，服务端用 data-access
- [ ] Server Actions 有权限校验（`requirePermission`），输入 Zod 验证，返回 `ActionState`
- [ ] 错误边界完善：`error.tsx`, `loading.tsx`, 网络异常处理
- [ ] 可访问性：焦点、键盘、ARIA、对比度

### 16.3 安全与合规

- [ ] 无 XSS 风险（无 `dangerlySetInnerHTML`）
- [ ] Cookie 安全（httpOnly + Secure + SameSite）
- [ ] 环境变量未泄露（服务端变量无 `NEXT_PUBLIC_` 前缀）
- [ ] 权限校验到位（前端 `usePermission`，后端 `requirePermission`）

### 16.4 测试与文档

- [ ] 关键逻辑有单元测试，交互有组件测试
- [ ] 新增组件有 Storybook（如适用）
- [ ] 复杂逻辑有注释
- [ ] 架构文档已同步更新（004 + 005）
- [ ] 提交信息规范，无无关文件混入

---

## 附录：与原规范的差异说明

本规范基于通用 Next.js 企业级规范适配，主要差异：

| 项目 | 通用规范 | 本项目 | 原因 |
|------|---------|-------|------|
| 项目结构 | Monorepo (Turborepo) | 单应用 + 模块化 | 项目规模适中，模块化已满足需求 |
| 数据获取层 | `services/` | `modules/[module]/data-access.ts` | 模块封装更好，避免跨模块直查 DB |
| 中间件 | `middleware.ts` | `proxy.ts` | Next.js 16 重命名 |
| 组件行数限制 | 300 行 | 500 行（硬上限 800） | 企业级 K12 系统表单/表格较复杂 |
| Actions 行数限制 | 无 | 800 行（硬上限 1000） | 编排层包含权限+验证+调用，需更多空间 |
| Tailwind 配置 | `tailwind.config.ts` 扩展 | CSS 变量（Tailwind v4） | Tailwind v4 推荐方式 |
| ActionState | `ActionResult<T>` 联合类型 | `ActionState<T>` 对象类型 | 已有实现，保持兼容 |
| 状态管理 | Zustand + Context | Zustand + Context + nuqs | URL 状态用 nuqs 更适合 Next.js |
| 环境变量校验 | Zod 自定义 | `@t3-oss/env-nextjs` + Zod | 已实现，更简洁 |