docs: 适配企业级编码规范并补充配置
- 新增 docs/standards/coding-standards.md 编码规范文档(16 章节) - 适配当前项目: 单应用+模块化架构(非 Monorepo) - 保留 data-access.ts 模式(非 services/) - 使用 proxy.ts(Next.js 16 重命名) - 保留企业级行数规范(组件 500/800, Actions 800/1000) - 保留 Tailwind v4 CSS 变量设计令牌 - 保留 ActionState<T> 类型 - 含"与原规范的差异说明"附录(10 项差异及原因) - 更新 .trae/rules/project_rules.md: - 新增编码规范章节, 引用 coding-standards.md - 新增架构分层/模块结构/TS规则/命名/组件/Action/Tailwind/安全/提交规范 - 架构文档清单新增解耦路线图 - 新增 .prettierrc 配置(匹配现有代码风格: 双引号/无分号/2空格) - 更新 docs/README.md 新增编码规范章节 - 更新 work_log
This commit is contained in:
@@ -16,6 +16,7 @@
|
||||
| `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` | 解耦路线图 |
|
||||
|
||||
### 需要同步图的场景
|
||||
|
||||
@@ -33,7 +34,11 @@
|
||||
- 修改 JSON 文档中对应的节点(`modules.*.exports`、`permissions`、`dependencyMatrix`、`routes`、`dbTables` 等)
|
||||
- 确保两个文档内容一致
|
||||
|
||||
## 代码质量规则
|
||||
## 编码规范
|
||||
|
||||
**详细规范见 `docs/standards/coding-standards.md`,以下为核心强制规则。**
|
||||
|
||||
### 代码质量规则
|
||||
|
||||
- 每次修改后运行 `npm run lint` 和 `npx tsc --noEmit` 确保零错误
|
||||
- Server Action 必须使用 `requirePermission()` 进行权限校验
|
||||
@@ -42,5 +47,77 @@
|
||||
- 配置文件、常量文件、类型定义文件:无限制
|
||||
- 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` 确保零错误
|
||||
|
||||
Reference in New Issue
Block a user