AGENTS.md

本文件是 xinghen.work 项目的长期协作规则、功能事实基线和变更确认记录。所有在本仓库中工作的开发者与 AI Agent 都必须遵守。

它的核心目的不是记录“做过什么动作”，而是保存：为什么这样改、功能实际确认到了什么程度、哪些判断以后不能在没有新证据时随意推翻。

1. 适用范围与优先级

本文件适用于整个仓库。
开始任何代码修改、功能新增、缺陷修复、数据结构调整或部署操作前，必须先阅读本文件，尤其是“项目事实基线”“既有决策”和“变更与功能确认记录”。
若子目录以后出现更具体的 AGENTS.md，子目录文件可补充局部规则，但不得绕过本文件的变更记录和验证要求。
用户在当前任务中的明确要求优先级最高；若新要求与历史判断冲突，必须指出冲突，并把最终采用的新判断及理由追加到本文件。
不得为了让当前实现显得合理而删除、覆盖或悄悄改写旧记录。旧判断失效时，应新增一条“替代/废止”记录并链接旧记录编号。

2. 项目事实基线

2.1 产品定位

星痕·智能课程工坊是一个支持个人与组织工作区的课程生产系统。

用户可拥有个人工作区，并加入多个组织。
课程归属于一个明确的工作区。
个人与组织分别拥有积分账户和积分流水。
组织成员可查看本组织课程及进度。
组织管理员可管理成员、课程和组织账单。
平台管理员负责组织创建、状态管理和组织积分调整。

以上是当前产品基线，不代表所有路径都已经完成端到端验证。实际确认状态以本文末尾的记录为准。

2.2 技术组成

前端：React 19、Vite 6、TypeScript、React Router。
服务端：Fastify 5、TypeScript。
数据库：PostgreSQL 16。
文件：上传文件保存在持久化目录，数据库保存业务数据与文件元数据。
生产运行：Docker Compose，应用默认监听 3001，通过外部反向代理网络提供域名和 HTTPS。

2.3 关键目录

src/：前端页面、组件、上下文、API 客户端和类型。
server/：接口、数据库连接、迁移/建表和服务端业务逻辑。
public/：公开静态资源。
uploads/：本地上传目录；业务文件不得当作源码处理。
deployment/、deploy.sh、docker-compose*.yml：部署入口和生产编排。
docs/：面向项目的专项说明。

3. 必须保留的产品与工程判断

以下判断是修改相关功能时必须主动核对的约束。若确需改变，应先说明影响，再在变更记录中写明新结论替代了哪一条。

D-001 工作区和数据归属必须明确

课程、积分、账单、成员权限等数据都必须能追溯到个人或某个组织工作区。不得仅靠前端当前选中的工作区推断服务端数据权限；服务端必须校验登录身份、成员关系和角色。

D-002 历史个人数据不得被组织功能误迁移

已有课程默认继续属于个人工作区，已有个人积分继续属于个人账户。旧的用户“单位”资料不是组织成员关系，不能据此自动建立权限。

D-003 组织停用不等于删除

组织停用后，应阻止新成员加入和新建组织课程；历史课程、成员、账单与审计信息必须保留。恢复组织后仍应能继续使用已有数据。

D-004 组织积分必须可审计

积分余额变化必须有流水记录。普通成员只能看到其本人课程产生的组织积分消耗；组织管理员可以查看组织完整账单。调整余额时不能只改余额而不留流水。

D-005 上传文件必须经过鉴权

上传素材和交付文件必须通过鉴权接口读取。不得重新开放可猜测的 /uploads/ 公共静态路径。新增下载、预览或图片展示能力时，必须验证未登录、无成员关系和跨组织访问均会被拒绝。

D-006 首次登录改密是服务端约束

组织管理员现场创建老师账号时，当前初始密码为 888888，首次登录必须修改密码。前端提示不能代替服务端限制；任何绕过强制改密的业务接口都属于缺陷。

D-007 数据库变更必须兼容已有数据

服务启动会执行建表/迁移逻辑。修改 server/schema.sql、数据库初始化或查询代码时，必须考虑已有生产数据库，而不是只验证空库。危险或不可逆的数据迁移必须提供备份、回滚或明确的人工步骤。

D-008 生产部署不得伤害持久化数据

部署和同步操作必须保护 .env、上传文件以及 PostgreSQL/上传持久卷。使用删除式同步、重建容器或修改挂载前，要先核对真实目标和持久化边界。容器启动成功不等于新代码已部署成功。

D-009 公网功能必须按用户路径验证

涉及部署时，至少区分并记录：本地构建通过、镜像构建通过、容器健康、HTTPS/反向代理正常、真实页面/API 可用、新版本特征可见。未完成最后几项时不得声称“已上线”。

4. 每次修改的强制工作流

4.1 修改前

阅读本文件，并搜索与目标功能相关的决策编号、文件路径、接口名和历史记录。
检查当前工作区状态和相关差异，区分用户已有修改与本次任务修改；不得覆盖或清理无关改动。
明确本次功能的用户路径、权限边界、数据影响和验收标准。
若拟议方案与历史判断冲突，先向用户说明冲突和影响。不能通过悄悄改变旧规则来推进。

