diff --git a/README.md b/README.md index 346444be..49a80731 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,142 @@ -# 星序 Astra · 一站式交互学习平台 +# 星序 Astra -星序 Astra 将可交互实验与教学管理结合在同一平台中，Web 实验体验与后端课程、协作和评价同等重要。当前包含： +**交互式学科学习与职业情景实训。** -- **工科试验室**：数学、物理、化学、算法、生物五大学科，共 90 个交互实验。 -- **代码空间**：独立子站 [`/codevis/`](codevis/README.md)，提供 6 组课程目录、18 个“预测—运行—追踪—修正”活动以及 JavaScript、Python、C、C++ 浏览器学习运行时。 -- **未来星系**：6 个跨学科方向、19 个活动身份，以课程目录、Canvas 观测和按需 Three.js 互动组织地球与宇宙、工程、数据、信息、材料与人文学习。 +星序把知识讲解、动手实验和教学任务放进浏览器。学生可以改变参数观察规律、追踪程序执行，也可以进入职业现场采访人物、核实资料并完成作品；教师可以组织资源、编排课程，在学校审核后发布，并回看学习记录。 -正式门户位于 `qianduan/`，使用 TypeScript、Vite、原生 DOM 和 Three.js；Python/FastAPI 提供认证、课程、作业、内容、学习分析与治理 API。三个原有实验空间保留，构建时打包为独立公开资源。 +项目包含学术主站与职业教育子站。两者通过教育方向入口衔接，分别维护业务服务和数据，适合本地课程演示、毕业设计与交互学习内容开发。 -[打开 GitHub Pages 演示](https://falling-feather.github.io/Astra/) · [前端开发与发布](qianduan/README.md) +[在线体验学术静态演示](https://falling-feather.github.io/Astra/) · [运行完整版本](#运行完整版本) · [了解技术设计](doc/01-开发者手册.md) · [查看当前计划](doc/02-更新规划.md) -## 当前状态 +## 可以在星序里做什么 -- `main` 保存完整源码，`qianduan` 保存 Pages 静态制品。线上使用明确标识的内存演示数据，本机完整版本连接真实账号和数据库。本轮采用普通开发提交，未新增产品发布号；提交与验证见 [本阶段记录](doc/03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装)。 -- 登录前导览、Cookie Session、教师申请、课程创建与审核、学生选课、多教师共享草稿、不可变发布、三种完成结果和三角色工作台均已进入当前实现。 -- 三个学习空间合计 127 项正式活动身份：工科试验室 90、代码空间 18、未来星系 19。课程可引用这些活动；目录身份数量不等于独立实验或完整教学闭环的数量。 -- 当前迁移包含个人笔记与发布单元状态修复，准确迁移 head 见 [部署指南](doc/04-部署指南.md)。本轮完成教师课程/版本/学生/批改、学生作业和必要管理审核页面；课程家族、跨分叉同步、候选批审和补做策略仍属于后续计划。公网业务后端、隔离源码执行和真实课堂实证未作为已完成能力。 -- 当前作品服务毕业设计、大作业与展示类竞赛；先打磨 Web 交互和后端架构，微信小程序暂不设计。实验端强调课程广度、递进、适配与解释性；业务规则和实施顺序见 [更新规划](doc/02-更新规划.md)，目标图见 [架构设计](doc/01-开发者手册.md#13-目标架构与设计待实现)。 +| 学习空间 | 当前内容 | 可以尝试的操作 | +| --- | --- | --- | +| 工科试验室 | 数学、物理、化学、算法、生物，90 项交互实验 | 调整双摆初始角差，比较轨迹和末端距离；改变色谱参数，观察色带与检测峰的对应关系 | +| 代码空间 | 6 组课程目录、18 项学习活动 | 先预测结果，再运行代码、追踪变量并修正判断；按需加载 JavaScript、Python、C、C++ 浏览器学习运行时 | +| 未来星系 | 地球与宇宙、工程、数据、信息、材料与人文，19 项活动 | 通过课程目录、Canvas 观测和按需三维交互，探索跨学科问题 | +| 职业教育 | 融媒体岗位下的 5 门课程，复用蟳埔、榕江和山地景区场景 | 调查现场、采访人物、核对来源、记录笔记、编辑作品，并在动态服务中查看过程评价与教师复核 | -当前实现见 [`doc/01-开发者手册.md`](doc/01-开发者手册.md)，下一阶段任务与版本见 [`doc/02-更新规划.md`](doc/02-更新规划.md)，全部版本、验收证据与历史档案统一见 [`doc/03-发布历史.md`](doc/03-发布历史.md)。 +前三个空间共 **127 个活动身份**。教师创建的授课课程、资源模板和职教情景课程另行管理；同一个实验可以被不同课程引用，课程成员和学习记录各自保留。 -## 快速开始 +第一次体验，可以先选一项实验改变一个变量，再进入代码空间完成一次“预测—运行—追踪—修正”。需要了解教学管理时，切换演示身份观察教师编排、管理员审核、教师发布和学生学习的过程；需要观察真实持久化与职教模型交互时，使用下方本地入口。 -### 推荐：9001 单入口一键启动 +## 核心设计 -在 Windows PowerShell 中从仓库根目录执行： +### 数值模型与可视化交互相结合 -```powershell -powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -``` +星云开场和透视课程轮盘提供空间化导航，具体实验使用 DOM、Canvas 或 Three.js 表达适合观察的关系。计算与绘制分别组织：例如双摆实验用四阶 Runge–Kutta 方法推进状态，再将轨迹、分离距离和能量误差显示出来。代表性模型的公式、单位、假设和可复算样例见 [学科实验指南](doc/01-子文档/15-学科实验与内容开发指南.md)。 -先核对 [运行环境约束](doc/04-部署指南.md#1-运行方式与环境)，使用仓库锁定的 Node/npm，并准备 Python 3.12+。脚本创建仓库内忽略的 `.venv`、按 `backend/requirements.lock` 安装哈希锁依赖、构建正式前端、执行 Alembic 迁移，并把前端与 API 同源启动在 `http://127.0.0.1:9001/`。数据默认保存在 `%LOCALAPPDATA%\Astra\local-preview`；再次执行会识别已经运行的星序站点，停止使用 `Ctrl+C`。 +### 从资源复用到课程审核与学习留档 -需要保持仓库内不产生 `.venv` 时，可把托管虚拟环境显式放到仓库外；路径允许 Unicode 和空格，但规范化后不得等于仓库根目录或位于其子目录： +教师可以引用现有活动、使用受控函数或图表模板，配合讲解、媒体、检查点和作业编排课程。课程支持独立派生、共同教师共享草稿、同源内容同步预览和候选审核；正式发布固定到已审核的内容快照。 -```powershell -$ExternalVenv = Join-Path $env:LOCALAPPDATA "Astra\Python 环境\preview venv" -powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -VirtualEnvironmentPath "$ExternalVenv" -``` +学生的检查点、作业与评分记录保留所见版本和来源。重新提交、退回与改分追加历史，旧结果是否沿用由发布策略和认定记录表达。具体流程及当前接入范围见 [课程工作流](doc/01-开发者手册.md#64-本轮课程工作流) 和 [学习历史](doc/01-开发者手册.md#65-版本化学习作业与评分历史)。 -该模式拒绝 Windows device namespace；所选目录及其现存祖先、`Scripts/python.exe`、依赖标记和 `Lib/site-packages` 也不得经过 junction、symlink、volume mount 或 cloud reparse point。脚本在所选目录创建/复用 Python 3.12+ 环境，要求该解释器回报的 `sys.prefix` 精确归属所选目录，按同一哈希锁安装依赖，并把锁文件 SHA 标记保存在该环境内，不创建或修改仓库 `.venv`。已有的调用方自管 Python 则使用 `-PythonExecutable "" -SkipDependencyInstall`；两种参数互斥。自管模式不安装依赖、也不写依赖标记，而是在创建数据目录、审计盐、环境配置、迁移、初始化或 Uvicorn 之前，先用解析后的同一可执行文件执行离线哈希锁 dry-run 和 `pip check`，任一步失败即停止。后续 pip、Alembic、bootstrap、演示初始化和前台 Uvicorn 也始终使用选定的精确 Python。 +### 让 AI 参与有依据的学习任务 -全新数据目录需要首个管理员时，使用交互式入口；密码只在隐藏输入和当前进程内短暂存在，不写入参数、脚本或仓库： +学术主站提供按配置启用的 AI 助教接口。职教子站进一步将人物知识范围、交流历史、课程证据与世界状态结合：模型提出回答或行动建议，程序核验允许动作、权限和状态后再提交变化，教师保留复核入口。 -```powershell -powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -BootstrapAdmin -``` +职教内容库保存来源版本、片段、知识、授权和审核记录，蟳埔旗舰课程已接入基于资料与本地向量的检索链。实时模型需要单独配置；公开导览使用预设访谈和本地草稿，两种体验的入口与能力见 [职教运行说明](doc/04-部署指南.md#8-职教子站运行与数据)。 -这是当前展示版的正式启动与验收入口；它不配置域名、TLS、Windows 服务或正式 MySQL，也不能被描述成 staging/production。完整边界见 [`doc/04-部署指南.md`](doc/04-部署指南.md)。 +## 体验方式 -### 前端独立开发与演示 +| 方式 | 入口 | 数据与适用场景 | +| --- | --- | --- | +| 学术静态演示 | [GitHub Pages](https://falling-feather.github.io/Astra/) | 三角色内存样例，刷新重置；适合先看界面和交互。线上制品版本以实际构建信息为准 | +| 学术本机完整版本 | `http://127.0.0.1:9001/` | FastAPI、Cookie 会话和 SQLite，保存真实本机账号、课程与学习记录 | +| 职教本机动态服务 | 默认 `http://127.0.0.1:4173/` | 独立 Fastify API、PGlite 和文件存储，适合观察人物交互、作品提交和教师流程 | +| 职教公开导览 | 按 [第 8 节](doc/04-部署指南.md#8-职教子站运行与数据) 独立构建 | 预设场景和浏览器本地草稿，不依赖动态 API | -在仓库根目录执行： +教育方向中的“职业教育”默认跳转本机 `4173`，可通过 `VITE_VOCATIONAL_APP_URL` 修改。打开学术 Pages 不会启动职教服务；两站也尚未共享账号、课程或成绩。 -```bash -npm --prefix qianduan ci --ignore-scripts -npm --prefix qianduan run dev -- --port 5173 --strictPort -``` +## 运行完整版本 -访问 `http://127.0.0.1:5173/`。真实模式的 `/api` 和 `/labs` 代理到上述本机 9001 服务。只看演示效果时改用 `npm --prefix qianduan run dev:demo`；独立打包、子路径与发布步骤见 [前端说明](qianduan/README.md)。 +### 学术主站 -### 单独运行业务 API +准备 Git、Python 3.12+，以及仓库锁定的 **Node 24.20.0 / npm 11.19.0**。从 Windows PowerShell 执行： -需要 Python 3.12+： - -```bash -cd backend -python -m pip install --require-hashes -r requirements.lock -python -m alembic upgrade head -python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 +```powershell +git clone https://github.com/falling-feather/Astra.git +cd Astra +powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -BootstrapAdmin ``` -默认数据库是本地 SQLite，也是当前展示版要求复验的数据库。以后恢复生产发布时，才需要显式配置 MySQL、关闭自动建表，并按 [`doc/04-部署指南.md`](doc/04-部署指南.md) 执行预检、迁移、烟测和回滚检查。 +首次运行会准备 Python 环境、安装锁定依赖、构建前端、执行数据库迁移，并交互创建首个管理员。密码输入不回显。成功后打开 `http://127.0.0.1:9001/`；再次启动可省略 `-BootstrapAdmin`，使用 `Ctrl+C` 停止。 -`backend/requirements.txt` 是直接依赖约束输入，不能用于发布安装。依赖升级必须在独立变更中同时更新哈希锁：先安装 `uv==0.10.6`，再从仓库根目录执行 `python backend/scripts/compile_requirements_lock.py --exclude-newer YYYY-MM-DD`；CI 会重新解析并拒绝漂移。 +需要合成演示账号、隔离数据目录、外置 Python 环境或自管解释器时，按 [本机完整版本](doc/04-部署指南.md#2-本机完整版本) 操作。数据默认保存在 `%LOCALAPPDATA%\Astra\local-preview\astra-local.sqlite3`。 -上述 8000 入口只运行 API；正式门户联调优先使用 9001 一键入口。其他域名或端口需同时配置前端接口地址和后端允许的来源，具体见 [部署指南](doc/04-部署指南.md)。 +### 职教子站与联合启动 -### 兼容用途：C++ 静态服务 +职教采用独立 pnpm 工作区，锁定 **pnpm 11.9.0**；可共用上方 Node 环境，Windows 启动器还要求 `corepack` 命令可用。依赖准备见 [运行环境](doc/04-部署指南.md#1-运行方式与环境)。从仓库根目录独立启动： -需要 CMake 与完整支持 C++17 filesystem 的编译器（GCC 9.1+、现代 Clang 或 MSVC）： +```powershell +powershell -ExecutionPolicy Bypass -File .\zhijiao\启动职教星云.ps1 +``` + +已完成学术主站初始化后，也可以联合启动两站并复用职教数据： -```bash -cmake -S server -B server/build -DCMAKE_BUILD_TYPE=Release -cmake --build server/build --config Release --target verify_build_manifest +```powershell +powershell -ExecutionPolicy Bypass -File .\start-joined-stack.ps1 -ReuseVocationalData ``` -C++ 进程只承担静态资源和内部存活探针，业务 `/api/*` 必须由反向代理转发到 FastAPI。FetchContent 固定 cpp-httplib v0.18.3 的完整 commit；构建旁生成并校验包含产物 SHA-256、工具链和依赖来源的 `englab_server.build-manifest.json`，离线缓存用法见 [`server/README.md`](server/README.md)。 +联合启动器不带 `-ReuseVocationalData` 时，为职教创建新的演示数据目录；这与职教独立启动默认复用数据的行为不同。依赖准备、模型选择、端口与备份方式统一见 [职教运行与数据](doc/04-部署指南.md#8-职教子站运行与数据)。 -## 质量门禁 +## 技术架构与代码入口 -```powershell -# 后端全量回归；真实 MySQL 专项在未提供隔离数据库时会显式跳过 -python -m pytest backend +| 部分 | 核心技术 | 代码位置 | +| --- | --- | --- | +| 学术门户 | TypeScript、Vite、原生 DOM、Three.js | [`qianduan/src/`](qianduan/src/)：界面、角色工作区、API 适配、状态与渲染 | +| 学术实验与编程活动 | JavaScript、HTML、CSS、Canvas、浏览器学习运行时 | [`pages/`](pages/)、[`shared/`](shared/)、[`codevis/`](codevis/) | +| 学术业务后端 | Python、FastAPI、Pydantic、SQLAlchemy、Alembic | [`backend/app/`](backend/app/)、[`backend/alembic/`](backend/alembic/) | +| 职教前端与 API | React、TypeScript、Vite；Node.js、Fastify | [`zhijiao/apps/web/`](zhijiao/apps/web/)、[`zhijiao/apps/api/`](zhijiao/apps/api/) | +| 职教业务模块 | 共享契约、课程、世界规则、检索上下文、模型网关、智能体与媒体处理 | [`zhijiao/packages/`](zhijiao/packages/) | +| 数据存储 | 主站默认 SQLite，可配置 MySQL；职教使用 PGlite 与 JSON/JSONL 文件 | 表结构、数据职责与边界见 [开发者手册](doc/01-开发者手册.md#2-系统全局架构) | -# 精确 Node/npm + package-lock；覆盖全部跟踪脚本语法与前端契约 -npm ci --ignore-scripts -npm test +主站由 FastAPI 决定权限、发布与学习结果，职教业务由自己的 Fastify 服务处理。根目录 `server/` 中的 Node/C++ 服务承担兼容静态服务和构建验证。两套业务实现及其接入关系见 [系统架构](doc/01-开发者手册.md#2-系统全局架构)。 -# 正式门户行为、类型、构建与公开制品 -npm --prefix qianduan ci --ignore-scripts +## 继续开发与阅读 + +| 你要做的事 | 建议入口 | +| --- | --- | +| 了解作品范围与当前交付 | [00 项目总纲](doc/00-项目总纲.md) | +| 理解接口、课程版本、学习记录与数据库 | [01 开发者手册](doc/01-开发者手册.md) | +| 核对业务规则、待办和恢复顺序 | [02 更新规划](doc/02-更新规划.md) | +| 查阅真实提交、历史验证与阶段问题 | [03 发布历史](doc/03-发布历史.md) | +| 配置运行、数据、模型与发布 | [04 部署指南](doc/04-部署指南.md) | +| 调整界面、导航和实验交互 | [05 UI 规范](doc/05-UI规范模板.md) | +| 增加实验并核验科学模型 | [15 学科实验指南](doc/01-子文档/15-学科实验与内容开发指南.md) | +| 单独开发学术前端或 API | [前端说明](qianduan/README.md)、[后端说明](backend/README.md) | + +按改动选择最接近的检查。下例在仓库根目录执行，假设已完成默认本机初始化；若使用外置或自管 Python，把解释器路径换成实际路径。原实验的根目录检查另需执行一次 `npm ci`： + +```powershell +# 学术业务、门户和原实验 +.\.venv\Scripts\python.exe -m pytest backend npm --prefix qianduan test npm --prefix qianduan run build npm --prefix qianduan run verify:package +npm ci +npm test -# 工作区差异检查 -git diff --check -``` +# 职教工作区：已完成职教依赖安装后执行 +Push-Location .\zhijiao +pnpm typecheck +pnpm test +Pop-Location -GitHub Actions 分别运行 Windows 前端合同、Linux 门户构建、SQLite 全量、MySQL 8.4 发布证据和 C++ Release 构建。当前阶段另实测新门户桌面三角色业务和 Pages 子路径；旧 `role-workflows-proof.cjs` 绑定 V8 页面选择器，仅供兼容与历史追溯，不能代替新门户浏览器验收。验证结果和未覆盖范围见 [本阶段记录](doc/03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装)。 - -## 项目结构 - -```text -. -├── qianduan/ # 正式门户、请求适配、演示适配及制品脚本 -├── index.html # 原实验站资源入口，构建时纳入 labs -├── package.json/package-lock.json # Node 质量工具入口与 integrity 锁 -├── pages/ # 三个原有学习空间及兼容角色页面 -├── shared/ # 实验求解/渲染、资源路由和兼容模块 -├── codevis/ # 代码空间独立子站 -├── backend/ # FastAPI、SQLAlchemy、Alembic、脚本与 pytest -├── server/ # Node 开发静态服务与 C++ Release 静态服务 -├── tools/quality/ # 跨平台跟踪脚本语法门禁 -├── tools/tests/ # 前端/静态公开面契约 -├── doc/ # 开发、规划、历史、部署、UI、审查与索引文档 -└── .github/workflows/ # 持续集成质量门禁 +# 提交前检查 +git diff --check ``` -## 文档入口 - -当前阶段只维护以下七篇。旧逐版本报告、冻结规划和迁移副本通过 Git 追溯，不在工作目录保留平行原件。 - -| 文档 | 职责 | -| --- | --- | -| [00 项目总纲](doc/00-项目总纲.md) | 项目定位与文档入口 | -| [01 开发者手册](doc/01-开发者手册.md) | 当前架构、业务、代码入口及待实现目标图 | -| [02 更新规划](doc/02-更新规划.md) | 完整规则、任务、依赖和验收 | -| [03 发布历史](doc/03-发布历史.md) | 真实提交、验证与历史恢复 | -| [04 部署指南](doc/04-部署指南.md) | 环境、启动、迁移、静态发布与运行边界 | -| [05 UI 规范](doc/05-UI规范模板.md) | 正式门户与实验交互约定 | -| [15 实验指南](doc/01-子文档/15-学科实验与内容开发指南.md) | 新实验接线和科学模型依据 | +各命令的依赖和范围见 [最小验证](doc/01-开发者手册.md#92-按改动选择验证)。历史通过记录属于对应提交，当前实现与未完成事项分别由 01、02 维护。 +## 当前阶段 -## 核心边界 +当前以 Web、本机持久化和展示为主要交付范围。课程版本、审核与学习历史已有实现，部分实验整页导航后的记录接线及其他已知回归仍需处理；具体问题与暂停后的继续事项见 [当前任务状态](doc/02-更新规划.md#3-当前任务状态)。完整移动端精调、公网业务运营、正式隔离判题与真实课堂效果不在当前交付范围。 -- 认证会话使用 HttpOnly cookie；前端不持久化 Bearer token 或学生敏感学习数据。 -- `/api` 全状态 `no-store`，Service Worker 不缓存业务 API。 -- 教师自定义脚本必须经过 allowlist、审核、SRI/hash、opaque iframe 与 CSP 边界，不能直接执行任意脚本。 -- C++/Node 静态服务只公开 `index.html`、`sw.js`、`LICENSE.md`、`pages/`、`shared/`、`UI/`、`codevis/`。 -- 外部投递、问题同步和审计锚定默认关闭，不能用本地 dry-run 冒充真实外部证据。 +`main` 保存完整源码，`qianduan` 保存学术 Pages 静态制品。代码更新和线上制品发布分别进行，发布流程见 [前端构建与发布](qianduan/README.md#制品与-github-pages)。 -## 许可证 +## 许可证与资源来源 -使用条件与第三方资源说明见 [`LICENSE.md`](LICENSE.md)。 +使用条件及第三方资源说明见 [LICENSE.md](LICENSE.md)。浏览器运行时、模型参考与媒体素材按各自来源记录维护。 diff --git "a/doc/00-\351\241\271\347\233\256\346\200\273\347\272\262.md" "b/doc/00-\351\241\271\347\233\256\346\200\273\347\272\262.md" index ceeb31f8..57928318 100644 --- "a/doc/00-\351\241\271\347\233\256\346\200\273\347\272\262.md" +++ "b/doc/00-\351\241\271\347\233\256\346\200\273\347\272\262.md" @@ -1,10 +1,10 @@ # 星序 Astra — 项目总纲 -> **文档梗概**：项目定位、当前交付和必要文档入口。 +> **文档梗概**：项目定位、当前作品、两类学习入口与文档职责。 > -> **具体规划法则**：实现、规划和历史分别由 01、02、03 维护；代码定义的字段以代码为准，旧记录通过 Git 追溯。 +> **具体规划法则**：实现、规划和历史分别由 01、02、03 维护；对象字段与运行行为以代码为准。介绍性内容从 README 进入，操作步骤与证据不在总纲重复。 > -> **最后一次更新时间**：2026-09-16 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -17,42 +17,49 @@ ## 1. 项目定位 -星序是一站式可交互学习平台，将实验探索与教学管理结合。Web 体验与后端架构同等重要：前者支持学习、设计和展示，后者承接课程、协作、评价及可解释记录。 +星序是一站式可交互学习平台，将实验探索、课程组织和学习评价结合。学生通过改变参数、比较现象、追踪程序或完成场景任务理解知识；教师组织资源与授课过程，保留提交、反馈和评价依据。Web 体验与后端业务共同构成作品。 -当前面向单校 Web、本机毕业设计和竞赛展示，先完善课程广度、递进、适配和解释性。微信小程序、跨校平台、AI 助教和公网长期运营仍属后续方向。 +当前有学术教育和职业教育两类入口。学术主站围绕学科实验、编程活动与校内课程展开；职教子站围绕融媒体岗位组织采访、核实、授权和作品表达。两站已有入口跳转与联合启动，账号、课程和成绩分别管理。 + +本阶段面向 Web、本机毕业设计与竞赛展示。学术主站采用单校课程权限，职教动态站使用本地教学演示身份；跨校平台、正式职业身份接入、公网长期运营和真实课堂效果另有实施与验证范围。 ## 2. 当前作品 -| 部分 | 当前事实 | -| --- | --- | -| 正式门户 | `qianduan/`：星云开场、透视课程轮盘和学生/教师/管理员页面 | -| 学习资源 | 工科 90、代码 18、未来 19，共 127 个活动身份；不等于 127 门完整独立课程 | -| 教学后端 | FastAPI：身份、组织、资源模板、独立课程与共享草稿、同步候选审核、冻结发布、选课、作业、批改与记录 | -| 本机版本 | `astra-local.ps1` 在 9001 同源提供真实前端、API 和 SQLite | -| 静态展示 | [GitHub Pages](https://falling-feather.github.io/Astra/) 使用明确标识的内存演示数据 | -| Git | `main` 为完整源码；`qianduan` 为静态制品，仅保留根工作树 | -| 下一阶段 | 学习版本绑定、换版补做、成绩历史与旧结果认定、统计/任务及课程统一改进，详见 02 | +| 部分 | 当前内容 | 维护入口 | +| --- | --- | --- | +| 学术门户 | 星云开场、教育方向、课程轮盘和学生/教师/管理员页面；TypeScript、Vite、原生 DOM 与 Three.js | `qianduan/`；01 第 5 章 | +| 学科学习资源 | 工科 90、代码 18、未来 19，共 127 个活动身份；支持按真实能力引用和配置 | `pages/`、`shared/`、`codevis/`；15 号指南 | +| 教学业务 | 身份与组织、资源模板、独立课程、共享草稿、同步候选审核、冻结发布、选课、作业与批改 | `backend/`；01 第 6 章 | +| 学习历史 | 学习上下文、检查点、历次作业与评分、结果认定；部分实验已声明参数记录能力 | 01 第 6.5—6.6 节；当前回归与未完成入口见 02 | +| 职教实训 | 5 门融媒体课程、3 个区域；场景、人物、资料、笔记、作品、过程评价和教师复核 | `zhijiao/apps/`、`zhijiao/packages/`；01 第 2 章 | +| 可选模型 | 主站 AI 助教；职教模型网关、人物交互与课程证据检索，按配置启用 | 04 第 9 章 | +| 运行交付 | 主站 9001 同源服务；职教独立动态站；两站可联合启动。主站另有 Pages 静态演示 | 04 部署指南 | + +127 项统计只包含三个原学习空间的活动身份，不包括职教课程、教师派生课程或模板版本。活动可自由探索，也可进入具体课程；来源相同不意味着共享成员、发布或完成结果。 + +数据分别保存在两套服务中：主站默认使用 SQLite，也有 MySQL 连接支持；职教以 PGlite 保存内容与证据关系，并通过文件记录部分会话、世界状态和作品。数据库模型、表数及代码层级见 [01 系统全局架构](01-开发者手册.md#2-系统全局架构)，实际数据位置见 [04](04-部署指南.md)。 -基础教学流程已完成 2026-09-08 验收；2026-09-16 新增课程创作、同步审核与冻结发布的开发实现和本机联调。测试计数与发布提交只在 03 保存，不把历史通过结果当成今天的复测。 +基础教学流程的 2026-09-08 验收、后续课程版本开发与 2026-09-18 职教迁入分别记录在 [03](03-发布历史.md)。当前代码存在后续改动和待处理问题，历史测试计数不作为当前全量通过证明。 ## 3. 文档入口 -| 文档 | 唯一职责 | +| 文档 | 职责 | | --- | --- | -| [01 开发者手册](01-开发者手册.md) | 当前架构、页面、业务边界和代码入口；第 13 章保留待实现目标图 | -| [02 更新规划](02-更新规划.md) | 完整业务方案、当前/后续任务、依赖与验收标准 | -| [03 发布历史](03-发布历史.md) | 实际提交、阶段验收、方向撤换和旧材料的 Git 恢复方式 | -| [04 部署指南](04-部署指南.md) | 当前本机运行、构建、数据目录、演示发布及生产边界 | -| [05 UI 规范](05-UI规范模板.md) | 正式门户与实验的视觉、交互和可访问性约定 | -| [15 实验开发指南](01-子文档/15-学科实验与内容开发指南.md) | 新实验注册流程与现有三项模型的科学依据、误差和复核记录 | +| [README](../README.md) | 面向首次访问者介绍作品、体验方式、技术亮点与启动入口 | +| [01 开发者手册](01-开发者手册.md) | 当前架构、业务、数据和代码入口；第 13 章对照完整目标与实际进度 | +| [02 更新规划](02-更新规划.md) | 完整业务方案、任务状态、依赖和验收条件 | +| [03 发布历史](03-发布历史.md) | 实际提交、验证范围、暂停节点和历史恢复依据 | +| [04 部署指南](04-部署指南.md) | 两站运行、环境、数据目录、可选模型与发布 | +| [05 UI 规范](05-UI规范模板.md) | 学术门户、职教场景及实验交互的视觉约定 | +| [15 实验开发指南](01-子文档/15-学科实验与内容开发指南.md) | 活动注册与记录接线、科学模型、误差和复核样例 | -本文件是总入口。组件目录内 README 只保留各自运行和维护说明；许可证、第三方来源记录、机器契约与有效测试不作为旧报告删除。 +各组件 README 保留本目录的开发与维护说明，不另建平行的产品规划或阶段历史。 ## 4. 开发与交付边界 -- 角色、授权、发布和完成结果由服务端决定。自由探索不直接产生授课成绩。 -- 课程家族、跨课程同步与候选正文审核已实现并完成阶段联调；跨版本学习结果和统一统计继续推进。 -- 以根工作区 main 单线推进，任务先登记于 02；不因扩展方向讨论自动开工。 -- 用户未提交文件、数据库和有效依赖保留；本次未修改 `UI.pen` 或应用已有 stash。 -- 协作规则见 [AGENTS.md](../AGENTS.md)。旧模型的冻结阶段、旧写入清单和过期报告不重新成为当前约束。 -- 文档整理前的完整材料保存在 `e73cfa7` 对应 Git 树中；恢复入口见 [03](03-发布历史.md#3-旧材料的git追溯)。 +- 学术主站的角色、发布和正式完成结果由 FastAPI 决定；职教业务由独立 Fastify 服务及世界规则处理。入口相通不表示两站已统一身份和数据。 +- 课程家族、同步候选、冻结发布、检查点和作业版本历史已有实现；实验记录能力、页面接线及后续统一查询按 01、02 逐项说明。 +- 模型接口与资料检索按配置和课程启用。主站助教回答不产生教师评分，职教模型建议经过规则校验；公开导览的预设访谈单独标明。 +- 2026-09-17 的学术持续开发任务保持暂停；之后的独立入口改动和职教迁入按实际提交记录。本次 README 与文档更新不恢复整个研发目标。 +- `main` 保存源码，`qianduan` 保存学术静态制品。源码、构建、推送和线上发布分别记录，不为普通文档维护新增产品发布号。 +- 协作约定见 [AGENTS.md](../AGENTS.md)。旧材料、暂停时的本机证据和未完成验证按 [03](03-发布历史.md) 追溯，保留用户已有数据和修改。 diff --git "a/doc/01-\345\255\220\346\226\207\346\241\243/15-\345\255\246\347\247\221\345\256\236\351\252\214\344\270\216\345\206\205\345\256\271\345\274\200\345\217\221\346\214\207\345\215\227.md" "b/doc/01-\345\255\220\346\226\207\346\241\243/15-\345\255\246\347\247\221\345\256\236\351\252\214\344\270\216\345\206\205\345\256\271\345\274\200\345\217\221\346\214\207\345\215\227.md" index be030004..7127e79f 100644 --- "a/doc/01-\345\255\220\346\226\207\346\241\243/15-\345\255\246\347\247\221\345\256\236\351\252\214\344\270\216\345\206\205\345\256\271\345\274\200\345\217\221\346\214\207\345\215\227.md" +++ "b/doc/01-\345\255\220\346\226\207\346\241\243/15-\345\255\246\347\247\221\345\256\236\351\252\214\344\270\216\345\206\205\345\256\271\345\274\200\345\217\221\346\214\207\345\215\227.md" @@ -1,10 +1,10 @@ # 星序 Astra — 学科实验与内容开发指南 -> **文档梗概**：保留新增实验的实际注册步骤、运行边界和三项现有科学模型说明。 +> **文档梗概**：新增实验的注册步骤、课程资源与操作记录接线、运行边界和三项现有科学模型说明。 > > **具体规划法则**：该文档隶属于[01 学习资源与实验维护](../01-开发者手册.md#4-三个学习空间与课程内容)。目录、字段和运行时以代码为准；模型的公式、误差、样例与来源在本文维护。 > -> **最后一次更新时间**：2026-09-16 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -23,10 +23,15 @@ | 未来星系 19 个活动身份 | [frontier-manifest.js](../../pages/frontier/frontier-manifest.js) | | 统一活动身份与恢复入口 | [learning-activity-catalog.js](../../shared/js/learning-activity-catalog.js) | | 后端受控活动引用 | [official_activity_keys.py](../../backend/app/schemas/official_activity_keys.py)、[content_v2.py](../../backend/app/schemas/content_v2.py) | +| 学习空间与系统资源版本 | [learning-spaces.v1.json](../../backend/app/catalogue/learning-spaces.v1.json)、[learning_resources.py](../../backend/app/services/learning_resources.py) | +| 模板配置与资源能力更新 | [templates.v1.json](../../backend/app/catalogue/templates.v1.json)、[resource-updates.v1.json](../../backend/app/catalogue/resource-updates.v1.json) | +| 课程学习上下文与参数记录 | [LearningWorkspace](../../qianduan/src/portal/learning-workspace.ts)、[CoursePlayer](../../qianduan/src/portal/course-player.ts)、[ActivitySession](../../qianduan/src/domain/activity-session.ts) | | 新实验模板与质量规则 | [tools/templates/new-experiment](../../tools/templates/new-experiment/) | | 正式门户目录与打包 | [catalog.mjs](../../qianduan/scripts/catalog.mjs)、[package-resources.mjs](../../qianduan/scripts/package-resources.mjs) | -资源身份、课程实例和课程内单元分别计数。不能把不同 slug、复制页面或改标题直接算成新的独立实验。同一资源在不同授课情境中的复用与独立学习记录见 [02](../02-更新规划.md)。 +三空间合计 127 个活动身份。资源身份、资源版本、课程实例和课程内单元分别计数；可配置模板、教师派生课程与职教情境课程不混入这一历史数量。不能把不同 slug、复制页面或改标题直接算成新的独立实验。同一资源在不同授课情境中的复用与独立学习记录见 [02](../02-更新规划.md)。 + +`zhijiao/` 的课程档案、岗位现场、人物交流和作品评价由独立 Web 与 API 承接，不经本节的实验目录打包。其当前结构与业务边界见 [01](../01-开发者手册.md)；本文继续维护原学科学习空间的实验注册和科学模型。 ## 2. 新增实验与验证 @@ -34,9 +39,9 @@ 1. 在 02 明确学习目标、必要前置、交互、解释、科学边界与验收；核对现有身份、模型和路由，避免同义扩数。 2. 使用现有模板建立独立 module、JS、CSS、候选 manifest 与预览记录。模型说明写入本文，不放进公开实验页面的开发说明文件。 -3. manifest 固定 `activity_key`、路由、owner、版本化资源、模型锚点与预览来源；代码占位全部替换后才能交付。只登记实际支持的记录能力。 +3. manifest 固定 `activity_key`、路由、owner、版本化资源、模型锚点与预览来源；代码占位全部替换后才能交付。资源版本中的配置、`operation_recording`、完成方式和运行适配说明只登记实际能力；已有不可变版本通过追加新版本更新。 4. 先在候选隔离页验证参数变化、暂停/重置、尺寸变化、减少动态效果、离页释放和重新进入；通过前不插入生产目录。 -5. 复核模型说明和预览素材，再接入 config、registry、页面与活动目录。后端引用白名单和门户目录要对应同一稳定身份。 +5. 复核模型说明和预览素材，再接入 config、registry、页面与活动目录。后端引用白名单、系统资源描述与门户目录要对应同一稳定身份；支持课程操作记录时，完成下方第 2.4 节的发布绑定与回读验证。 6. 执行受影响行为回归与旧活动保护检查；已授权变更更新适用回归，不能用替换哈希掩盖意外变化。 7. 接线完成后移除只供候选发现的 manifest，保留可读 module、模型和素材来源记录；最终目录不再把已发布资源当成未注册候选。 @@ -67,6 +72,28 @@ 原模板的桌面、手机和 reduced-motion 行为检查继续有效；当前门户桌面优先不意味着删除实验已有的响应式回归。操作、失败、离页、重入和资源释放需真实验证，不能只看截图。 +### 2.4 课程资源与操作记录接线 + +资源版本保存运行入口、允许配置和记录能力；同一实验是否计入某门课程，还取决于实际学习上下文、发布版完成规则与服务端回执。系统自主探索、教师预览和正式授课学习分别建模，打开页面或调动任意控件不直接产生课程完成。 + +| 资源与入口 | 当前接线与边界 | +| --- | --- | +| 可配置函数图像 v2 | 在课程正文内运行，通过 [CoursePlayer](../../qianduan/src/portal/course-player.ts) 与 [ActivitySession](../../qianduan/src/domain/activity-session.ts) 记录发布版声明的参数变化；结果是否认定完成由服务端规则决定 | +| 数据图表模板 | 支持受控配置与预览，当前资源未声明操作记录能力；课程完成使用实际配置的检查点或作业要求 | +| 原力学实验 `physics.mechanics` v2/v3 | 资源声明支持参数记录，但课程入口改为整页导航后，播放器跳过 legacy 的记录会话，实验端尚未读取传入的学习上下文；当前无法据这条入口确认课程参数记录与操作完成 | +| 其他原活动与公开资源预览 | 逐资源核对能力；公开预览不产生授课成绩，不能因同属 legacy 或位于目录中就宣称已有自动记录 | + +原力学入口的具体差异可对照 [resource-updates.v1.json](../../backend/app/catalogue/resource-updates.v1.json) 与 [course-player.ts](../../qianduan/src/portal/course-player.ts)：前者保留 `numeric-controls-v1` 能力，后者仅为非 legacy 资源建立记录会话，整页地址附带 `astra_context_key` 和返回位置。当前公开实验包未接收这两个参数，打包入口见 [package-resources.mjs](../../qianduan/scripts/package-resources.mjs)。实验画面与控件仍可使用；本项回归限定为正式课程中原力学参数记录的接线，不表示所有原实验失效。修复与复验安排见 [02 第 3 节](../02-更新规划.md#3-当前任务状态)。 + +支持操作记录的资源按以下步骤验收： + +1. 学生进入课程单元时，以所见发布 ID 建立正式学习上下文；记录请求固定课程、单元、发布版本与允许的控件。 +2. 改变一个已声明参数，核对实际运行事件、原请求编号和服务端回执；发送失败时保留同一请求重试，不把失败显示为已保存。 +3. 回读该学生的学习记录与当前完成状态，分别核对操作事实、完成规则和旧结果认定；导航成功或 URL 带有上下文不能替代这一步。 +4. 验证换版、开放条件变化、撤权、离页和重新进入；未经确认的记录不得静默丢弃，探索与预览不得写入正式课程结果。 + +原活动标记 `legacy-compatibility` 时，仅承诺其已实现的兼容入口与记录范围；资源配置版本不等于全部运行字节、运动状态或历史画面都可复现。验收结论分别记录导航、科学模型、操作事实和完成结果，具体日期与证据由 [03](../03-发布历史.md) 保存。 + ## 3. 科学模型说明 以下三段保留已经复核的公式、数据、限制与来源。本轮仅整理外围目录与指南，模型记录原文未改。 diff --git "a/doc/01-\345\274\200\345\217\221\350\200\205\346\211\213\345\206\214.md" "b/doc/01-\345\274\200\345\217\221\350\200\205\346\211\213\345\206\214.md" index 901a8369..31e316ac 100644 --- "a/doc/01-\345\274\200\345\217\221\350\200\205\346\211\213\345\206\214.md" +++ "b/doc/01-\345\274\200\345\217\221\350\200\205\346\211\213\345\206\214.md" @@ -1,12 +1,12 @@ # 星序 Astra — 开发者手册 -> **文档梗概**：说明正式门户、三个学习空间和教学后端的当前实现、数据边界、维护入口；第 13 章保留已确认但待实现的目标架构。 +> **文档梗概**：说明主站门户、三个学习空间、教学后端及独立职教子系统的当前实现、数据边界与维护入口；第 13 章保留七组目标架构图，并逐组对照当前实现与后续边界。 > > **具体规划法则**：代码和验证决定当前事实；业务规则、任务和进度只在 [02](02-更新规划.md) 维护，提交及历史验收只在 [03](03-发布历史.md) 维护。类型和接口字段链接权威代码，不再复制多份字段表。 > -> **当前基线**：业务代码沿用 2026-09-08 收口；正式前端为 `qianduan/`，FastAPI 为业务权威。2026-09-16 已进入持续开发：资源与模板、独立教学分叉、同步送审及冻结发布已完成本机功能联调；版本化检查点、作业重交与评分留档已接入；实验运行和后续查询/任务按 02 推进。 +> **当前基线**：以 `main` 提交 `b177706` 为本次代码核对基线。主站正式前端为 `qianduan/`，FastAPI 为主站教学业务权威；资源与模板、独立教学分叉、同步送审、冻结发布、版本化学习和评分历史均已有实现。教育方向入口、可选 AI 助教和 `zhijiao/` 独立职教栈也已进入代码。2026-09-17 研发暂停及当时未结束的验收保留为历史事实；本次仅更新文档，不表示恢复全部研发或完成后续验收。 > -> **最后一次更新时间**：2026-09-17 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -24,17 +24,17 @@ 10. [当前完成边界](#10-当前完成边界) 11. [新增内容与空间](#11-扩展接口与维护边界) 12. [文档职责](#12-其他权威文档) -13. [目标架构与七组设计图](#13-目标架构与设计待实现) +13. [目标架构与当前实现对照](#13-目标架构与当前实现对照) ## 1. 先用五分钟理解项目 -星序将交互学习资源与教学管理结合。当前优先服务单校 Web、本机毕业设计和竞赛展示；微信小程序、跨校平台和公网业务运营没有纳入已完成能力。 +星序将交互学习资源与教学管理结合。当前入口区分学科教育主站和职业教育：主站优先服务单校 Web、本机毕业设计和竞赛展示；职教是独立的情境教学与内容工作区，不复用主站的账号、课程和数据库。微信小程序、跨校统一平台和公网业务运营没有纳入已完成能力。下表角色与第 3—7 章教学流程均指主站。 | 对象 | 当前职责 | | --- | --- | | 学生 | 加入课程、阅读已授权发布、打开实验、提交作业和检查点、查看反馈、保存个人笔记 | | 教师 | 申请身份、创建课程、编排共享草稿、显式发布、管理成员、设置开放计划、批改 | -| 管理员 | 审核教师和课程资料、管理组织和账号；审计及后台任务有独立后端接口 | +| 管理员 | 审核教师身份和课程候选、承接旧课程资料审核、管理组织和账号；审计及后台任务有独立后端接口 | | 系统资源 | 工科 90、代码 18、未来 19，共 127 个活动身份；数量不等于独立高质量课程数量 | | 授课课程 | 教师组织的教学实例，拥有自己的成员、单元、发布和成绩；不能与资源目录混为一谈 | @@ -42,7 +42,7 @@ ### 2.1 运行时上下文 -源码在 `main`；`qianduan` 分支只保存编译后的 Pages 演示制品。两种构建共用页面和数据接口约定，实际数据源明确分开： +源码在 `main`；`qianduan` 分支只保存编译后的 Pages 演示制品。主站两种构建共用页面和数据接口约定，实际数据源明确分开；职教运行方式另见第 2.4 节： | 模式 | 产物与入口 | 权威数据 | | --- | --- | --- | @@ -52,16 +52,16 @@ ### 2.2 分层结构 -下图是当前实现。部署方式不改变 FastAPI 对权限、发布和学习结果的决定权。 +下图是主站当前分层。部署方式不改变 FastAPI 对主站权限、发布和学习结果的决定权。 ```mermaid flowchart TB - WEB["正式门户 qianduan
页面 / 状态 / Three.js"] - APIADAPTER["真实 API 适配器
Cookie 请求"] - DEMO["显式演示适配器
内存数据"] - LABS["labs 公开资源
原三个学习空间"] + WEB["主站门户 qianduan"] + APIADAPTER["真实 API / Cookie"] + DEMO["演示适配 / 内存数据"] + LABS["labs / 三个学习空间"] HTTP["FastAPI HTTP 适配"] - SERVICE["业务服务
授权 / 事务 / 查询"] + SERVICE["授权 / 事务 / 查询"] DB[("SQLite / MySQL 兼容模型")] WEB --> APIADAPTER WEB --> DEMO @@ -71,13 +71,29 @@ flowchart TB SERVICE --> DB ``` -数据服务入口是 [api-gateway.ts](../qianduan/src/services/api-gateway.ts)、[school-api.ts](../qianduan/src/services/school-api.ts) 和 [http-client.ts](../qianduan/src/services/http-client.ts)。网络失败不会自动切换为演示成功；页面不把凭据或学习正文存入普通浏览器存储，不缓存业务 API。 +数据服务入口是 [api-gateway.ts](../qianduan/src/services/api-gateway.ts)、[school-api.ts](../qianduan/src/services/school-api.ts) 和 [http-client.ts](../qianduan/src/services/http-client.ts)。主站正式模式的网络失败不会自动切换为演示成功；页面不把凭据或学习正文存入普通浏览器存储，不缓存业务 API。 ### 2.3 静态服务与业务服务的边界 -正式门户使用 TypeScript、Vite、原生 DOM、Three.js；原实验保留 JavaScript、Canvas、DOM 或 Three.js。后端使用 FastAPI、SQLAlchemy 与 Alembic。准确依赖版本由 lockfile 和配置决定。 +主站正式门户使用 TypeScript、Vite、原生 DOM、Three.js；原实验保留 JavaScript、Canvas、DOM 或 Three.js。主站后端使用 Python、FastAPI、SQLAlchemy 与 Alembic。准确依赖版本由 lockfile 和配置决定。 -Node/C++ 静态服务保留兼容及构建验证用途，不承担教学业务。当前本机入口 [local_preview.py](../backend/app/local_preview.py) 挂载构建后的门户及经过限制的公开目录，不能用仓库根目录作为任意静态文件根。 +仓库根部的 Node/C++ 静态服务保留兼容及构建验证用途，不承担主站教学业务。当前主站本机入口 [local_preview.py](../backend/app/local_preview.py) 挂载构建后的门户及经过限制的公开目录，不能用仓库根目录作为任意静态文件根。`zhijiao/apps/api/` 则是真实的独立业务服务，不能与这些静态服务混为一谈。 + +### 2.4 职教子系统与数据边界 + +主站 [main.ts](../qianduan/src/main.ts) 的教育方向选择可导航到职教入口；这一步只是进入另一个应用，不建立主站与职教之间的单点登录或数据同步。 + +| 层级 | 学科教育主站 | 职业教育子系统 | +| --- | --- | --- | +| 页面与交互 | `qianduan/`，TypeScript、原生 DOM、Vite、Three.js | `zhijiao/apps/web/`，React、TypeScript、Vite、Three.js | +| 业务接口 | `backend/app/`，Python、FastAPI；课程、审核、学习与成绩 | `zhijiao/apps/api/`，Node.js、TypeScript、Fastify；情境会话、角色协作、内容与发布 | +| 身份与授权 | 主站用户、会话、学校、课程成员关系 | 职教自己的主体、成员资格和会话；不自动继承主站身份 | +| 结构化数据 | SQLAlchemy 应用表，默认 SQLite，Alembic 管理迁移；另有 MySQL 验证配置 | 内容库使用 PGlite，保存来源、知识、素材、处理任务、案例草稿及发布 | +| 其他持久化 | 主站媒体文件与数据库中的取用关系 | 情境事件与多类业务记录还使用 JSONL 文件；不能只按 PGlite 表数理解全部状态 | + +按当前模型与全新临时库迁移核对，主站注册 **75 张应用表**，加 `alembic_version` 共 **76 张表**，迁移 head 为 `20260916_0064`；未计入 SQLite 内部对象。职教内容库定义 **14 张应用表**，加 `content_store_schema_migration` 共 **15 张表**；另有 JSONL 持久化，两侧不能相加当作同一个数据库。这个计数描述当前结构，不代表任一既有部署已经执行迁移。 + +主站实体入口是 [models](../backend/app/models/) 与 [alembic](../backend/alembic/)；职教内容表与迁移见 [migrations.ts](../zhijiao/packages/content-store/src/migrations.ts)、[store.ts](../zhijiao/packages/content-store/src/store.ts)，会话事件见 [file-event-store.ts](../zhijiao/apps/api/src/file-event-store.ts)，其他存储装配与业务路由见 [server.ts](../zhijiao/apps/api/src/server.ts)。目录职责见第 8 章，启动配置见 [04 部署指南](04-部署指南.md)。 ## 3. 角色、作用域与班级业务 @@ -95,7 +111,7 @@ Node/C++ 静态服务保留兼容及构建验证用途，不承担教学业务 ### 3.3 当前与目标的区别 -当前已有教师申请、课程资料审核、共享草稿、发布和选课。课程家族、内容同步、学校对候选内容快照的逐门/批量审核、换版补做仍是第 13 章及 02 的目标，不能把“资料审核通过”写成“每次正文修改均已审核”。 +当前已有教师申请、课程家族、独立教学分叉、共享草稿、同源内容同步、候选快照的逐项/批量审核、冻结发布和选课；换版后的结果沿用、补做与评分历史也已有后端及页面实现。旧课程资料审核继续承接兼容请求，不能把“资料审核通过”写成“每次正文修改均已审核”。第 13 章对照这些实现与尚未收口的实验入口、查询、任务和验收边界，正式任务仍以 02 为准。 ## 4. 三个学习空间与课程内容 @@ -108,6 +124,8 @@ Node/C++ 静态服务保留兼容及构建验证用途，不承担教学业务 内容成熟度不完全一致；部分活动身份共用模型。数学扩展、学习路径与共同质量标准见 [02 第 2.12—2.14 节](02-更新规划.md#212-实验端课程拓展与统一改进计划)，不能只用目录数量推断教学质量。 +这三个空间属于主站资源目录。`zhijiao/` 已有独立应用，但尚未注册为主站的第四个学习空间；教育方向入口不等于资源、身份或成绩已经互通。 + 力学和桥梁当前是直接实验，不能恢复已撤换的课程叙事层。科学计算与画面渲染分开，3D 动效不能替代物理或数学结果。双摆、色谱和机械臂的公式、假设、误差、样例和来源保留在 [15 号实验指南](01-子文档/15-学科实验与内容开发指南.md)。 ## 5. 前端页面、路由与可见交互 @@ -128,6 +146,8 @@ flowchart TB 门户使用 `#/overview`、`#/courses`、`#/course/{id}` 等路由；实验内部保留原 Router/PageRegistry 深链。两者不能共用一份可被页面任意改写的教学状态。 +进入学科教育后走上述门户流程；教育方向选择中的职业教育则导航到独立职教应用，不经过主站课程页面。 + ### 5.2 已经可见的交互能力 | 页面 | 实际行为 | @@ -137,13 +157,13 @@ flowchart TB | 教师课程 | 资料与共同教师、准入条件、送审、内容编排、版本查看/比较/恢复、成员、作业和开放计划 | | 学生学习 | 授权正文、锁定提示、携带发布 ID 的检查点、作业提交、退回与教师反馈 | | 个人资料与笔记 | 本人资料；笔记分页、保存、删除、导出和修订冲突 | -| 学校管理 | 教师申请、课程资料审核、账号停用/恢复、基本学校和班级管理 | +| 学校管理 | 教师申请、课程候选审核及旧资料审核、账号停用/恢复、基本学校和班级管理 | ### 5.3 生命周期与资源边界 页面和实验都有成对的进入、退出生命周期。监听器、观察器、定时器、请求和 GPU 资源随所属页面释放；迟到响应不能覆盖新页面或新课程状态。未保存草稿在离页前提示，写入结果不明时不盲目自动重发。 -图形层限像素密度、支持减少动态效果和基本画面降级。星盘切换、后台节流与容器尺寸变化不能影响业务身份。原实验的 owner 和清理契约仍由原注册表管理，不能因为新门户使用 iframe 就略过内部销毁。 +图形层限像素密度、支持减少动态效果和基本画面降级。星盘切换、后台节流与容器尺寸变化不能影响业务身份。原实验的 owner 和清理契约仍由原注册表管理；嵌入预览和完整页面导航都必须遵守各自的进入、退出与资源释放边界。 ### 5.4 正式门户的实现与数据适配 @@ -168,15 +188,17 @@ flowchart TB ### 6.1 API 领域 -权威接口注册位于 [router.py](../backend/app/api/router.py)，DTO 在 [schemas](../backend/app/schemas/)，数据库模型在 [models](../backend/app/models/)。当前基础教学保留 `/api` 与 `/api/v1`；`/api/v2` 已提供资源、课程草稿、派生、同步、候选审核、发布、媒体、学习上下文和结果历史接口；实验运行对接及后续治理按 02 继续实施。 +主站权威接口注册位于 [router.py](../backend/app/api/router.py)，DTO 在 [schemas](../backend/app/schemas/)，数据库模型在 [models](../backend/app/models/)。当前基础教学保留 `/api` 与 `/api/v1`；`/api/v2` 已提供资源、课程草稿、派生、同步、候选审核、发布、媒体、学习上下文、结果历史和实验运行接口。接口路径版本、课程的 `workflow_generation` 与结果的 `result_contract_version` 分别表达不同代际，不能看到旧 URL 就断言绕开新规则，也不能仅凭新 URL 判定全部页面已接通。 | 领域 | 实现与维护入口 | | --- | --- | | 会话、用户、本人笔记 | `auth_sessions.py`、`users.py`、`user_profile.py`、[user_notes.py](../backend/app/services/user_notes.py) | | 身份、组织和课程准入 | `teacher_applications.py`、`course_authoring.py`、`course_information_reviews.py`、`course_enrollments.py` | -| 草稿与不可变发布 | [content_platform.py](../backend/app/services/content_platform.py)、[content_platform schema](../backend/app/schemas/content_platform.py) | +| 资源、草稿与教学分叉 | [learning_resources.py](../backend/app/services/learning_resources.py)、[course_drafts_v2.py](../backend/app/services/course_drafts_v2.py)；原内容模型与兼容入口保留在 [content_platform.py](../backend/app/services/content_platform.py) | +| 同步、候选与冻结发布 | [course_sync.py](../backend/app/services/course_sync.py)、[course_candidates.py](../backend/app/services/course_candidates.py)、[course_reviews_v2.py](../backend/app/services/course_reviews_v2.py)、[course_publications_v2.py](../backend/app/services/course_publications_v2.py) | | 单元开放与完成统计 | [course_release_plans.py](../backend/app/services/course_release_plans.py)、[course_learning_metrics.py](../backend/app/services/course_learning_metrics.py) | | 作业与评分 | [assignment_history.py](../backend/app/services/assignment_history.py) 为提交/评分权威；[submissions.py](../backend/app/api/endpoints/submissions.py) 提供兼容读取与传输 | +| 上下文、结果与历史回读 | [learning_contexts.py](../backend/app/services/learning_contexts.py)、[learning_results.py](../backend/app/services/learning_results.py)、[learning_history_queries.py](../backend/app/services/learning_history_queries.py) | | 学习事实与运行 | [learning_evidence.py](../backend/app/services/learning_evidence.py)、[learning_activity_runtime.py](../backend/app/services/learning_activity_runtime.py)、`course_completion.py` | | 管理、任务与审计 | [admin.py](../backend/app/api/endpoints/admin.py)、[background_tasks.py](../backend/app/services/background_tasks.py)、`audit.py` | | 代码学习 | [code_judge.py](../backend/app/services/code_judge.py)；浏览器预检不等于正式隔离判题 | @@ -187,9 +209,9 @@ flowchart TB 检查点尝试、作业批改与实验操作是不同的完成依据。页面提交操作事实，服务端按规则决定完成；浏览次数、停留时间和装饰动画不等于掌握。 -学生打开正文时绑定发布 ID，发生冲突不能悄悄把尝试投到新版。已发布内容和历史版本读取仍受当前成员关系及开放计划约束：隐藏单元不返回，锁定单元只返回提示，不包含原题目、答案或媒体正文。 +学生打开正文时绑定发布 ID，发生冲突不能悄悄把尝试投到新版。v2 发布正文、学习上下文和媒体入口按当前成员关系及开放计划校验：隐藏单元不返回，锁定单元不提供可学习正文。旧作业兼容读取尚有返回锁定任务描述的缺口，不能据此宣称所有读取路径已经满足相同边界；具体收口范围见第 10 章及 02。 -既有运行已固定课程、单元、用户、运行和规则坐标；统一学习上下文与不可变发布绑定仍由 D 批次接入。学习者命令序号与服务端事实序号是两种游标：服务端派生事件会增加事实序号，但不占用下一次学习者命令序号。幂等重放保持原事实位置，不能把两种序号合成一个计数器。 +既有运行已固定课程、单元、用户、运行和规则坐标；v2 运行服务通过学习上下文进一步绑定实际发布、资源版本和声明参数。学习者命令序号与服务端事实序号是两种游标：服务端派生事件会增加事实序号，但不占用下一次学习者命令序号。幂等重放保持原事实位置，不能把两种序号合成一个计数器。 恢复必须校验运行身份、快照和配套事实元数据；缺失、漂移或无法确认的批量待发送记录应要求重新核验，不把未经确认的浏览器数据当成服务器结果。活动适配器采用准备/返回、运行时成功后再提交的边界，不能宣称这个约定能回滚任意外部副作用。相关运行、恢复、并发绑定与失败分支由机器契约和行为测试维护；结构校验本身不证明学生操作的真实性。 @@ -204,19 +226,19 @@ flowchart TB - 开放计划变更后使用最近有效的规则绑定统计完成，不把已有完成数清零。 - 已新增本人笔记及资料编辑修订迁移 `0059`；`0060` 修复旧的发布单元派生状态。迁移不删除原学习事件。 -实体表与外键以模型为准；当前唯一迁移 head 是 `20260916_0064`。0061 增加资源版本、独立课程家族、单元来源、修订/修改批次/候选/审核项和幂等发布回执表；旧课程逐门建立独立根，旧发布的候选引用保持空，不补造审核。0062 分离课程设置草稿与通用操作回执，0063 保存不可变媒体文件及课程取用关系。0064 增加学习上下文、作业尝试、评分历史和结果认定；旧证据与投影保留来源，新的发布完成统计读取统一结果索引。实验运行的接线仍在推进，不能把旧投影直接当作新版完成状态。 +实体表与外键以模型为准；当前唯一迁移 head 是 `20260916_0064`，主站应用表与迁移表的计数见第 2.4 节。0061 增加资源版本、独立课程家族、单元来源、修订/修改批次/候选/审核项和幂等发布回执表；旧课程逐门建立独立根，旧发布的候选引用保持空，不补造审核。0062 分离课程设置草稿与通用操作回执，0063 保存不可变媒体文件及课程取用关系。0064 增加学习上下文、作业尝试、评分历史和结果认定；旧证据与投影保留来源，新的发布完成统计读取统一结果索引。声明参数运行已接入后端，原实验完整页面导航仍需补齐记录接线；不能把旧投影直接当作新版完成状态。 ### 6.4 本轮课程工作流 -2026-09-16 的当前工作区已建立 v2 课程草稿、独立教学分叉、公共内容同步预览、候选审核、冻结发布与历史恢复接口；正式页面已完成三角色真实 API 联调，开发提交与验证范围见 [03 本阶段记录](03-发布历史.md#104-课程创作同步审核与冻结发布)。这不表示第 13 章全部目标已经完成。任务状态以 [02 当前任务状态](02-更新规划.md#3-当前任务状态) 为准。 +2026-09-16 阶段建立的 v2 课程草稿、独立教学分叉、公共内容同步预览、候选审核、冻结发布与历史恢复接口已纳入当前 `main`。正式页面曾完成三角色真实 API 联调，提交与当时的验证范围见 [03 本阶段记录](03-发布历史.md#104-课程创作同步审核与冻结发布)。历史联调不表示当前全部检查通过，也不表示第 13 章全部目标已经完成。任务状态以 [02 当前任务状态](02-更新规划.md#3-当前任务状态) 为准。 - [课程用例入口](../backend/app/api/endpoints/course_workflow.py)只做传输与异常转换；草稿、同步、审核和发布分别有服务模块。v1 发布请求进入同一候选门禁，通用内容写入口不能改写课程路径。 - 发布绑定的是候选所引用的不可变修订。送审后继续编辑时，发布旧候选不会覆盖后续草稿。逐项结论和选中范围内的原子操作分开处理；成功回执保存与公开响应一致的结果。 - 当前共同教师授权、创建者和准入班级也进入候选依赖检查。审核后授权变化使旧候选失效，不能借发布恢复已撤销权限；再次送审会明确展示当前授权与拟发布设置的差异。 - [媒体服务](../backend/app/services/course_media.py)保存不可变文件与课程取用记录。支持图片、音频、视频及 PDF；每文件最多 12 MiB，每课程上传累计最多 100 MiB。素材不经外部 URL 代理，PDF 下载展示，学生访问需携带实际发布版和单元身份并通过成员与开放检查。 -- 草稿设置、通用回执与文件存储分别由 0062、0063 迁移承接；已有新数据时拒绝有损降级。尚未运行本轮真实 MySQL 迁移与并发验收。 +- 草稿设置、通用回执与文件存储分别由 0062、0063 迁移承接；已有新数据时拒绝有损降级。当前 CI 已有 MySQL 迁移和既有专项证据，但该专项不覆盖全部 v2 课程流程；完整流程的 MySQL 与并发验收仍需单独收口。 -结果沿用与补做现已接通检查点、作业和成绩回读；实验运行、跨课程关联与统一汇总继续按 D—E 批次实施。 +结果沿用与补做现已接通检查点、作业和成绩回读；声明参数运行有后端实现，原实验页面接线、跨课程关联与统一汇总仍按 02 保留后续边界。 ### 6.5 版本化学习、作业与评分历史 @@ -228,7 +250,7 @@ flowchart TB 正式页面由 [LearningWorkspace](../qianduan/src/portal/learning-workspace.ts)、[AssignmentWorkspace](../qianduan/src/portal/assignment-workspace.ts) 和 [StudyGateway](../qianduan/src/portal/study-types.ts)承接学习、历史与评阅，真实接口和内存演示分开。旧写接口委托同一服务；对已有发布的作业，缺少学习上下文与修订条件会明确要求更新页面，不替学生推定所见版本。 -0064 能恢复旧提交与审计中可确认的分数；未知旧发布、满分及已脱敏反馈继续标为未知。出现新历史事实后拒绝有损回退。学习结果与学生自己的历史回读已经验证；声明参数运行已由下一节接入；退出课程后的历史目录入口及真实 MySQL/并发验收仍有后续工作，不能据本节宣称整个 D—F 阶段完成。 +0064 能恢复旧提交与审计中可确认的分数；未知旧发布、满分及已脱敏反馈继续标为未知。出现新历史事实后拒绝有损回退。学习结果与学生自己的历史回读已有实现及历史验证；声明参数运行的边界见下一节。退出课程后的历史目录入口及完整 v2 流程的 MySQL/并发验收仍有后续工作，不能据本节宣称整个 D—F 阶段完成。 ### 6.6 声明参数的实验运行 @@ -236,9 +258,15 @@ flowchart TB 资源更新是追加版本，不改写 v1 原件。[资源更新清单](../backend/app/catalogue/resource-updates.v1.json)为函数图像增加参数记录，为原力学实验声明数值控件。可安装目录仍为 127 个活动和 2 个模板，完整空库安装包含 132 个资源版本；版本数不是课程数。未声明可靠记录能力的资源仍采用检查点或作业完成。新观察快照只保存参数观察，不宣称恢复完整物理运动或所有旧运行器字节。 -[ActivitySession](../qianduan/src/domain/activity-session.ts)串行发送并保留原请求重试；离页释放监听器与未发送内存队列，不把观察或答案持久化至普通浏览器存储。[CoursePlayer](../qianduan/src/portal/course-player.ts)对课程中的原实验入口执行完整页面导航，不再在课程页内嵌套 iframe；导航地址带有本次学习上下文和返回位置，实验完成后可用浏览器后退返回课程。原求解器不承担教学授权或评分。原力学重力滑杆的步长已由 50 改为 10，以避免默认 980 被浏览器归整成 1000；原保护基线不变，有独立的一致性回归与精确变更记录。 +[ActivitySession](../qianduan/src/domain/activity-session.ts)串行发送并保留原请求重试；离页释放监听器与未发送内存队列，不把观察或答案持久化至普通浏览器存储。[CoursePlayer](../qianduan/src/portal/course-player.ts)对课程中的原实验入口执行完整页面导航，不再在课程页内嵌套 iframe；导航地址带有本次学习上下文和返回位置，可用浏览器后退返回课程。当前该分支跳过门户内运行会话，公开实验页也尚未消费传入的上下文，因此不能将完整页面打开视为已完成正式操作记录。原求解器不承担教学授权或评分。原力学重力滑杆的步长已由 50 改为 10，以避免默认 980 被浏览器归整成 1000；原保护基线不变，有独立的一致性回归与精确变更记录。 + +2026-09-17 用户主动暂停。当时已有定向验证与页面操作记录，最后页面复看和其余阶段仍未结束，实际范围见 [03 暂停快照](03-发布历史.md#106-实验操作版本绑定与暂停快照)。这些证据仅适用于各自提交和场景；当前页面导航缺口、配置边界与回归状态仍需分别处理。本次文档更新不恢复产品研发，后续范围与授权仍按 02 记录。 + +### 6.7 可选 AI 助教 + +主站已有 [ai_tutor.py](../backend/app/api/endpoints/ai_tutor.py) 与原实验公共界面的 [ai-tutor.js](../shared/js/ai-tutor.js)。配置与聊天接口都要求主站登录；默认关闭，只有启用开关、服务端密钥和受支持的 DeepSeek provider 同时满足才对外可用。模型、地址和超时由 [后端配置](../backend/app/core/config.py)管理；密钥只保留在服务端，配置接口返回启用状态、provider 和启用时的模型名。 -2026-09-17 用户主动暂停。上述主链路已验证，暂停前的最后页面复看和其余阶段仍未结束，实际范围见 [03 暂停快照](03-发布历史.md#106-实验操作版本绑定与暂停快照)，恢复安排只认 02。 +当前每次请求只发送本次问题与浏览器提供的空间、路由、页面标题，服务端构造系统提示后调用模型。界面显示的消息列表不构成服务端多轮会话；接口没有读取实时实验参数、课程正文、学生结果或学习上下文，也没有持久化聊天历史。它可以作为已登录用户的可选页面问答入口，不能写成已接通学情诊断、实验自动观测、自动批改或跨主站/职教的统一助教。 ## 7. 关键业务旅程 @@ -256,42 +284,49 @@ flowchart TB ### 7.4 当前验证范围 -2026-09-08 已完成真实建课、审核发布、学生提交、教师批改、重启后回读成绩、笔记与检查点完成回读。具体证据、测试计数和部署提交只在 [03 本阶段记录](03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装) 保存；它们不是后续任一修改的自动验收结果。2026-09-16 新课程工作流的定向验证与浏览器证据见 [03 第 10.4 节](03-发布历史.md#104-课程创作同步审核与冻结发布)。 +2026-09-08 已完成真实建课、审核发布、学生提交、教师批改、重启后回读成绩、笔记与检查点完成回读。具体证据、测试计数和部署提交只在 [03 本阶段记录](03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装) 保存；它们不是后续任一修改的自动验收结果。2026-09-16 新课程工作流的定向验证与浏览器证据见 [03 第 10.4 节](03-发布历史.md#104-课程创作同步审核与冻结发布)。当前基线仍有待归因或待修复的回归失败，不能将历史通过记录合并成当前全量通过结论。 ## 8. 仓库入口与开发顺序 | 目录 | 维护对象 | | --- | --- | -| `qianduan/` | 唯一正式门户，真实/演示适配与部署制品 | +| `qianduan/` | 主站正式门户；`src/portal` 承接教学页面，`src/services` 连接 API，`src/domain` 与 `src/render` 分管业务状态和图形；`scripts` 负责资源及制品 | | `pages/`、`shared/`、`index.html` | 保留实验、公共资源入口与兼容角色代码 | | `codevis/` | 代码空间与固定版本浏览器运行时 | -| `backend/app/` | HTTP 适配、业务服务、模型、配置与数据库访问 | +| `backend/app/` | 主站 Python 后端；`api` 做 HTTP 适配，`services` 承接授权与用例，`models`/`schemas` 分管存储与传输类型，`core`/`db` 提供配置和数据库访问 | +| `backend/app/catalogue/` | 主站空间元数据、活动资源与追加资源版本清单 | | `backend/alembic/` | 结构及派生状态迁移 | +| `zhijiao/apps/web/` | 职教 React 页面、独立演示入口与交互工作区 | +| `zhijiao/apps/api/` | 职教 Fastify 业务接口、身份、情境会话与文件持久化装配 | +| `zhijiao/packages/` | 职教内部共享包，包括领域协议、教学与场景逻辑、内容库和运行能力；不复用主站 ORM | | `backend/tests/`、`qianduan/tests/`、`tools/tests/` | 对应业务、门户和原实验合同 | | `tools/templates/`、`tools/quality/` | 新实验模板与注册、模型、素材、保护检查 | | `server/` | 兼容静态服务、C++ 构建及制品清单 | | `doc/` | 当前必要文档；旧报告和冻结规划从 Git 追溯 | -新功能先定位 02 的任务及相关 DTO、服务和页面；修改权威实现，补最近的行为回归。不要把旧角色页面发展成第二个正式门户。大型控制器按业务职责逐步拆分，避免用全面换框架代替具体改进。 +主站改动先沿“门户页面 → API 适配 → FastAPI 用例 → 模型/迁移”定位；职教改动沿“React 页面 → Fastify 路由 → 共享领域包/内容库或文件存储”定位。两条链路分别核对身份、状态和验证方式，不能只因放在同一仓库就交叉写入。 + +新功能先定位 02 的任务及相关 DTO、服务和页面；修改权威实现，补最近的行为回归。不要把主站旧角色页面发展成第二个正式门户。大型控制器按业务职责逐步拆分，避免用全面换框架代替具体改进。 ## 9. 启动与最小验证 ### 9.1 推荐启动 -在仓库根目录执行： +主站在仓库根目录执行： ```powershell powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 ``` -成功后从 `http://127.0.0.1:9001/` 访问真实版本。数据目录、管理员引导、依赖约束、演示构建与 Pages 发布统一见 [04 部署指南](04-部署指南.md)，避免在多个手册重复配置细节。 +成功后从 `http://127.0.0.1:9001/` 访问主站真实版本。主站数据目录、管理员引导、依赖约束、演示构建与 Pages 发布，以及职教独立服务的运行入口，统一见 [04 部署指南](04-部署指南.md)，避免在多个手册重复配置细节。职教工作区命令以 [package.json](../zhijiao/package.json) 为准，不能假定主站 Python 进程已经启动职教 API。 ### 9.2 按改动选择验证 | 改动 | 最接近的验证 | | --- | --- | -| 后端业务、权限或数据库 | `.venv/Scripts/python.exe -m pytest backend`，先定向，再按影响扩大 | -| 正式门户 | `npm --prefix qianduan test`、`run build`、`run verify:package`；流程变更补浏览器操作 | +| 主站后端业务、权限或数据库 | `.venv/Scripts/python.exe -m pytest backend`，先定向，再按影响扩大 | +| 主站正式门户 | `npm --prefix qianduan test`、`run build`、`run verify:package`；流程变更补浏览器操作 | +| 职教页面、API 或共享包 | 在 `zhijiao/` 按其 package scripts 选择对应包的类型、测试与构建检查；主站 pytest 不覆盖职教业务 | | 原实验、目录或生命周期 | 受影响 `tools/tests/*`、实验保护检查；阶段收口再运行 `npm test` | | 演示打包 | `build:demo`、`verify:demo` 与目标子路径真实打开 | | 文档 | 文件、目录、相对链接、锚点、图文语义及 `git diff --check`；触及工具引用时补关联合同 | @@ -300,15 +335,17 @@ powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 ## 10. 当前完成边界 -当前可展示正式星云门户、三角色基础教学流程、127 项资源目录、本机持久化记录与静态演示。学校管理新页面只覆盖必要审核和组织操作，不覆盖所有旧运维面板。 +当前主站可展示正式星云门户、三角色基础教学流程、127 项活动资源目录及 2 个模板、本机持久化记录与静态演示。学校管理新页面只覆盖必要审核和组织操作，不覆盖所有旧运维面板。职教已有独立 React/Fastify 应用与自己的内容、会话存储；两端入口可达不等于账号、课程和学习结果已经统一。 + +已接通课程家族、同源同步、候选审核与文件服务；检查点与作业的跨版本认定、补做和评分历史已有实现。声明参数的实验运行服务已经存在，当前仍有三项具体收口边界：原实验完整页面导航尚未接回正式运行记录；函数模板允许空参数时仍可发布“实验操作”完成条件，运行中却无可记录控件；旧作业兼容读取可返回锁定单元的任务描述。这些问题不能用已有后端接口或历史联调通过记录代替修复与复验。 -已接通课程家族、同源同步、候选审核与文件服务；检查点与作业的跨版本认定、补做和评分历史已接通。声明参数的实验运行已接入；退出课程后的历史目录、校内课程发现、统一跨课程路径及后续统计/任务尚未完成。公网业务后端、真实课堂效果、正式隔离执行与完整移动端精调未作为已完成能力。 +退出课程后的历史目录、校内课程发现、统一跨课程路径及发布后的通知/汇总/导出任务尚未完成。通用后台任务设施已存在，但不表示这些课程后续任务已经入队。主站基础 AI 问答可选启用，实时实验与学情接入仍未完成。公网业务后端、真实课堂效果、正式隔离执行与完整移动端精调未作为已完成能力。 资源数量不是课程质量结论；前三类学习空间仍存在模型与解释差异。具体改进按 02，不再把历史“精品课优先”“所有实验冻结”“固定行数即架构质量”当成当前产品规则。 ## 11. 扩展接口与维护边界 -新增主题与新增学习空间是不同工作。`Course.galaxy_key`、`subject_key` 可容纳新分类，但正式导航、教师选项、活动路由、打包目录和官方活动白名单仍有三空间配置。 +新增主题与新增学习空间是不同工作。`Course.galaxy_key`、`subject_key` 可容纳新分类，空间元数据与纯前端 bundle 已有扩展机制；当前安装清单仍只注册三个基础空间。导航、教师选项、活动路由、打包目录和官方活动白名单必须一起核对，不能只增加一个分类字符串。 | 扩展位置 | 当前权威代码 | | --- | --- | @@ -319,7 +356,7 @@ powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 | 原实验模型与注册 | [15 号指南](01-子文档/15-学科实验与内容开发指南.md) | | 旧模块边界门禁 | [机器契约](../tools/architecture/v76-module-boundaries.json)、[边界合同](../tools/tests/architecture-boundary-contract.cjs) | -空间元数据已集中至 [learning-spaces.v1.json](../backend/app/catalogue/learning-spaces.v1.json)，正式导航与教师分类由它生成。新增纯前端 bundle 使用独立空间 key、space: 路由、extensions//public 制品及 astra-activities.json 目录，构建与后端安装均检查身份、入口和路径范围。已有三个空间仍保留原运行器；新空间的正式学习记录仍需按声明能力接入，不因能打开页面就自动计分。适用学段、难度与先修关系也不能都塞进星系名称。 +空间元数据已集中至 [learning-spaces.v1.json](../backend/app/catalogue/learning-spaces.v1.json)，正式导航与教师分类由它生成。新增纯前端 bundle 使用独立空间 key、`space:` 路由、`extensions//public` 制品及 `astra-activities.json` 目录，构建与后端安装均检查身份、入口和路径范围。这是扩展约定，当前仓库没有已注册的 `extensions/` 空间；`zhijiao/` 也未通过这条链路合入主站目录。已有三个空间仍保留原运行器；新空间的正式学习记录仍需按声明能力接入，不因能打开页面就自动计分。适用学段、难度与先修关系也不能都塞进星系名称。 机器契约中的旧任务号、候选处置和路径白名单是兼容追溯信息，当前改动范围由用户授权、02 与有效行为回归决定。文档精简不删除运行时保护检查或科学模型依据。 @@ -344,21 +381,22 @@ powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 | [05 UI 规范](05-UI规范模板.md) | 修改正式门户和实验视觉 | | [15 实验指南](01-子文档/15-学科实验与内容开发指南.md) | 新实验接线、科学模型与数值复核 | -## 13. 目标架构与设计（待实现） + +## 13. 目标架构与当前实现对照 -本章按项目负责人要求展开完整目标架构与七组设计图。资源目录/模板预览与部分存储模型已落实，现状见前文，其余仍按 02 待实施任务推进。第 1—12 章及其实现子文档继续描述可核实的当前系统；本章展示完整目标：资源、谱系、同步和候选发布已进入开发提交，学习结果认定与查询/任务等部分仍在推进；图本身不表示全部上线。业务规则、正式任务和验收条件只在 [02 完整实施方案](02-更新规划.md#2-完整实施方案) 与 [当前任务状态](02-更新规划.md#3-当前任务状态) 维护。 +本章保留按项目负责人要求展开的主站目标架构与七组设计图，并在每组图后说明代码已经实现什么、哪些尚未完整验收、哪些仍是后续目标。资源、谱系、同步、候选发布、学习上下文和结果认定均已有实现；统一查询、发布后任务及部分页面接线仍有缺口。图中的完整链路不表示全部上线，实体概念也不必与物理表一一对应；职教的独立业务不纳入这些主站图。业务规则、正式任务和验收条件只在 [02 完整实施方案](02-更新规划.md#2-完整实施方案) 与 [当前任务状态](02-更新规划.md#3-当前任务状态) 维护。 -| 对照项 | 当前实现起点 | 本轮目标 | +| 对照项 | 当前已有实现 | 尚待收口或后续目标 | | --- | --- | --- | -| 内容与课程 | 活动目录、课程单元、共享草稿和不可变发布 | 增加系统资源/模板版本、课程家族、教学分叉和稳定内容来源 | -| 审核 | 课程信息审核与教师内容发布分离 | 学校审核冻结的课程候选及其影响，支持逐项与批量批复 | -| 同步 | 页面有版本差异和影响预演 | 后端按本人名下同源内容产生跨课程同步计划与修改批次 | -| 学习 | 旧事件与证据、运行和投影并存 | 明确学习上下文、尝试/评分历史和新版对旧结果的认定 | -| 客户端 | `/api`、`/api/v1` 与现有页面 | 增加 `/api/v2`，兼容读取与统一发布检查 | +| 内容与课程 | 系统资源/模板版本、共享草稿、课程家族、教学分叉和稳定内容来源 | 资源质量、空参数与完成条件的边界、完整性能及并发验收 | +| 审核 | 冻结候选、逐项/批量批复、教师显式发布和幂等回执 | 完整 v2 流程的 MySQL、并发与故障验收 | +| 同步 | 后端计算同源内容差异、冲突、学习影响并生成修改批次 | 真实规模与全部并发失效场景验收 | +| 学习 | 学习上下文、尝试/评分历史、统一结果及沿用认定、声明参数运行服务 | 原实验完整页面接线、退出课程后的历史目录、统一查询与解释 | +| 客户端 | `/api/v2` 与正式页面，`/api`、`/api/v1` 保留兼容职责 | 兼容读取权限边界一致、后续查询/任务页面；不以历史通过记录替代当前回归 | ### 13.1 系统分层与模块职责 -第一组图描述校内目标系统的职责方向。图中的箭头表示目标调用或数据连接，不是已完成状态。 +第一组图描述主站校内目标系统的职责方向。图中的箭头表示目标调用或数据连接，统一查询与新增后台任务连接仍含待实现部分。 ```mermaid flowchart TB @@ -368,7 +406,7 @@ flowchart TB ADMIN["学校审核与管理工作台"] STUD["学生选课、学习与结果回读"] end - API["HTTP 适配与学习上下文
新增 api/v2，兼容既有接口"] + API["HTTP / 学习上下文"] AUTH["身份、学校、课程关系与操作授权"] subgraph USECASE["业务用例与事务边界"] RESOURCE["资源与模板配置"] @@ -377,11 +415,11 @@ flowchart TB REVIEW["候选审核与发布"] LEARN["学习尝试、评价与结果认定"] end - QUERY["统一查询与统计
课程关联、下一步与解释"] - DB[("关系数据库
现有模型与有映射的迁移")] + QUERY["统一查询 / 统计 / 解释"] + DB[("关系数据库 / 迁移")] AUDIT["审计与可追溯记录"] QUEUE["持久化后台任务"] - WORKER["已有 worker 扩展
站内通知、汇总与导出"] + WORKER["worker / 通知 / 汇总 / 导出"] ASSETS["资源版本与模板运行制品"] SYS --> API TEACH --> API @@ -409,6 +447,7 @@ flowchart TB WORKER --> DB ``` +- **实现对照**：资源、创作、同步、审核、发布、上下文和学习结果已有对应服务；v2 与兼容 HTTP 入口并存，关系模型及迁移已落库。通用任务队列与 worker 已存在，但课程发布后的通知、汇总、导出尚未接线；统一跨课程查询仍是后续目标。既有用例测试不等于这些目标已完成负载和并发验收。 - **职责**：HTTP 层只做请求/响应适配；业务用例拥有事务；查询不产生第二套完成真值；后台任务处理已持久化的后续工作。 - **数据来源**：现有认证、学校、课程、发布、证据与任务模型，加上经过迁移的新版本/谱系关系；前端不自行声明身份或“已审核”。 - **关键约束**：单校使用；系统资源和校本课程具有不同访问边界；业务写入与审计、任务入队保持一致；外部投递不因新站内任务而开启。 @@ -416,7 +455,7 @@ flowchart TB ### 13.2 系统资源、模板与课程分叉关系 -第二组图区分系统原件、模板、来源和使用实例。实体及字段是目标概念关系，不是本次新增的数据库表。 +第二组图区分系统原件、模板、来源和使用实例。实体及字段表达概念关系，物理模型以代码为准，不能按图中的名称逐一寻找同名表。 ```mermaid erDiagram @@ -470,6 +509,7 @@ erDiagram **高一版与高二版**是同一家族中的两个课程对象，有不同课程 ID、昵称、设置、名单和发布历史；**高一版修订 1、修订 2**属于同一课程的内部修订。两者不能共用一个“版本号”字段或依靠学科名区分。 +- **实现对照**：[资源模型](../backend/app/models/learning_resource.py)保存资源及追加版本，[课程工作流模型](../backend/app/models/course_workflow.py)保存家族与修订，[课程模型](../backend/app/models/course.py)保存单元及内容块来源；模板配置与内容实例通过资源版本、正文块和来源映射表达，不另设图中每个概念的同名表。独立派生及不复制学生记录已有实现；更多模板、内容质量与配置边界仍需按场景验收。 - **职责**：资源版本保存原件与运行依据，模板定义允许修改的能力，分叉保存教学安排，实例表示某处具体使用。 - **数据来源**：受控的资源取用与派生操作；来源身份由服务端建立。纯文字块不要求引用运行资源，但仍有自己的实例与来源身份。 - **关键约束**：同一资源可以出现多次，实例和学习结果独立；取用不复制学生记录；相同标题、模板或学科不自动产生同源关系。 @@ -530,6 +570,7 @@ erDiagram } ``` +- **实现对照**：0061—0064 已建立课程修订、修改批次、候选、审核项、发布关联、学习上下文、作业尝试、评分历史和结果认定。图中的 `LEARNING_ATTEMPT` 是概念统称，实际由检查点尝试、作业尝试和运行事实等分别承接。旧内容发布、提交摘要与证据投影继续兼容；它们不能替代新历史来源。完整迁移回退、并发及跨库验收仍按 02 逐项确认。 - **职责**：一个修改批次有多个审核项，每项对应一门课程的候选。审核不直接改变学生发布指针；发布只消费已通过的候选。 - **数据来源**：候选固定内容、配置、资源版本和补做策略；学习尝试绑定实际读取的发布版本；结果认定引用既有事实，不修改原事实。 - **关键约束**：审核后的草稿修改不能进入既有候选；补做和再次评分生成新记录；回滚也生成新修订。该图不把已有 `transferred` 状态重新定义为版本继承。 @@ -541,28 +582,29 @@ erDiagram ```mermaid flowchart TD - START["教师修改源课程并选择同步"] --> SCOPE["校验源课程归属
筛选本人名下的同源目标"] - SCOPE --> DELTA["提取本次修改的允许字段
不传播名单、章节增删与排序"] + START["教师选择同步"] --> SCOPE["校验归属 / 筛选同源目标"] + SCOPE --> DELTA["提取允许同步的字段"] DELTA --> MATCH{"目标存在对应来源内容？"} - MATCH -- "否" --> SKIP["记录跳过
不补插内容"] + MATCH -- "否" --> SKIP["跳过 / 不补插内容"] MATCH -- "是" --> SAME{"目标已经是新内容？"} SAME -- "是" --> NOOP["记录无需修改"] SAME -- "否" --> BASE{"目标仍等于修改前内容？"} BASE -- "是" --> PATCH["加入可同步修改"] - BASE -- "否" --> CONFLICT["列出已有不同修改
由教师选择保留或替换"] - SKIP --> PREVIEW["逐课程预览修改、跳过、冲突与学习影响"] + BASE -- "否" --> CONFLICT["冲突 / 教师选择保留或替换"] + SKIP --> PREVIEW["逐课差异与学习影响"] NOOP --> PREVIEW PATCH --> PREVIEW CONFLICT --> PREVIEW PREVIEW --> RESOLVED{"冲突及其他待审版本已明确处理？"} - RESOLVED -- "否" --> WAIT["等待处理
不写入候选"] + RESOLVED -- "否" --> WAIT["等待处理 / 不写候选"] RESOLVED -- "是" --> CONFIRM["教师一次确认提交"] CONFIRM --> RECHECK{"源和目标代际、权限仍有效？"} - RECHECK -- "否" --> RETRY["明确提示过期或权限变化
保留草稿，重新预览"] - RECHECK -- "是" --> SAVE["事务内生成修改批次
及各课程的冻结候选"] - SAVE --> KEEP["现有学生发布版本保持原样
进入学校审核"] + RECHECK -- "否" --> RETRY["保留草稿 / 提示重新预览"] + RECHECK -- "是" --> SAVE["事务生成批次与冻结候选"] + SAVE --> KEEP["保留当前发布 / 进入审核"] ``` +- **实现对照**：[course_sync.py](../backend/app/services/course_sync.py)已经按服务端来源映射比较修改前值、新值和目标值，并处理跳过、无变化、可同步与冲突；[course_candidates.py](../backend/app/services/course_candidates.py)复验后建立批次及候选，页面承接预览和冲突决定。名单、章节增删与排序不随公共内容传播。业务分支已有定向覆盖，真实规模与完整并发验收仍不能由此推定完成。 - **职责**：匹配来源、比较本次改动前值/新值/目标值、输出可理解的预览；只有确认且复验成功后才提交。 - **数据来源**：源草稿代际、目标草稿/发布基础、服务端来源映射、课程归属及当前学生事实。 - **关键约束**：高二版没有三角内容就跳过；有复数内容才比较；改名和重排不改变匹配；他人课程和无关同名课程不进入可修改目标。 @@ -585,6 +627,7 @@ stateDiagram-v2 Submitted --> Approved: 学校通过该项 Submitted --> Rejected: 学校退回该项 Submitted --> Withdrawn: 教师撤回该项 + Approved --> Withdrawn: 发布前教师撤回 Approved --> Published: 教师发布已通过快照 Rejected --> [*] Withdrawn --> [*] @@ -604,14 +647,15 @@ stateDiagram-v2 end note ``` +- **实现对照**：[course_reviews_v2.py](../backend/app/services/course_reviews_v2.py)与 [course_publications_v2.py](../backend/app/services/course_publications_v2.py)已实现候选审核和独立发布；发布前已通过项也可撤回。图中的“已发布”是由发布包关联表达的业务状态，不表示审核项另有一个同名状态值。资料审核是兼容路径，当前审核已覆盖候选正文与策略；完整并发及 MySQL 验收仍见 02。 - **职责**：每项保存候选、审核人、意见与结论，批次提供来源和影响范围视图。 - **数据来源**：明确冻结的候选 ID 与摘要，不从教师当前可变草稿反推“学校审过什么”。 - **关键约束**：退回、撤回与发布后的历史均保留；再次送审是新对象。批量请求内选中操作有事务结果，各课程仍可在不同请求中独立审核和发布。 -- **迁移位置**：目标审核扩展到实际课程内容、配置与结果策略，区别于当前仅审核课程资料的实现。详见 [02 第 2.5—2.6 节](02-更新规划.md#25-学校审核批量操作与逐门结果)。 +- **迁移位置**：候选审核已扩展到实际课程内容、配置与结果策略，旧课程资料审核保留兼容职责。详见 [02 第 2.5—2.6 节](02-更新规划.md#25-学校审核批量操作与逐门结果)。 ### 13.6 教师提交、学校审核与发布时序 -第六组图把审核与实际发布分开，并说明后台任务何时能够执行。当前未增加这些接口或任务类型。 +第六组图把审核与实际发布分开，并保留后台任务的目标接入位置。预览、提交、审核、发布与学习上下文接口已经实现；通知、汇总、导出任务仍待接线，图中用可选段标明。前图表示发布事务，后图表示提交成功后的读取与任务执行。 ```mermaid sequenceDiagram @@ -619,8 +663,6 @@ sequenceDiagram participant A as 学校管理员 participant API as 后端用例 participant DB as 数据库 - participant W as 后台任务 - participant S as 学生 T->>API: 请求同步与发布影响预览 API->>DB: 读取源、目标、归属与版本依据 API-->>T: 逐课差异、冲突、跳过与影响 @@ -634,21 +676,37 @@ sequenceDiagram T->>API: 发布选中的已通过候选 API->>DB: 锁定并复验当前基础、权限与资源 alt 所选范围全部有效 - API->>DB: 同事务追加发布、规则、绑定、审计和任务 + API->>DB: 同事务追加发布、规则、绑定和审计 + opt 后续任务接线目标 + API->>DB: 同事务持久化课程后续任务 + end DB-->>API: 提交成功 API-->>T: 发布回执 - W->>DB: 领取已持久化任务 - W->>DB: 幂等执行通知、汇总或导出 - S->>API: 新进入课程并请求学习上下文 - API-->>S: 授权后的新发布快照与运行身份 else 冲突或写入失败 API->>DB: 回滚本次选中集合的写入 API-->>T: 明确失败或冲突，提供回读路径 end Note over API,DB: 重复请求回读既有回执，不生成重复包 - Note over W,DB: 任务失败可重试，不撤销已成功提交的发布 ``` +```mermaid +sequenceDiagram + participant S as 学生 + participant API as 后端用例 + participant DB as 数据库 + participant W as 后台任务 + Note over API,DB: 发布事务已提交成功 + opt 后续任务接线目标 + W->>DB: 领取已持久化任务 + W->>DB: 幂等执行通知、汇总或导出 + end + S->>API: 新进入课程并请求学习上下文 + API->>DB: 校验权限并读取新发布 + API-->>S: 授权后的新发布快照与运行身份 + Note over W,DB: 任务失败可重试，不撤销成功的发布 +``` + +- **实现对照**：当前发布用例已经复验基础、授权和候选依赖，并在事务内写发布、结果认定、审计和回执；选中范围的失败按同一用例处理。通用后台任务设施不等于这三个课程任务已实现，当前发布路径没有图示的通知/汇总/导出入队。API 与页面已有联调证据，完整故障、并发及任务验收仍需分别确认。 - **职责**：教师提交和发布、学校审核、后端事务与任务执行各自明确，不由页面直接拼接发布数据库状态。 - **数据来源**：已通过候选、当前发布基础、版本化资源、角色与课程关系；通知及汇总从已提交事件产生。 - **关键约束**：实际发布必须等于审核通过的快照；选中集合失败时不留下半套发布结果；旧发布接口也要经过同一检查。 @@ -660,29 +718,30 @@ sequenceDiagram ```mermaid flowchart TD - ENTRY["请求学习入口
服务端确认会话与上下文"] --> KIND{"内容与使用方式"} - KIND -- "系统预设资源" --> EXPLORE["登录后自由探索
仅记自主探索事实"] - KIND -- "教师预览" --> PREVIEW["核验创作权限
不产生学生正式结果"] + ENTRY["请求入口 / 确认学习身份"] --> KIND{"内容与使用方式"} + KIND -- "系统预设资源" --> EXPLORE["自由探索 / 不计课程结果"] + KIND -- "教师预览" --> PREVIEW["权限预览 / 不计学生结果"] KIND -- "教师校本课程" --> MEMBER{"已加入且权限有效？"} - MEMBER -- "否" --> INTRO["仅课程介绍与加入申请
不返回正文或历史内容"] - MEMBER -- "是" --> RUN["创建学习尝试
绑定课程、单元和发布版本"] - RUN --> EVENT["记录前复核权限与版本
在途尝试按已绑定版本收尾"] - EVENT --> HISTORY[("追加尝试、评分与学习结果
历史记录不覆盖")] + MEMBER -- "否" --> INTRO["仅课程介绍与加入申请"] + MEMBER -- "是" --> RUN["创建尝试 / 固定发布版本"] + RUN --> EVENT["复核权限 / 按绑定版本记录"] + EVENT --> HISTORY[("追加尝试 / 评分 / 结果")] HISTORY --> CURRENT{"结果适用于当前版本？"} CURRENT -- "是" --> VALID["当前课程的有效结果"] CURRENT -- "需要新版认定" --> IMPACT{"新修订是否影响认定要求？"} - IMPACT -- "纯展示或未受影响" --> CARRY["沿用依据
追加旧结果认定"] + IMPACT -- "纯展示或未受影响" --> CARRY["追加旧结果认定"] IMPACT -- "影响要求" --> POLICY{"教师送审并确认的策略"} POLICY -- "沿用" --> CARRY - POLICY -- "补做" --> REDO["建立补做项和新尝试
保留旧成绩与原记录"] + POLICY -- "补做" --> REDO["新版补做 / 保留原记录"] CARRY --> VALID REDO --> RUN - VALID --> VIEW["当前进度、成绩与解释
不串入其他课程或自主探索"] + VALID --> VIEW["本课程进度 / 成绩 / 解释"] ``` +- **实现对照**：学习上下文、检查点/作业历史和结果认定已有服务及页面接入，补做通过新版要求与新尝试表达，不要求另建图示同名任务表。后端声明参数运行也已有实现，但原实验完整页面导航尚未接回正式记录；退出课程后的本人历史有后端读取能力，门户历史目录与统一查询仍待完成。非成员不能读取课程正文，自己的既有学习历史另按历史授权读取，不能混为同一种访问。 - **职责**：服务端确认学习身份与准入，尝试固定运行版本，评价和认定给出可追溯依据；当前状态从有效事实派生。 - **数据来源**：课程成员、发布包、具体单元、尝试与评分历史，以及教师确定并送审的补做/沿用策略。 - **关键约束**：校本课程未加入只能看介绍；课程更新不抹去历史；补做新建尝试；仅其他单元变化不能使本单元无故失效；撤权后停止写入。 - **迁移位置**：现有学习证据、恢复与投影通过新上下文和结果认定映射逐步接入。不能创建虚假班级承载系统探索，也不能把旧成绩批量复制到新分叉。规则和测试矩阵见 [02 第 2.7—2.8 节](02-更新规划.md#27-学习上下文成绩留档与补做)、[第 5 节验收](02-更新规划.md#5-验收与性能目标)。 -本章七组图是当前目标设计的图示原件。实现改变时先核对代码，再更新当前实现章节；尚未落地部分继续标为待实现。正式任务与状态不在本章重复维护。 +本章七组图保留目标设计，并以图后的实现对照说明当前代码与验收边界。实现改变时先核对代码，再同步更新当前实现章节及相应对照；尚未落地部分继续明确标注。正式任务与状态不在本章重复维护，历史验证仍回到 03 核对。 diff --git "a/doc/02-\346\233\264\346\226\260\350\247\204\345\210\222.md" "b/doc/02-\346\233\264\346\226\260\350\247\204\345\210\222.md" index 4407d933..1a3efc08 100644 --- "a/doc/02-\346\233\264\346\226\260\350\247\204\345\210\222.md" +++ "b/doc/02-\346\233\264\346\226\260\350\247\204\345\210\222.md" @@ -1,19 +1,19 @@ # 星序 Astra — 更新规划 -> **文档梗概**：校内课程资源、分叉同步、学校审核、教师发布和学习结果管理的完整实施方案；本文是业务规则、正式任务、依赖与验收条件的唯一原件。 +> **文档梗概**：学术主站的校内课程资源、分叉同步、学校审核、教师发布和学习结果管理方案；本文是这组业务规则、正式任务、依赖与验收条件的唯一原件。双站当前能力由 01 说明，独立交付由 03 记录。 > > **具体规划法则**： > > 1. 以项目负责人在本轮讨论中确认的规则为准。实验端强调广度、递进、适配和解释性；管理平台完成主要后端能力及必要页面。 -> 2. 架构图和对象关系见 [01 第 13 章](01-开发者手册.md#13-目标架构与设计待实现)。其中新增设计均为待实现，不能覆盖 01 中已经核实的当前实现。 -> 3. DOC-006 已完成设计落档；2026-09-07 用户授权新门户接入、实际联调、静态部署和收束审查。新课程家族及 `/api/v2` 任务仍须按下方依赖实施，不把本轮接入等同于整个目标架构完成。 +> 2. 架构图和对象关系见 [01 第 13 章](01-开发者手册.md#13-目标架构与当前实现对照)。逐项区分已经接入和仍待实施的部分，不能把整张目标图当作已完成实现，也不能把已有功能重新列为尚未开发。 +> 3. DOC-006 已完成设计落档；正式门户和 `/api/v2` 已分批接入资源、课程家族、同步审核、发布和学习历史。剩余任务仍按下方依赖收口，阶段联调不等于整个目标架构完成。 > 4. 当前代码基线与未提交工作区改动分别记录。不分配未获安排的发布号，不虚构 Git 提交、完成状态或新测试结果。 > -> **当前提交基线**：`main`，2026-09-08 为上一轮收口；本轮已进入资源、课程工作流与学习结果的普通开发提交，事实索引见 [03 第 10 节](03-发布历史.md#10-2026-09-16-持续开发目标)，未安排新的产品发布号。 +> **当前提交基线**：本次文档核对以 `main / b177706` 为准，包含资源、课程工作流、学习结果及后续双站接入提交；事实索引见 [03 第 10 节](03-发布历史.md#10-2026-09-16-持续开发目标)与[第 11 节](03-发布历史.md#11-2026-09-18-双站接入与文档同步)，未安排新的星序产品发布号。 > -> **当前规划周期**：2026-09-17 用户要求“先停止目标，收束暂停”，持续开发目标已暂停。保留 A—F 完整范围，不标记整体完成；恢复开发须由用户明确发起。本次只保存暂停快照，不继续新增功能或运行测试。 +> **当前规划周期**：2026-09-17 用户要求“先停止目标，收束暂停”，A—F 持续开发目标仍暂停，恢复须由用户明确发起。后续独立功能和本次用户要求的 DOC-008 文档更新分别记录，不据此恢复原研发任务。 > -> **最后一次更新时间**：2026-09-17 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -21,7 +21,7 @@ ## 0. 全局总览与硬规则 -星序面向单校使用：管理端由学校管理，教师制作与组织教学，学生按授权学习。本校实例保留系统预设资源，不建设跨校公共平台或跨校资源交流。 +本方案的学术主站面向单校使用：管理端由学校管理，教师制作与组织教学，学生按授权学习。本校实例保留系统预设资源，不建设跨校公共平台或跨校资源交流。职教子站已有独立情景实训运行栈，其演示身份、课程内容和数据不自动并入本方案。 “系统资源”与“教师授课课程”是不同对象。系统资源可以在登录后自由探索；教师发布到学校资源库的课程，未加入的学生只能看介绍，加入后才能读取正文。资源可重复引用，课程、教学分叉和学生记录仍有各自的身份。 @@ -49,7 +49,7 @@ 现有系统具备三角色、学校与班级、教师申请、建课审核与选课、多人共享草稿、不可变发布、实验、检查点与两类作业评阅完成预设、学习证据和工作台。正式目录为 `90 / 18 / 19 = 127` 个活动身份；它不是新分叉课程的数量，也不代表所有活动具备相同记录能力。 -基础教学仍使用 `/api` 与 `/api/v1`；`/api/v2` 已接通资源与模板、课程家族和独立分叉、同源同步预览、逐项/批量候选审核、冻结发布及媒体访问；这些主流程已完成本机联调。学习上下文与作业/检查点跨版本认定已接通，实验运行、统计和后台任务继续实施。不能把已存在的内容版本或页面预演等同于本计划的新版本管理系统。 +基础教学仍使用 `/api` 与 `/api/v1`；`/api/v2` 已接通资源与模板、课程家族和独立分叉、同源同步预览、逐项/批量候选审核、冻结发布及媒体访问；这些主流程已有本机联调记录。学习上下文、作业/检查点跨版本认定和部分实验操作记录已有实现，后续整页导航仍有记录接线问题。统计、后台任务和整体迁移收口尚未完成，当前问题与恢复顺序见第 3 节。 上一轮审查与工作区修正的真实结果见 [03 工作区交付与规划归档](03-发布历史.md#7-2026-09-05-开发提交与工作区收尾)。`ARCH-011 / BE-031 / BE-032` 的范围和验证已迁出活动任务区，不作为本轮研发已完成的证据。 @@ -241,49 +241,57 @@ | 交互 | 代码空间有预测—运行—追踪—修正框架，普通实验的记录能力不一致 | 公共改进先统一“预测、改变一个变量、比较结果、解释原因”；不能把点击或停留时长当作完成 | | 深度 | 127 个身份的模型复杂度和讲解完整度不同；工程三条旧 slug 仍共享桥梁实现 | 保持共同的解释与反馈底线，在目录声明实际模型与共用关系；提高整组质量后再增加难度，不优先打造单门精品 | | 表现 | 已有 Canvas、DOM 和 Three.js 表达，3D 未必对每项内容都有收益 | 3D 优先用于空间关系、遮挡和视角确有教学价值的模板；Blender 资产与数值求解分离，不以精细美术替代可解释模型 | -| 适配 | 参数、说明和评价规则还没有统一的可配置模板 | BE-033 与 FE-046 先实现受控公式图像和数据图表模板；同一模板支持不同情境与讲解，配置越界要拒绝 | +| 适配 | 函数图像和数据图表已有受控配置模板，旧实验的配置与记录能力仍不一致 | 在既有模板基础上逐项补齐能力声明与适配；配置越界要拒绝，不把所有旧实验视为同等可编辑 | | 评价 | 检查点/作业的版本、补做与旧结果认定已接通；实验运行与汇总仍待收口 | DATA-011、BE-037、BE-038 明确旧尝试、当前认定和教师补做决策；沿用、补做、换版与重复请求都须有可追溯结果 | -| 内容资源 | 媒体块已有结构元数据，缺少完整素材文件服务与版本化读取链路 | 随资源版本任务补齐素材登记、可用性、授权、来源和版本固定；资源缺失不得以空白图或假播放器通过验收 | +| 内容资源 | 0063 已接入素材文件、授权取用和版本固定读取，更多内容类型仍需逐项核对 | 复用现有媒体服务，验证来源、缺失处理和授权变化；资源缺失不得以空白图或假播放器通过验收 | 课程扩展以一组相互衔接的活动为单位交付，每组都能复用同一套编辑、解释与评价工具。目录和后台中的活动、授课课程、单元实例分别计数；不得把复制界面、修改标题或新增旧 slug 算成独立高质量课程。 ## 3. 当前任务状态 -B—C 的课程主流程已完成本机功能验证，记录见 [03 第 10.4 节](03-发布历史.md#104-课程创作同步审核与冻结发布)。当前目标继续推进 D—F；下列任务在结果、权限、查询及整体迁移收口后再完成最终归档，不把阶段联调当成整个系统验收。 +B—C 的课程主流程已有本机功能验证，记录见 [03 第 10.4 节](03-发布历史.md#104-课程创作同步审核与冻结发布)。A—F 目标目前暂停；下列任务在结果、权限、查询及整体迁移收口后再完成最终归档，不把阶段联调当成整个系统验收。 -D1—D2 已提交至 `92552fc`，覆盖版本化检查点、作业重交与评分历史。D3 已接入实验运行和声明参数观察，函数图像与原力学控件均完成真实页面记录，暂停快照与证据见 [03 第 10.6 节](03-发布历史.md#106-实验操作版本绑定与暂停快照)。 +D1—D2 已提交至 `92552fc`，覆盖版本化检查点、作业重交与评分历史。D3 在 `4bbfc04` 保存了实验运行和声明参数观察；当时函数图像与原力学控件的真实页面记录见 [03 第 10.6 节](03-发布历史.md#106-实验操作版本绑定与暂停快照)。后续入口已改为整页导航，不能直接沿用当时 iframe 接线的验证结论。 -**暂停位置**：停止新增开发和测试，临时联调服务与本轮测试标签页已关闭；隔离数据库保留在 `.tmp-test-audit-anchor/portal-v2-20260916/astra.sqlite3`，用户实际数据库未改动。最后暂停于力学页面修正后的最终复看：函数/力学操作记录和两个单元完成已验证，重力默认值修正有针对性回归，最终页面加载后的复看未完成；不把它写为完成验收。源代码保存于本地，尚未推送或更新 Pages。 +**原暂停位置**：9 月 17 日停止新增开发和测试，关闭临时联调服务和测试标签页；当时的隔离库与未完成复看保留在 [03 第 10.6 节](03-发布历史.md#106-实验操作版本绑定与暂停快照)。当时源码只在本地保存；本次核对时相关提交已在远端 `main`，不能继续写成“尚未推送”。源码入库与 Pages 制品发布分别判断。 -**恢复顺序**：先复看最新默认值和操作历史展示，再完成退出课程后的历史目录、校内课程发现/教师取用入口；随后按 BE-039—BE-041 推进课程关联、统一统计和站内任务，最后执行性能、真实 MySQL、整体复核及课程扩展计划。已有验证证据继续使用，只重测新变化与尚未覆盖的范围。 +**恢复顺序**：先修复当前学习入口的回归，再复看默认值与操作历史，完成退出课程后的历史目录、校内课程发现/教师取用入口；随后按 BE-039—BE-041 推进课程关联、统一统计和站内任务，最后执行性能、真实 MySQL、整体复核及课程扩展计划。已有证据按原基线保留，新变化和未覆盖范围须重新验证。 + +| 当前复核问题 | 对应实现与影响 | 处理位置 | +| --- | --- | --- | +| 旧实验整页入口缺少原控件记录桥接 | `course-player.ts` 已移除 iframe 控件监听；链接附带学习上下文不等于实验页已完成操作上报 | BE-038、FE-048 | +| 空参数模板仍能配置操作完成条件 | 函数模板可不声明参数，但运行中没有对应控件；发布门禁须拒绝无法完成的操作要求 | BE-033、BE-038 | +| 旧作业读取与单元锁定不一致 | 旧兼容路径仍可返回锁定任务描述，须按当前课程开放计划统一正文读取边界 | BE-038、FE-048 | + +以上是当前源码核对结果，本次文档更新不修改业务实现，也不将其记为已修复。职教的模型启用、检索范围和分项验证边界见 [04 第 8—9 节](04-部署指南.md#8-职教子站运行与数据)，不混入学术 A—F 的完成状态。 TOOLS-003 已统一开发与构建运行环境，交付记录见 [03 第 10 节](03-发布历史.md#10-2026-09-16-持续开发目标)。 -DOC-007 文档精简的工作区交付和验证见 [03 第 9 节](03-发布历史.md#9-2026-09-16-当前阶段文档精简)；本次按 DOC-007 独立提交，未新增产品发布或业务功能。 +DOC-007 文档精简已由 `b924d1c` 保存，交付和验证见 [03 第 9 节](03-发布历史.md#9-2026-09-16-当前阶段文档精简)。DOC-008 已完成 README 与现行文档同步，内容和验证归档至 [03 第 11.3 节](03-发布历史.md#113-doc-008-项目介绍与现行文档同步)，不新增产品发布号。 -REL-010—REL-011、BE-042—BE-044、FE-053 和 ARCH-013 已完成，归档入口为 [03 第 8 节](03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装)。正式门户、三角色本机联调、GitHub Pages 静态演示、五组 CI 与分支收束已验收；本地和远端只保留 main、qianduan。FE-049—FE-052、UI-019、DOC-006、REL-009 的旧完成记录也由历史承接。本轮交叉审查由 01 当前实现与第 2.14 节维护，以下仅保留未完成和后续任务；不把本轮交付等同于 `/api/v2` 目标方案完成。 +REL-010—REL-011、BE-042—BE-044、FE-053 和 ARCH-013 已完成，归档入口为 [03 第 8 节](03-发布历史.md#8-2026-09-07-正式门户接入与前后端封装)。正式门户、三角色联调、Pages、五组 CI 与分支收束均是当时基线的验收事实，当前分支和测试状态须重新核对。FE-049—FE-052、UI-019、DOC-006、REL-009 的旧完成记录也由历史承接。以下仅保留未完成和后续任务。 - [ ] UI-018｜状态：暂缓｜执行阶段：Figma 布局绘制未完成｜目标版本：未分配｜模块：通用 Web 页面设计稿｜任务：核对当前页面并在用户已打开的 Figma 文件中绘制可编辑通用布局，重复实验仅取一个代表，保留后续交互调整空间｜主责：UI组｜协作：无（主开发单线）｜前置：用户明确要求在 Figma 绘制当前通用页面布局｜关联文档：[当前页面结构](01-开发者手册.md#5-前端页面路由与可见交互)、[UI 规范](05-UI规范模板.md)｜关联版本：无｜验证：已完成部分导入与网页对照，整体尚未验收，不标为交付完成｜暂缓原因：用户明确要求先不处理 Figma，转向新前端目录｜暂缓开始：2026-09-06｜恢复条件：用户明确恢复 Figma 工作；目前未安排日期 -- [ ] ARCH-012｜状态：进行中｜执行阶段：A 基线与模型｜目标版本：未分配｜模块：领域与协议边界｜任务：整理模型职责、权限与事务入口，明确资源/分叉/候选/学习上下文及新旧协议映射｜主责：架构组｜协作：无（当前主开发单线）｜前置：DOC-006｜关联文档：[2.1 模型边界](#21-术语身份与模型边界)、[01 分层图](01-开发者手册.md#131-系统分层与模块职责)｜关联版本：无｜验证：现状与目标逐项对应，接口/依赖方向可验证，兼容边界清楚 +- [ ] ARCH-012｜状态：暂停｜执行阶段：A 基线与模型｜目标版本：未分配｜模块：领域与协议边界｜任务：整理模型职责、权限与事务入口，明确资源/分叉/候选/学习上下文及新旧协议映射｜主责：架构组｜协作：无（当前主开发单线）｜前置：DOC-006｜关联文档：[2.1 模型边界](#21-术语身份与模型边界)、[01 分层图](01-开发者手册.md#131-系统分层与模块职责)｜关联版本：无｜验证：现状与目标逐项对应，接口/依赖方向可验证，兼容边界清楚 -- [ ] DATA-011｜状态：进行中｜执行阶段：资源/谱系/候选模型已交付；0064 学习上下文与历史模型在工作区实现，尚未迁移真实数据｜目标版本：未分配｜模块：模型与迁移｜任务：建立资源版本、课程谱系、候选审核及学习历史所需的数据映射和可回退迁移｜主责：数据组｜协作：无（当前主开发单线）｜前置：ARCH-012｜关联文档：[2.11 迁移](#211-渐进迁移与维护边界)、[01 数据关系](01-开发者手册.md#133-草稿候选审核项与发布数据关系)｜关联版本：无｜验证：空库与已有库升级、回退、再升级通过，既有事实可对账，未知来源不补造 +- [ ] DATA-011｜状态：暂停｜执行阶段：资源/谱系/候选模型已交付；0064 学习上下文与历史模型已提交，隔离迁移有记录，用户实际数据升级另行确认｜目标版本：未分配｜模块：模型与迁移｜任务：建立资源版本、课程谱系、候选审核及学习历史所需的数据映射和可回退迁移｜主责：数据组｜协作：无（当前主开发单线）｜前置：ARCH-012｜关联文档：[2.11 迁移](#211-渐进迁移与维护边界)、[01 数据关系](01-开发者手册.md#133-草稿候选审核项与发布数据关系)｜关联版本：无｜验证：空库与已有库升级、回退、再升级通过，既有事实可对账，未知来源不补造 -- [ ] BE-033｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：资源与模板｜任务：提供资源/模板目录、版本、配置校验和受控预览，声明真实记录能力｜主责：后端组｜协作：无（当前主开发单线）｜前置：DATA-011｜关联文档：[2.2 资源模板](#22-系统资源模板与教师创作)｜关联版本：无｜验证：预设引用可回读，非法配置/缺失资源拒绝，版本与能力一致 +- [ ] BE-033｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：资源与模板｜任务：提供资源/模板目录、版本、配置校验和受控预览，声明真实记录能力｜主责：后端组｜协作：无（当前主开发单线）｜前置：DATA-011｜关联文档：[2.2 资源模板](#22-系统资源模板与教师创作)｜关联版本：无｜验证：预设引用可回读，非法配置/缺失资源拒绝，版本与能力一致 -- [ ] BE-034｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：课程派生与草稿｜任务：提供取用、派生、独立单元/内容实例及并发草稿能力，不复制学生记录｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-033｜关联文档：[2.3 分叉](#23-教学分叉与独立草稿)｜关联版本：无｜验证：高一/高二并存，同资源重复引用不串用，过期草稿保存不覆盖他人修改 +- [ ] BE-034｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：课程派生与草稿｜任务：提供取用、派生、独立单元/内容实例及并发草稿能力，不复制学生记录｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-033｜关联文档：[2.3 分叉](#23-教学分叉与独立草稿)｜关联版本：无｜验证：高一/高二并存，同资源重复引用不串用，过期草稿保存不覆盖他人修改 -- [ ] BE-035｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：跨分叉同步｜任务：实现本人同源内容匹配、三值比较、冲突预览、一次提交与冻结候选｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-034｜关联文档：[2.4 同步](#24-公共内容同步与冲突处理)｜关联版本：无｜验证：标准复数/三角案例、缺失跳过、他人排除、重排匹配、过期与冲突处理通过 +- [ ] BE-035｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：跨分叉同步｜任务：实现本人同源内容匹配、三值比较、冲突预览、一次提交与冻结候选｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-034｜关联文档：[2.4 同步](#24-公共内容同步与冲突处理)｜关联版本：无｜验证：标准复数/三角案例、缺失跳过、他人排除、重排匹配、过期与冲突处理通过 -- [ ] BE-036｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：学校审核｜任务：提供修改来源与影响明细、逐项/批量批复和可追溯审核意见｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-035｜关联文档：[2.5 审核](#25-学校审核批量操作与逐门结果)｜关联版本：无｜验证：整批与逐门可操作，混合结果正确，快照不可变，审核条件写入可靠 +- [ ] BE-036｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：学校审核｜任务：提供修改来源与影响明细、逐项/批量批复和可追溯审核意见｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-035｜关联文档：[2.5 审核](#25-学校审核批量操作与逐门结果)｜关联版本：无｜验证：整批与逐门可操作，混合结果正确，快照不可变，审核条件写入可靠 -- [ ] BE-037｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：发布与回滚｜任务：统一新旧发布门禁，发布已通过候选，维护原子绑定、幂等回执和回滚新修订｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-036｜关联文档：[2.6 发布](#26-教师发布回滚与版本生效)｜关联版本：无｜验证：未审拒绝、通过后改草稿不夹带、选中集合失败回滚、重复与回滚流程通过 +- [ ] BE-037｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：发布与回滚｜任务：统一新旧发布门禁，发布已通过候选，维护原子绑定、幂等回执和回滚新修订｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-036｜关联文档：[2.6 发布](#26-教师发布回滚与版本生效)｜关联版本：无｜验证：未审拒绝、通过后改草稿不夹带、选中集合失败回滚、重复与回滚流程通过 -- [ ] BE-038｜状态：进行中｜执行阶段：D1—D3 主链路已联调；用户暂停，历史目录与最终复看待恢复｜目标版本：未分配｜模块：学习结果与成绩｜任务：统一上下文、尝试与评分历史、补做策略和旧结果认定，迁移当前投影读取｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-037｜关联文档：[2.7 结果](#27-学习上下文成绩留档与补做)、[2.8 权限](#28-两种学习入口与权限)｜关联版本：无｜验证：自由探索/预览隔离，版本和撤权检查有效，历史不覆盖、不重复计分 +- [ ] BE-038｜状态：暂停｜执行阶段：D1—D3 有阶段联调记录；整页实验接线、读取边界、历史目录与最终复看待恢复｜目标版本：未分配｜模块：学习结果与成绩｜任务：统一上下文、尝试与评分历史、补做策略和旧结果认定，迁移当前投影读取｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-037｜关联文档：[2.7 结果](#27-学习上下文成绩留档与补做)、[2.8 权限](#28-两种学习入口与权限)｜关联版本：无｜验证：自由探索/预览隔离，版本和撤权检查有效，历史不覆盖、不重复计分 - [ ] BE-039｜状态：未认领｜执行阶段：待实施｜目标版本：未分配｜模块：课程关联与解释建议｜任务：提供关联类型、循环/失效校验以及依据有效事实生成的下一步说明｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-038｜关联文档：[2.10 关联服务](#210-分层统计关联建议与后台任务)｜关联版本：无｜验证：建议有可回读依据，不自动选课或改分，先修门槛只按显式课程配置生效 @@ -291,11 +299,11 @@ REL-010—REL-011、BE-042—BE-044、FE-053 和 ARCH-013 已完成，归档入 - [ ] BE-041｜状态：未认领｜执行阶段：待实施｜目标版本：未分配｜模块：后台任务与追踪｜任务：接入站内通知、汇总与导出，贯通事务入队、幂等、重试和审计追踪｜主责：后端组｜协作：无（当前主开发单线）｜前置：BE-037、BE-040｜关联文档：[2.10 后台任务](#210-分层统计关联建议与后台任务)｜关联版本：无｜验证：提交与入队一致，重试不重复产生结果，失败和权限变化有明确回执 -- [ ] FE-046｜状态：进行中｜执行阶段：编排、派生、同步送审和冻结发布已联调，待整体收口｜目标版本：未分配｜模块：教师创作管理页面｜任务：完成模板编课、派生、同步预览、冲突处置及已通过候选发布页面｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-033、BE-034；同步/发布部分依赖 BE-035、BE-037｜关联文档：[2.2—2.6 教师流程](#22-系统资源模板与教师创作)｜关联版本：无｜验证：真实 API 下保存、预览、同步、重读与发布可用，桌面/移动 Web 及错误状态通过 +- [ ] FE-046｜状态：暂停｜执行阶段：编排、派生、同步送审和冻结发布已联调，待整体收口｜目标版本：未分配｜模块：教师创作管理页面｜任务：完成模板编课、派生、同步预览、冲突处置及已通过候选发布页面｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-033、BE-034；同步/发布部分依赖 BE-035、BE-037｜关联文档：[2.2—2.6 教师流程](#22-系统资源模板与教师创作)｜关联版本：无｜验证：真实 API 下保存、预览、同步、重读与发布可用，桌面/移动 Web 及错误状态通过 -- [ ] FE-047｜状态：进行中｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：学校审核管理页面｜任务：展示源版本与影响列表，支持批量/逐门审核、意见和校内资源治理｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-036、BE-037｜关联文档：[2.5 学校流程](#25-学校审核批量操作与逐门结果)｜关联版本：无｜验证：混合审核结果可理解，页面不直接伪造发布，权限与双视口操作通过 +- [ ] FE-047｜状态：暂停｜执行阶段：B—C 主链路已通过定向与真实页面联调，待本轮整体收口｜目标版本：未分配｜模块：学校审核管理页面｜任务：展示源版本与影响列表，支持批量/逐门审核、意见和校内资源治理｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-036、BE-037｜关联文档：[2.5 学校流程](#25-学校审核批量操作与逐门结果)｜关联版本：无｜验证：混合审核结果可理解，页面不直接伪造发布，权限与双视口操作通过 -- [ ] FE-048｜状态：进行中｜执行阶段：学习版本、作业与实验记录已联调；用户暂停，退出课程后历史入口和学校课程发现待恢复｜目标版本：未分配｜模块：学生入口与历史回读｜任务：实现系统探索、校本介绍/加入/正文、版本提示、补做与成绩历史视图｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-038、BE-039｜关联文档：[2.7—2.8 学生流程](#27-学习上下文成绩留档与补做)｜关联版本：无｜验证：未加入无法取正文，探索不计课程成绩，当前与历史版本解释准确 +- [ ] FE-048｜状态：暂停｜执行阶段：学习版本与作业历史已有接入；实验入口回归、退出课程后历史入口和学校课程发现待恢复｜目标版本：未分配｜模块：学生入口与历史回读｜任务：实现系统探索、校本介绍/加入/正文、版本提示、补做与成绩历史视图｜主责：前端组｜协作：无（当前主开发单线）｜前置：BE-038、BE-039｜关联文档：[2.7—2.8 学生流程](#27-学习上下文成绩留档与补做)｜关联版本：无｜验证：未加入无法取正文，探索不计课程成绩，当前与历史版本解释准确 - [ ] PERF-002｜状态：未认领｜执行阶段：待实施｜目标版本：未分配｜模块：性能与并发验证｜任务：建立固定隔离数据集与采样，验证新查询、同步发布和任务路径的耗时及 SQL 行为｜主责：性能组｜协作：无（当前主开发单线）｜前置：BE-035—BE-041｜关联文档：[5.2 性能验收](#52-性能与运行证据)｜关联版本：无｜验证：报告数据量、硬件、耗时和查询数，发现的超预算与并发问题完成整改 @@ -357,6 +365,7 @@ CONTENT-011 可在 DOC-006 完成后独立推进规划细化，不依赖新增 | 来源 | 决策 | 本文落位 | | --- | --- | --- | +| 本次用户明确要求 | 更新 doc 与 README；doc 沿用既有文体，README 加强项目介绍和阅读引导 | DOC-008、03 第 11 节 | | 用户明确确认 | 前端增加广度、递进与共同质量，本轮先出修改与拓展计划 | 2.12、CONTENT-011 | | 用户明确确认 | 系统资源预置，教师可调整并从模板简单创作 | 2.2、BE-033 | | 用户明确确认 | 模板提供基本交互，教师配置开放项 | 2.2；不扩展为任意交互编程 | @@ -374,12 +383,12 @@ CONTENT-011 可在 DOC-006 完成后独立推进规划细化，不依赖新增 ## 7. 长期方向与暂缓任务 -本节为范围边界，不是正式任务状态流水。当前不实施：微信小程序、跨校公共平台、跨校课程交流、批量实验重绘、少数精品课深度专项、外部 AI、隔离 OJ 集群、公网部署和真实课堂实证。 +本节为 A—F 的范围边界，不是正式任务状态流水。该计划暂不实施：微信小程序、跨校公共平台、跨校课程交流、批量实验重绘、少数精品课深度专项、隔离 OJ 集群、公网部署和真实课堂实证。后续独立提交已有可选 AI 助教与职教模型接入，不再将“外部 AI”整体列为不存在；扩大检索覆盖和教学效果评估仍需另行安排。 -3D、学习网络的学生端展示及批量课程扩充在前端规划基础上后续推进；它们不能反向阻止本轮资源、审核发布与后端调优。已有 MySQL、部署、审计和外部适配工具保留，不因本轮范围收束而删除。 +现有 Three.js 门户和部分 3D 实验继续保留；更多 3D 内容、学习网络展示及批量课程扩充在前端规划基础上后续推进。已有 MySQL、部署、审计和外部适配工具保留，不因本轮范围收束而删除。 ## 8. 维护与历史追溯 -DOC-006 的已确认业务规则与当前未完成任务继续保留本文；本次精简不改变其范围、状态或验收要求。01 保留当前实现和七组目标架构图，03 保留实际交付及 Git 索引。 +DOC-006 的已确认业务规则与当前未完成任务继续保留本文；DOC-008 校正实现与暂停状态，不扩大研发范围或降低验收要求。01 对照当前实现与七组目标架构图，03 保留实际交付及 Git 索引。 旧冻结规划、阶段控制表和重复历史分卷已退出当前目录。原文可从 [03 的 Git 追溯入口](03-发布历史.md#3-旧材料的git追溯) 查看，不再作为另一份执行计划。完成新的功能块时核对代码、验证与交付事实，再更新 01/03 并从本节任务原件移出完成项。 diff --git "a/doc/03-\345\217\221\345\270\203\345\216\206\345\217\262.md" "b/doc/03-\345\217\221\345\270\203\345\216\206\345\217\262.md" index bec36713..cb8f93d5 100644 --- "a/doc/03-\345\217\221\345\270\203\345\216\206\345\217\262.md" +++ "b/doc/03-\345\217\221\345\270\203\345\216\206\345\217\262.md" @@ -4,7 +4,7 @@ > > **具体规划法则**：记录已发生事实，不承担未来任务；历史测试不替代本轮验证。旧逐版本流水不再复制到当前目录，完整原文保留在 Git。 > -> **最后一次更新时间**：2026-09-17 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -20,12 +20,13 @@ 8. [正式门户与前后端封装](#8-2026-09-07-正式门户接入与前后端封装) 9. [当前文档精简](#9-2026-09-16-当前阶段文档精简) 10. [持续开发阶段记录](#10-2026-09-16-持续开发目标) +11. [双站接入与文档同步](#11-2026-09-18-双站接入与文档同步) ## 1. 当前交付 -上一轮整体业务验收基线为 `b832151`（2026-09-08）。`main` 当前继续进行第 10 节的本地开发提交；它们尚未作为新产品发布或推送远端。Pages 制品是 `627b2b7`，来自前端源提交 `caebfa8`。之后的 CI 和文档修正没有改变该静态前端。 +本次文档核对的远端源码基线为 `main / b177706`，已包含第 10 节资源、课程和学习结果提交，以及第 11 节教育方向、可选 AI 助教和职教动态栈接入。它们属于实际 Git 开发提交，没有分配新的星序产品发布号。9 月 17 日暂停的是 A—F 持续开发目标，不抹去随后独立完成的工作。 -完整项目、静态演示、真实三角色联调与五组 CI 已在第 8 节记录。没有新增产品发布号。当前实现以 [01](01-开发者手册.md) 为准，下一阶段只认 [02](02-更新规划.md)。 +上一轮整体业务验收基线为 `b832151`（2026-09-08），三角色联调、Pages 制品 `627b2b7` 和当时五组 CI 的证据保留在第 8 节。历史通过不代表 `b177706` 全部通过；当前 CI 与验证范围见第 11.2 节。线上 Pages 版本应读取实际 `build-info.json`，不由源码已推送推定。当前实现以 [01](01-开发者手册.md) 为准，后续任务只认 [02](02-更新规划.md)。 ## 2. 历史里程碑 @@ -40,6 +41,8 @@ | 2026-09-05 | 重新审查架构，修复课程统计/发布计划，明确广度与统一质量路线 | | 2026-09-07—08 | 接收新门户，完成真实前后端接入、身份与发布边界修复、Pages 和分支收束 | | 2026-09-16 | 清理重复手册、旧报告与冻结规划；工作区结果见第 9 节 | +| 2026-09-16—17 | 资源与模板、课程派生和同步审核、冻结发布、版本化学习与评分历史分批提交；D3 保存暂停快照 | +| 2026-09-18 | 教育方向与可选 AI 助教、角色课程目录及职教动态栈接入；README 和现行文档同步 | 表格只是历史导航，不替代独立提交事实；原分卷、标题、任务号和当时验证均可按下一节从 Git 查看。 @@ -69,7 +72,7 @@ git log --all -- doc/03-子文档/35-V8版本发布历史.md 已撤换“少数精品课程/3D 代表实验优先”的主线，现以广度、递进、适配、解释性和共同质量为主。力学与桥梁的旧课程叙事层已撤换，不能从旧报告推断它们仍在运行。 -`qianduan/` 已成为正式门户。原角色页面保留兼容代码，正式功能不再扩成两套前端。课程家族、跨课程同步、候选正文审核和补做仍待实施；本次精简没有将其标记为完成。 +`qianduan/` 是学术主站正式门户，原角色页面保留兼容代码。课程家族、同源同步、候选正文审核、补做和学习历史已有实现；剩余入口、查询、后台任务及整体验收由 02 承接。`zhijiao/` 是后来接入的职教应用，保留独立 React/Fastify、演示身份和数据，不属于原角色页面的重复实现。 旧版本的冻结、固定行数、旧写入白名单和特定模型审批记录不构成永久约束；当前规则以用户指令、AGENTS、02 和有效回归为准。 @@ -83,7 +86,7 @@ git log --all -- doc/03-子文档/35-V8版本发布历史.md 早期 ARCH-011、BE-031、BE-032 的未提交交付及其后实际提交分别保留在 Git 原文与第 7 节。工作区整理可以形成可审阅结果，但不能写成已经发布或已经推送。 -DOC-007 没有新增产品版本，其独立提交与验收见第 9 节。 +DOC-007 没有新增产品版本，其独立提交与验收见第 9 节。DOC-008 的介绍与文档同步见第 11.3 节；文档提交、远端推送和 Pages 发布分别确认。 ## 7. 2026-09-05 开发提交与工作区收尾 @@ -121,7 +124,7 @@ DOC-007 没有新增产品版本，其独立提交与验收见第 9 节。 - **Git 提交**：`chore(frontend): 接收已验收的新前端原型基线（REL-010）`（`0c06dd2`）。 - **具体完成**：将 FE-050—FE-052 的已验收新前端、设计图及说明纳入 Git，保留用户未提交的 `UI.pen`；同时登记用户已确认的新接入阶段。 - **验证结论**：独立前端 11 项测试与 TypeScript/Vite 构建通过。该提交不代表真实后端接入或 Pages 部署完成。 -- **关联说明**：[01 当前前端](01-开发者手册.md#54-qianduan-独立前端原型)、[39 原交付记录](https://github.com/falling-feather/Astra/blob/e73cfa7/doc/03-%E5%AD%90%E6%96%87%E6%A1%A3/39-%E8%B7%A8%E7%89%88%E6%9C%AC%E7%BB%BC%E8%BF%B0%E4%B8%8E%E8%A7%84%E5%88%92%E8%BF%81%E7%A7%BB%E9%99%84%E5%BD%95.md#c9-fe-052-%E9%80%8F%E8%A7%86%E5%A4%9A%E8%BD%A8%E8%AF%BE%E7%A8%8B%E8%BD%AE%E7%9B%98%E5%AE%9E%E7%8E%B0)。 +- **关联说明**：[01 当前前端](01-开发者手册.md#54-正式门户的实现与数据适配)、[39 原交付记录](https://github.com/falling-feather/Astra/blob/e73cfa7/doc/03-%E5%AD%90%E6%96%87%E6%A1%A3/39-%E8%B7%A8%E7%89%88%E6%9C%AC%E7%BB%BC%E8%BF%B0%E4%B8%8E%E8%A7%84%E5%88%92%E8%BF%81%E7%A7%BB%E9%99%84%E5%BD%95.md#c9-fe-052-%E9%80%8F%E8%A7%86%E5%A4%9A%E8%BD%A8%E8%AF%BE%E7%A8%8B%E8%BD%AE%E7%9B%98%E5%AE%9E%E7%8E%B0)。 FE-049 的目录准备、UI-019 的选型与 FE-050—FE-052 的原型交付均由上项接收提交承接，不补造独立产品发布或旧提交。原过程分别保留在 39 号 C.6—C.9；DOC-006 与 REL-009 的真实提交继续见第 7 节。 @@ -158,7 +161,7 @@ FE-049 的目录准备、UI-019 的选型与 FE-050—FE-052 的原型交付均 - **Git 提交**：`feat(frontend): 接入正式门户与三角色教学流程（FE-053）`（`e2522d7`）。 - **具体完成**：qianduan 提升为正式前端；增加教师课程资料、内容、版本预览/比较/恢复、名单、作业、批改及开放计划，学生提交/反馈、检查点、本人笔记与账号，管理员身份和课程资料审核。保留三星系 127 项活动，统一构建至 labs；真实与演示数据源分离，加入独立制品检查与发布工具。 - **验证结论**：前端 25 项单元测试、TypeScript/Vite 构建和制品检查通过；浏览器完成真实建课、送审、发布、入课申请及批准、学生回答、教师批改和重启回读 95 分反馈；检查点返回服务端完成后星盘进度为 1/1；笔记刷新保留正文及缩进；管理员能核验申请人并完成合成账号审核。Windows PowerShell 5.1 一键启动与 0060 迁移实测通过，原数学预设和代码浏览器运行保持可操作。 -- **关联说明**：[01 正式门户](01-开发者手册.md#54-qianduan-独立前端原型)、[前端运行与打包](../qianduan/README.md)。本提交提供部署工具，不将尚未执行的 Pages 发布或分支清理写成已完成。 +- **关联说明**：[01 正式门户](01-开发者手册.md#54-正式门户的实现与数据适配)、[前端运行与打包](../qianduan/README.md)。本提交提供部署工具，不将尚未执行的 Pages 发布或分支清理写成已完成。 ### 8.6 架构与课程体系交叉审查 @@ -317,3 +320,49 @@ FE-049 的目录准备、UI-019 的选型与 FE-050—FE-052 的原型交付均 - **具体完成**：课程播放器中的旧实验资源由课程页内 iframe 改为整页导航，按钮改为“进入完整实验”。目标地址仍经过 `labs/` 路径校验，并附带本次学习上下文标识和课程返回位置；实验页结束后可通过浏览器后退回到原课程页查看进度。课程模板资源和资源预览页的既有配置预览不在本次范围内。 - **实现位置**：[course-player.ts](../qianduan/src/portal/course-player.ts)。移除该入口不再需要的跨 iframe 控件监听，保留实验端自己的完整页面生命周期。 - **验证**：TypeScript 检查与演示构建通过；9002 演示站以学生账号打开机械能课程，点击“进入完整实验”后实际进入 `/labs/index.html?astra_context_key=…&astra_return_to=…#physics/mechanics`，AX 树显示独立实验页面且课程页没有 iframe；浏览器后退后重新回到原课程页。未把本次导航改动包装成实验运行或成绩链路的全量验收。 + +## 11. 2026-09-18 双站接入与文档同步 + +### 11.1 已入库的独立功能 + +本节按实际提交核对 9 月 17 日暂停之后的独立改动。日期采用提交原记录的 UTC+8；第 10.8 节保留功能工作日期，正式整页导航提交发生在 9 月 18 日零时。这些提交已在 `b177706` 的远端历史中，不再作为“仅在本地”的未提交工作。 + +| Git 提交 | 实际标题 | 对应变化 | +| --- | --- | --- | +| `b73c51a` | `feat(frontend): 实验入口改为整页导航` | 旧实验改为完整页面入口；记录接线的当前缺口见 01 和 02 | +| `513add0` | `feat(integration): 接入教育方向与AI助教` | 增加学术/职教选择、职业入口跳转和主站可选助教 API | +| `e3a9446` | `fix(integration): 双站启动继承 AI 配置` | 联合启动继承职教本地 DeepSeek 密钥并配置主站助教 | +| `a010b20` | `feat(courses): 按角色收口课程渲染范围` | 按当前角色组织课程目录和可见内容 | +| `5f90258` | `fix(courses): 合并管理员系统与校内课程预览` | 管理员预览同时读取系统和校内课程 | +| `6ed1387` | `fix(courses): 为系统资源补齐实验入口` | 系统资源目录补入实验运行链接 | +| `c88da36` | `fix(courses): 恢复实验链接点击命中` | 修正课程实验链接的点击范围 | +| `eef9e35` | `feat(courses): 管理员预览改为树状课程目录` | 管理员预览改用课程树展示 | +| `3dc6279` | `feat(vocational): 迁移职教星云动态运行栈` | 将职教 Web、API、共享模块、课程与运行脚本纳入仓库 | +| `5542ff3` | `fix(vocational): 清理迁移副本旧品牌引用` | 整理职教迁移后的展示与品牌引用 | +| `b177706` | `chore(vocational): 补齐动态站测试样本` | 补入动态站所需测试样本，形成本次源码核对基线 | + +主站仍使用 Python/FastAPI 与默认 SQLite；职教使用 React/Fastify、嵌入式 PGlite 和文件记录。教育方向入口负责跳转，两站没有因此完成统一登录或成绩互通。职教五门融媒体课程与 127 个学术活动身份分别计数。 + +### 11.2 当前验证范围 + +本次核对读取了 `b177706` 对应的 [Quality gates 第 18 次运行](https://github.com/falling-feather/Astra/actions/runs/35254571542)。实际结果如下，不沿用第 8 节的全通过表述： + +| 检查组 | 远端结果 | +| --- | --- | +| Backend · SQLite | 17 failed、745 passed、12 skipped；未通过完整后端检查 | +| Frontend · syntax and contracts | 324 项 JavaScript 语法检查通过；第 5 个契约因旧页面行数上限失败 | +| Backend · MySQL release evidence | 通过，仅说明该专项范围 | +| Portal · Linux standalone builds | 通过 | +| C++ · release build | 通过 | + +职教迁入后有自己的类型检查、测试和运行烟测入口；当前组合门禁所需的部分文档与端到端配置缺失，见 [04 第 8.5 节](04-部署指南.md#85-分项验证入口)。本次文档工作不重复运行全部业务测试，不调用真实模型，也不把已有接口、类型检查或历史页面证据当作完整课堂效果验证。 + +### 11.3 DOC-008 项目介绍与现行文档同步 + +- **用户要求**：更新 README 与 doc；doc 严格沿用原有文体，README 加强介绍和引导。 +- **Git 提交**：本节随 `docs: 重构项目介绍并同步双站文档（DOC-008）` 保存；不新增产品发布号，不发布 Pages。 +- **README**：按项目用途、学习空间、核心设计、体验方式、本机启动、技术入口与继续阅读组织内容；把外置 Python、详细参数与数据维护移入 04，保留可直接执行的首次启动入口。 +- **现行文档**：00 说明双站范围；01 对照已实现能力、数据职责与七组目标图；02 保留完整规则和原任务号并校正暂停状态；04 补齐职教、联合启动、数据和可选 AI；05 与 15 更新页面及资源接线。03 保留旧验收原文，并追加本节实际提交和验证范围。 +- **文体与保护**：沿用文档梗概、规划法则、编号章节、规则表格和具体操作叙述；科学模型正文、公式、样例与历史测试原文保留。旧章节锚点保留兼容，跨文档引用指向现行标题。 +- **文档核验**：14 份 Markdown 的 415 处本地文件与章节引用无断链，`git diff --check` 通过；10 张 Mermaid 经固定版本 11.12.0 解析并在 Chromium 133 实际渲染，页面错误为 0。原有 18 项未完成任务全部保留，科学模型正文逐字一致；另经独立文档与源码交叉复核。 +- **合同验证**：科学模型说明契约与旧实验保护契约通过。架构边界契约仍停在旧 `index.html` 行数限制：3759 行超过 3758 行上限；该文件及检查脚本与 `b177706` 一致，本次未修改。该失败保留为当前门禁问题，不通过改写保护规则消除。 diff --git "a/doc/04-\351\203\250\347\275\262\346\214\207\345\215\227.md" "b/doc/04-\351\203\250\347\275\262\346\214\207\345\215\227.md" index 41e3febc..ec8c1ed3 100644 --- "a/doc/04-\351\203\250\347\275\262\346\214\207\345\215\227.md" +++ "b/doc/04-\351\203\250\347\275\262\346\214\207\345\215\227.md" @@ -1,10 +1,10 @@ # 星序 Astra — 部署与运行指南 -> **文档梗概**：当前正式门户、本机真实 API、静态演示的运行与发布；保留生产能力的代码入口，不重复旧 staging 操作流水。 +> **文档梗概**：学科主站、职教子站、本机真实 API 与公开静态展示的运行方式；说明独立数据目录、可选 AI 配置和验证边界，不重复旧 staging 操作流水。 > > **具体规划法则**：默认操作本机开发环境。部署、初始化、迁移与外部副作用必须区分；历史演练结果不证明当前生产可用。 > -> **最后一次更新时间**：2026-09-16 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -17,17 +17,23 @@ 5. [后端与迁移](#5-后端与迁移) 6. [生产边界与维护工具](#6-生产边界与维护工具) 7. [故障定位](#7-故障定位) +8. [职教子站运行与数据](#8-职教子站运行与数据) +9. [可选 AI 配置与验证边界](#9-可选-ai-配置与验证边界) ## 1. 运行方式与环境 | 方式 | 数据与输出 | | --- | --- | -| 完整本机版本 | `qianduan/dist` + FastAPI + SQLite，`http://127.0.0.1:9001/` | -| 前端热更新 | Vite 5173；真实模式的 `/api`、`/labs` 代理到 9001 | -| 静态演示 | `qianduan/dist-demo`；无真实账号或成绩，刷新重置 | +| 学科主站完整本机版本 | `qianduan/dist` + FastAPI + SQLite，`http://127.0.0.1:9001/` | +| 学科主站前端热更新 | Vite 5173；真实模式的 `/api`、`/labs` 代理到 9001 | +| 学科主站静态演示 | `qianduan/dist-demo`；无真实账号或成绩，刷新重置 | +| 职教动态课堂 | `zhijiao/apps/web/dist` + Fastify；页面 4173、API 3001，见第 8 节 | +| 职教公开导览 | `zhijiao/.local/public-student-demo/dist`；预设访谈、浏览器草稿，无教师提交与评分 | | 公网业务后端 | 尚未作为本阶段交付；不能把 Pages 当作业务服务器 | -Python 使用 3.12+ 和 [requirements.lock](../backend/requirements.lock)。Node/npm 按 [.node-version](../.node-version) 与 [package.json](../package.json) 使用 Node 24.20.0 / npm 11.19.0；该版本满足当前 Windows 递归复制约定。CI 读取同一 Node 配置，不维护另一份版本值。 +学科主站 Python 使用 3.12+ 和 [requirements.lock](../backend/requirements.lock)。Node/npm 按 [.node-version](../.node-version) 与 [package.json](../package.json) 使用 Node 24.20.0 / npm 11.19.0；该版本满足当前 Windows 递归复制约定。CI 读取同一 Node 配置，不维护另一份版本值。 + +职教子站是独立 pnpm 工作区；[package.json](../zhijiao/package.json) 当前版本为 `3.0.1`。运行预检要求 Node `>=22.12.0` 和精确的 pnpm `11.9.0`，并非任意 pnpm 11 均可。Windows 启动器还要求 `corepack` 命令可用；不能仅凭 Node 版本推定 Corepack 已安装。根 npm 锁与职教 pnpm 锁分别安装，不能互相替代。 中文文件使用 PowerShell 7 与显式 UTF-8；Python 命令使用 UTF-8 模式。临时文件只放工作区已有临时目录，不在磁盘根创建临时目录。 @@ -39,7 +45,11 @@ Python 使用 3.12+ 和 [requirements.lock](../backend/requirements.lock)。Node powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 ``` -启动器解析精确 Python，安装锁定依赖、构建正式门户、执行 Alembic 后前台启动 Uvicorn。成功入口为 `http://127.0.0.1:9001/`；停止使用 `Ctrl+C`。准确行为以 [astra-local.ps1](../astra-local.ps1) 为准。 +启动器默认在仓库 `.venv` 创建或复用 Python 环境，解析精确 Python，安装锁定依赖、构建正式门户、执行 Alembic 后前台启动 Uvicorn。成功入口为 `http://127.0.0.1:9001/`；停止使用 `Ctrl+C`。准确行为以 [astra-local.ps1](../astra-local.ps1) 为准。首次使用空数据目录并需要管理员时，执行： + +```powershell +powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -BootstrapAdmin +``` 数据默认保存在 `%LOCALAPPDATA%/Astra/local-preview`，包含 `astra-local.sqlite3` 与审计盐。`-DataDirectory` 可选择隔离目录；同一数据库的重复进程由实例标识与互斥检查阻止。用户的既有数据库不得因演示失败而删库重建。 @@ -53,6 +63,17 @@ powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 两个 Python 选择参数互斥。外置环境需要匹配真实 `sys.prefix`；初始化失败后先检查输出，不将未知环境当作可用后继续迁移。 +需要把托管 Python 环境放在仓库外时，可使用以下示例；路径允许 Unicode 和空格，规范化后不得等于仓库根或位于其子目录： + +```powershell +$ExternalVenv = Join-Path $env:LOCALAPPDATA "Astra\Python 环境\preview venv" +powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -VirtualEnvironmentPath "$ExternalVenv" +``` + +该模式拒绝 Windows device namespace。所选目录及现存祖先、`Scripts/python.exe`、依赖标记和 `Lib/site-packages` 不得经过 junction、symlink、volume mount 或 cloud reparse point。脚本要求 Python 3.12+ 的 `sys.prefix` 精确归属所选目录，依赖锁 SHA 标记保存在该环境内，不创建或修改仓库 `.venv`。 + +已有调用方自管环境时使用 `-PythonExecutable "" -SkipDependencyInstall`。脚本不会安装依赖或写依赖标记，而是在创建数据目录、审计盐、迁移和初始化之前，用同一解释器执行离线哈希锁 dry-run 与 `pip check`；失败即停止。后续 pip、Alembic、初始化及 Uvicorn 均使用选定的精确 Python。`-BootstrapAdmin` 与 `-InitializeDemoData` 也不能同时使用。 + 演示初始化器会检查既有合成记录是否漂移，不覆盖已被人工修改的账号、课程或学习事实。保留可用原数据；需要全新演示时明确指定新的隔离目录。合成记录不代表真实课堂证据。 当前 HTTP 服务读取 `qianduan/dist`，不会自动把修改过的 TypeScript 变成新的静态产物。正式验收时重新构建并重启；前端开发使用 Vite。 @@ -114,3 +135,134 @@ python -X utf8 -m uvicorn app.main:app --host 127.0.0.1 --port 8000 | Cookie 写入被拒绝 | 页面来源、API 来源与允许列表是否一致 | | 演示初始化拒绝既有记录 | 是否人工修改过合成样例；保留原库，选新隔离目录 | | 新课程没有可引用活动 | 核对目录注册、官方活动白名单和前端选项，见 01 第 11 章 | +| 主站职业教育入口无法打开 | 职教 4173 是否已就绪，主站构建时的 `VITE_VOCATIONAL_APP_URL` 是否正确 | +| 联合启动后职教进度似乎消失 | 默认创建新目录；检查终端输出的 `dataDir`，下次复用使用 `-ReuseVocationalData` | +| 职教提示包管理器版本不符 | 在 `zhijiao/` 运行 `corepack pnpm preflight`，须精确匹配 pnpm 11.9.0 | +| AI 助教返回 503 | 主站是否同时设置启用开关与服务端密钥；见第 9 节 | + +## 8. 职教子站运行与数据 + +### 8.1 独立启动与账号 + +从仓库根目录启动动态课堂： + +```powershell +powershell -ExecutionPolicy Bypass -File .\zhijiao\启动职教星云.ps1 +``` + +[启动器](../zhijiao/启动职教星云.ps1) 会准备本地 pnpm shim、执行预检、按 `pnpm-lock.yaml` 安装依赖，再构建和启动 API/Web。就绪后学生入口为 `http://127.0.0.1:4173/`，教师入口为 `http://127.0.0.1:4173/login?role=teacher`；API 为 `http://127.0.0.1:3001/`。Web 通过同源代理访问 `/api` 与 `/health`，停止使用启动终端的 `Ctrl+C`。 + +| 参数 | 用途与边界 | +| --- | --- | +| `-Role teacher` | 启动后打开教师登录入口；不绕过登录 | +| `-FreshData` | 在 `.local/fresh-runs/<时间与进程标识>` 创建新数据目录，不删除旧目录 | +| `-SkipInstall` | 跳过依赖安装；仅用于现有依赖与锁文件一致时 | +| `-SkipBuild` | 复用已有构建产物；修改源码后应重新构建 | +| `-NoBrowser` | 只启动服务，不自动打开浏览器 | + +登录页提供教师 `teacher` 和学生 `student1`、`student2`、`student3`，公开演示密码均为 `Demo2026`，原件见 [demo-login-accounts.ts](../zhijiao/apps/api/src/demo-login-accounts.ts)。这是本机演示身份体系，与主站首管理员、账号和 Cookie 会话独立；不能据此声明已完成公网账号体系。 + +也可在已提供精确 pnpm 命令的环境中，从 `zhijiao/` 运行： + +```powershell +pnpm preflight +pnpm install --frozen-lockfile +pnpm start +``` + +`pnpm start` 默认复用数据；`pnpm start:fresh` 创建新目录；`pnpm dev` 构建共享包后启动开发 API 与 Vite。职教开发 Web 默认也是 5173，与主站 Vite 相同，同时开发须为其中一个显式选择其他端口。页面入口和端口以启动输出为准。 + +### 8.2 联合启动与主站入口 + +已经完成主站首次账号初始化后，从仓库根目录运行： + +```powershell +powershell -ExecutionPolicy Bypass -File .\start-joined-stack.ps1 -ReuseVocationalData +``` + +[start-joined-stack.ps1](../start-joined-stack.ps1) 分别启动主站 9001 和职教 4173/3001；保留两套服务和数据，不合并 API、账号或数据库。**省略 `-ReuseVocationalData` 时，联合启动器默认向职教传递 `-FreshData`，每次创建新目录。** 此开关复用默认目录或 `DEMO_DATA_DIR` 指定目录，不会自动选择最近一次 fresh 目录；需要接续该次进度时，应把 `DEMO_DATA_DIR` 指向其实际路径。 + +联合启动还支持 `-AstraPort`、`-VocationalRoot`、`-SkipVocationalInstall`。它不透传主站 `-BootstrapAdmin`、自管 Python 或外置环境等全部参数；需要这些选项时，按第 2 节和 8.1 节分别启动两个进程。 + +主站职业教育入口通过 [environment.ts](../qianduan/src/services/environment.ts) 的 `VITE_VOCATIONAL_APP_URL` 跳转，默认值为 `http://127.0.0.1:4173/`。修改职教 Web 端口或使用其他地址时，应在构建主站前设置此变量，并重新构建主站；仅改职教端口不会同步改变跳转地址。现有主站 Pages 包也不能自动提供本机职教 API。 + +| 配置 | `pnpm start` / 启动器行为 | +| --- | --- | +| `DEMO_HOST` | API/Web 共同监听地址，默认 `127.0.0.1` | +| `DEMO_API_PORT` / `DEMO_WEB_PORT` | 默认 3001 / 4173；Web 代理随之设置，端口占用会拒绝启动 | +| `DEMO_DATA_DIR` | 复用模式的数据目录；推荐绝对路径，fresh/smoke 模式另建目录 | +| `WEB_ALLOWED_ORIGINS` | 允许来源列表；启动脚本追加本次 Web 来源 | +| `VITE_API_PROXY_TARGET` | 单独运行职教 Web 时的 `/api`、`/health` 代理目标 | + +配置示例见 [zhijiao/.env.example](../zhijiao/.env.example)。启动脚本读取 `zhijiao/.env.local`；其中 `HOST`、`PORT`、`DATA_DIR` 用于直接运行 API，完整演示栈会用上表 `DEMO_*` 计算后覆盖它们。不要把更改 `PORT` 当作更改完整栈端口。 + +### 8.3 数据与停机备份 + +| 系统 | 默认位置与内容 | +| --- | --- | +| 学科主站 | `%LOCALAPPDATA%/Astra/local-preview`，包括 `astra-local.sqlite3`、审计盐；可用 `-DataDirectory` 隔离 | +| 职教动态课堂 | `zhijiao/.local/data`；fresh 模式另存 `.local/fresh-runs/`，实际路径由启动输出的 `dataDir` 确认 | +| 职教内容库 | 职教数据目录的 `content-library/`，嵌入式 PGlite；14 张业务表加 1 张迁移记录表 | +| 职教学习记录 | 同一职教数据目录内的 JSON/JSONL、会话事件、选课、世界状态、笔记、作品、评价及 `objects/` 附件等 | +| 职教公开导览 | 当前浏览器的本地记录；不进入上述服务端目录 | + +职教 SQL schema 位于 [migrations.ts](../zhijiao/packages/content-store/src/migrations.ts)，文件存储接线位于 [server.ts](../zhijiao/apps/api/src/server.ts)。PGlite 是内嵌 PostgreSQL 运行时，无需单独安装 PostgreSQL 服务；它只承载内容库，不能把所有课堂状态都视为 SQL 表。两套数据分别备份，主站 SQLite 副本不能恢复职教会话，只复制职教内容库也不能恢复全部课堂进度。 + +职教提供 `pnpm data:backup`、`pnpm data:verify`、`pnpm data:restore`。它们调用已构建的 [data-safety-cli.ts](../zhijiao/apps/api/src/data-safety-cli.ts)，所以先完成正常构建。备份前停止持有同一数据目录的 API；恢复只接受尚不存在的新目标目录。以下示例在 `zhijiao/` 执行，若本次用了 fresh 或自定义目录，替换为实际路径： + +```powershell +$VocationalData = (Resolve-Path .\.local\data).Path +$VocationalBackups = Join-Path $env:LOCALAPPDATA "Astra\vocational-backups" +pnpm data:backup --data-dir "$VocationalData" --backup-root "$VocationalBackups" +``` + +使用备份输出的绝对 `backupPath` 执行 `pnpm data:verify --backup "<备份目录>"`；恢复参数为 `pnpm data:restore --backup "<备份目录>" --target-data-dir "<新目录>"`。后续运行把 `DEMO_DATA_DIR` 指向恢复目录并采用复用模式，不能继续使用 fresh 开关后误认为恢复无效。 + +### 8.4 公开导览构建与预览 + +公开导览与动态课堂是不同构建入口。准备好职教依赖后，在 `zhijiao/` 执行： + +```powershell +pnpm build:packages +node scripts/build-public-demo.mjs +python -X utf8 -m http.server 4174 --bind 127.0.0.1 --directory .local/public-student-demo/dist +``` + +访问 `http://127.0.0.1:4174/`；上述预览使用已安装的 Python 标准库静态服务。[build-public-demo.mjs](../zhijiao/scripts/build-public-demo.mjs) 实际生成 `.local/public-student-demo/dist`，包含相对路径资源、课程目录及分课程 JSON。当前 `package.json` 没有专用 `build:public` / `preview:public` 脚本，也没有 `preview-public-demo.mjs`；`@ronggang/web preview` 预览的是动态 Web 的 `dist`，不能替代这里的目录预览。 + +导览包含蟳埔、榕江、山地景区三个地区的五门课程：社区深度采访、赛事采编、发布与回应、素材与版权、暴雨服务报道。页面提供课程资料、预设人物访谈、当前浏览器内的笔记和作品草稿，以及 Markdown 导出；没有实时模型对话、服务端提交或教师评分。清除浏览器数据会清除导览记录，正式业务数据不应填入公开导览。 + +### 8.5 分项验证入口 + +在 `zhijiao/` 按变更范围选择 `pnpm preflight`、`pnpm build`、`pnpm typecheck`、`pnpm test`。服务连通烟测使用 `pnpm start:smoke`，会创建临时数据、检查 API/Web/代理和演示会话，结束后清理本次临时目录；它不证明所有课程或真实模型流程已通过。需要离线验证时，先显式设置 `DEMO_MODEL_PROVIDER=deterministic` 和 `IFLYTEK_MODE=mock`，避免继承已有真实服务配置。 + +`pnpm check` 是定义中的组合入口；当前快照缺少其 `check:docs` 预期的 `zhijiao/doc` 文档集，也未提供 Playwright 配置与独立端到端套件。不能把脚本存在或其他分项通过写成完整门禁已通过。实际执行结果、缺项和验证环境统一记录在 03。 + +## 9. 可选 AI 配置与验证边界 + +### 9.1 学科主站 AI 助教 + +主站助教由 FastAPI [ai_tutor.py](../backend/app/api/endpoints/ai_tutor.py) 提供，需要已登录用户。默认关闭；仅当启用开关、DeepSeek 提供方和服务端密钥同时满足时才发起模型请求。配置由进程环境或 `backend/.env` 提供，读取规则见 [config.py](../backend/app/core/config.py)，更改后重启 API。 + +| 配置 | 当前默认与用途 | +| --- | --- | +| `ASTRA_AI_TUTOR_ENABLED` | `false`；启用时设为 `true` | +| `ASTRA_AI_TUTOR_PROVIDER` | `deepseek`，当前支持的提供方 | +| `ASTRA_AI_TUTOR_API_KEY` | 服务端密钥；不写入浏览器 `VITE_*`、源码或公开制品 | +| `ASTRA_AI_TUTOR_BASE_URL` | `https://api.deepseek.com` | +| `ASTRA_AI_TUTOR_MODEL` | 代码默认 `deepseek-chat`；按实际账号可用模型明确配置 | +| `ASTRA_AI_TUTOR_TIMEOUT_SECONDS` | 默认 30，允许 5–120 秒 | + +登录后 `GET /api/ai-tutor/config` 返回可用状态，`POST /api/ai-tutor/chat` 未启用时返回 503“学校尚未启用 AI 助教”；上游请求失败或没有可显示回答时返回 502。当前请求使用单次问题与页面上下文，不自动查询课程证据库，也不替代教师评分或学习掌握认定。普通本机启动和静态演示不构成真实模型验收。 + +联合启动器另有配置桥接：若 `zhijiao/.env.local` 中存在非空 `DEEPSEEK_API_KEY=`，会为主站设置助教启用、DeepSeek 地址及 `deepseek-flash` 模型。该行为不取决于职教的 `MODEL_PROVIDER`，也不自动采用职教自定义模型地址；需要分别控制两站 AI 时，采用独立启动并显式设置各自环境。 + +### 9.2 职教模型、检索与媒体处理 + +职教 [model-gateway](../zhijiao/packages/model-gateway/src/config.ts) 支持 `deterministic`、`deepseek`、`iflytek_xingchen`。默认模型为 `deterministic`，讯飞适配器为 `IFLYTEK_MODE=mock`，核心课堂演示不要求真实模型密钥。真实 DeepSeek 需在服务端设置 `MODEL_PROVIDER=deepseek`、`DEEPSEEK_API_KEY` 和所用模型等配置；完整栈若设置 `DEMO_MODEL_PROVIDER`，其优先级高于 `MODEL_PROVIDER`。 + +`DEEPSEEK_LIVE_SMOKE` 是专门测试的开关，不是业务联网总开关；即使值为 0，已选择真实提供方的业务请求仍可能访问外部服务。`SHOWCASE_DETERMINISTIC_STRUCTURED=1` 会让部分结构化智能体继续使用确定性实现，不能凭健康检查中的提供方名称宣称全部智能体都调用了真实模型。模型输出仍需经过人物知识范围、结构校验和世界规则；需要教师确认的状态变更由教师门控承认。 + +本地材料解析、向量检索与媒体能力需要额外环境，不包含在 pnpm 安装内。[setup-ai025-runtime.ps1](../zhijiao/scripts/setup-ai025-runtime.ps1) 和 [setup-be007-runtime.ps1](../zhijiao/scripts/setup-be007-runtime.ps1) 默认建立 Python 3.11 的独立工作环境；模型资源可能首次下载。解释器路径可用 `RONGGANG_AI025_PYTHON`、`RONGGANG_CONTENT_PYTHON` 指定。仅提供模型 API Key 不等于完成材料导入、授权、切片和向量索引。 + +当前场景材料覆盖五门课程，但人物采访的内容库检索接线仍以蟳埔课程作用域为入口，不能描述为所有课程均已完成通用 RAG。`pnpm content:prepare` 依赖既有 `资料/04-职业教育依据/` 中的指定 PDF 和正在运行的动态站，会执行导入与索引，不属于无条件的首次启动步骤。真实模型、向量工作环境、媒体转写/理解和教师评价应分别验证；没有配置图像模型及对应处理依赖时，不把文本降级结果宣称为真实多模态观察。 diff --git "a/doc/05-UI\350\247\204\350\214\203\346\250\241\346\235\277.md" "b/doc/05-UI\350\247\204\350\214\203\346\250\241\346\235\277.md" index 3cf4f107..28631210 100644 --- "a/doc/05-UI\350\247\204\350\214\203\346\250\241\346\235\277.md" +++ "b/doc/05-UI\350\247\204\350\214\203\346\250\241\346\235\277.md" @@ -1,10 +1,10 @@ # 星序 Astra — UI 规范与实验视觉约定 -> **文档梗概**：当前正式门户与保留实验的视觉、交互和可访问性约定。 +> **文档梗概**：学术门户、职教页面与保留实验的视觉、交互和可访问性约定。 > > **具体规划法则**：样式数值以代码为准；本文件解释设计意图和跨页面规则。旧概念图、旧签收流水和被替换的页面壳不作为当前规范。 > -> **最后一次更新时间**：2026-09-16 +> **最后一次更新时间**：2026-09-18 > > **更新者**：主开发组 @@ -18,15 +18,19 @@ ## 1. 正式门户 -当前样式来源是 [styles.css](../qianduan/src/styles.css)、[navigation.css](../qianduan/src/styles/navigation.css)、[workspace.css](../qianduan/src/styles/workspace.css) 和 [portal/styles.css](../qianduan/src/portal/styles.css)。 +未登录时，主站在开场后提供学术教育与职业教育两个方向。学术教育进入 `qianduan/` 的登录与三角色页面；职业教育跳转到独立的 `zhijiao/` 站点，目标由 `VITE_VOCATIONAL_APP_URL` 配置。当前默认地址是本机 4173，部署到其他环境时需对应可访问的职教入口，不能把跨站跳转描述为统一登录。接线见 [main.ts](../qianduan/src/main.ts) 与 [environment.ts](../qianduan/src/services/environment.ts)。 + +学术门户的样式来源是 [styles.css](../qianduan/src/styles.css)、[navigation.css](../qianduan/src/styles/navigation.css)、[workspace.css](../qianduan/src/styles/workspace.css) 和 [portal/styles.css](../qianduan/src/portal/styles.css)。 保留深色空间、冷青色交互点与少量暖色品牌表达；导航透明简洁，减少重复圆角矩形。内容层级优先依靠对齐、间距、字体、细线和留白，不能以增加装饰容器代替结构。 -顶栏为品牌及空间切换、当前页面名称、搜索和必要操作。侧栏随角色提供入口并可收起。学生、教师、管理页面共用视觉语言；后台状态文字要能帮助决策，不向普通用户堆积内部字段。 +学术门户顶栏为品牌及空间切换、当前页面名称、搜索和必要操作。侧栏随角色提供入口并可收起。学生、教师、管理页面共用视觉语言；后台状态文字要能帮助决策，不向普通用户堆积内部字段。 + +职教页面围绕课程档案、采访现场、作品和教师复核组织。档案页保留清楚的课程信息与进入动作，现场页面优先呈现当前地点、任务、人物和学习工具；不把星云轮盘复制为职教现场布局。独立样式见 [v2.css](../zhijiao/apps/web/src/v2/v2.css)、[experience-shell.css](../zhijiao/apps/web/src/v2/experience-shell.css)、[student-theme.css](../zhijiao/apps/web/src/v2/student-theme.css) 与 [teacher-theme.css](../zhijiao/apps/web/src/v2/teacher-theme.css)。 ## 2. 星云与课程轮盘 -运行时使用程序化三维场景，不使用固定星空图片冒充空间动画。课程轮盘采用局部、多轨、倾斜透视构图：近处间距较大，远处收紧，两门为主、过渡时最多三门。星云和可选课程应与轨迹一致，固定信息区保持可读。 +学术门户运行时使用程序化三维场景，不使用固定星空图片冒充空间动画。课程轮盘采用局部、多轨、倾斜透视构图：近处间距较大，远处收紧，两门为主、过渡时最多三门。星云和可选课程应与轨迹一致，固定信息区保持可读。 当前构图与换层参考： @@ -47,14 +51,27 @@ - 学生看到任务、反馈与下一动作；完成、分数和准入以服务端返回为准。 - 键盘焦点清楚，按钮有文字或可访问名称，不能只用颜色区分状态。 -复杂题型、媒体管理及新审核流程尚未完整实现，不能在设计说明中写成现成功能。准确页面范围见 [01 第 5 章](01-开发者手册.md#5-前端页面路由与可见交互)。 +学术课程编辑已支持讲解、函数与图表配置、原实验引用、图片/音视频/PDF、单选/多选/数值/简答检查点及作业完成条件。已有题组引用继续保留，当前表单不编辑题组原件。送审页面展示同步差异、冲突选择和旧结果处理方式，学校审核候选快照，教师发布已通过内容。实现见 [course-studio.ts](../qianduan/src/portal/course-studio.ts)、[submission-workspace.ts](../qianduan/src/portal/submission-workspace.ts) 与 [candidate-workspace.ts](../qianduan/src/portal/candidate-workspace.ts)；准确页面范围见 [01 第 5 章](01-开发者手册.md#5-前端页面路由与可见交互)。 + +学习页面显示所见发布版本和学习记录入口，继续旧版时说明认定边界；不把“回答正确”“获得评阅”“单元完成”合成一个状态。作业页显示本次任务快照、当前稿及可展开的历次记录；重交后同步列表状态。教师选择具体稿件批改，历史复核必须明确选择，原评分与积分差额可回读。未保存状态的验收要求是：子模块只管理自己的输入，保存成功后父页面也不能留下错误离页提示；须通过嵌套表单的真实操作核对。 -学习页面显示所见发布版本和学习记录入口，继续旧版时说明认定边界；不把“回答正确”“获得评阅”“单元完成”合成一个状态。作业页显示本次任务快照、当前稿及可展开的历次记录；重交后同步列表状态。教师选择具体稿件批改，历史复核必须明确选择，原评分与积分差额可回读。子模块只管理自己的未保存状态，保存成功后不遗留父页面的错误离页提示。 +职教现场的任务、地图、资料、人物交流、采访本和作品入口保持可辨识，工具面板不长期遮住主要观察区域。预设访谈、实时生成、等待教师复核和已确认结果分别标明；请求失败不能显示为已完成交流或交付。 + +| 体验方式 | 页面必须说明的状态 | +| --- | --- | +| 学术真实服务 | 账号与业务记录由服务端保存；保存失败、冲突和未知结果可辨识 | +| 学术静态演示 | 明确标识内存演示；切换身份用于体验流程，刷新重置业务数据 | +| 职教动态服务 | 区分人物生成结果、学生决定、作品提交和教师评价，不把建议当作既成事实 | +| 职教公开导览 | 明确标识预设访谈片段；笔记与草稿保存于当前浏览器，导出不等于提交或评分 | + +公开导览的现有说明见 [public-demo/main.tsx](../zhijiao/apps/web/src/public-demo/main.tsx)。这些模式分别说明，不把动态服务能力写成公开导览已具备的能力。 ## 4. 实验视觉与生命周期 原实验的 [tokens.css](../shared/css/tokens.css) 与代码空间私有样式继续保留，不把正式门户全局样式注入各个实验。每个新实验明确 page/module/namespace，避免 CSS 和全局对象冲突。 +公共学习空间与原活动资源预览保留 iframe；课程中的原实验通过“进入完整实验”整页打开，函数与图表模板在课程正文中呈现。页面导航与课程记录分别验收：当前原力学实验整页入口尚未接回发布绑定的参数记录，具体范围与源码见 [15 第 2.4 节](01-子文档/15-学科实验与内容开发指南.md#24-课程资源与操作记录接线)。 + Canvas 依据实际容器尺寸与像素密度绘制，不能把边框高度反复写回父容器造成 ResizeObserver 递增。标签、单位、图例和对比读数应足够清晰；科学计算与渲染表现分开，结果变化必须可解释。 实验进入后能操作、暂停或重置；退出取消 rAF、监听、观察器、定时器和专有图形资源。模型公式、适用范围、数值误差和复核说明统一放在 [15 号指南](01-子文档/15-学科实验与内容开发指南.md)，不把长篇开发说明塞进学生首屏。 @@ -63,6 +80,6 @@ Canvas 依据实际容器尺寸与像素密度绘制，不能把边框高度反 ## 5. 验证与边界 -当前正式门户以桌面为主要设计和验收环境，手机端精调尚未作为本轮交付。修改导航、编辑或实验操作时验证真实浏览器路径、关键尺寸、错误状态与离页重入；截图只能证明当时画面，不能代替权限或业务验证。 +学术门户与职教页面以桌面为主要设计和验收环境，手机端精调尚未作为本轮交付。键盘操作、焦点、基础触控和减少动态效果仍需可用。修改导航、编辑或实验操作时验证真实浏览器路径、关键尺寸、错误状态与离页重入；截图只能证明当时画面，不能代替权限或业务验证。当前已知问题与后续验收见 [02 第 3 节](02-更新规划.md#3-当前任务状态)。 既有实验保护规则和科学模型门禁继续运行。历史的固定行数、旧签收日期、旧代表课路线不构成新的设计目标；改动范围由当前任务与用户授权决定。 diff --git a/qianduan/README.md b/qianduan/README.md index 202edfb3..7546748f 100644 --- a/qianduan/README.md +++ b/qianduan/README.md @@ -1,6 +1,6 @@ # 星序正式前端 -当前门户使用 TypeScript、原生 DOM、Vite 和 Three.js。设计与页面说明统一见 [01 第 5.4 节](../doc/01-开发者手册.md#54-qianduan-独立前端原型)，进度与未来任务见 [02](../doc/02-更新规划.md)，不要在本目录另建一份实施计划。 +当前门户使用 TypeScript、原生 DOM、Vite 和 Three.js。设计与页面说明统一见 [01 第 5.4 节](../doc/01-开发者手册.md#54-正式门户的实现与数据适配)，进度与未来任务见 [02](../doc/02-更新规划.md)，不要在本目录另建一份实施计划。 ## 两种运行方式