# 项目规则

## 架构图优先规则

**任何任务开始前，必须先查阅架构影响地图，通过图定位代码和模块。**

1. **先图后码**：执行任何分析、修改、搜索任务时，首先阅读 `docs/architecture/004_architecture_impact_map.md` 或 `docs/architecture/005_architecture_data.json`，从图中定位目标模块、函数、依赖关系，再按图索骥读取源码
2. **图未覆盖则先补图**：如果发现项目中存在架构图未记录的模块、函数、表、路由等，**必须优先完善架构图信息**，然后再继续后续工作
3. **改码必同步图**：对源码的任何修改完成后，必须同步更新 004 和 005 两个架构文档

### 架构文档清单

| 文档 | 用途 |
|------|------|
| `docs/architecture/004_architecture_impact_map.md` | 人类可读的架构影响地图 |
| `docs/architecture/005_architecture_data.json` | AI 友好格式的结构化数据 |
| `docs/architecture/006_k12_feature_checklist.md` | 标准功能模块清单 |
| `docs/architecture/007_gap_audit_report.md` | 差距审计报告 |
| `docs/architecture/audit/01_decoupling_roadmap.md` | 解耦路线图 |

### 需要同步图的场景

- 新增/删除/重命名导出函数、组件、Hook、类型
- 修改函数签名（参数、返回类型）
- 修改权限点（Permissions 常量）或角色-权限映射
- 新增/删除数据库表
- 新增/删除路由页面或 API 路由
- 修改模块间依赖关系
- 新增模块

### 同步方式

- 修改 Markdown 文档中对应的模块章节
- 修改 JSON 文档中对应的节点（`modules.*.exports`、`permissions`、`dependencyMatrix`、`routes`、`dbTables` 等）
- 确保两个文档内容一致

## 编码规范

**详细规范见 `docs/standards/coding-standards.md`，以下为核心强制规则。**

### 代码质量规则

- 每次修改后运行 `npm run lint` 和 `npx tsc --noEmit` 确保零错误
- Server Action 必须使用 `requirePermission()` 进行权限校验
- 前端组件禁止使用 `role === "xxx"` 硬编码，统一使用 `usePermission().hasPermission()`
- 单文件行数遵循企业级规范：
  - 配置文件、常量文件、类型定义文件：无限制
  - React 组件：建议 ≤ 500 行（复杂表单/大型表格可放宽至 800 行）
  - Server Actions / Data Access 模块：建议 ≤ 800 行
  - 工具函数：建议 ≤ 40 行
  - 自定义 Hook：建议 ≤ 80 行
  - 超过建议行数时应考虑拆分（如 data-access 拆分为多个按职责划分的文件）
  - 硬性上限：任何文件不超过 1000 行，超过必须拆分

### 架构分层规则

- 严格三层架构，依赖方向单向：`app → modules → shared`
- `app/` 只能调用 `modules/` 的 Server Actions 和 data-access，不直接访问 DB
- `modules/` 之间通过对方 data-access 通信，**不直接查询对方 DB 表**
- `shared/` 是被依赖方，**不得反向依赖** `@/auth`、`@/proxy` 或任何 `modules/*`

### 模块标准结构

```
src/modules/[module]/
├─ actions.ts              # Server Actions（编排层）
├─ data-access.ts          # 数据访问层（可拆分为 data-access-*.ts）
├─ schema.ts               # Zod 验证（可选）
├─ types.ts                # 类型定义
├─ components/             # 模块专属组件
└─ hooks/                  # 模块专属 Hook（可选）
```

### TypeScript 规则

- **禁止 `any`**：未知类型用 `unknown` 并做类型守卫
- **禁止 `as` 断言**（除非从 `unknown` 转换或测试中，需注释原因）
- **函数返回值必须显式标注**，特别是 `Promise<T>`
- **仅用于类型的导入必须使用 `import type`**
- **可选链后禁止跟非空断言 `!`**

### 命名规范

- 目录：kebab-case（`user-profile/`）
- 组件文件：PascalCase（`UserProfile.tsx`）
- Hook 文件：camelCase（`useAuth.ts`）
- 变量/函数：camelCase，布尔值用 `is/has/can/should` 前缀
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`）
- 类/接口：PascalCase，接口不加 `I` 前缀

### 组件规范

- 组件必须为纯函数，使用 `function` 声明
- 页面组件（`page.tsx`）使用默认导出；其余组件使用具名导出
- 默认服务端组件，需要交互时才添加 `"use client"`（必须位于文件第一行）
- **不使用 `React.FC`**，直接用函数声明 + 显式标注 props 类型

### Server Action 规范

- 每个 Action 必须调用 `requirePermission()` 进行权限校验
- 输入使用 Zod 验证，验证失败返回结构化错误
- 返回值统一采用 `ActionState<T>` 类型
- 使用 `revalidatePath` 精确刷新缓存

### Tailwind 规范

- 使用 `cn()` 工具函数管理条件类名
- **禁止**字符串拼接动态类名（`bg-${color}-500`）
- **禁止**使用任意值（`w-[137px]`），除非有充分理由并注释
- 设计令牌在 `src/app/globals.css` 中使用 CSS 变量定义

### 安全规范

- **禁止 `dangerlySetInnerHTML`**（如必须使用，先用 DOMPurify 清洗）
- JWT/session ID 存储在 httpOnly + Secure + SameSite=Strict 的 Cookie 中
- 服务端环境变量不加 `NEXT_PUBLIC_` 前缀
- 环境变量使用 `@t3-oss/env-nextjs` + Zod 校验（已实现于 `src/env.mjs`）

### 提交规范

- 使用 Conventional Commits 格式：`feat(scope): description`
- 类型：`feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `perf`, `ci`
- 提交前必须运行 `npm run lint` 和 `npx tsc --noEmit` 确保零错误