4.2 修改中

只修改本次目标所需的最小范围。
前端、接口、权限、数据库和部署配置如存在联动，必须逐层检查，不能只改可见界面。
不得提交密钥、密码、私钥、真实 .env 或用户上传数据。
对高风险变更保留回滚路径；对数据库或部署变更写清兼容性和恢复方式。
发现原判断不成立时，保留证据并在记录中更正，不得继续沿用未经验证的假设。

4.3 修改后

执行与风险相称的验证。基础代码改动通常至少运行：
- npm run check
- npm run build
仅有类型检查和构建通过，不能证明业务功能正确。涉及用户功能时，还要验证实际路径、关键状态和失败路径。
涉及权限时，至少验证：未登录、普通用户、正确角色、错误组织/越权访问。
涉及数据库时，至少验证：已有数据兼容、新数据写入、重复执行、约束与流水一致性。
涉及部署时，按 D-009 分层记录证据，并明确当前验证停在哪一层。
在结束当前任务前，必须按第 5 节模板向本文件末尾追加记录。代码和记录应属于同一次修改，不得留给“以后补”。

5. 变更与功能确认记录规范

5.1 不可省略的原则

每次修改代码或增加功能，都必须新增一条记录，即使只是小修复。
每条记录必须有唯一编号，格式为 C-YYYYMMDD-NN；同一天从 01 递增。
记录按时间顺序追加在文件末尾，不覆盖旧记录。
“修改完成”和“功能确认”是两回事。记录必须分别写清实现范围和验证证据。
不能运行的检查、未覆盖的场景、依赖人工确认的部分必须写入“未确认/风险”。
禁止使用“应该可以”“基本没问题”“已优化”等无证据结论。
若一次任务只调查而未改代码，可不新增变更记录；但若调查形成会影响后续实现的重要判断，应新增一条“仅决策”记录。

5.2 状态定义

已确认：目标用户路径已通过实际功能验证，并有可复述的结果。
部分确认：只完成了部分层级，例如类型检查/构建通过，但没有完成浏览器、接口、权限、数据库或公网验证。
未确认：实现或现状存在，但没有足够证据证明功能成立。
失败：验证明确未通过，必须保留失败现象和后续处理建议。
已替代：历史结论已被后续编号明确取代；旧记录仍保留。

5.3 追加模板

复制以下模板到本文件末尾并填写，不保留空泛占位文字：

### C-YYYYMMDD-NN｜简短标题

- 日期：YYYY-MM-DD
- 类型：功能 / 修复 / 重构 / 数据库 / 部署 / 文档 / 仅决策
- 需求与原因：用户要解决什么问题，为什么需要修改。
- 修改范围：列出实际修改的功能、接口、数据结构和关键文件。
- 保留/新增判断：引用既有 `D-xxx`；若形成新判断，写清适用边界。
- 功能确认状态：已确认 / 部分确认 / 未确认 / 失败 / 已替代
- 验证证据：执行了什么检查，验证了哪些用户路径，实际结果是什么。
- 未确认与风险：明确尚未验证、环境受限、兼容性或回滚风险；没有则写“无已知未确认项”。
- 后续修改提示：未来改到本功能时必须先确认什么。
- 关联：相关提交、任务、Issue 或被替代的记录编号；没有则写“无”。

5.4 记录质量示例

不合格：

完成了组织功能，测试正常。

合格：

新增组织停用接口，并在创建组织课程和审批成员接口中校验组织状态。npm run check、npm run build 通过；使用管理员账号确认停用后两个接口均返回 403，恢复后可再次创建课程。未验证生产数据库上的旧组织数据，因此状态为“部分确认”。

6. 验证矩阵

根据改动范围选择并记录，不要求与本次无关的验证，但不得省略相关层级。

改动范围	最低验证要求
纯文案/样式	目标页面实际查看；桌面端和受影响的窄屏布局；构建
React 页面/状态	主路径、空状态、加载、错误、刷新后状态；类型检查与构建
API 客户端/服务端接口	成功请求、参数错误、未登录、无权限、资源不存在
登录/权限	不同角色、首次改密、跨用户/跨组织越权、会话失效
组织/课程/积分	个人与组织归属、角色可见性、余额与流水一致性、组织停用状态
上传/下载	文件类型与大小、鉴权访问、跨组织拒绝、文件不存在、持久化
数据库结构	空库初始化、已有库升级、重复执行、约束、备份/回滚考虑
部署	脚本语法、Compose 配置、镜像、容器健康、HTTPS/API、版本特征

7. 安全与数据边界

仓库中即使出现本地密钥文件，也不得读取、展示、提交或复制其内容；优先检查其是否被忽略，并提醒轮换意外暴露过的凭据。
日志、截图、错误信息和变更记录不得包含密码、Token、Cookie、连接串中的密钥或个人敏感数据。
uploads/ 中的文件属于业务数据，不得为了测试批量删除或纳入版本控制。
删除组织、用户、课程、账单、上传文件、卷或生产数据属于破坏性操作，必须有用户明确授权和可核对的目标。
部署前必须核对目标服务器、目录、容器/项目名和数据卷；不得把历史服务器状态当作当前事实。

