# 团队共同开发规范

## 1. 基本原则
所有代码、接口、配置、任务进度均以仓库为准。禁止直接在主分支上试验性开发；禁止提交真实密钥、个人数据、未经授权的数据集。每个任务有负责人、验收条件和关联 Issue。

## 2. 分支管理
- `main`：稳定可演示版本，仅通过合并请求更新。
- `dev`：阶段集成分支（创建后使用）。
- `feat/<模块>-<描述>`：新功能，如 `feat/backend-knowledge-api`。
- `fix/<描述>`：修复；`docs/<描述>`：文档；`test/<描述>`：测试。

从最新 `dev` 拉分支，完成后发 Pull Request（Gitea 可称合并请求），禁止覆盖他人提交或强制推送共享分支。初次初始化仓库时允许负责人向空仓库推送 `main`。

## 3. 提交信息
使用 `feat: ...`、`fix: ...`、`docs: ...`、`refactor: ...`、`test: ...`、`chore: ...`，例如 `feat: add knowledge CRUD API`。一次提交只处理一个相对独立的主题。

## 4. 合并请求与代码审查
合并前说明：需求/Issue、改动范围、测试命令及结果、截图（界面改动）、数据库变更、风险和回滚方式。至少一位非作者成员审查；无成员可审查时由负责人确认并记录。发现冲突先沟通，不直接覆盖。

## 5. 前后端协作
- 所有接口以 `/api` 开头；Pydantic 定义输入输出模型。
- 接口字段命名使用 `snake_case`，日期使用带时区的 ISO 8601；错误响应明确错误原因。
- 新增接口须同步更新 OpenAPI 文档和前端调用层。
- 前端不直接连接数据库、不保存服务端 API 密钥。
- 使用 `.env.example` 记录变量名称，真实 `.env` 不入库。

## 6. 数据与知识质量
- 知识须记录标题、分类、正文、来源、采集/核验时间、审核状态。
- 未审核资料不得进入正式检索；网络搜索结果不自动等于可靠事实。
- 模型向量按 `model/version/dimension` 管理，更新用后台任务和版本切换。
- 测试数据与演示数据明确区分；禁止编造论文实验结果。

## 7. 完成定义（DoD）
代码能启动、主要功能有测试或可复现验收步骤、无明文密钥、文档同步、合并请求审查通过，才视为完成。

## 8. 沟通与任务
优先在 Gitea Issues 记录任务；每周更新已完成/阻塞/下一步。技术选型变更先在 `docs/DECISIONS.md` 留痕。公共接口或数据库结构变更必须提前通知前后端负责人。