130 lines
3.7 KiB
Markdown
130 lines
3.7 KiB
Markdown
# 贡献指南
|
||
|
||
感谢参与本项目！请遵循以下规范提交贡献。
|
||
|
||
## 开发环境准备
|
||
|
||
```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 配置与运行时"
|