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 可用、新版本特征可见。未完成最后几项时不得声称“已上线”。

D-010 包管理器统一为 pnpm，禁止提交 npm lock

依赖管理以 pnpm 为准：使用 pnpm install / pnpm install --frozen-lockfile 安装依赖，提交 pnpm-lock.yaml 与 pnpm-workspace.yaml，不得提交 package-lock.json。新增或升级依赖后必须刷新 pnpm-lock.yaml 并验证 pnpm install --lockfile-only --frozen-lockfile 通过；.gitignore 已忽略 package-lock.json。

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-01 协作规范 · C-02 蓝色品牌色 · C-03 扁平按钮 · C-04 课程时间排序 · C-05 数字讲师资产库 · C-06 统一创建入口 · C-07 禁止删除已用讲师 · C-08 创建流程优化 · C-09 手机拍照录音 · C-10 独立创建编辑页 · C-11 搜索备注收起 · C-12 照片参考样例 · C-13 待制作队列 · C-14 取消制作详情页 · C-15 平台/用户隔离 · C-16 讲师默认所有者 · C-17 顶部栏管理员匹配与千分位。 验证状态：C-01 已确认；C-02/C-03 为样式“部分确认”；C-04~C-16 均为功能/修复“部分确认”（仅过 check/build 及接口隔离测试，未做公网与生产库验收）。

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-13｜平台管理员独立待制作课程队列

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

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

日期：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-14。

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

日期：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。

C-20260923-17｜顶部栏工作区管理员匹配与积分余额千分位展示

日期：2026-09-23
类型：UI / 体验 / 逻辑修复
需求与原因：用户明确要求：右侧“管理员”字样要跟当前工作区严格匹配，只有当前选中的工作区角色为管理员才显示，避免切换到个人工作区或普通组织成员时误显；积分部分文案需写清楚“积分余额：xxx”，且数字格式保持统一每三位用逗号隔开。
修改范围：
1. src/components/Layout.tsx：将 isOrgManager 从全局匹配任一组织角色（organizations.some）改为仅匹配当前工作区（currentOrganization?.role === 'MANAGER'）；若处于个人工作区或非管理员组织，则不渲染管理员徽标；
2. src/components/Layout.tsx：积分徽章文案更新为“积分余额：xxx”，并使用 .toLocaleString('zh-CN') 统一千分位逗号展示；
3. src/pages/OrganizationManage.tsx：组织积分余额数字同样增加 .toLocaleString('zh-CN') 格式化，保持全站一致。
保留/新增判断：遵守 D-001。前台“管理员”徽章必须与当前选中的工作区上下文保持一致，不能泄露或混淆其他工作区的管理权限。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 全部通过。
未确认与风险：未在生产环境构建部署。
关联：C-20260923-05。

C-20260923-18｜口播稿富文本弹窗与课程附件多选追加

日期：2026-09-23
类型：功能 / 样式 / 接口
需求与原因：长篇口播稿需要独立编辑空间与基础排版；分集素材和通用资产需要一次选择多份，也能多次添加待上传文件。
修改范围：课程详情页改为口播稿摘要与“编辑”入口，新增富文本弹窗，支持加粗、斜体、列表和长篇滚动编辑；保存到原讲稿字段，旧纯文本按段落显示；服务端保存时清理富文本标签。分集附件和通用附件的多次文件选择改为追加，显示待上传清单与删除入口，每批限 20 份。平台制作队列和组织管理详情按安全富文本显示讲稿，复制讲稿时提取纯文字。
保留/新增判断：遵守 D-001、D-005、D-009；讲稿沿用原字段，富文本使用显式格式标记区分旧纯文本，展示时清理 HTML；附件仍经原鉴权接口保存，不开放公开静态路径。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 通过；核对原上传接口支持 multipart 多文件、每次最多 20 份且单份最大 200 MB。
未确认与风险：未在已登录浏览器实际执行富文本保存、刷新回显、多次选择文件及上传；未部署公网。构建有既存的大包提示。旧分集创建弹窗仍提供纯文本初稿入口，创建后可进入新弹窗排版。
后续修改提示：若增加讲稿导出、搜索或下游 AI 处理，应先将富文本转换为纯文本或明确解析格式；新增讲稿展示处不得直接信任数据库中的 HTML。
关联：C-20260923-04、C-20260923-17。

C-20260923-19｜课程素材全屏预览与讲稿弹窗布局、统计