8. 完成标准

一次代码任务只有同时满足以下条件，才能向用户报告完成：

请求的实现已经落到代码或配置中。
没有覆盖用户已有的无关修改。
已完成与风险相称的验证，并如实区分通过、部分通过和未验证。
本文件末尾已经追加本次变更与功能确认记录。
对后续修改有约束力的新判断已经编号或明确写入记录。

如果因环境、账号、生产权限或外部依赖无法完成验证，应报告“部分确认”或“未确认”，说明缺口，不得用构建通过代替功能完成。

9. 变更与功能确认记录

C-20260923-01｜建立项目级协作、决策与功能确认机制

日期：2026-09-23
类型：文档 / 仅决策
需求与原因：后续修改代码和增加功能时，需要持续保存每次修改、功能确认结果和历史判断，避免新修改忽略此前已经确认的产品与工程边界。
修改范围：新增项目根目录 AGENTS.md；整理当前产品与技术基线、九条关键判断、修改前后流程、验证矩阵、记录状态和统一追加模板。
保留/新增判断：新增 D-001 至 D-009，覆盖工作区归属、历史数据、组织停用、积分审计、文件鉴权、首次改密、数据库兼容、持久化部署和公网验证。
功能确认状态：已确认
验证证据：已对照当前 README.md、package.json、docker-compose.prod.yml、.gitignore 和工作区文件结构核对文档中的项目名称、技术栈、常用命令、生产端口、持久卷及主要功能描述；确认本次只新增该文档，未修改现有业务代码。
未确认与风险：当前工作区存在一批此前产生、尚未提交的组织工作区相关代码改动；本记录不宣称这些业务功能已经完成端到端验证。
后续修改提示：任何后续代码任务必须先阅读相关 D/C 编号，并在同一次任务结束前继续向本节末尾追加记录；不得覆盖本条记录。
关联：无。

C-20260923-02｜全站蓝色适配纯粹星辰品牌色

日期：2026-09-23
类型：样式
需求与原因：用户提供纯粹星辰品牌蓝色样图，要求全项目蓝色视觉统一。
修改范围：从样图主体区域采样为 #55B0F7；调整 src/styles.css 的主色、悬停色、蓝色浅底、边框、阴影和常用状态色，并同步课程、首页与管理台组件中的蓝色行内样式。
保留/新增判断：保留 D-001 至 D-009 的业务与工程边界。品牌主蓝为 #55B0F7；浅蓝背景上的按钮文字使用深蓝，交互悬停使用较深蓝与白字以保持辨识度。
功能确认状态：部分确认
验证证据：npm run check、npm run build 通过；浏览器检查了本地营销首页桌面和窄屏呈现，主按钮、标题强调及进度条已显示新蓝色。仓库检索未发现主要旧蓝色值残留。
未确认与风险：未逐一检查需登录的课程工作区和管理台页面；未部署到公网。当前本地 3001 端口已有其他服务占用，未用本次启动的服务端验证登录页面。
后续修改提示：新增蓝色样式优先使用 --blue、--blue-dark 和对应蓝色浅底；在有文字的浅蓝按钮上检查对比度。进入登录后页面或部署时继续做实际页面核对。
关联：无。

C-20260923-03｜按钮与蓝色层级改为简约扁平风格

日期：2026-09-23
类型：样式
需求与原因：用户反馈 C-20260923-02 后的浅蓝底深字按钮观感欠佳，要求整体保持简约、扁平并重新调整配色。
修改范围：调整 src/styles.css 的主按钮、强调按钮、次按钮、导航和选中态。品牌蓝 #55B0F7 继续用于视觉强调；承载白字的操作按钮改用同色系深蓝 #0875BD，悬停色为 #075F9B；移除按钮阴影与上浮效果，圆角收至 6px，增加键盘焦点轮廓。
保留/新增判断：替代 C-20260923-02 中“品牌浅蓝直接作为主按钮底色”的具体用法；保留其品牌蓝采样结论与 D-001 至 D-009。品牌色用于强调，文字按钮使用对比度更高的深蓝。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；本地浏览器查看营销首页，主按钮呈现为平面深蓝底白字，导航注册按钮与标题强调有明确层级。
未确认与风险：需登录的课程工作区和管理台尚未逐页目视核对；未部署公网。
后续修改提示：新增按钮先复用 .primary-button、.secondary-button，品牌蓝 --blue 用于强调，按钮面使用 --blue-action；勿恢复主按钮阴影和上浮位移。
关联：C-20260923-02。

C-20260923-04｜全站课程展示最后更新时间与创建时间并支持按时间排序

