docs: add pr collaboration guidelines

Author: cat0825

.github/pull_request_template.md

@@ -0,0 +1,56 @@
+## 这次 PR 是做什么
+
+请用几句话说明这个 PR 的目的。
+
+示例：修复资源发布表单没有校验，导致空内容也能发布的问题。
+
+## 改了什么
+
+- 
+- 
+- 
+
+## 提交方自检
+
+- [ ] 我确认这个 PR 只做一件事，没有混入无关修改。
+- [ ] 我已经本地运行过相关功能。
+- [ ] 我已经运行 `npm test`，或说明了为什么不需要跑。
+- [ ] 我已经运行 `npm run lint`，或说明了为什么不需要跑。
+- [ ] 我已经运行 `npm run build`，或说明了为什么不需要跑。
+- [ ] 如果改了 UI，我已经附上截图或录屏。
+- [ ] 如果改了数据库，我已经更新 `supabase-schema.sql` 并写清楚线上需要执行什么 SQL。
+- [ ] 如果新增环境变量，我已经更新 README 或部署文档。
+- [ ] 我没有提交 `.env.local`、密钥、token、service role key。
+
+## 截图或录屏
+
+如果改了页面、样式、交互，把截图放在这里。
+
+## 数据库 / 环境变量 / 部署影响
+
+请选择并填写：
+
+- 数据库：无 / 有，说明：
+- 环境变量：无 / 有，说明：
+- 部署影响：无 / 有，说明：
+
+## 我是怎么测试的
+
+写清楚你实际做过的测试，不要只写“已测试”。
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+手动测试步骤：
+
+1. 
+2. 
+3. 
+
+## 需要维护者重点看的地方
+
+- 
+- 

CONTRIBUTING.md

