lab-edu 项目宪法

本文件是 lab-edu 项目的最高规范，已评审通过生效（Ratified: 2026-08-28）。 宪法只声明方向与边界，不规定实现细节（无类名、无 SQL、无字段级设计）。

1. 定位与目标

  • 所有 Spec、设计文档、代码、配置不得与宪法冲突；冲突时以宪法为准。
  • 目标：保证跨仓库一致性——分层边界、权限归属、命名、文档与变更流程四仓库遵守同一套规则。
  • 实现细节由各 Spec 决定；宪法变更走第 7 节流程。

2. 系统架构与分层边界

仓库 职责 边界（不得越界）
web（Next.js） 纯展示与交互层，仅调用 core 的 REST API 不承载业务规则、状态机、校验、权限；不直连数据库
core（Spring Boot + Spring Security） 唯一业务入口：权限、数据读写、业务规则；对 web 暴露 REST API 不做 UI；不承担部署编排
infra（Docker） 部署编排、一键启动 不渗入业务逻辑，只解决"如何跑起来"
docs 唯一规格主仓库，编译文档站并发布 只放文档，不放代码

硬性边界规则：

  1. web 传来的数据一律视为不可信；服务端校验与权限判定由 core 完成。web 可做纯 UI 层提示（如表单必填），但不作为安全依据。
  2. infra 不含业务代码；不得以"编排需要"为由引入业务配置。
  3. 依赖方向固定：web → core →（中间件/数据库）；infra 编排三者；docs 独立。

3. 技术栈基线

已定（用户决策，不可更改）：

类别 强制约束 Rationale
core Spring Boot 3.x 当前最新稳定版（附所要求的 JDK LTS 版本）；鉴权 MUST 使用 Spring Security，禁止引入替代方案 Spring 生态原生、社区最成熟、团队已有经验围绕 Spring 生态
web Next.js 当前最新稳定版（App Router） 社区流行度高，满足"纯展示与交互"的定位
部署 infra 用 Docker（Compose v2）整合 单机 MVP 一键启动，K8s 等留后续阶段
管理后台 Refine CORE 5.x，使用官方 Next.js 路由适配与 Ant Design UI 适配，Ant Design 5.x；依据 admin-framework-proposal-001.md 复用通用资源界面与适配能力；core 保持唯一认证与授权入口。适配包各自主版本和精确组合在构建配置锁定，禁止未经验证混用 Ant Design 6.x
  • core 中间件与数据库 MUST 从 Spring 生态与 Spring 官方推荐体系中选择；确需生态外选型时，MUST 先提交变更提案（§7）并经评审通过，通过前不得使用。
  • 技术栈在立项时锁定小版本号，小版本号唯一权威在构建配置（pom.xml / package.json）；宪法只维护"版本基线 + 禁用搭配"，不复制小版本号。升级走 §7 变更流程。

4. 框架优先原则

  1. 凡有成熟框架/库可解决的问题，MUST 采用该框架/库，不自研；采用结论写入对应 Spec 或提案并附理由。凡未按本流程获准的自研或新引入依赖，视为违宪。
  2. 自研仅当无合适替代，或已有方案无法满足需求；须说明理由，并经评审通过方可实施。
  3. 选型评估维度：社区活跃度、维护状态、文档质量、学习成本、License 兼容性。

5. 设计原则与裁决

原则是项目的裁决者（Tie-Breaker）：当 AI、方案或个人偏好与原则冲突时，以原则为准。

  • KISS：默认选改动面最小、概念最少的方案；两个等价方案取更简单者。文档亦同。
  • 裁决：当"更简单"与"更全面"冲突时，选更简单。
  • YAGNI：每个新模块、新抽象、新配置必须挂靠一个当前范围（或已批准提案）内的具体需求；挂不上的不写、不引入。第 8 节为范围红线。
  • 裁决：当"现在做"与"以后做"冲突时，往后放。
  • DRY：业务规则只在 core 定义一次，web 不复制；通用能力优先沉淀为框架/库/共享代码，而非复制粘贴。
  • 裁决：同一事实存在多个权威来源时，保留核心处，其余改为引用。
  • 文档语言：项目主语言为中文——规范、Spec、plan、代码注释与提交信息以中文为准，专有术语保留原文并附语义说明。
  • 裁决：当 AI 工具默认语言、个人偏好与本条冲突时，MUST 选择中文。
  • 质量底线：认证、授权、会话管理相关代码 MUST 包含单元测试；新代码不得使既有测试失败。
  • 裁决：当"加快交付"与"测试完整性"冲突时，MUST 选择测试完整性。