日期：2026-09-23
类型：功能 / 前后端协同
需求与原因：个人登录后，所有课程展示位置需在合适处呈现课程的最后更新时间与创建时间，尤其在组织管理的课程列表中需展示且支持按时间排序。
修改范围：
1. 服务端：server/db.ts（mapCourse 增加 updatedAt）、server/organizations.ts（补充 c.updated_at 与 c.created_at 查询字段）、server/index.ts（资产上传/删除同步触发 courses.updated_at = NOW()）。
2. 前端类型与工具：src/types.ts（Course 增加 updatedAt?: string）、新增 src/utils/date.ts 规范化时间格式化。
3. 页面展示与排序：
  - src/pages/OrganizationManage.tsx：课程管理表格增加“最后更新时间”与“创建时间”两列，支持表头点击升降序排序与下拉框快捷切换；
  - src/pages/Dashboard.tsx：课程卡片底部展示创建日期与最后更新时间，并在顶栏支持按更新时间/创建时间升降序排序；
  - src/pages/OrganizationPage.tsx：课程进度表格增加最后更新时间与创建时间列，并支持表头点击排序与下拉选择；
  - src/pages/CourseWorkspace.tsx：工作区头部标题栏下方展示创建时间与最后更新时间；
  - src/pages/admin/AdminCourses.tsx 与 AdminOrganizations.tsx：补充创建时间与最后更新时间列与详情展示。
保留/新增判断：保留 D-001 至 D-009。课程时间以服务端数据为准，编辑讲稿、分集、上传或删除资产均更新课程 updated_at；排序默认采用最后更新时间最新优先（降序）。
功能确认状态：已确认（代码及编译已验证）
验证证据：npm run check（TypeScript 类型检查无报错）、npm run build（Vite 生产构建成功，无模块冲突）。
未确认与风险：未涉及数据库字段新增（原有 created_at、updated_at 字段已在 courses 表中存在），无数据迁移风险；公网尚未部署。
后续修改提示：任何对课程内容的实质性变更接口，应确保维护 updated_at = NOW()。
关联：无。

C-20260923-05｜工作区数字讲师资产库与课程单讲师引用

日期：2026-09-23
类型：功能 / 数据库
需求与原因：将课程级讲师改为个人或组织工作区的数字讲师资产；组织成员共用资产但按所有者分配编辑权限，并允许个人讲师独立复制到组织。用户随后明确允许资料不全时创建及选课，提交制作前才要求照片、录音齐备；未来 AI 素材验证另行接入。
修改范围：新增 digital_instructors、digital_instructor_files、digital_instructor_events 及课程讲师引用和提交快照；增加幂等旧讲师迁移；新增资产库、统一选择器、个人复制到组织、所有者转移、文件补充/替换、平台管理员维护入口；课程创建、编辑和模板流程改用工作区讲师，移除旧课程级讲师写入接口；更新文件鉴权、提示和帮助文案。核心文件为 server/schema.sql、server/digital-instructors.ts、server/index.ts、server/db.ts、src/components/DigitalInstructorPicker.tsx、src/pages/DigitalInstructorsPage.tsx、src/pages/admin/AdminDigitalInstructors.tsx、src/pages/NewCourse.tsx、src/pages/CourseWorkspace.tsx、src/api.ts。
保留/新增判断：遵守 D-001、D-002、D-005、D-007、D-009。讲师只属于一个工作区，组织讲师默认所有者为创建者；组织成员可使用全部组织讲师，普通成员仅所有者可编辑，组织管理员及平台管理员可编辑组织讲师并变更所有者。个人讲师加入组织使用独立文件副本。每门课程最多选择一位讲师；创建和选课允许素材不全，提交制作必须有至少一张照片及一份录音。当前只校验文件格式、大小及是否上传，不判断素材质量；未来接入 AI 验证时必须将其结果纳入提交条件。已提交课程使用讲师快照；讲师删除从资产库隐藏，保留历史课程引用和文件。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；在独立 PostgreSQL 测试库执行空库建表、插入旧课程讲师后重复运行迁移，旧讲师只迁移一次并关联旧课程；隔离服务中实际验证资料不全创建和选课、提交返回 409、补齐文件后提交成功；验证组织成员查看及选择、非所有者编辑返回 403、组织管理员和平台管理员编辑成功、所有者转移后新所有者可编辑、跨工作区选课返回 400、未登录及越权文件访问返回 401/403、个人讲师复制后照片和录音文件名均独立；删除已提交课程引用的讲师后，资产库隐藏但历史快照仍可读取。浏览器查看个人资产库、课程创建选择器及平台管理员组织讲师维护页。
未确认与风险：未在生产库或公网执行迁移、部署或验收；未用真实可克隆录音验证音频可用性，当前不会进行 AI 质量判断；未覆盖所有窄屏与旧数据异常组合。生产升级前必须备份数据库及上传目录，核对迁移后的旧课程引用和文件数；如需回退，恢复备份数据库及文件目录并回滚应用镜像，不应直接删除新表以免丢失升级期间新增资产。
后续修改提示：新增 AI 验证后，不能仅以“文件存在”作为提交准入；应保存可追溯的检测结果和版本，保证已提交课程快照不随资产编辑变化。新增文件访问或删除路径时继续验证跨个人、跨组织及历史快照。迁移旧讲师不凭空补录音。
关联：无。

C-20260923-06｜统一讲师创建入口并核查组织页面与管理功能

