NextEdu/CONTRIBUTING.md

贡献指南

感谢参与本项目！请遵循以下规范提交贡献。

开发环境准备

# 1. 安装依赖
npm install

# 2. 准备环境变量
cp .env.example .env
# 编辑 .env 填入实际配置

# 3. 初始化数据库
npm run db:push

# 4. 启动开发服务器
npm run dev

强制工作流程

所有代码改动前必须先查阅架构文档：

1. 阅读 docs/architecture/004_architecture_impact_map.md 了解架构设计意图
2. 运行 npm run arch:scan 更新 arch.db
3. 运行 npm run arch:query -- module-deps 查目标模块依赖
4. 阅读 src/modules/[模块]/README.md 了解模块工作流程
5. 查 docs/troubleshooting/known-issues.md 读相关经验

代码改动后必须：

1. 运行 npx tsc --noEmit 确保零错误
2. 运行 npm run lint 确保零错误
3. 运行 npm run arch:scan 更新 arch.db
4. 若架构设计意图变化，同步更新 004 文档
5. 若发现新场景→技术映射，更新 known-issues.md

提交规范

Conventional Commits 格式

<type>(<scope>): <description>

[optional body]

[optional footer]

类型（type）：

• feat: 新功能
• fix: Bug 修复
• docs: 文档变更
• style: 代码格式（不影响功能）
• refactor: 重构（既不是新功能也不是修复）
• test: 测试相关
• chore: 构建/工具/依赖变更
• perf: 性能优化
• ci: CI/CD 变更

示例：

feat(arch-scan): add @public JSDoc tag exemption mechanism
fix(permissions): fix parent module 6 Action permission violations
refactor: split 5 oversized files into domain-specific subfiles
docs(architecture): rewrite 004 as architecture design document

提交前检查

husky + lint-staged 会在 git commit 时自动执行：

• ESLint 检查暂存文件
• Prettier 格式化暂存文件
• commitlint 校验 commit message 格式

如果检查失败，请修复后重新提交。

架构约束

严格三层架构

app → modules → shared

• app/ 只能调用 modules/ 的 Server Actions 和 data-access
• modules/ 之间通过对方 data-access 通信，不直接查询对方 DB 表
• shared/ 不得反向依赖 modules/* 或 app/*

代码质量规则

• 禁止 any，未知类型用 unknown + 类型守卫
• 禁止 as 断言（除非从 unknown 转换，需注释原因）
• 函数返回值必须显式标注，特别是 Promise<T>
• 仅用于类型的导入使用 import type
• Server Action 必须调用 requirePermission()（或加 @public 标记豁免）
• 前端权限检查使用 usePermission().hasPermission()，禁止 role === "xxx" 硬编码
• 单文件行数：组件 ≤500，actions/data-access ≤800，硬限 1000

设计令牌规范

• 禁止硬编码颜色（#hex），使用 hsl(var(--*)) 或 Tailwind 类
• 禁止硬编码字体（'Inter'），使用 var(--font-family-*)
• 禁止 Tailwind 任意值（w-[137px]），映射到 --space-* 或默认阶梯

文档同步

需要同步架构图的场景

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

同步方式

• 修改源码后运行 npm run arch:scan 更新 arch.db（强制）
• 若架构设计意图变化，同步更新 docs/architecture/004_architecture_impact_map.md
• 若发现新"场景→技术"映射，更新 docs/troubleshooting/known-issues.md

问题报告

• 构建/lint/tsc 报错 → 记录到 docs/troubleshooting/known-issues.md "全局经验"分区
• 运行时异常 → 记录到"模块经验"分区
• 框架/库版本兼容问题 → 记录到"全局经验: Next.js 配置与运行时"