docs(platform): describe controlled judging startup and recovery

backend/.env.example

@@ -1,7 +1,15 @@
 KF_OJ_ENVIRONMENT=development
 KF_OJ_LOG_LEVEL=INFO
-# Optional until database-backed use cases are implemented.
+# Dedicated platform login inherits only kf_oj_platform; replace development credentials.
 KF_OJ_DATABASE_URL=postgresql+asyncpg://kf_oj:local-dev-only@127.0.0.1:5432/kf_oj
 KF_OJ_AMQP_URL=amqp://kf_oj:local-dev-only@127.0.0.1:5672/kf_oj
-KF_OJ_BROWSER_ORIGINS='["http://localhost:5173","http://localhost:8000"]'
+KF_OJ_BROWSER_ORIGINS='["http://localhost:5173","http://localhost:8000","http://127.0.0.1:5173","http://127.0.0.1:8000"]'
 KF_OJ_SESSION_LIFETIME_SECONDS=43200
+# Required for submissions: private absolute artifact root and trusted JSON admission policy.
+# KF_OJ_ARTIFACT_ROOT=/srv/kf-platform/artifacts
+KF_OJ_ARTIFACT_MAX_BYTES=536870912
+KF_OJ_ARTIFACT_MAX_FILES=4096
+# KF_OJ_JUDGE_ADMISSION=<JSON matching the Coordinator and Worker policy>
+# Cancellation requires both; token equals Coordinator platform_token, never a Worker token.
+# KF_OJ_COORDINATOR_URL=http://127.0.0.1:8100
+# KF_OJ_COORDINATOR_TOKEN=<privately generated 64 lowercase hexadecimal characters>

backend/README.md

@@ -17,7 +17,7 @@ make worker-check
 
 API 提供存活、真实登录/退出/当前用户、公开题目与有效 Worker 租约的清单/工件读取。
 配置数据库后在 lifespan 内组合模块，配置缺失时业务端口明确不可用，存活接口仍可用。
-Worker 目前仅支持 `--check`，默认拒绝进入尚未实现的任务循环。
+学习 Worker 目前仅支持 `--check`；Rust 判题 Worker 使用单独的常驻消费入口。
 提交创建 API 在持久化源码后，同一事务写入初始评测和 outbox；按用户与幂等键
 防止重复创建，待评测总量和个人待评测数有固定上限。
 
@@ -28,7 +28,18 @@ Worker 目前仅支持 `--check`，默认拒绝进入尚未实现的任务循环
 队列最多 64 条、32 KiB，拒绝溢出，消息有效期 10 分钟；broker 不可用采用有界退避，
 不阻塞提交事务。日志仅固定错误代码，不打印源码、答案或连接口令。
 后台每次投递最多 12 秒，关闭连接最多 2 秒，SIGTERM 在当前有界操作结束后退出。
-账号/题目/工件命令及限制见对应模块 README，前端成绩读取与模型接入尚未实现。
+账号/题目/工件命令及限制见对应模块 README；模型能力尚未接入。
+
+个人提交查询 `/api/v1/submissions` 使用 `(created_at,id)` 降序游标，最多100条；
+`/{id}`、`/{id}/source` 仅允许提交本人读取，统一拒绝外来/不存在记录。
+成绩投影不包含租约、工件摘要、隐藏用例 ID/输入/答案或程序输出；编译诊断至多64KiB，
+缺失计量保留 null，未完成报告不展示成绩。身份/提交/内部响应均为 no-store。
+`POST /{id}/cancel` 验证本人、Origin、会话和 CSRF，再调用 Coordinator 接受取消；
+202仅表示已持久化意图，实际停止与资源回收由执行服务确认。
+配置 `KF_OJ_COORDINATOR_URL` 为数值 loopback HTTP origin，
+`KF_OJ_COORDINATOR_TOKEN` 与私有 Coordinator 的 `platform_token` 一致；
+缺少配置或通信失败返回503，不直接修改执行状态。新增运行依赖 `httpx` 仅负责这个
+3秒有界控制调用，禁用代理/重定向，不缓存或打印远端响应及内部凭据。
 
 Python 虚拟环境位于 `backend/.venv`，可在 `backend/` 直接使用 `uv sync --locked` 和 `uv run --locked`。
 数据库由 Alembic 唯一管理；业务模型在 `migrations/env.py` 中显式登记元数据。

backend/src/kf_oj/modules/submissions/README.md

@@ -3,7 +3,10 @@
 负责提交幂等请求、不可变源码引用、创建初始评测、历史查询与学生可见结果。
 创建提交、评测和待投递事件必须处于同一事务。
 协调器拥有领取后的执行状态与最终结果写入权；本模块不能绕过协议覆盖终态。
-`queries.py` 提供已验证主体的私有源码读取，其他账号不可读取。
+`queries.py` 提供已验证主体的提交历史、详情与私有源码读取，其他账号不可读取；
+历史按创建时间/UUID降序游标翻页，一次至多100条。读取完整成绩时严格核对报告契约和
+评测绑定，仅投影允许公开的诊断/计量/测试点序号。取消通过注入的 Coordinator 控制
+端口接受意图，不更新执行状态；202与清理完成的终态不同。
 `worker_access.py` 核对当前 evaluation / attempt / Worker / fencing、未撤销及未过期凭证、
 固定 submission 与版本及任务清单摘要；只允许读取该清单声明的工件。
 内部 API 使用 WorkerLease bearer 和 X-Worker-ID / X-Fencing-Version，不使用用户会话授权。
@@ -14,5 +17,9 @@
 Python/Rust `manifest_bytes` 与共享字节样例保持一致；Coordinator 必须用同一序列化定义存快照。
 读取凭证与客户端提交的身份分开：身份和归属从实际数据库绑定获得，不接受客户端自报 user ID。
 
-当前只实现读取与授权基础。提交创建/幂等/outbox、Coordinator 正式 claim、报告及用户成绩
-查询仍在后续模块阶段，不能把测试数据库 fixture 的租约当作正式领取或实际执行证据。
+`service.py` 按账号与幂等UUID绑定版本/语言/源码摘要，持久化源码后同一事务创建
+submission、queued evaluation 和 outbox；同键同内容复用既有提交，不同内容409。
+待评测固定总量64、个人8，取消清理中也占用容量；配置或容量不足明确拒绝。
+Coordinator 通过正式 claim 创建短期领取权，Worker 不写业务数据库。
+真实服务链与安全条件必须在独立 VM 验收；数据库 fixture 的租约或合成报告只能
+验证控制规则、授权和投影，不能作为真实程序执行/停止证明。