日期：2026-09-23
类型：功能 / 修复
需求与原因：数字讲师应只在资产库创建，课程创建与编辑只选择已有讲师；同时检查组织页面和组织管理功能。
修改范围：src/components/DigitalInstructorPicker.tsx 移除内嵌创建流程，改为仅选择并提供资产库入口；src/pages/DigitalInstructorsPage.tsx 整理独立创建表单、搜索、空状态和工作区标题，移除组织权限说明文案，并避免创建与编辑表单同时显示；src/pages/CourseWorkspace.tsx 更新选择文案；src/styles.css 补齐页面样式；src/pages/OrganizationPage.tsx、src/pages/OrganizationManage.tsx 将课程排序 useMemo 移到条件返回之前，修复状态变化时的 Hook 调用顺序问题。
保留/新增判断：遵守 D-001、D-005、D-006、D-009 和 C-20260923-05。数字讲师的创建入口为资产库，课程路径只引用已有资产；组织管理权限继续以服务端成员关系和角色校验为准。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；本地浏览器检查数字讲师、组织页面及组织管理页面，组织课程、成员、积分、邀请和管理区块正常展示；独立 PostgreSQL 测试库实际验证未登录、成员、管理员和非成员的访问边界，申请及审批、邀请加入及停用、成员创建和改名、首次改密限制、积分调整与流水可见性、组织停用和恢复后的接口行为，断言均通过。测试库已删除。
未确认与风险：未在公网或生产数据上验证；未执行真实组织的增删改操作，浏览器端交互仅核查已有页面与只读展示；窄屏布局和所有课程操作未逐项验证。
后续修改提示：组织页面若增加条件渲染，保持 Hook 在所有返回之前调用；组织管理新增操作需复核角色和停用状态，并用独立数据验证失败路径。
关联：C-20260923-04、C-20260923-05。

C-20260923-07｜已用于课程的讲师禁止删除并支持复制

日期：2026-09-23
类型：功能 / 修复
需求与原因：用户要求任何已有课程引用的数字讲师不可删除，并在讲师管理页面复制讲师。
修改范围：server/digital-instructors.ts 删除时在事务中锁定讲师并检查全部课程引用，命中时返回 409；新增同工作区复制接口，复制讲师资料和独立上传文件，记录来源与事件，复制件默认归操作人所有；src/api.ts 增加复制客户端；src/pages/DigitalInstructorsPage.tsx 和 src/pages/admin/AdminDigitalInstructors.tsx 增加复制操作。
保留/新增判断：遵守 D-001、D-005、D-007 和 C-20260923-05。只要课程仍引用讲师，无论课程状态，讲师都不能删除；复制件不继承课程关联，文件使用独立副本；停用组织不能复制新讲师。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；独立 PostgreSQL 测试库验证复制后 ID、来源、所有者及照片文件路径不同，未登录复制返回 401，草稿和已完成课程引用均阻止删除，未使用的复制件可以删除；本地浏览器确认资产库中出现“复制讲师”按钮。测试库已删除。
未确认与风险：未对生产数据、平台管理员页面的实际点击复制和组织停用场景做浏览器端验证；未部署公网。复制文件可能随讲师数量增加而占用更多存储空间。
后续修改提示：如引入课程讲师引用的新状态或关系，删除准入仍需覆盖全部引用；如调整复制机制，保持文件独立和来源可追溯。
关联：C-20260923-05、C-20260923-06。

C-20260923-08｜讲师创建流程按照片与录音步骤优化并统一名称备注

日期：2026-09-23
类型：功能 / 数据库 / 样式
需求与原因：用户提供素材拍摄与录音准备参考图，要求创建讲师更友好；讲师资料只保留名称和备注，同一组织不能重名。
修改范围：新增 src/components/DigitalInstructorCreateForm.tsx，将创建流程分为讲师资料、照片、录音三个区块，增加拍摄/录音提示、格式大小校验、照片预览和录音试听；调整资产库和平台管理页的编辑字段为名称及备注；更新 src/api.ts、src/types.ts 和 server/digital-instructors.ts 的输入输出与复制逻辑；server/schema.sql 新增备注列并把旧简介一次性迁入备注，新增组织内名称去重触发器，保留历史重名数据；src/styles.css 补齐表单与窄屏导航样式。
保留/新增判断：遵守 D-001、D-005、D-007 和 C-20260923-05。组织内有效讲师姓名按去首尾空格、忽略大小写比较，创建、改名和跨库复制冲突返回 409；同工作区复制自动生成不冲突的“副本”名称。个人库允许同名。名称必填、备注选填；照片和录音允许创建后补齐，课程提交制作前仍须两项齐备。当前提示仅供用户自查，不声称已通过素材质量验证。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；独立 PostgreSQL 测试库验证组织同名创建/改名/个人复制入组织返回 409、组织内复制自动递增副本名、个人库不受组织重名限制、备注字段正确返回；重复执行建表脚本成功；模拟旧库缺少备注列后重跑迁移，旧简介保留到备注。浏览器查看桌面创建表单、输入已有名称的即时提示和禁用保存，390px 视口下无页面横向溢出。测试库已删除。
未确认与风险：未在生产库或公网执行迁移与验证；浏览器未实际上传真实照片和录音并听审质量。历史组织同名记录保留，编辑其名称时须改为唯一名称；旧 organization、introduction 数据列暂留作兼容，不再出现在新讲师界面。
后续修改提示：未来 AI 质量检验须保存可追溯结果，并在提交制作时加入准入判断；若改变讲师命名规则，需同步服务端触发器、复制命名及前端即时提示。生产升级前备份数据库与上传目录。
关联：C-20260923-05、C-20260923-07。