日期：2026-09-23
类型：功能 / 修复 / 样式 / 接口 / 部署配置
需求与原因：用户要求 PPTX、PDF、Word、图片和视频上传后可预览，PDF 与 PPTX 可翻页；用户截图显示口播稿弹窗的工具栏和底部操作透出遮罩，并要求实时字数和口播时间估算。
修改范围：src/components/CourseAssetPreview.tsx 新增全屏预览，图片按原比例展示、视频使用浏览器播放控件、PDF 逐页渲染，PPTX 与 Word 调用鉴权转换接口后逐页渲染；分集和通用素材列表增加预览及下载入口，文件选择器标明支持格式。server/index.ts 新增课程素材鉴权预览接口，LibreOffice 按需转 PDF 并在私有上传卷缓存，删除素材或课程时清理对应缓存；Dockerfile 安装 LibreOffice 和中文字体。src/components/LectureNotesDialog.tsx 与 src/styles.css 修复弹窗整体白色容器、滚动和窄屏布局，增加实时字数与按每分钟约 260 字计算的时长；src/api.ts 的组织课程预览请求携带当前工作区标识。
保留/新增判断：遵守 D-001、D-005、D-008、D-009。预览先按素材所属课程和用户/组织角色鉴权；转换后的 PDF 保存在私有上传卷的 .previews 目录，不开放公共静态路径。时长仅为按字数估算，不代表成片实际时长。
功能确认状态：部分确认
验证证据：npm run check、npm run build、git diff --check 与本地 Docker 镜像构建通过；在隔离数据库、服务和上传目录中批量上传 PPTX 与图片，另上传 PDF、DOCX、MP4。PPTX 转换得到 6 页 PDF，浏览器实际从第 1 页翻到第 2 页；PDF 同样翻页，Word 显示转换后页面，图片全屏展示，MP4 显示播放控件；生产镜像内分别实际转换 PPTX 和 DOCX 并返回 PDF。未登录、其他用户、目标素材不存在分别返回 401、403、404；组织课程正确工作区访问返回 200，其他组织工作区返回 404，即使指定目标工作区但不属于该组织也返回 403。浏览器确认讲稿弹窗各区域在同一白色容器内，输入后字数与时间实时变化，取消后文字未保存。
未确认与风险：未部署到公网或使用生产数据验收；未在真实手机上验证讲稿弹窗触控与所有浏览器的视频编码兼容性，也未压测超大文档。PDF.js 工作线程与 LibreOffice 会增加前端资源体积和生产镜像体积；构建仍有主包超过 500 kB 的提示。非浏览器支持的视频格式需下载原文件查看。
后续修改提示：扩展预览类型时继续复用课程鉴权与工作区校验，不得直接公开缓存文件；生产部署前核对新镜像体积、上传持久卷、LibreOffice 可用性，并按 D-009 验证公网路径。
关联：C-20260923-18。

C-20260923-20｜修复本地 PPTX 预览调用并导入演讲者备注

日期：2026-09-23
类型：修复 / 功能
需求与原因：用户上传的 PPTX 在课程详情提示预览生成失败，并希望上传时自动把演讲者备注提取为口播稿。
修改范围：server/index.ts 的 LibreOffice 调用支持 SOFFICE_PATH，并在本机运行时提供现有依赖路径作为回退；新增 server/pptx-notes.ts 读取 PPTX 备注正文；上传单份 PPTX 时，对指定分集或仅有一个分集的课程，在口播稿为空时写入逐页备注。上传结果返回导入页数，课程详情显示导入提示。增加 jszip、fast-xml-parser 依赖。
保留/新增判断：遵守 D-001、D-005、D-007、D-009。备注只填空白讲稿，不覆盖人工内容；多分集课程的通用素材不自动猜测目标分集。原始 PPTX 继续保存在原鉴权路径。
功能确认状态：部分确认
验证证据：用户文件的 ZIP 校验通过，6 页均有演讲者备注；本机 LibreOffice 转换成功并生成 259015 字节 PDF；现有本地服务进程的 PATH 未包含 soffice，定位到原预览失败原因。使用新解析函数读取该文件得到 6 段正文；npm run check、npm run build、git diff --check 通过。
未确认与风险：未在已登录浏览器完成上传到分集、刷新回显和预览接口的端到端验证；未部署公网。该课程现有口播稿非空，按保留规则不自动回填。PPTX 备注顺序目前按 notesSlide 编号读取，重排过幻灯片但备注 XML 编号未重排的文件可能顺序不一致。
后续修改提示：生产环境优先使用镜像内 soffice 或显式 SOFFICE_PATH；如需覆盖已有口播稿，应增加用户确认与预览差异。处理特殊 PPTX 时应按 presentation 关系映射真实页序。
关联：C-20260923-19。

C-20260923-21｜确保生产容器可转换 PPTX 并修复预览中文缺字

日期：2026-09-23
类型：修复 / 部署配置
需求与原因：用户要求部署服务器后仍能调用 LibreOffice，并反馈当前预览中中文文字缺失，需增加原文件优先提示。
修改范围：Dockerfile 在安装 LibreOffice 后检查 /usr/bin/soffice 可执行；docker-compose.prod.yml 显式设置 SOFFICE_PATH；server/index.ts 在 macOS 转换时提供系统中文字体目录与微软雅黑到冬青黑体的替代配置，预览缓存升级为 v2 以跳过已生成的缺字 PDF，删除素材时一并清理两版缓存；src/components/CourseAssetPreview.tsx 与 src/styles.css 加入预览差异提示。
保留/新增判断：遵守 D-005、D-008、D-009。生产容器继续使用镜像内 LibreOffice 和 Noto CJK 字体；转换结果仍仅存私有上传卷，经鉴权接口读取。预览仅供查看，原文件为准。
功能确认状态：部分确认
验证证据：使用部署脚本相同的 linux/amd64 架构构建生产镜像成功；容器中 /usr/bin/soffice --version 正常，fc-match 微软雅黑 匹配 Noto Sans CJK；以用户 PPTX 在容器内转换成功，PDF 第一页正文完整可见且文字层含中文。本机原配置生成的 PDF 中文缺失；显式加载 macOS 字体目录与替代规则后，同文件转换的第一页中文完整可见。
未确认与风险：尚未部署服务器，未验证公网实际课程接口及持久卷中的新缓存；其他罕见或嵌入字体不保证版式完全一致。生产部署后仍需按 D-009 验证真实预览路径。
后续修改提示：升级 LibreOffice 或字体包时，用有中文及演讲者备注的真实 PPTX 检查渲染图和文字层；如更改缓存算法，更新缓存版本并维护删除清理。
关联：C-20260923-19、C-20260923-20。

