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:
SpecialX
2026-06-17 22:54:29 +08:00
parent ee517f2b33
commit 02dc1093fb
5 changed files with 960 additions and 1 deletions

View File

@@ -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` 确保零错误