3.3 KiB
3.3 KiB
团队共同开发规范
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 留痕。公共接口或数据库结构变更必须提前通知前后端负责人。