23 lines
2.2 KiB
Markdown
23 lines
2.2 KiB
Markdown
# KF-OnlineJudge 工程约定
|
||
|
||
按现有模块边界扩展。本地存在 `docs/ENGINEERING.md` 和 `docs/DEVELOPMENT.md` 时先阅读；开发文档不在远端仓库中。
|
||
|
||
- 本机 `docs` 使用共享目录链接，Windows 和 CachyOS 使用同一份共享文档；实际目标由 `readlink docs` 确认。不创建另一份同步副本，不把源码、依赖或构建产物写回共享目录。
|
||
- `docs/` 中的开发文档仅保留本地，不加入 Git 提交，不推送到 Gitea；不得用 `git add -f` 绕过忽略规则。
|
||
- 分支采用 `feat/`、`fix/`、`chore/`、`perf/`、`test/` 等工程前缀，提交采用 Conventional Commits；不添加工具名称前缀或工具署名。
|
||
- 本仓库提交身份使用 `kronecker <2026692687@qq.com>`。
|
||
- 后端固定 Python 3.13.16，由 uv 管理；不要改用系统 Python 3.14 或用 uvx 运行项目服务。
|
||
- 在本机原生文件系统中开发，使用仓库根目录 Makefile；Python 环境为 `backend/.venv`，Rust 构建产物为 `judge/target`。
|
||
- 平台为模块化单体；业务域之间通过 `public.py` 调用，不直接操作其他模块的 ORM/repository。
|
||
- Runtime 通过注入端口调用业务工具；不导入业务模块或具体基础设施实现。
|
||
- Rust crate 依赖方向与 Python 分层由 `scripts/check_architecture.py` 检查。新增边界须同步更新架构说明与检查规则。
|
||
- 跨服务协议变更先更新模型和共享样例，运行 `make contracts`，保留 Python/Rust 的兼容验证。
|
||
- 数据库迁移只由后端 Alembic 管理；协调器控制执行状态，判题 Worker 不直接写评测数据库。
|
||
- 沙箱未验证隔离前拒绝执行；不得用直接运行宿主命令作为临时判题实现。
|
||
- 只建立当期需要的接口和实现；未实现能力明确报告，不提供模拟成绩或虚假任务成功状态。
|
||
- 使用项目锁文件；新增依赖说明职责。凭据、私有代码和隐藏测试数据不进入仓库。
|
||
|
||
按变更运行 `make check-backend`、`make check-judge`、`make check-frontend` 和 `make architecture`。
|
||
跨工程骨架或契约改动运行完整 `make check`，记录实际通过项和未验证的能力。
|
||
沙箱的权限、隔离、超限和破坏性测试单独在规定执行环境验证。
|