HIT 课程资料管理

本上下文描述培养方案身份、课程代码与资料仓库之间的关系。课程记录和课程代码保持独立、可追溯；仓库是唯一资源归属边界，独立资源边界通过拆仓表达，不在仓库内部维护资源组。

Language

培养方案记录（CurriculumRecord）： 一门课程或培养要求在一份培养方案中的一次出现，以稳定 record_id 标识。它保存专业、学期、学分和学时等上下文，不因资料共仓而合并。 避免使用：课程仓库、课程身份

课程代码描述（CourseDescriptor）： 一个完整课程代码及其规范名称、培养方案记录集合和资料仓库绑定。每个有代码课程恰好有一个独立描述；课程代码是仓库拆分、合并和重组时不可继续拆分的最小原子，也是课程展示与检索的独立单元。课程名称及同代码名称变体仅来自该代码的规范描述和培养方案记录；物理仓库用于合并、迁移的近似名称与历史路径不属于课程别名，共仓不意味着课程等价。 避免使用：用课程族指代单个课程代码、仓库身份、把一个课程代码拆到多个物理仓

课程组（CourseGroup）： 由培养方案中的可审计范围关系形成、允许重叠的课程集合。当前关系范围为单份培养方案、同一学院内的同名专业、培养方案归属学院，以及这些专业或学院中的选修课程记录。课程组保留每个 CourseDescriptor 与 CurriculumRecord 的独立身份，只表达成员为什么相关。

每个课程组有稳定 course_group_id、group_type、scope_conditions、relation_key、membership_semantics 和成员快照。一个课程代码可以同时属于多个课程组；课程组只用于检索、导航和仓库策略审阅证据，不直接创建、合并或拆分资料仓库。 避免使用：相似课程桶、互斥分区、资料仓库合并指令

共享资料约束（SharedMaterialConstraint）： 同一份资料明确关联的课程代码必须共同归属一个仓库；它是拆仓时必须保持的关系，不是需要持久化或展示的资源组。共仓本身不产生新的资料共享关系。 避免使用：资源组实体、仓内子仓库、按相似名称推断资料共享

物理仓库（PhysicalRepository）： 直接承载课程代码和资料文件的 GitHub 仓库，是资料维护与归属的唯一边界。每个完整课程代码只归属一个仓库，每份资料只在一个仓库中维护；需要独立维护不同资料范围时拆分仓库，而不是建立仓内资源组。无资料课程可按真实开课单位共仓，但不因此获得其他课程的资料。 避免使用：资源组、逻辑资料仓、从仓库名称反推课程身份

资料分类（MaterialCategory）： 仓库中按资料用途组织文件的统一中文分类，例如教材、笔记、课件、试卷、作业、实验、软件、教程、模板、项目和其他。分类不是资源归属边界，不绑定课程集合；维护者不得自行增加预设范围之外的根级分类，软件包和文档可在分类内保留必要结构。 避免使用：资源组、子仓库、用课程名或历史分桶作为根级分类

物理仓上位语义（PhysicalRepositoryUmbrellaSemantics）： 一个仓库所覆盖课程和文件的真实、可解释主题。主题名称应准确描述仓库整体，不用学院级名称掩盖多个需要独立维护的资源边界；是否共仓取决于实际维护范围，不取决于历史分组或分桶数量。 避免使用：内部组编号、实现分桶、用仓内资源组代替拆仓

仓库描述（RepositoryDescription）： GitHub 仓库列表中的短辨识文本，保留该仓独有且稳定的上位语义。课程仓的“课程代码 → 原始课程名”映射也是稳定结构身份：完整映射能在 GitHub 350 字限制内表达时全部写入；超限时按课程代码稳定顺序保留尽可能多的完整映射条目，并以明确的“尚余 N 项”标记截断。不得在课程代码或课程名中间硬截断，也不得伪装成完整映射。README 与 Registry 始终保存全量映射。文件数、字节数、资料类别和当前是否为空等内容库存不进入 description；普通内容变化不触发更新，只有课程代码成员或原始课程名变化才触发更新。 避免使用：无截断标记的部分映射、在条目中间硬截断、代表性随机节选、库存摘要、跨仓通用说明、内部实现词

仓库说明文档（RepositoryREADME）： 仓库内承载通用结构、路由角色、Registry 权威关系、目录约定、维护和贡献流程的可版本化文档。每个课程仓 README 必须完整列出该仓所有课程代码及其原始课程名，不受 GitHub description 字数限制；description 出现“尚余 N 项”时，README 与 Registry 是余下映射的完整权威来源。 避免使用：让 README 映射与 Registry 不一致、按 description 的截断范围删减 README、把截断 description 误作完整映射

