ppt

Prompt

你是一名 Principal Product Engineer / Software Architect。 以下是一个已经完成大部分开发、目前进入产品化和体验优化阶段的真实项目。 不要重新设计一个理想化的新系统，也不要泛泛而谈。 请基于当前实现寻找最高价值的改进机会。 请从： 产品定位 → 用户体验 → 信息架构 → 功能闭环 → 业务流程 → 系统架构 → 工程质量 依次分析。 最终给出： Top 10 改进项，每项包含： 问题 / 证据 / 影响 / 建议方案 / 优先级 / 实现成本 最后再给出： 立即做、下一阶段做、暂时不要做 三档路线。 特别寻找那些： “代码已经做了很多，但用户仍然觉得系统复杂” 的根本原因。 不要因为技术上可以重构就推荐重构。优先寻找真正影响产品价值和用户体验的问题。 以下是项目资料： # Project Review Brief DeckForge（课件锻造中心）· 2026-10-06 · 基于仓库代码/配置/文档/迁移/测试的只读审查。标注：[F]=仓库证据确凿，[I]=推断，[U]=无法确认。 ## 1. Project Overview [F] DeckForge 是「卖成品的课件生产与交付系统」——明确不是 AI PPT 生成器、不是在线编辑器（`README.md` 、`docs/product/00_SOURCE_OF_TRUTH.md` ）。闭环：运营者在工作台打磨课件 → 发布为不可变「正式版」→ 公开演示在小红书获客 → 站外人工收款 → 客户（初中班主任）凭一次性 token 链接填 8 项班级信息，得到印着自己班级的课件（网页课堂播放 + 可编辑 PPTX 双交付）。 [F] 用户三类：创作者/运营者（当前同一团队单人）、客户班主任（无账号凭链接）、教师（HTML 课件线实例使用者）。市场为中国大陆初中班会/家长会，硬约束：禁境外 CDN/字体、断网可播、Chrome/Edge 优先。 [F] 成熟度：核心 MVP（P1–P6.6）代码层 VERIFIED，已部署内网测试机与公网生产（2026-10-03）。发布状态锁定`READY_WITH_EXTERNAL_QA_PENDING` ：PowerPoint/WPS 桌面 QA、教室硬件 QA 未完成（`docs/MVP_LAUNCH_CHECKLIST.md` §B/C 未勾选）。商业验证为零：两环境订单 0 行，客户仅 2 个试用实例。 [F] 实含两条产品线：① PPTX 线（slide-model → 9 个 React 渲染器 + PptxGenJS，27 页 Hero 版《初三，我们一起走》）；② HTML 课件线（2026-09 新增，24 套导入班会课件 + 教师实例）。两线领域模型/发布语义/交付方式独立，仅共享认证、存储卷与控制台外壳。 [F] 规模：npm workspaces，3 应用 + 12 包；Fastify API 约 171 端点（8 路由文件）；PostgreSQL 19 迁移约 40 表；控制台约 3.3k 行 TS/TSX；测试 59 文件约 150 用例；单人+AI 代理开发，无 CI。 ## 2. Current User Experience 四类入口：管理控制台（账号密码）、客户链接（免登录）、教师链接（免登录）、公开演示/公开 HTML（匿名）。 - 任务1 运营者造课件：`/new` 三步向导 → 工作台（内容 Tab 逐页改文案/绑素材/写讲稿，650ms 自动保存；结构 Tab 调页序与槽位默认值；发布与交付 Tab 跑 26 规则发布检查 →「审批并发布」→ 历史可下载 PPTX/回滚）。编辑是结构化字段表单+真实渲染器预览，非自由画布（产品原则 A/B 有意为之）；需理解 草稿→审批修订→正式版快照→current 指针 四层语义。 - 任务2 商品化收款：`/creator` 填商品资料→保存不可变商品版本→下载资料包→人工小红书发布→站外收款后`/creator/orders` 登记收款→创建客户实例→客户发布后回台账「确认交付」（服务端复核快照 COMPLETE+PPTX 字节/SHA）→CSV。订单-交付靠人工两页搬运；登记退款≠执行退款（UI 已提示）；无支付网关（设计如此）。 - 任务3 交付客户：`/customer-instances` 新建实例→弹窗一次性显示编辑/播放链接→人工发微信。下载文件名是技术名，SOP 解法为运营者下载后手动改名。 - 任务4 客户个性化：`/customer/edit/:token` → 左侧逐页真实渲染预览，右侧 8 槽位+照片焦点缩放（700ms 自动保存）→「发布我的版本」→ 播放页与 PPTX 下载。缺照片取景拖拽控件（契约支持 transform，UI 默认中心构图）；「当前版/购买原版」两种 PPTX 概念有解释成本。 - 任务5 发放教师实例：`/html-instances` 选模板+教师名→一次性`/t/<token>` 链接。 - 任务6 教师改信息生成课堂版：`/t/:token` 6 Tab 编辑器（内容/班级信息/图片/讲稿/检查/课堂版备份）→ 几何排版检查 → 「检查并生成课堂版」→ 下载单文件 playback.html（无讲稿/凭据/隐藏页）+ dfpkg 备份可续编。 - 任务7 公众售前：`/demo/:slug` 播放器（Beat 导航/缩略图/全屏/黑屏/断网续播）、`/api/v1/html-public/:slug` 沙箱、38 套家长会静态资源库`/resources/` 、硬编码 Hero 页的小红书图组页`/xiaohongshu.html` 。 [F] 系统性认知负担：导航 14 项（10 可见+4 折叠「高级」），领域概念 15+；「课件」一词同时指 PPTX 线 Edition 与 HTML 线 Courseware；「快照/正式版/版本/修订」四词并存最陡。 ## 3. Current Feature Map 已完整实现（真库+浏览器级验证）[F]： - PPTX 线全链：向导→工作台（乐观锁/冲突提示）→26 规则 QA→审批→确定性发布（指纹幂等/两阶段写入/逐件 SHA/原子 finalize/失败回收/回滚）→公开演示→客户实例/8 槽位/私有照片/客户快照/PPTX（`apps/api/src/publication.ts` 、`customer-delivery.ts` ）。 - 课堂播放器：manifest 严格校验、逐资产字节+SHA+解码验证、Cache API+SW 断网续播（`apps/player-web/src/runtime.ts` 、`public/sw.js` ）。 - Admin 认证：scrypt+12h 可吊销会话+5 次失败锁定+机器 Token 双通道（迁移 011/012）。 - 手动订单台账：幂等登记、乐观锁退款补录、交付事务内复核 PPTX、CSV 公式注入防护（迁移 014/015）。 - 创作者商品资料包：不可变版本、成本测算、按历史版本重导出。 - HTML 线：结构化/普通 HTML 双类型 CRUD、上传外链 CSP 告警、发布检查、公开沙箱、教师实例全流程、24 套一键导入（迁移 016–019）。 - 工件完整性审计工具链（`scripts/audit-artifact-integrity.mjs` 等）。 已实现但不完整 [F]： - VisualTemplate 持久化 payload 与渲染管线间有 adapter 缝（决策 D-023）：模板 token 未真正驱动渲染器/PPTX，预览仍走本地 Hero adapter。 - Demos 管理 items 顺序靠手编 JSON 文本域（`pages/demos.tsx` ）。 - 普通 HTML 课件刻意无在线编辑器（上传+沙箱预览，运营决策）。 - SW 无跨版本缓存淘汰/更新策略；局域网 HTTP 下 SHA 校验降级跳过（runtime.ts 注释自认）。 已规划未实现 [F]（`docs/GAP_BACKLOG_V2.md` 等）：商户/多租户隔离与开放注册；支付网关对账/自动退款；token 轮换、按人审计、RBAC（admin_users 无角色列）；R-042 历史渲染器版本保留 fixture。 看起来存在但未闭环 [F]： - 小红书获客→成交：物料生成完整，但订单数为 0，漏斗零转化验证。 - 38 套家长会内容库（`pages/public-catalog.tsx` ）：静态展示+合订 PPTX 下载，与商品/订单/交付零关联。 - 生产环境无任何 published demo row——生产售前演示入口实际不存在。 - AI 生图与 agent 写作桥（agent-context/agent-draft）：运营辅助工具，非客户产品能力。 ## 4. Architecture [F] 栈：TS strict + npm workspaces；Fastify v5；React 19 + AntD 5 + Vite（控制台/播放器两个 SPA）；PostgreSQL 16 无 ORM 手写 SQL；PptxGenJS；sharp；本地 FS 对象存储；Docker Compose+nginx；无队列/缓存/可观测性栈。 Plain Text 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 `创作者/运营者 ─账号登录→ Control Web SPA(~30路由, 含免登录分支 /customer/* /t/* /preview/*) │ Bearer(机器Token或12h会话) ▼ Fastify API 单体(~171端点, 8路由模块): CMS·Workbench·Publication(P3)·CustomerDelivery(P4)· Demo(P5)·Creator商品/订单·HTML课件/教师实例·AdminAuth·AI生图·XHS物料 │ 手写SQL(packages/db) │ ObjectStorage ▼ ▼ PostgreSQL 16 本地FS对象存储(不可变key) 19迁移/~40表/触发器强制不可变 snapshots/ customer-snapshots/ html-coursewares/ html-instances/ staging/ │ │ ├─PPTX线: slide-model(唯一内容源)→renderers(9个React渲染器@版本)→控制台预览+player-web； │ pptx-renderer(PptxGenJS 同源派生) └─HTML线: packages/html-courseware(单文件HTML渲染器)→沙箱预览/教师playback.html 发布产物 = manifest + assets + thumbnails + PPTX(同指纹确定性派生) 客户/教师 ─一次性hash-only token→ 控制台免登录页/Player；公众→/demo/:slug、/html-public/:slug、/resources/ nginx edge 聚合 / /player/ /api/ /resources/；生产前置 Caddy；一份多阶段Dockerfile出3镜像；全人工runbook部署` [F] 要点：单 SPA 服务管理员/客户/教师/预览四类受众（AppFrame 路径前缀分支）；不可变性靠 DB 触发器+约束在库层兜底，迁移带 SHA-256 校验和且历史不可改；存储`O_EXCL` 不可变写+staging→promote 原子晋升，S3 适配器全方法 throw 占位；无 LLM 进产品（仅服务端 AI 生图与外部 agent 桥）；无搜索/RAG；无 RBAC；无外部系统对接（支付/通知/CDN 均无，刻意）。 ## 5. Important Domain Model [F] 五组概念即可理解系统： 1. 内容语义链：Topic→Outline→OutlineRevision（不可变）；VisualTemplate→Revision；Asset→AssetVersion（不可变二进制，SHA/商用核验）。一切版本实体 append-only。 2. 生产链：Edition（绑定主题+大纲版本+模板版本）→EditionDraft（可变，lock_version 乐观锁）→QA Run（26 规则门禁）→EditionRevision（审批后不可变）→PublishedSnapshot（staging→complete，内容指纹幂等）。Edition 的 current 指针只能指向本 Edition 的 COMPLETE 快照（回滚=改指针）。 3. 销售交付链：CreatorProductRevision（商品资料，不可变，绑定快照）→CreatorOrder（人工收款台账，绑定商品版本，事件不可变）→CustomerInstance（purchasedOriginalSnapshotId 永久钉住购买时快照）→客户草稿（8 槽位）→CustomerSnapshot（客户专属不可变快照，独立工件根）。商业交付物=当前 COMPLETE 客户快照 PPTX；购买原版 PPTX 仅运营兜底。 4. HTML 线（平行）：HtmlCourseware（structured/plain）→HtmlCoursewareVersion（不可变）→HtmlPublication（slug）；HtmlUserInstance（教师双 token）→课堂快照（playback.html+dfpkg）。与 Edition 体系零外键。 5. 凭证：Admin（scrypt 账号或机器 token）；客户/教师全为 hash-only capability token（库中只存 SHA，明文一次性返回，丢失靠重置）；公开投影（Demo manifest/html-public）为显式 allowlist，永不携带讲稿/QA/凭据。 [I] 最关键设计：三层不可变（Revision→Snapshot→CustomerSnapshot）与「Web/PPTX 同源不互转」（slide-model 唯一内容源，两个渲染器独立消费；00 §0.3、决策 D-004/D-030~033）。 ## 6. Current Strengths - 确定性发布管线 [F]：指纹幂等（同内容必得同快照）、两阶段写入、逐工件 SHA 复核、原子 finalize、失败保持旧指针、advisory lock、staging 回收——「卖出去的版本永不变」是数据库级保证而非流程约定。 - 隐私/安全模型 [F]：公开 manifest 是 allowlist（默认不含而非事后删）；DB 触发器强制不可变；token 全 hash-only；恒时比较；登录锁定；HTML 线对外输出全过 CSP`default-src 'none'` 沙箱。 - 课堂可靠性工程 [F]：逐资产字节+SHA+解码三重验证才 READY、snapshot 级 Cache Storage、SW 不抢占会话、断网续播——直击中国教室网络约束。 - 证据文化 [F]：每里程碑有可复核证据 JSON 与边界声明；明确区分「机器结构校验通过」与「桌面应用 QA 通过」，拒绝以前者冒充后者。 - 测试分层诚实 [F]：`buildApp` 依赖注入，150 用例=9 套真库集成+5 套门控 Playwright+纯函数单测；mock 盲区（迁移 018 列名 bug）被如实记录为教训。 - 代码卫生 [F]：第一方源码几乎零 TODO/FIXME；统一错误结构。 - 产品原则先行 [F]：三铁律（客户买作品非编辑器/后台探索前台确定性/草稿可变发布不可变）在代码中可验证地贯彻，避开通用编辑器复杂度黑洞。 ## 7. Problems and Friction - P1 双产品线割裂【架构·High】 [F] PPTX 线与 HTML 线在 DB/API/存储/导航/发布语义/交付上完全平行，仅共享认证与外壳 →[I] 横切能力（搜索/统计/权限/备份）都要做两遍，「课件」导航歧义 → 维护成本翻倍，一条线终将成僵尸代码。 - P2 领域模型过度工程【架构·High】 [F] 约 40 表/15+ 概念/五层版本实体，服务「单人运营、2 个 Edition、2 试用客户、0 订单」现实；Outline/Template 高级编辑仍是 JSON 文本域（UI 自标注「面向开发维护」）→[I] 概念税由唯一运营者承担，第二人加入学习曲线陡峭。 - P3 单 SPA 四受众【架构·Medium-High】 [F] 客户/教师/预览页与 Admin 同包；`/t/:token` 曾因 react-router v7 useParams 裸用 bug 在所有已部署版本长期损坏，API 级 HTTP 200 验证发现不了，2026-09-23 首次真实浏览器验证才修复 →[I] 对外承诺页面共享 Admin 依赖与回归风险；缺免登录页浏览器冒烟，同类故障可复发。 - P4 零 CI/CD【运维·High】 [F] 无任何 CI；部署=tar 分块上传+手动迁移+手动验证+手写证据；迁移校验和字节级敏感，Windows LF/CRLF 漂移曾需按 DB 变体逐文件对齐；content/ WIP 致 1 例测试长期失败 →[I] 每次部署耗高级人力，环境漂移靠文档追。 - P5 商业闭环零验证【产品·High】 [F] 订单 0、客户 2 试用、生产无 demo、无真实收款；三项外部 QA 悬置数月；38 套静态库与商品系统脱节 →[I] 「有人愿意付费」这一最贵假设未验证，可能为不存在的规模过度建设。 - P6 运营体验的开发者残留【UX·Medium】 [F] Demos items JSON、Outline/Template JSON 编辑、HTML 结构化编辑器英文枚举+「字段：内容」行格式、客户 PPTX 技术文件名、一次性 token 人工传递 →[I] 每环节能用但叠加后对非技术协作者不友好。 - P7 存储单点与灾备薄弱【运维·High】 [F] 本地 FS 单点（S3 stub throw）；曾发生 artifacts 卷清空（92 引用文件丢失）+56 文件漂移，靠人力密集字节级恢复闭合；备份仅部署时手动 pg_dump →[I] 单盘故障=全部历史快照与交付物丢失，恢复依赖关键人员在场。 - P8 HTML 线测试盲区【测试·Medium】 [F] HTML 课件/教师实例仅 mock 测试（假 db），018 列名 bug 正是 mock 测不出类别；真库集成只覆盖 P1–P5 与 creator 线 →[I] 最新上生产的线防线最薄。 - P9 无角色无租户【权限·Medium→High】 [F] admin_users 无角色列，任一管理员全量权限；文档明确不能作陌生商户隔离 →[I] 开放多创作者前必须补租户隔离+跨租户负向测试，是已识别未动工的最大前置工程。 - P10 遗留共存物【可维护性·Medium】 [F] publish-compiler（P1 旧发布路径）与 PublicationService 共存均维护；MemoryDeckforgeDb 内存库；hero.js/hero.ts 双份；死测试文件；两套预览实现（public-catalog 手写 CSS 假页 vs SlideRenderer）；根目录开发工具页；scripts 硬编码本机路径脚本 →[I] 新读者难判权威路径。 - P11 无可观测性【运维·Medium】 [F] 无指标/日志检索/告警；排查靠手工 curl 与只读审计脚本 →[I] 「课堂级可靠」承诺缺运行时证据。 - P12 性能【性能·Low】 [F] Hero 快照 48.6MB/27 页、客户 PPTX 约 53MB；无 CDN；素材 base64 上传 →[I] 单客户交付无碍，上量后带宽/存储曲线与弱网未验证。 ## 8. Suspected Missing Capabilities 仓库证据明确缺失 [F]：多租户/商户隔离与 RBAC；支付网关/自动退款；token 轮换与按人审计；S3 实现；自动备份/恢复演练；可观测性全缺；HTML 线真库测试与免登录页浏览器冒烟；WPS/PowerPoint 完整桌面 QA 与教室 QA；SW 缓存淘汰/更新策略；客户照片取景拖拽控件。 据架构推测可能缺失 [I]：公开端点限流/防滥用（demo resolve、html-public、customer token 路径匿名可达，未见限流与 token 枚举速率防护证据）；公开演示访问统计/获客埋点（漏斗无度量）；存储生命周期管理（快照只增不减）；PPTX 线内容规模化生产管线（每套 27 页仍是手工工程）；客户售后通道（无反馈入口，问题走微信人工）。 无法确认 [U]：生产真实流量与可用性；生产 Admin 是否被真实使用过；小红书投放真实数据（仓库内只有复盘表模板）。 ## 9. Technical Debt and Risks # 债务/风险 等级 1 双产品线模型割裂，横切能力双倍成本 High 2 无 CI/CD+迁移校验和跨平台脆弱+content/ WIP 污染主测试 High 3 本地 FS 存储单点，无自动备份，历史卷丢失事故 High 4 免登录承诺页共享 Admin SPA，无浏览器冒烟防线（/t/ 曾长期损坏） High 5 商业核心假设（付费意愿）零验证，投入回报错配 High 6 HTML 线仅 mock 测试（最新上生产的线防线最薄） Medium 7 领域模型复杂度超当前运营规模 Medium 8 遗留共存物（旧发布路径/内存库/双预览/死文件） Medium 9 无可观测性 Medium 10 SW 无淘汰、大资产无分发策略 Low 11 html-coursewares.tsx 压缩式单行风格与全仓割裂 Low ## 10. Constraints [F] 以下为刻意设计边界，不建议为「更漂亮」而推翻： 1. 中国大陆课堂硬约束（00 §0.5）：禁境外 CDN/字体/演示时生成；必须预加载+就绪+断网可播+PPTX 兜底——决定了自托管与本地 FS 形态。 2. 三铁律：客户买作品非编辑器（客户侧仅 8 槽位）；后台探索前台确定性；草稿可变发布不可变。 3. Web 与 PPTX 同源不互转（D-004），禁 HTML→PPTX 路线。 4. 已发布工件永不改名/移动；文件命名靠运营者下载后手动改（SOP 共识）。 5. 历史迁移不可修改（字节级校验和），只能追加增量（017 即证明）；Windows 开发机与 Linux 服务器换行差异是现实约束。 6. 部署拓扑：内网测试机（不能直连 Docker Hub）与公网生产两套独立 compose/数据，生产前置 Caddy；测试机 DB 容器为预存不可重建资产。 7. 支付诚实性原则：登记≠平台验证；未接网关是当前边界非缺陷。 8. 运营纪律：Hero 客户数恒为 2；生产凭据不可为验收重置。 9. 单体 API 与 slide-model 唯一内容源分层是当前规模合理形态与防退化资产。 ## 11. Evidence `apps/api/src/{publication,customer-delivery,creator-order-routes,html-courseware-routes,html-instance-routes,admin-auth}.ts` ；`infra/migrations/008/009/011/012/014/015/016–019` ；`packages/storage/src/index.ts` （S3 stub）；`apps/control-web/src/{app-shell,main,customer,teacher-instance}.tsx` 与`pages/{demos,outlines,public-catalog,html-coursewares}.tsx` ；`apps/player-web/src/runtime.ts` 、`public/sw.js` ；`tests/{p3-api,html-courseware-api}.test.ts` 、`playwright.config.ts` ；`docs/{MVP_LAUNCH_CHECKLIST,GAP_BACKLOG_V2,HTML_COURSEWARE_MODULE,CREATOR_COMMERCIAL_WORKFLOW,ARTIFACT_RECOVERY_PLAN_20260920}.md` 、`docs/product/00_SOURCE_OF_TRUTH.md` 、`DECISIONS.md` （D-030~034）；`deploy/Dockerfile` 、`deploy/docker-compose.production.yml` 、`docs/DEPLOYMENT.md` 。 ## 12. Questions for External Reviewers 1. 继续迭代最值得优先改造的 5 处？（候选：双线收敛、CI/CD 与迁移健壮性、HTML 线真库测试、存储灾备、获客验证——请独立判断排序） 2. 哪些环节属「功能完整但使用成本过高」？Demos JSON、Outline/Template JSON 域、一次性 token 人工传递、订单-交付两页搬运应如何重构？ 3. PPTX 线与 HTML 线应合并、分层（HTML 自助低端线/PPTX 高端成品线）还是砍一条？合并的技术路径代价如何？ 4. 约 40 表/15+ 概念 vs 单人运营+0 订单：哪些版本化实体（OutlineRevision/TemplateRevision/AssetVersion 三层）可降维而不破坏「发布不可变」核心承诺？ 5. 控制台信息架构应如何从领域实体转向「一单生意」（制作→发布→获客→收款→交付）重组？ 6. 关键闭环还缺什么？获客→收款→交付链路中哪一环最可能因摩擦流失真实客户？生产环境连 demo 都不存在意味着什么？ 7. 无真实销售数据下，如何最小成本验证「班主任愿为成品课件付费」——先补产品，还是先用现有 38 套静态库做 landing page 实验？ 8. 哪些架构会严重限制未来（单 SPA 四受众/本地 FS/无租户/双线/无 CI）？哪些必须现在解，哪些可延到有 N 个真实客户后？ 9. 只投入两周该做什么？投入两个月应形成怎样的目标架构与产品形态？ 10. 团队易忽略但优秀产品常备的能力？（候选：可观测性、埋点、客户售后通道、内容规模化生产管线、备份演练、限流——请基于本 brief 判断真缺口。）