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。

AGENTS.md 63 KB Verlauf Originalformat