C-20260923-09｜手机拍照与设备直接录音

日期：2026-09-23
类型：功能 / 样式
需求与原因：用户要求创建讲师时可追加多张照片，手机可以直接拍照，手机或电脑可以直接录音，不必预先准备文件。
修改范围：src/components/DigitalInstructorCreateForm.tsx 的照片选择改为分批追加、去除重复选择、单张移除和最多 19 张限制；窄屏提供后置摄像头拍照入口；新增基于浏览器 getUserMedia 和 MediaRecorder 的录音、计时、结束、取消、试听与重录流程，并在离开表单时释放麦克风。server/digital-instructors.ts 接受浏览器录音常见的 WebM、Ogg MIME 类型；讲师编辑及平台管理页的文件选择同步允许这些格式；src/styles.css 调整桌面与手机上传布局。
保留/新增判断：遵守 D-005 和 C-20260923-05、C-20260923-08。照片可多张，录音每位讲师当前仍为一份；录制与选择文件最终走相同的鉴权上传接口和提交前素材齐备判断。最多 19 张照片加一份录音对应当前服务端 20 文件限制。手机拍照调用系统相机，浏览器录音需要 HTTPS 或 localhost 及麦克风权限；未获得权限时可继续上传文件。当前只校验文件存在、格式和大小，不判断质量。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；390px 浏览器视口下显示拍照入口，页面无横向溢出；通过浏览器文件选择器先选两张测试照片，再从拍照入口追加第三张，已选数量由 2 变为 3 且前两张仍在；独立 PostgreSQL 测试库验证 multipart 请求保存两张照片及一份 WebM 录音，讲师返回素材齐备。测试库已删除。
未确认与风险：未在真实手机上触发系统相机，也未授权真实麦克风录音，因此设备兼容性、权限弹窗和录音质量尚未确认；浏览器录制格式因设备而异，后续声音克隆服务若只接受特定格式，需在接入时转换或限制格式；未部署公网。
后续修改提示：若提高照片上限，需同步调整 multipart 文件数量限制和前端提示；接入声音克隆接口前确认 WebM、Ogg、M4A 的实际支持范围。
关联：C-20260923-08。

C-20260923-10｜数字讲师独立创建编辑与资产管理页

日期：2026-09-23
类型：功能 / 样式 / 接口
需求与原因：用户确认数字讲师的创建和编辑均使用独立页面，并要求统一照片、录音表单以及列表中的复制、删除和课程使用状态。
修改范围：新增独立创建及编辑路由和共用表单；编辑时可逐张保留、移除或添加照片，设置封面，更换或保留录音，组织管理员可调整所有者；重排个人、组织和平台管理资产列表，加入搜索、素材状态、课程使用情况、复制与删除确认；新增讲师详情、课程引用查询和一次提交多项编辑的接口，并为列表返回课程引用数量。核心文件为 src/pages/DigitalInstructorEditorPage.tsx、src/components/DigitalInstructorCreateForm.tsx、src/pages/DigitalInstructorsPage.tsx、src/pages/admin/AdminDigitalInstructors.tsx、server/digital-instructors.ts、src/api.ts、src/types.ts、src/App.tsx 和 src/styles.css。
保留/新增判断：遵守 D-001、D-005、D-007，以及 C-20260923-05、C-20260923-08、C-20260923-09。创建和编辑共用三段资料流程；照片和录音仍可暂缺，提交课程制作前要求齐备；已被课程引用的讲师在界面禁止删除，服务端继续返回 409；普通组织成员只能编辑自己拥有的讲师，组织管理员和平台管理员可维护组织讲师。编辑表单的文件增删和资料变更一次保存，失败时不提交部分数据库修改。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；独立 PostgreSQL 测试库及本地服务验证两张照片加录音创建、非所有者编辑返回 403、组织管理员一次编辑姓名备注及所有者并移除一张旧照片、增加封面照片和更换录音、课程引用数量变化、已使用讲师删除返回 409；平台管理员管理接口及引用查询通过。浏览器查看资产卡片、课程使用弹层、操作菜单、独立创建与编辑页，390px 视口无横向溢出且底部操作可见。测试服务已停止，测试库已删除。
未确认与风险：未在真实手机上验证系统相机和麦克风；未在生产数据库或公网验证。本地浏览器未对真实组织资料执行保存、复制或删除，相关写入由隔离接口测试覆盖。
后续修改提示：接入 AI 素材质量验证时，需同时更新共用表单提示与课程提交条件；若改变讲师删除策略，须同步课程引用查询、界面禁用状态和服务端 409 校验。生产升级前核对数据库与上传目录备份。
关联：C-20260923-05、C-20260923-08、C-20260923-09。

C-20260923-11｜数字讲师搜索、备注收起与照片完整预览