中心培养方案元数据（RegistryCurriculumMetadata）： 培养方案、执行教学计划、课程记录与课程代码描述的中心权威数据，分别保留方案版本与入学年级。没有课程代码的原始要求只属于教学计划记录，不绑定资料仓库，不伪造课程代码。 避免使用：培养要求仓库、无代码课程、资源组元数据

历史资料单元（LegacyUnit）： 冻结旧附件树中具有来源证据的资料范围，仅用于迁移核验与历史追溯。迁移完成后，资源归属直接由课程代码、专题入口和目标仓库表达，历史目录不成为现行仓库中的分组。 避免使用：旧目录即课程、永久资源组、绕过显式路由猜测归属

冻结源文件（FrozenSourceFile）： 冻结附件树在指定 source commit 下的一个原始 Git blob。它以源 owner、repository、commit、path、blob SHA-1、SHA-256、size 和 mode 共同标识；当前仓库体系建立阶段要求每个冻结源文件原字节进入唯一可路由目标，不因格式损坏、内容质量、重复、许可判断或未来整理计划而被筛除、修复、解压或替换为链接。 避免使用：待筛选资料、可选迁移文件、用 Release 或上游链接替代源 blob

仓库路由（RepositoryRoute）： 从稳定 route_key 到目标 repo_id 的类型化可见入口。kind 分为 curriculum-course、special-topic、plan-record 与 infrastructure；官方课程代码只存在于 curriculum-course，专题和培养要求不得伪装成课程代码。plan-record 指向中心 registry 的 metadata_path，不表示附件归属。 避免使用：从仓库名猜入口、把专题码写入 CourseDescriptor、把空分类仓当导航路由

仓库脚手架（RepositoryScaffold）： 为实体仓库提供身份、同步契约和空目录结构的托管元数据，包括 README、repository.toml、统一 workflow 与 .gitkeep。脚手架不是学习资料；只有脚手架且没有资料、成员或路由的实体仓不构成有效导航。 避免使用：把脚手架文件计作课程资料、以空仓替代 registry/site 虚拟导航

控制面世代（ControlPlaneGeneration）： 一组不可混用的注册表、管理仓库、模板和由该模板生成的资料仓库。当前权威世代为 v2：fireworks-course-registry-v2、fireworks-repos-management-v2、fireworks-course-template-v2 与 fireworks-collection-template-v2。培养要求已集中进 registry，因此不存在 requirement template。旧 canary 四仓只作为冻结迁移前置条件保留，不属于 v2 manifest，也不得被 v2 初始化器覆盖或复用。 避免使用：原地升级旧控制面、跨世代复用模板、继续创建培养要求模板

虚拟分类（VirtualCollection）： 学院、实验、公共课或待识别等分类只存在于站点与 Registry 索引中，不对应 production GitHub 实体仓。分类本身没有课程代码或专题路由能力，因此不得作为资料目标；分类下的资料必须进入可路由的 course、shared 或 competition 仓。 避免使用：CollectionRepository、空分类实体仓、把分类名当路由目标

共享资料仓（SharedRepository）： 承载有明确 special-topic 路由、横跨多门课程或不属于单一课程的共享资料。共享仓必须公开其专题路由键；不能路由的空共享仓同样不应存在。当前共享目标包括校内与跨课程专题资料，以及文档模板。 避免使用：collection、课程仓、无路由的杂物仓

竞赛资料仓（CompetitionRepository）： 承载明确竞赛主题资料的仓库。需要独立维护的竞赛主题通过拆仓表达，不以单一总仓中的资源组代替实体仓库边界。 避免使用：强制全部竞赛共仓、仓内竞赛资源组

软件中间仓（SoftwareRepository）： 为整包软件、教程和配套资料提供迁移来源身份的历史维护容器，不是稳定 production 类型。SOFTWARE-C2BE460F2397 的完整内容已原字节迁入有官方课程路由的课程仓并完成逐 blob 核验，软件中间仓已删除。 避免使用：永久软件仓、用下载链接替代冻结源文件

控制仓（ControlRepository）： 组织级权威数据与自动化控制面，不承载学生资料。当前仅有课程 registry 与仓库管理两个 v2 控制仓。 避免使用：资料仓、模板仓、学生导航入口

模板仓（TemplateRepository）： 用于创建同结构实体仓的 GitHub template，不承载迁移资料或课程身份。当前 course 模板服务课程仓；非课程模板只服务具有显式专题路由的 shared 与 competition 仓，不再创建 collection 实体仓。 避免使用：资料仓、控制仓、用模板维持不可路由的空 collection