@@ -0,0 +1,264 @@
+# Research Hub 协作与 PR 规范
+
+这个仓库的代码修改统一走 Pull Request。不要直接往 `main` 推代码。
+
+PR 的目的不是增加麻烦，而是让每一次改动都能被看见、被测试、能回退。只要影响网站代码、数据库结构、登录、发布、上传、部署配置，都必须走 PR。
+
+## 什么情况需要提交 PR
+
+需要提交 PR：
+
+- 修改页面、样式、交互、组件。
+- 修 bug。
+- 新增功能，比如资源发布、文章发布、PDF 上传、评论回复。
+- 修改 API、数据库 schema、权限规则。
+- 修改依赖、构建脚本、部署配置。
+- 修改文档、README、协作规范。
+
+不需要提交 PR：
+
+- 只是在网站里正常发布一篇文章。
+- 只是在网站里正常发布一个资源。
+- 只是在评论区回复别人。
+
+内容创作走网站功能。代码和配置修改走 GitHub PR。
+
+## 提交方应该怎么做
+
+### 1. 先拿到最新代码
+
+如果你是仓库成员：
+
+```bash
+git checkout main
+git pull origin main
+```
+
+如果你不是仓库成员，先 Fork 仓库，再从自己的 Fork 创建分支。
+
+### 2. 创建一个清楚的分支名
+
+分支名要让别人一眼看懂你在改什么。
+
+推荐格式：
+
+```bash
+git checkout -b feat/article-editor
+git checkout -b fix/empty-resource-validation
+git checkout -b docs/pr-rules
+git checkout -b chore/update-deps
+```
+
+常用前缀：
+
+- `feat/`：新功能。
+- `fix/`：修 bug。
+- `docs/`：文档。
+- `style/`：只改样式。
+- `refactor/`：重构，不改变功能。
+- `chore/`：依赖、脚本、配置。
+
+### 3. 本地跑起来再改
+
+```bash
+npm ci
+npm run dev
+```
+
+本地地址：
+
+```text
+http://localhost:3001
+```
+
+如果需要登录、数据库、上传功能，先配置 `.env.local`。不要把 `.env.local`、密钥、token、service role key 提交到 GitHub。泄露密钥是低级错误，别干。
+
+### 4. 控制 PR 范围
+
+一个 PR 只做一件事。
+
+正确示例：
+
+- 只修“空表单也能发布”的校验问题。
+- 只新增“评论回复”功能。
+- 只新增“PR 协作规范”文档。
+
+错误示例：
+
+- 一个 PR 同时改登录、上传、首页 UI、数据库和 README。
+- 顺手格式化全仓库文件。
+- 改了很多无关文件，但 PR 里不解释。
+
+范围越小，越容易 review，也越容易合并。
+
+### 5. 改数据库时必须说明
+
+如果你改了数据库结构，必须同时做这些事：
+
+- 更新 `supabase-schema.sql`。
+- 在 PR 里写清楚新增或修改了哪些表、字段、索引、权限。
+- 说明线上是否需要手动执行 SQL。
+- 说明旧数据会不会受影响。
+
+只改代码不改 schema，最后线上炸掉，这种 PR 不合格。
+
+### 6. 提交前先自测
+
+提交 PR 前至少跑：
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+如果你只改了文档，可以说明“只改文档，未跑构建”。
+
+如果你改了页面或交互，PR 里必须放截图。移动端有明显变化时，也要放移动端截图。
+
+### 7. 写清楚 PR 内容
+
+PR 描述必须包含：
+
+- 为什么要改。
+- 改了什么。
+- 怎么测试的。
+- 是否影响数据库、环境变量、部署。
+- 是否有截图或录屏。
+- 还有什么风险。
+
+不要只写“fix bug”“update”“优化一下”。这种描述没有 review 价值。
+
+### 8. Review 后怎么处理
+
+维护者提出修改意见后，提交方应该：
+
+- 在同一个分支继续提交 commit。
+- 回答每一条关键问题。
+- 改完后重新跑必要检查。
+- 如果不同意 review 意见，说明原因，不要沉默。
+
+不要开一个新 PR 来逃避旧 PR 的 review。
+
+## 维护者应该怎么做
+
+维护者就是仓库负责人或有合并权限的人。
+
+### 1. 先看 PR 是否合格
+
+先检查：
+
+- 标题是否清楚。
+- 描述是否说明了目的、改动、测试结果。
+- 是否有无关文件。
+- 是否有截图。
+- 是否提到数据库或环境变量影响。
+
+描述不清楚就要求补充，不要急着看代码。
+
+### 2. 优先看风险点
+
+Review 时重点看：
+
+- 表单是否有校验，不能再出现空内容也能发布。
+- 登录态和权限是否正确。
+- 用户输入是否可能破坏页面或数据。
+- API 是否处理错误情况。
+- 数据库 schema 是否和代码一致。
+- 上传文件是否限制类型和大小。
+- 移动端布局是否能正常使用。
+- 是否泄露密钥、token、数据库连接信息。
+
+样式细节可以讨论，但安全、数据、权限问题必须优先。
+
+### 3. 本地或预览环境验证
+
+维护者至少选择一种方式验证：
+
+- 拉到本地运行。
+- 使用 Vercel Preview 查看。
+- 对纯文档 PR 直接读 diff。
+
+涉及功能修改时，建议本地跑：
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+如果 PR 涉及数据库，先在测试 Supabase 项目里执行 SQL，确认不会破坏线上数据。
+
+### 4. 如何给 review 意见
+
+Review 意见要具体：
+
+- 指出文件和位置。
+- 说明为什么有问题。
+- 给出可以执行的修改建议。
+
+不要只写“这里不行”“再优化一下”。这种意见没法执行。
+
+### 5. 合并前检查
+
+合并前确认：
+
+- PR 范围明确。
+- CI 通过。
+- 必要测试通过。
+- review 对话已解决。
+- 没有密钥泄露。
+- 数据库变更有说明。
+- UI 改动有截图。
+- 部署影响已确认。
+
+推荐使用 Squash merge，让 `main` 的历史保持干净。
+
+## 推荐的 GitHub 仓库设置
+
+建议给 `main` 分支开启保护规则：
+
+- 禁止直接 push 到 `main`。
+- 必须通过 PR 合并。
+- 至少 1 个维护者 review。
+- CI 必须通过。
+- 所有 review 对话必须解决。
+- 禁止 force push。
+- 禁止删除 `main`。
+
+这样其他人可以参与修改，但不会随便把线上版本改坏。
+
+## PR 标题建议
+
+标题用中文或英文都可以，但必须具体。
+
+推荐：
+
+```text
+fix: 修复资源空表单也能发布的问题
+feat: 新增文章发布入口
+docs: 新增 PR 协作规范
+chore: 更新 Vercel 部署说明
+```
+
+不推荐：
+
+```text
+update
+fix
+优化
+改了一些东西
+```
+
+## 最低合并标准
+
+一个 PR 至少要满足：
+
+- 解决了一个明确问题。
+- 没有引入明显回归。
+- 没有无关改动。
+- 本地检查或 CI 通过。
+- 描述能让别人看懂。
+- 需要人工操作的地方写清楚了。
+
+达不到这些标准，就不要合并。

README.md

@@ -40,6 +40,10 @@ npm run lint
 npm run build
 ```
 
+## Contributing
+
+All code, schema, configuration, and documentation changes should go through Pull Requests. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a PR.
+
 ## Vercel Deployment
 
 Production deployment now targets Vercel. The repository keeps a lightweight GitHub Actions CI workflow for tests, lint, and build checks only.