# 贡献指南

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

## 开发环境准备

```bash
# 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 配置与运行时"