C-20260923-22｜统一包管理器为 pnpm

日期：2026-09-23
类型：仅决策 / 文档
需求与原因：工作区此前同时存在已跟踪的 package-lock.json（npm）与未跟踪的 pnpm-lock.yaml / pnpm-workspace.yaml，包管理器混用会导致依赖不一致与部署失败。用户确认统一使用 pnpm。
修改范围：删除已跟踪的 package-lock.json；将 pnpm-lock.yaml 与 pnpm-workspace.yaml 纳入版本控制；.gitignore 新增忽略 package-lock.json；本文件新增 D-010 工程判断。
保留/新增判断：新增 D-010。依赖以 pnpm 为准，禁止提交 npm lock；新增或升级依赖后须刷新并提交 pnpm-lock.yaml，并用 pnpm install --lockfile-only --frozen-lockfile 校验一致。
功能确认状态：已确认（仅决策）
验证证据：用 corepack 激活 pnpm 12.5.1，pnpm install --lockfile-only --frozen-lockfile 返回 exit 0，确认 pnpm-lock.yaml 与当前 package.json 完全一致；npm 阶段新增的四个依赖（jszip、fast-xml-parser、qrcode、@types/qrcode）均已存在于 lock 的 packages 与 importers 段。
未确认与风险：本机此前未安装 pnpm，已通过 corepack 临时激活；后续开发/CI 需确保 pnpm 可用（建议 corepack enable 或全局安装 pnpm）。node_modules 当前仍为 npm 格式，首次 pnpm install 会将其转为 pnpm 符号链接结构，属本地可逆变更。
后续修改提示：所有安装、升级依赖必须走 pnpm；提交前确认 pnpm-lock.yaml 已更新且 package-lock.json 不出现在 git status。
关联：D-010。

C-20260923-23｜机构主页管理员点击课程进入详情

日期：2026-09-23
类型：功能
需求与原因：组织管理员需要从机构主页课程进度表直接打开课程详情。
修改范围：src/pages/OrganizationPage.tsx 将管理员视角的课程名称改为课程详情链接；点击时切换到该机构工作区。
保留/新增判断：遵守 D-001；沿用现有课程详情接口的服务端权限校验，仅向机构管理员提供此入口。
功能确认状态：部分确认
验证证据：确认 /courses/:id 路由和课程详情接口允许所属组织管理员访问；npm run check、npm run build、git diff --check 通过。
未确认与风险：未使用已登录机构管理员在浏览器实际点击验证，也未部署公网。
后续修改提示：若普通组织成员也需进入课程详情，先调整并验证服务端课程访问权限，再开放入口。
关联：D-001、C-20260923-04。

C-20260923-24｜广告落地页 /lp：数字人课程制作引流入口与线索后台

