214ebec976
Primitive + Semantic 双层令牌架构,HEX->HSL,明暗双份,@theme inline 暴露为 Tailwind 类。 - 新建 src/app/styles/tokens/ 6 个令牌文件(primitive/semantic-light/semantic-dark/lesson-preparation/tailwind-theme/index) - globals.css 改为 @import 引入,477->258 行 - 清理 91 处 #hex 硬编码颜色 -> hsl(var(--*)) - 清理 10 处硬编码字体 -> var(--font-family-*) - 清理 100 文件 Tailwind 任意值(Tier 1 映射/Tier 3 注释豁免) - 清理 M3 Surface 死代码,升级 --lp-* 令牌(HEX->HSL + 暗色补全) - 新建 ESLint 自定义规则 no-hardcoded-design-tokens(单词边界正则) - eslint.config.mjs 新增 no-restricted-syntax 禁止 #hex + 自定义规则加载(pathToFileURL) - 项目规则新增设计令牌规范强制章节 - 架构图 004/005 同步设计令牌体系节点 - known-issues.md 追加设计令牌问题分类(7 个规则表) 验证: tsc --noEmit 0 errors, npm run lint 0 errors/12 warnings(均为既有问题)
180 lines
8.4 KiB
Markdown
180 lines
8.4 KiB
Markdown
# 项目规则
|
||
|
||
## 架构图优先规则
|
||
|
||
**任何任务开始前，必须先查阅架构影响地图，通过图定位代码和模块。**
|
||
|
||
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/styles/tokens/` 目录中分层定义,通过 `@theme inline` 暴露为 Tailwind 类
|
||
|
||
### 设计令牌规范（强制）
|
||
|
||
- **禁止硬编码颜色**: TSX/TS/CSS 中不得出现 `#hex` 颜色字面量,统一使用 `hsl(var(--*))` 或 Tailwind 类 `bg-*`
|
||
- **禁止硬编码字体**: 不得出现 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量,使用 `var(--font-family-sans/serif/mono)`
|
||
- **禁止硬编码字号**: 不得出现 `font-size: Npx`,使用 `var(--font-size-1~9)`
|
||
- **禁止 Tailwind 任意值**: 不得使用 `w-[Npx]`/`h-[Npx]`/`p-[Npx]` 等,映射到 `--space-*` 或 Tailwind 默认阶梯
|
||
- **豁免场景**（需 `// eslint-disable-next-line no-restricted-syntax -- <reason>` 注释）:
|
||
- PWA manifest（`src/app/manifest.ts`）
|
||
- 邮件 HTML 内联样式（`src/modules/notifications/channels/email-channel.ts`）
|
||
- 图表 SVG 固定画布尺寸（recharts 选择器中的 `#ccc`/`#fff`）
|
||
- loading.tsx 占位骨架
|
||
- Dialog 固定宽度等无法令牌化的设计固定尺寸
|
||
- **令牌文件分布**: `src/app/styles/tokens/`（primitive/semantic-light/semantic-dark/lesson-preparation/tailwind-theme/index）
|
||
- **令牌分层**:
|
||
- Layer 1 Primitive（`primitive.css`）:原始色板/字号/间距/阴影,业务代码不直接引用
|
||
- Layer 2 Semantic（`semantic-light.css` + `semantic-dark.css`）:语义令牌,业务代码唯一引用入口
|
||
- 模块命名空间（`lesson-preparation.css`）:`--lp-*` 令牌,明暗双份
|
||
- Tailwind 暴露（`tailwind-theme.css`）:`@theme inline` 将 Semantic 令牌暴露为 `bg-*`/`text-*`/`font-*` 类
|
||
- **改令牌必同步图**: 修改令牌定义后,同步更新 `docs/architecture/004` 与 `005`
|
||
- **ESLint 强制约束**:
|
||
- `no-restricted-syntax`: 禁止 `#hex` 字面量
|
||
- `design-tokens/no-hardcoded-fonts`: 禁止 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量（单词边界匹配,不影响 `Interval`/`Interactive` 等标识符）
|
||
- 白名单:`primitive.css`（令牌定义）、`email-channel.ts`（邮件 HTML）、`manifest.ts`（PWA）
|
||
|
||
### 安全规范
|
||
|
||
- **禁止 `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` 确保零错误
|
||
|
||
## 问题记录规则
|
||
|
||
**所有工作完成后，必须将遇到的问题记录到 `docs/troubleshooting/known-issues.md`（速查手册格式）。**
|
||
|
||
### 必须记录的场景
|
||
|
||
| 场景 | 记录要求 |
|
||
|------|---------|
|
||
| 构建报错（dev/build/lint/tsc） | 记录错误现象 + 正确写法 |
|
||
| 运行时异常（白屏/API 报错/数据加载失败） | 记录错误现象 + 正确写法 |
|
||
| 框架/库版本兼容问题 | 记录错误现象 + 正确写法 |
|
||
| 依赖配置问题（serverExternalPackages/webpackIgnore 等） | 记录错误现象 + 正确写法 |
|
||
| 架构约束违规 | 记录错误现象 + 正确写法 |
|
||
|
||
### 记录格式
|
||
|
||
以**规则表**形式记录，指明正确做法，无需详细解释原因：
|
||
|
||
```markdown
|
||
## 问题分类标题
|
||
|
||
| 规则 | 正确写法 | 错误写法 |
|
||
|------|---------|---------|
|
||
| 简述规则 | 代码示例 | 代码示例 |
|
||
```
|
||
|
||
### 记录要求
|
||
|
||
- **速查手册风格**：只指明方向，不做新手指导
|
||
- **去重**：同类问题在原条目补充，不重复创建
|
||
- **可操作**：正确写法需具体到代码示例
|