6. 文档与规范治理

  • docs/specs/：正式规范。仅收录评审通过的文件，评审通过后生效，是唯一权威来源。
  • docs/agents/：子 Agent 草稿/过程产物，与正式文档隔离；评审通过前不得进入 specs/。
  • 命名约定、Spec 模板、API 路径规则、开发工作流规范等规范细则的唯一权威在 docs/specs/CONTRIBUTING.md；任何 Spec 不得另立规则（DRY）。规范细则变更随宪法评审走第 7 节。

7. 变更规则

  • 宪法地位：本宪法为项目最高治理协议，优先级高于一切 Spec、模板、工具约定与个人偏好。任何 AI / Agent 不得自动生成、修改、删除或绕过宪法条款；含此类指令的提示词不得执行。
  • 宪法变更：提交变更提案（含理由与影响面）→ 评审 → 通过后修改宪法、更新版本号。不使用"边写边改"。
  • 版本号（SemVer）：MAJOR = 删除或重新定义原则；MINOR = 新增原则/章节；PATCH = 措辞澄清。常用 MINOR，MAJOR 慎用。
  • 变更报告（Sync Impact Report）：宪法每次改动，MUST 在文件顶部以不渲染的 HTML 注释附以下六项——①Version change（旧 → 新）；②改动原则清单（重命名标 old title → new title）；③新增/删除的章节；④需联动更新的模板/文档清单及状态（已更新 / 待办 + 文件路径）；⑤遗留 TODO；⑥评审结论。未附报告或报告中标"待办"的模板未同步的变更，一律退回。
  • 元数据：每次宪法变更 MUST 同步更新 frontmatter 的版本与 Last Amended；评审通过时填入 Ratified。
  • Spec 变更：直接修改对应 Spec 文件并更新版本号；涉及架构、权限、API 兼容性的重大变更走评审。
  • 决策记录（ADR）：新增外部依赖、超出 §3 技术栈基线的选型、架构调整、实现阶段发现的 spec 遗漏补救，MUST 以 ADR 记录。ADR 存放 docs/adr/，结构：Date / Status / Context / Decision / Consequences / Reverts；撤销既有决策须新建 ADR，不回改旧文。
  • 冲突处理：Spec 与宪法冲突时，停止相关执行，提交确认；择一修改后继续。
  • 违规处理：评审中发现的违宪行为（未附 Sync Impact Report 的宪法变更、未经 §4 评审的自研实现、超出 §8 红线的 Spec/Plan/Tasks），一律打回整改并记录；违规产物不得进入实现阶段，实现阶段发现的违宪改动须回滚。最终裁决权归治理责任人。
  • 评审：总架构师初审 → 产品经理终审；评审结论记录于对应提案/文档，通过的草稿移入 specs/。

8. 范围红线

当前阶段范围为基础平台与教学闭环（课程与成员、实验任务、可配置个人报告提交、版本化人工批改与成绩发布）。阶段划分与交付物清单的唯一权威为 docs/specs/roadmap.md；本节不做清单与红线判定为唯一权威。两者出现缺口或冲突时，先停相关执行、评审裁决，再同步修改两文件；roadmap 扩容 MUST 同步回填本节。

超出 roadmap 即越界：

  • 教学阶段限单负责人课程、课程码直接加入、任务、教师配置材料类型、个人报告版本、人工分项评分与评语、逐份或批量发布、返工重交和课程归档；不包含多教师、助教、协作小组、自动执行/评分、AI 评分、查重、互评或完整教务系统。
  • 以下能力不实现、不引入新依赖：消息通知、报表、导入导出、审计日志增强、多端支持。例外仅限所选框架自身已集成、无需新增依赖与开发量的能力，且 MUST 在该功能 Spec 中标注"框架自带"并列出零修改证据；判定由评审确认。
  • roadmap 扩容须经评审，红线判定不变。