日期：2026-09-23
类型：功能 / 样式
需求与原因：用户希望资产库默认隐藏搜索栏，创建讲师默认隐藏选填备注；编辑照片要显示完整画面，并可点击放大。
修改范围：src/pages/DigitalInstructorsPage.tsx 将搜索和素材状态筛选折叠到搜索按钮，筛选生效时在按钮上提示并提供清除操作；src/components/DigitalInstructorCreateForm.tsx 将备注改为按需展开，已有备注在编辑时自动展开；已保存和待上传照片均支持点击查看大图及 Escape 关闭；src/styles.css 补充搜索面板、按钮、完整照片缩略图和全屏预览的桌面/手机样式。
保留/新增判断：遵守 D-005 及 C-20260923-10。搜索收起时保留筛选条件，并在入口标识“已筛选”，避免列表变化无法解释；备注收起不清空已有输入；受保护照片放大仍通过鉴权获取，不公开文件路径。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；浏览器确认资产库搜索默认收起、点击展开并聚焦输入框；编辑页照片点击后出现完整大图及关闭按钮；创建页备注默认收起，点击后出现文本框；390px 浏览器视口查看资产库搜索入口和创建页布局，无明显横向溢出。
未确认与风险：未在真实手机上验证触摸查看照片；未部署公网。本次未改服务端接口或数据结构。
后续修改提示：若增加照片处理或裁剪功能，缩略图和大图仍应保留查看原图的路径；筛选条件隐藏时需保持可见提示或恢复默认筛选。
关联：C-20260923-10。

C-20260923-12｜照片参考样例与录音倒计时朗读提示

日期：2026-09-23
类型：功能 / 样式
需求与原因：用户希望上传照片时能查看合适与不合适的参考样例；直接录音时显示朗读稿，先倒数 3、2、1 再录制，并显示录音时间，满 10 秒后用绿色提示。
修改范围：src/components/DigitalInstructorCreateForm.tsx 增加照片样例入口和弹层、固定朗读稿、获取麦克风后 3 秒倒数、实际开始录制后计时及 10 秒绿色时长提示，倒数期间可取消并释放麦克风；src/styles.css 增加样例、朗读稿与录音状态样式；public/guides/digital-instructor-photo-reference.png 保存用户提供的示例材料，弹层按适合和不适合两张画面展示，并可展开完整说明。
保留/新增判断：遵守 D-005 和 C-20260923-09。倒数结束前不启动 MediaRecorder；10 秒绿色仅说明本次录音时长达到提示线，不代表声音质量或未来 AI 检验合格，也不新增服务端时长限制。用户仍可上传现有录音文件。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；本地浏览器确认创建页出现样例入口和朗读稿，点击样例后显示照片对照；390px 视口查看两张对照照片可辨认、弹层可滚动，随后恢复默认视口。
未确认与风险：未授权真实麦克风，故倒数、实际录音计时和 10 秒状态切换尚未做设备端验证；未部署公网。构建提示主 JS 包超过 500 kB，未影响构建通过，本次未作拆包调整。
后续修改提示：接入正式声音质量或时长校验时，需在服务端校验音频真实时长和内容，不能依赖前端绿色提示；若替换参考图，检查手机端两张示例的裁切位置。
关联：C-20260923-09、C-20260923-11。

C-20260923-12｜平台管理员独立待制作课程队列

日期：2026-09-23
类型：功能 / 样式
需求与原因：制作团队需要单独查看当前等待制作的课程及提交资料，无需在全量课程表中筛选。
修改范围：新增 src/pages/admin/AdminProductionQueue.tsx 与 /admin/production-queue 路由；管理导航增加“待制作课程”，概览入口指向队列；队列逐课展示提交人、工作区、提交时间、分集与讲稿数量、素材文件下载、提交时的数字讲师快照照片和录音文件；src/styles.css 增加桌面与窄屏布局。
保留/新增判断：遵守 D-001、D-005、D-009 和 C-20260923-05。队列仅查询 WAITING_PRODUCTION 状态；讲师资料以提交快照为准；文件继续通过鉴权接口下载，不公开静态文件路径；完整制作操作仍进入现有课程详情页。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；核对现有管理员课程列表接口按状态过滤且由 adminAuth 保护，文件接口校验登录及管理员身份。未改服务端或数据库结构。
未确认与风险：当前未使用真实管理员账号在浏览器中验证队列加载、搜索、素材下载与窄屏页面；未部署公网。既有工作区含其他未提交修改，本次未清理或覆盖。
后续修改提示：若增加制作状态或团队分工，明确队列纳入条件和权限；讲师照片与录音需继续使用提交快照及受保护文件接口。
关联：C-20260923-05、C-20260923-10。

C-20260923-14｜平台管理员与普通用户身份彻底隔离

