46 lines
3.3 KiB
Markdown
46 lines
3.3 KiB
Markdown
# 团队共同开发规范
|
||
|
||
## 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、改动范围、测试命令及结果、截图（界面改动）、数据库变更、风险和回滚方式。至少一位非作者成员审查；无成员可审查时由负责人确认并记录。发现冲突先沟通，不直接覆盖。
|
||
|
||
### 审阅与合并权限
|
||
|
||
- 范涵宇、杨星萱完成工作后，必须从各自 `feat/...` 或 `docs/...` 分支向 `dev` 发起合并请求；作者不得自行合并。
|
||
- 吉海燕负责审阅范涵宇、杨星萱提交的合并请求。只有吉海燕明确批准后，才可合并到 `dev`。
|
||
- 吉海燕自己的前端分支由 Codex 在本项目对话中进行代码审阅。吉海燕须提供合并请求链接或差异；只有在 Codex 明确回复“批准合并”后，才可执行合并。Codex 不代替 Gitea 平台账号点击批准按钮。
|
||
- `dev` 合入 `main` 前，须完成对应阶段验收，并由吉海燕确认。任何成员不得直接向 `main` 推送功能改动。
|
||
- 审阅意见、测试结果与最终批准结论应保留在 Gitea 合并请求中，便于项目验收和软著材料追溯。
|
||
|
||
## 5. 前后端协作
|
||
- 所有接口以 `/api` 开头；Pydantic 定义输入输出模型。
|
||
- 接口字段命名使用 `snake_case`，日期使用带时区的 ISO 8601；错误响应明确错误原因。
|
||
- 新增接口须同步更新 OpenAPI 文档和前端调用层。
|
||
- 前端不直接连接数据库、不保存服务端 API 密钥。
|
||
- 使用 `.env.example` 记录变量名称，真实 `.env` 不入库。
|
||
|
||
## 6. 数据与知识质量
|
||
- 知识须记录标题、分类、正文、来源、采集/核验时间、审核状态。
|
||
- 未审核资料不得进入正式检索；网络搜索结果不自动等于可靠事实。
|
||
- 模型向量按 `model/version/dimension` 管理，更新用后台任务和版本切换。
|
||
- 测试数据与演示数据明确区分；禁止编造论文实验结果。
|
||
|
||
## 7. 完成定义（DoD）
|
||
代码能启动、主要功能有测试或可复现验收步骤、无明文密钥、文档同步、合并请求审查通过，才视为完成。
|
||
|
||
## 8. 沟通与任务
|
||
优先在 Gitea Issues 记录任务；每周更新已完成/阻塞/下一步。技术选型变更先在 `docs/DECISIONS.md` 留痕。公共接口或数据库结构变更必须提前通知前后端负责人。
|