日期：2026-09-23
类型：功能 / 数据库 / 前端
需求与原因：需要在外部广告位投放 banner 引流，落地页须与主站隔离、互不干扰；以留下联系方式为主要目标、注册降为可选，并用广告语言写清数字人课程制作服务内容。用户确认：独立构建入口、留资为主 + 注册折叠选填、线索入库并做后台管理页、复用现有微信群二维码，微信号对外展示 bob-yuxinyang，价格不外露，暂不放样片。
修改范围：
1. 新增独立入口 landing.html 与 src/landing/（main.tsx、LandingPage.tsx、landing.css）；vite.config.ts 改为双入口构建；生产服务端新增 /lp、/lp/* 显式路由，返回 dist/landing.html。
2. server/schema.sql 新增 lead_requests 表（姓名/手机/微信/需求类型/体量/描述/来源/状态/备注/关联用户/时间）。
3. server/index.ts 新增 POST /api/public/leads（公开提交、按 IP 60 秒限流、同手机号 24 小时内合并更新、可选密码注册）、GET /api/admin/leads、PATCH /api/admin/leads/:id（均 adminAuth）。
4. 前端新增 src/pages/admin/AdminLeads.tsx、/admin/leads 路由与「落地页线索」导航项；src/api.ts 增加 admin.listLeads / admin.updateLead；src/types.ts 增加 Lead / LeadStatus；src/styles.css 仅新增 .status-filter-select 与 .lead-message 两个类。
5. README 补充落地页说明。
保留/新增判断：保留 D-001 至 D-010。新增：广告落地页必须与主站物理隔离（独立 HTML 入口 + 独立 CSS，不加载主站认证/路由上下文，样式统一 lp- 前缀）；线索属公开写入数据，必须限流并在服务端剥离 HTML；注册只能由用户显式填写密码触发，不得自动建号；同手机号 24 小时内重复提交按更新处理，避免线索重复。
功能确认状态：部分确认
验证证据：npm run check、npm run build 通过，产物含独立 dist/landing.html 与 landing-*.css|js，主站 dist/index.html 不引用任何 landing 资源（grep 计数 0）。以 NODE_ENV=production 启动本地服务（端口 3011）实测：/lp 与 /lp/anything 返回 200 且标题为「数字人课程制作 · 星痕智能课程工坊」，/dashboard 仍走主站 SPA 兜底；POST /api/public/leads 正常 201、非法手机号 400、缺微信号 400、同 IP 60 秒内 429、带密码提交返回 token 且用该 token 调 /api/me 返回 200（姓名与微信号已写入）、同手机号重复注册 409；同手机号 24 小时内再次提交经 SQL 核对仍为 1 行且字段为最新值；<script>alert(1)</script><b>加粗</b> 落库为「加粗正常内容」。GET /api/admin/leads 管理员 200 且带 userName，未登录与普通用户 token 均 401，PATCH 更新状态与备注返回 200。测试数据已清理（3 个测试账号、5 条线索、1 条临时管理员会话）。
未确认与风险：未做公网部署验证（D-009 的 HTTPS 与真实域名层未覆盖）；未做浏览器真机目视核对，桌面与窄屏仅按 CSS 断点编写；/lp 依赖 NODE_ENV=production 分支，本地开发需访问 /landing.html；lead_requests 建表仅在本地 dev 库执行过，未在生产库验证（语句为 CREATE TABLE IF NOT EXISTS + ADD COLUMN IF NOT EXISTS，可重复执行，但未经生产库实测）；本次未新增依赖，pnpm-lock.yaml 无需变更，验证使用的是 npm scripts 而非 pnpm。
后续修改提示：改落地页只动 src/landing/ 与 landing.css，禁止 import 主站 styles.css 或 src/api.ts；新增线索字段须同步 leadSchema、mapLead、Lead 类型与后台表格；投放链接建议带 ?from= 或 utm_source 以保留渠道归因；对外微信号与二维码位于 LandingPage.tsx 的 WECHAT_ID 常量与 src/assets/contact-group-qrcode.jpg。
关联：无。

C-20260923-25｜修复现场创建老师报错并取消首次登录强制改密

日期：2026-09-23
类型：修复 / 功能 / 数据库
需求与原因：机构管理员创建老师后账号已写入，却因异步提交后读取已清空的 React 事件 currentTarget 而显示 reset 报错；用户要求老师首次登录直接进入工作区。
修改范围：src/pages/OrganizationManage.tsx 在异步请求前保存表单元素，成功后重置表单并更新提示；server/organizations.ts 创建老师时将强制改密标记设为 FALSE；server/index.ts 与 src/App.tsx 移除旧强制改密拦截；src/pages/Profile.tsx 保留自愿改密入口但移除强制提示；server/schema.sql 幂等清除已有账号的旧强制改密标记；同步更新 README.md。
保留/新增判断：本条替代 D-006 的“首次登录必须修改密码”规则。现场创建账号仍使用初始密码 888888，首次登录可直接进入工作区；用户可在账户安全自行改密。服务端仍须校验登录身份及组织权限（D-001）。
功能确认状态：部分确认
验证证据：代码检查确认创建流程在异步边界前保存表单引用；npm run check、npm run build、git diff --check 通过。迁移语句仅更新标记为 TRUE 的账号，重复执行不再产生变化。
未确认与风险：未在隔离数据库中实际执行迁移及新老师登录全流程；未在公网部署或验收。固定初始密码仍需由机构管理员妥善交付，账号可自行改密。
后续修改提示：不得恢复新老师首次登录强制改密，除非用户提出新的规则；涉及登录流程应同时核对前端路由和服务端鉴权。
关联：替代 D-006；C-20260923-06。

C-20260923-26｜部署当前系统到 xinghen.work

日期：2026-09-23
类型：部署 / 修复
需求与原因：用户要求将整个系统部署到服务器，并确保 xinghen.work 可访问；授权必要时覆盖服务器数据库数据。
修改范围：Dockerfile 改为按 pnpm-lock.yaml 冻结安装、构建和启动；deploy.sh 同步时排除 uploads/；将当前代码构建为 linux/amd64 镜像并上传至 47.93.193.127:/opt/xinghen，重建应用容器。保留现有 PostgreSQL 与上传持久卷，未执行数据库覆盖。部署前数据库备份位于服务器 /opt/xinghen/.deploy/pre-deploy-20260923.dump。
保留/新增判断：遵守 D-007 至 D-010。数据库迁移在现有库上成功时保留数据，不因已有覆盖授权而无故清库；生产代理与证书配置沿用已核对的当前配置。
功能确认状态：部分确认
验证证据：本地 pnpm run check、pnpm run build、生产镜像构建、Compose 配置检查、脚本语法检查通过；新容器运行镜像 SHA 589c7600dc81faf8f563db789fa5fb6200fe56b862cd944434f6e08c52e4fddf。公网首页与 /lp 均返回 200，且返回本次构建的主站及落地页资源名；资源请求返回 200；/api/health 返回 200 与 {"ok":true}；HTTP 跳 HTTPS 返回 301；证书 SAN 包含 xinghen.work，有效期至 2026-12-12；未登录访问 /api/me 与 /api/admin/leads 均返回 401。容器内 LibreOffice 可执行，上传卷仍挂载。迁移后普通用户 5 条、平台管理员 1 条、课程 5 条，lead_requests 表存在。
未确认与风险：未使用真实账号完成登录、课程编辑、素材预览、线索提交及后台操作的公网端到端验收；未覆盖所有旧数据组合。回滚可恢复部署前数据库备份和先前镜像，上传卷没有被替换。
后续修改提示：后续部署仍须核对实际域名、当前代理配置和持久卷；若触发数据库覆盖，应先核对备份及目标库；新增功能需补充公网业务路径验收。
关联：D-007、D-008、D-009、D-010、C-20260923-21、C-20260923-24。

C-20260923-27｜修正 PPTX 备注换行并在选取素材后直接上传

日期：2026-09-23
类型：修复 / 功能
需求与原因：PPTX 备注导入的口播稿把换行显示为字面量 
；课程详情选择素材后还需再次点击上传。
修改范围：server/pptx-notes.ts 仅将备注中的十进制或十六进制换行字符引用转为真实换行；src/utils/lectureNotes.ts 对以“第 1 页”开头的旧版纯文本导入稿在展示、复制和打开编辑器时做相同规范化；src/pages/CourseWorkspace.tsx 选择分集素材或通用附件后立即上传，移除待上传清单及二次上传按钮，增加上传期间禁用重复选择，并在失败后刷新素材列表、提示核对后重选。
保留/新增判断：遵守 D-005、D-009 和 C-20260923-20；原始 PPTX 不变，已有人工口播稿不被自动覆盖；只识别换行字符引用，不对任意 HTML 实体做全面解码。历史讲稿的数据库原值暂不批量改写，用户打开并保存后写回规范化文本。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build 通过；使用合成 PPTX 备注验证 &#10; 经解析变成实际换行，而无关的 &amp; 仍保持原文本；检查两处文件选择入口均直接调用上传函数，且上传期间禁用再次选择。
未确认与风险：未使用已登录浏览器完成真实上传与刷新回显，也未在公网验证；未对生产数据库中的历史讲稿进行批量更新。现有上传接口逐份存储文件后写入数据库，若请求中途失败可能留下部分成功文件，重试前应查看素材列表。
后续修改提示：若需要批量持久修正历史讲稿，先按课程和分集预览差异并备份原值；PPTX 特殊文件仍需核对幻灯片真实顺序与备注对应关系。
关联：C-20260923-18、C-20260923-20。

C-20260923-28｜提交全量代码并重新部署生产站点

日期：2026-09-23
类型：部署 / 文档
需求与原因：用户要求提交当前所有代码，并把该提交重新部署到服务器。
修改范围：提交当时全部未提交的代码与记录，提交号 fcf1e84；构建 linux/amd64 生产镜像并部署到 47.93.193.127:/opt/xinghen，仅重建应用容器，保留数据库和上传持久卷。重部署前备份数据库至 /opt/xinghen/.deploy/pre-redeploy-fcf1e84.dump。
保留/新增判断：遵守 D-005、D-007 至 D-010。生产现有 Nginx 路由和证书仍有效，因此沿用现有代理配置。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、pnpm install --lockfile-only --frozen-lockfile、脚本语法检查、镜像构建通过；生产应用容器运行镜像 SHA cc0632a94d3520f130c26d5aec3ee9e2cf6b2ee092c3736d05ec97c0c3e53d9f，PostgreSQL 健康。https://xinghen.work/ 和 /lp 返回 200，首页引用本次构建的 main-8LOcnJ-3.js 且资源返回 200；/api/health 返回 200 与 {"ok":true}，未登录后台接口返回 401，HTTP 返回 301 跳转 HTTPS，证书 SAN 包含 xinghen.work 且有效期至 2026-12-12。对照本次部署前备份，课程记录部署前后均为 4 条；普通用户 5 条、平台管理员 1 条；上传卷仍挂载。
未确认与风险：尚未用已登录真实用户验证 PPTX 备注解析、自动上传、课程编辑及后台流程；这些功能仍为部分确认。上次部署记录的 5 门课程与本次部署前备份的 4 门不同，变化发生在本次重部署前，原因未在本次调查。
后续修改提示：若要追查课程数变化，检查应用审计和数据库备份，不要直接恢复整个库覆盖当前数据；后续部署仍须核对镜像、持久卷、域名及真实业务路径。
关联：C-20260923-26、C-20260923-27；提交 fcf1e84。

C-20260923-29｜修复管理后台组织管理创建组织及表单异步 reset 报错

日期：2026-09-23
类型：修复 / 前端
需求与原因：在管理后台创建组织时，接口调用成功但页面抛出 Cannot read properties of null (reading 'reset') 并在错误栏显示红字；排查确认系 React 异步事件处理函数中在 await 之后直接访问 e.currentTarget.reset() 导致（恢复执行时 SyntheticEvent 的 currentTarget 已被清空为 null）；同时全面排查项目中其他表单提交逻辑与异步事件处理。
修改范围：src/pages/admin/AdminOrganizations.tsx 在 await 前将 e.currentTarget 赋值给本地变量 formElement，成功后调用 formElement.reset()；在 create、setMember、points、rename、updateSlug、review 等表单与操作提交前统一清空旧的 error 和 message 状态；优化成员与积分表单成功后的重置体验。
保留/新增判断：遵守 D-001 至 D-010。前端表单处理中涉及异步操作并需要 reset() 时，必须在首个 await 之前保存 DOM 元素引用。
功能确认状态：部分确认
验证证据：已静态全量扫描 src/ 下所有 .reset()、currentTarget、target 及 onSubmit 异步函数，确认无其他类似跨 await 访问空引用的隐患；pnpm run check（tsc -b）通过，pnpm run build（vite build）通过。
未确认与风险：未在生产环境或浏览器真机模拟网络延迟端到端点击；未重新构建并推送 Docker 镜像至服务器。
后续修改提示：编写表单异步提交函数时，需遵循在 await 之前提取数据和保存表单引用（或使用受控组件/React Hook Form）的范式。
关联：C-20260923-25。

C-20260923-30｜提交组织管理表单修复并重新部署

日期：2026-09-23
类型：部署 / 文档
需求与原因：用户要求提交当前所有代码并重新部署生产站点。
修改范围：将组织管理表单修复及 C-20260923-29 记录提交为 17b3aff；构建 linux/amd64 镜像并部署到 47.93.193.127:/opt/xinghen，仅重建应用容器；部署前数据库备份在 /opt/xinghen/.deploy/pre-redeploy-17b3aff.dump，保留 PostgreSQL 和上传持久卷。
保留/新增判断：遵守 D-007 至 D-010；生产现有域名代理与证书有效，沿用现有配置。
功能确认状态：部分确认
验证证据：本地 pnpm run check、pnpm run build、git diff --check 与生产镜像构建通过；生产容器运行镜像 SHA dcc9fe5ed14c0084c1e15620749d27d8a4bf7ec865a3e84bbc0a483e9fc36596，PostgreSQL 健康。公网首页与 /lp 均返回 200，首页引用新版 main-B1p2drP9.js 且资源请求返回 200；/api/health 返回 200 与 {"ok":true}，未登录后台接口返回 401，HTTP 返回 301 跳转 HTTPS，证书 SAN 包含 xinghen.work 且有效期至 2026-12-12。课程部署前后均为 4 条，普通用户 5 条、平台管理员 1 条；上传卷仍挂载。
未确认与风险：尚未用真实平台管理员账号在浏览器完成创建组织、成员调整与积分表单操作；表单修复的公网业务路径仍为部分确认。
后续修改提示：如再次修改组织管理表单，应以真实管理员账号验证成功、错误与刷新后状态，并继续保护生产持久卷。
关联：C-20260923-29；提交 17b3aff。

C-20260924-01｜现场演示 HTML 幻灯片与品牌视觉

日期：2026-09-24
类型：文档 / 前端
需求与原因：为现有系统制作对外现场演示幻灯片，并加入纯粹星辰 Logo，整体视觉与星痕网站一致。
修改范围：新增 docs/现场演示-slides.html，包含 9 页可键盘、按钮和触屏翻页的单文件幻灯片；内嵌现有联系二维码与纯粹星辰官方 SVG Logo；采用主站品牌蓝、宋体标题、浅灰背景及扁平卡片。
保留/新增判断：保留 D-009 的证据边界；成品课程视频需在现场另行播放，讲课录音转写与 AI 整理逐字稿作为制作流程说明，不宣称当前系统已具备一键生成能力。
功能确认状态：部分确认
验证证据：HTML 解析成功，含 9 页、内嵌 Logo 与二维码；JavaScript 语法检查通过，静态检查确认翻页事件与联系方式存在；git diff --check 通过。
未确认与风险：本地 file:// 页面被浏览器工具安全策略阻止，尚未完成桌面及窄屏目视放映；正式演示前须实际打开幻灯片检查排版，并准备已制作课程样片。
后续修改提示：更新对外联系方式或品牌素材时同步检查本文件内嵌内容；增加播放视频应使用授权样片，并验证离线放映路径。
关联：无。

C-20260924-02｜导出现场演示 PDF

日期：2026-09-24
类型：文档
需求与原因：将现场演示 HTML 幻灯片导出为可投影、可分享的 PDF。
修改范围：新增 output/pdf/星痕现场演示.pdf，共 9 页 16:9 横版；沿用幻灯片的内容、品牌配色、纯粹星辰 Logo 与联系二维码。
保留/新增判断：延续 C-20260924-01；样片播放位置保留提示，PDF 不嵌入视频。
功能确认状态：已确认
验证证据：pdfinfo 确认 9 页、960×540 pt；逐页渲染 PNG 并检查九宫格缩略图，中文字体、Logo、二维码和卡片均可见；pypdf 确认标题、逐字稿与联系方式可提取。
未确认与风险：未在现场投影设备上检查；视频样片需单独准备。
后续修改提示：若 HTML 文案继续变化，应同步重导 PDF，并逐页渲染核对。
关联：C-20260924-01。

C-20260924-03｜导出可编辑 PPTX 现场演示稿

日期：2026-09-24
类型：文档
需求与原因：用户需要一份便于二次修改的 PPTX 版本。
修改范围：新增 output/pptx/星痕现场演示-可编辑版-v2.pptx，沿用 9 页 HTML/PDF 的内容、配色与纯粹星辰 Logo；标题、正文、卡片和色块保留为原生可编辑幻灯片元素，Logo 与二维码保留为图片素材。
保留/新增判断：延续 C-20260924-01 和 C-20260924-02 的内容边界；样片需现场另行播放，不在 PPTX 中内嵌视频。
功能确认状态：部分确认
验证证据：PPTX 结构校验与版面几何校验通过，9 页均可被 Artifact Tool 导入；使用项目工作区字体配置通过 LibreOffice 渲染 9 页并目视检查，中文、Logo、二维码与内容均正常；检查幻灯片 XML，关键文案保留为文本元素。
未确认与风险：未在 Microsoft PowerPoint 中实际打开编辑；现场使用的设备需安装中文字体或允许字体替换，否则可能出现换行变化。
后续修改提示：二次编辑后检查第 2 页样片占位与第 9 页联系方式；更换字体时重新检查整套幻灯片的换行和边界。
关联：C-20260924-01、C-20260924-02。

C-20260924-04｜平台制作与成员共用课程内容视图

日期：2026-09-24
类型：功能 / 样式
需求与原因：平台管理员接单时看到的课程详情与普通成员提交课程后看到的内容结构不同，双方沟通分集、讲稿和素材容易产生误会；制作操作需要与课程内容分区。
修改范围：新增 src/components/CourseContentView.tsx，在成员课程内容页及新平台单课制作页共用分集、讲稿、分集素材、通用备注与素材、数字讲师展示；成员提交后仍可查看课程内容。新增 src/pages/admin/AdminProductionWorkspace.tsx 与 /admin/production-queue/:id 路由，将接单、联系人、实际积分、按分集上传及删除交付文件、交付说明和结单放入独立制作操作区。制作队列改为简要入口；全部课程增加单课查看入口；调整桌面和窄屏样式。
保留/新增判断：遵守 D-001、D-004、D-005、D-009。共用组件只负责读取和呈现课程内容，管理员操作继续通过已有鉴权后台接口执行；提交后讲师优先展示提交快照。替代 C-20260923-14 中“制作操作必须全部放在队列卡片、不设置平台单课页面”的具体布局判断；保留“队列与单课页面不得重复承载完整制作内容”的目的。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、git diff --check 通过；用同一份模拟课程数据在本地浏览器打开成员与平台管理员页面，核对分集顺序、讲稿、每集素材、通用备注和讲师资料相同；桌面及 390px 窄屏目视检查，修复窄屏两列挤压问题；管理员制作进度页签可切换，交付区与课程内容视觉分离，未上传文件时结单按钮禁用。
未确认与风险：本地浏览器使用模拟接口和账号，未用真实已登录用户或平台管理员验证接单、积分调整、文件上传/删除、交付扣费及完成后回看；未部署公网。后台既有状态接口允许的流转范围比页面按钮更宽，本次未改动服务端流转规则。原有课程内容编辑视图与共用的提交后只读视图仍由不同组件呈现，需用真实课程核对特殊讲稿和旧讲师数据。
后续修改提示：修改课程详情字段或素材展示时，应同时检查成员与平台共用视图、提交快照和鉴权预览；新增制作操作必须保持在独立区域，并验证错误状态、跨组织访问及积分流水。上线前按 D-009 完成真实账号与公网路径验证。
关联：C-20260923-14、C-20260923-18、C-20260923-19。

C-20260924-05｜制作状态前置并简化数字讲师录音展示

日期：2026-09-24
类型：修复 / 样式
需求与原因：用户在真实课程页面指出制作中状态位于全部课程资料之后，打开页面难以先确认当前进度；数字讲师已上传声音时只需试听，无须在课程详情展示文件名和下载入口。
修改范围：src/pages/CourseWorkspace.tsx 将制作中状态面板移动到“课程内容”页签的最前面，课程内容仍在其后；src/components/CourseContentView.tsx 移除数字讲师录音文件名与下载按钮，保留鉴权试听；src/styles.css 清理不再使用的录音文件名样式。共用内容组件的改动同时作用于成员与平台管理员页面。
保留/新增判断：延续 C-20260924-04 的课程内容共用结构；制作中课程优先展示状态，数字讲师声音在课程详情中仅提供试听。素材文件的预览和下载功能不受影响。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、git diff --check 通过；在本地已登录的真实课程页面目视确认“制作中”卡片位于课程分集内容之前，数字讲师卡片只显示“试听”按钮，页面可访问性树中不再出现录音文件名和录音下载按钮。
未确认与风险：未在真实平台管理员账号中另行点击试听或做公网验证；播放器实现未变，本次只调整其周围的展示。
后续修改提示：若更改共用的数字讲师展示，需同时核对成员与平台管理员页面；状态顺序按课程状态分别检查，勿让制作中提示重新落到长讲稿之后。
关联：C-20260924-04。

C-20260924-06｜平台管理员编辑制作中课程的全部内容与素材

日期：2026-09-24
类型：功能 / 数据库
需求与原因：平台管理员接单后需要修改课程资料、分集讲稿和素材，原有成员接口在提交后限制分集增删和文件操作，后台只能查看课程内容与上传交付物。
修改范围：server/index.ts 新增仅平台管理员可调用、仅 IN_PRODUCTION 可写的课程资料、分集增删改、通用与分集素材上传删除、数字讲师快照同步及本课程专用编辑接口；server/schema.sql 新增 course_instructor_files 保存本课程专用照片和录音元数据，并接入鉴权文件读取；src/api.ts、src/components/AdminCourseContentEditor.tsx、src/pages/admin/AdminProductionWorkspace.tsx、src/styles.css 增加后台编辑模式。课程预览仍使用成员与平台共用的 CourseContentView。分集删除前校验至少保留一集及无关联交付文件；增删分集重算预计积分，不改实际积分或已扣流水。
保留/新增判断：遵守 D-001、D-004、D-005、D-007、D-009。平台管理员可修改制作中课程的课程级内容；本课讲师照片和声音修改只写课程快照及本课文件，不改共享讲师资产库。管理员主动“从资产库重新同步”才覆盖本课快照。后台编辑与成员读取同一份课程记录。制作完成后不允许继续编辑。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、git diff --check 通过；独立 PostgreSQL 测试库从空库启动并重复执行建表脚本通过。实际 API 验证管理员修改课程资料、分集、素材上传，成员刷新读取相同结果；未登录及普通成员无法调用后台编辑接口，其他个人账号无法读取文件；非法分集、唯一分集删除、错误讲师照片 ID、完成课程编辑均被拒绝。测试本课讲师名称、备注、照片和录音替换后成员可读取，资产库原讲师未变；重新同步后本课专用文件元数据被清理。隔离浏览器中核对后台编辑入口、保存回显、讲师编辑和预览，以及成员端显示管理员修改的讲师备注。
未确认与风险：未在生产库或公网验证；未用真实音视频文件检查媒体质量，也未完成窄屏实际目视检查。生产部署前备份数据库与上传目录；若需回退到旧版应用，须同时恢复与该版本对应的数据库和上传文件，否则本课新增的讲师文件旧版鉴权接口无法读取。管理员课程编辑与结单同时发生时，部分分集和素材接口仍可能有状态竞态，后续需通过事务串行化。
后续修改提示：课程快照专用文件必须始终经课程权限鉴权，新增快照替换路径需清理失效的本课文件；修改共享讲师资产不得自动改写历史课程快照。完成制作路径和预计/实际积分关系需一起复核。
关联：C-20260923-05、C-20260924-04。

C-20260924-07｜成员课程详情的各状态提示统一前置

日期：2026-09-24
类型：修复 / 样式
需求与原因：用户确认课程详情中只要存在状态提示框，均应在课程内容页签最前面，先说明状态再展示分集和素材。
修改范围：src/pages/CourseWorkspace.tsx 将已完成课程的交付提示和等待制作课程的排期提示移到共用课程内容视图之前；此前已前置的制作中提示保留原位。草稿和驳回状态目前没有独立状态提示框，本次未新增文案或状态流程。
保留/新增判断：延续 C-20260924-05，成员课程内容页签中现有的等待制作、制作中、已完成三类状态提示均先于分集和素材。制作进度页签与课程内容视图的数据来源不变。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、git diff --check 通过；独立测试库中的成员课程分别设为等待制作、制作中、已完成，浏览器可访问性树均显示状态提示标题在“课程分集与素材”之前。制作中课程还核对了讲师备注仍与后台保存结果一致。
未确认与风险：未在真实生产课程或公网逐状态核对；草稿和驳回目前没有独立提示框，若以后新增须遵守前置规则。
后续修改提示：增加或调整任何课程状态提示框时，把它放在课程内容页签的课程分集视图之前，并用对应状态的真实页面核对顺序。
关联：C-20260924-05、C-20260924-06。

C-20260924-08｜平台制作工作区课程内容编辑与共用视图

日期：2026-09-24
类型：功能 / 前后端协同
需求与原因：平台管理员制作课程时需要在课程详情中直接编辑提交内容，且成员与制作人员看到一致的课程内容，避免课程信息和制作操作分散。
修改范围：server/index.ts、server/schema.sql 增加平台管理员制作中课程编辑接口、课程讲师文件鉴权与元数据结构；src/components/AdminCourseContentEditor.tsx、src/components/CourseContentView.tsx、src/pages/admin/AdminProductionWorkspace.tsx 提供编辑器、共用视图和制作工作区；更新 src/App.tsx、src/api.ts、src/pages/CourseWorkspace.tsx、src/pages/admin/AdminCourses.tsx、src/pages/admin/AdminLayout.tsx、src/pages/admin/AdminProductionQueue.tsx 与 src/styles.css 接入页面和样式。
保留/新增判断：遵守 D-001、D-004、D-005、D-007、D-009 及 C-20260924-04、C-20260924-06。制作操作仍需管理员鉴权，制作中课程编辑范围及课程讲师快照文件遵循 C-20260924-06。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build 与 git diff --check 通过；具体业务路径及数据库/API 验证沿用 C-20260924-06 记录，本次未重复执行端到端验证。
未确认与风险：未在生产库或公网验证本次组合后的代码；课程内容和制作操作仍需真实平台管理员账号端到端验收。
后续修改提示：修改课程编辑、快照文件或制作队列时，继续核对成员与管理员读取同一课程记录、文件鉴权以及编辑与结单并发状态。
关联：C-20260924-04、C-20260924-06。

C-20260924-09｜部署制作工作区编辑至生产服务器

日期：2026-09-24
类型：部署
需求与原因：将已推送的课程制作工作区编辑功能部署到生产服务器。
修改范围：部署提交 866412f 对应镜像到 47.93.193.127:/opt/xinghen，仅重建 xinghen-app-1；部署前数据库备份保存为 /opt/xinghen/.deploy/pre-redeploy-866412f-20260924113445.dump。未修改反向代理配置；PostgreSQL 与上传卷保留。
保留/新增判断：遵守 D-007 至 D-010。生产数据库迁移由应用启动逻辑执行；数据库卷 xinghen_postgres_data 与上传卷 xinghen_uploads_data 不重建。
功能确认状态：部分确认
验证证据：pnpm run check、pnpm run build、docker buildx build --platform linux/amd64 --pull --load 通过；生产应用容器运行镜像 SHA 0ff8774dd3195b561027c6907fcfcee91d5cf296d384a7050b941332acd2c849，状态为 running；PostgreSQL 健康，上传卷仍挂载到 /app/uploads。https://xinghen.work/api/health 返回 200 与 {"ok":true}，首页返回本次构建静态资源 main-fVQOLHwP.js 和 main-CEdAkTL-.css，HTTP 跳转 HTTPS 为 301，证书 SAN 包含 xinghen.work。
未确认与风险：未使用真实平台管理员账号在公网完成课程编辑、分集与素材修改、成员端刷新回看等业务验收；新数据库迁移仅由应用启动执行，未在生产逐项检查新增数据结构。
后续修改提示：后续继续验证平台编辑与成员端读取同一课程内容、鉴权文件访问以及编辑与结单竞态；数据库或上传卷仍按 D-007、D-008 保护。
关联：C-20260924-06；部署提交 866412f。

AGENTS.md 88 KB Előzmények Nyers