日期：2026-09-23
类型：功能 / 数据库 / 修复
需求与原因：平台管理员账户必须与普通用户、组织成员和组织管理员分开保存，双方不能通过后台操作互相转换，避免权限和数据归属误操作。
修改范围：新增 platform_admins、platform_admin_sessions 独立表；后台登录和后台鉴权改用独立管理员会话；普通登录只使用 users 与普通会话；启动迁移旧 users.role='ADMIN' 记录并保留管理员审计归属；数据库触发器禁止普通表出现非 USER 角色，也禁止管理员表与普通用户手机号重叠；移除用户管理中的升降级操作；管理员操作的审计、积分流水、组织审批和数字讲师事件增加管理员归属字段；平台管理员不能创建普通用户数字讲师资产。
保留/新增判断：保留 D-001、D-004、D-006、D-007、D-009。新增判断：users 只保存普通用户，platform_admins 只保存平台管理员；平台管理员与普通用户没有角色转换接口、共享会话或共享手机号；旧管理员若拥有课程、组织成员关系或数字讲师业务数据，启动迁移会停止并要求人工处理，不自动删除或转移业务归属。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；隔离 PostgreSQL 库验证普通注册、管理员注册手机号拦截、普通登录、管理员登录、交叉登录拒绝、普通会话访问 /api/me、管理员会话访问 /api/me、普通会话访问后台返回 401、管理员访问后台统计/课程/用户/组织/数字讲师接口成功、管理员退出后会话失效、角色转换接口返回 403；实际操作验证用户创建/重置密码、组织创建/更新、成员授权/移除、组织积分、申请审批、课程制作状态/积分/交付/结单、数字讲师查看/编辑/复制/删除；浏览器实际验证管理员登录后台、管理员退出、普通用户登录课程首页；迁移库验证旧管理员从 users 迁入 platform_admins 且普通用户表不再保留管理员记录；数据库触发器验证三种手机号/角色越界写入均被拒绝；生产模式服务启动成功。
未确认与风险：未在生产数据库或公网部署；本地隔离测试使用临时数据库和测试账号，临时服务已停止，测试数据库待清理；历史管理员若拥有业务数据会按设计阻止自动迁移，需要备份后人工制定归属方案；构建仍有 Vite 大包体积提示，但不影响构建。
后续修改提示：新增平台后台接口必须使用 adminAuth，普通用户接口不得接受管理员会话；审计、积分流水、审批和资产事件涉及操作人时应分别写入 admin_actor_id 或普通用户字段；不得恢复 users.role='ADMIN' 或升降级接口。生产升级前备份数据库和上传目录，并先核对旧管理员是否拥有业务数据。
关联：C-20260923-05、C-20260923-10、C-20260923-13。

C-20260923-13｜取消平台制作详情页并合并制作操作

日期：2026-09-23
类型：功能 / 重构
需求与原因：用户明确要求删除平台管理员现有制作详情页，避免与新待制作页面重复。
修改范围：移除 /admin/courses/:id 平台路由及各管理页面对此路径的链接；待制作队列卡片加入完整讲稿、提交人资料，以及接单操作；同页增加“制作中”切换、交付文件上传与下载、实际积分调整和完成交付。全部课程页保留为只读总览。AdminCourseDetail 组件仍供组织管理员课程路径使用，不作为平台管理员页面。
保留/新增判断：保留 D-001、D-004、D-005、D-009；平台制作操作集中于 /admin/production-queue，受原管理员接口鉴权约束。替代 C-20260923-12 中“完整制作操作仍进入现有课程详情页”的判断。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；检索确认平台管理端没有残留指向 /admin/courses/:id 的链接，组织管理路径仍引用原组件。
未确认与风险：未用真实平台管理员账号验证接单、上传、积分调整与交付；未部署公网。旧平台详情页中的更多辅助操作未全部迁入新队列，例如删除交付文件、退回待制作和修改已完成课程的交付说明。
后续修改提示：若团队需要恢复辅助操作，应直接在制作队列卡片中补充并验证相应状态及权限，不要重新引入重复的详情页。
关联：C-20260923-12。

C-20260923-14｜数字讲师创建默认所有者且编辑所有者权限收紧

日期：2026-09-23
类型：功能 / 样式 / 权限
需求与原因：用户明确要求：数字讲师创建时默认所有者为创建者本人，无需填写；编辑时普通用户不可修改所有者，仅管理员编辑时可以修改。
修改范围：src/components/DigitalInstructorCreateForm.tsx 确认创建时不展示所有者字段；编辑组织讲师时，非管理员显示只读禁用的所有者姓名并提示仅管理员可修改，管理员提供成员下拉框支持更换；保存时非管理员不传 ownerId；src/pages/DigitalInstructorEditorPage.tsx 补充系统管理员与组织管理员判断并传递 canManageOwner；src/styles.css 补充输入框禁用样式。服务端原有时序与权限（创建直接设为创建者自身、编辑非管理员改所有者报 403）保持生效。
保留/新增判断：遵守 D-001、D-005、D-009 和 C-20260923-05。数字讲师创建时不提供所有者填写项，服务端强制设为 uid(req)；编辑时所有者修改权严格限定为组织管理员及平台管理员，普通所有者编辑时字段只读。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 全部通过。
未确认与风险：未在生产环境或真实公网验证；既有未提交改动继续保留。
后续修改提示：未来若扩展协作者或多人所有权，需在此表单和接口保持只读与管理员授权逻辑一致。
关联：C-20260923-05、C-20260923-10。

AGENTS.md 44 KB История Исходник