- 产品名称：Typst 协作写作平台
- 文档版本：v0.1
- 文档状态：草案
- 产品阶段：MVP 规划
- 目标：指导第一阶段从“单人编辑器”演进到“团队协作平台”的产品与研发实现
打造一个面向团队的在线 Typst 写作平台，让用户可以在同一工作区内协作编写、审阅、导出和管理结构化文档，并支持团队自部署。
这是一个“团队文档协作系统”，不是单纯的浏览器编辑器。
它要解决的问题包括：
- 多人共同维护一套 Typst 文档时，缺少统一的在线协作空间
- 团队成员之间缺少明确的权限边界
- 文档缺少评论、审阅和版本回溯能力
- 项目模板、资产和输出过程难以统一管理
- 现有工具部署复杂，不适合中小团队快速落地
- 论文与报告协作团队
- 编辑、出版和内容制作团队
- 需要输出规范 PDF 文档的工程与运营团队
- 课程讲义、教材或实验文档协作团队
MVP 阶段要实现以下目标：
- 支持用户账号与登录
- 支持工作区与团队成员管理
- 支持工作区内的项目创建、共享和权限控制
- 支持在线编辑 Typst 文件
- 支持评论、审阅和版本历史
- 支持稳定 PDF 导出
- 支持 Docker Compose 自部署
MVP 阶段暂不包含：
- 字符级实时协同编辑
- 商业化计费
- 企业级 SSO
- 公开模板市场
- 完整的公开发布门户
- 复杂审批流
当前系统已经有基本编辑、文件树、预览和导出能力，但仍然停留在单人项目编辑器阶段，主要问题包括：
- 没有用户与身份体系
- 没有工作区和团队概念
- 没有项目成员和权限控制
- 没有评论与审阅流程
- 没有版本历史与回滚能力
- 没有多人协作的状态感知
- 没有面向团队交付的部署方案
- 团队成员共享同一文档时，容易发生误覆盖
- 审阅意见只能在外部沟通工具中分散交流
- 无法追溯“谁改了什么、为什么改”
- 无法按角色限制编辑、评论、查看、导出等操作
- 模板、资产和项目输出缺少统一入口
- 自建使用门槛偏高
owner：拥有工作区最高权限，可管理成员、角色和工作区设置admin：可协助管理工作区与项目member：可参与工作区内项目viewer：仅查看工作区内容
maintainer：可管理项目成员和关键设置editor：可编辑文件、创建修订、导出commenter：可评论，但不可编辑文件viewer：只读查看
工作区是团队协作的组织容器，用来承载：
- 一组成员
- 一组工作区级角色与权限
- 多个项目
- 团队级设置与资源
工作区解决的问题是：“谁和谁一起工作”。
典型例子：
- 某实验室
- 某编辑部
- 某公司文档团队
项目是具体文档工作的业务容器，用来承载：
- 项目文件树
- 项目成员与项目角色
- 评论与审阅
- 修订历史
- 导出结果
项目解决的问题是：“这次具体在协作哪一份文档或哪一组文档”。
典型例子：
- 一篇论文
- 一本讲义
- 一个报告
- 一套操作手册
- 一个工作区下可以有多个项目
- 一个项目必须归属于一个工作区
- 工作区负责团队管理，项目负责具体协作
- 工作区权限决定用户是否能进入某个协作空间
- 项目权限决定用户能否编辑、评论、导出某个具体项目
如果只有项目而没有工作区，会带来这些问题：
- 成员关系只能散落在各个项目上，管理成本高
- 无法形成团队级权限体系
- 无法沉淀团队级模板、资源和设置
- 一个团队拥有多个项目时缺少统一归属层
- 后续的审计、配额、部署和计费都没有合理承载对象
- 用户注册并登录
- 创建工作区
- 邀请成员加入工作区
- 在工作区中创建一个 Typst 项目
- 给成员分配项目角色
- 成员进入项目开始写作与审阅
- 编辑者打开项目文件
- 系统显示当前在线成员和活跃文件状态
- 编辑者修改内容并保存
- 审阅者选中正文中的一段内容，在该选区上发起评论
- 编辑者回复评论并完成修改
- 审阅者关闭评论线程
- 团队发现文档被错误修改
- 成员打开版本历史
- 查看某次修订的文件变化
- 回滚到某一版本或恢复某个文件内容
- 项目维护者确认文档状态
- 发起 PDF 导出
- 下载生成结果
- 如有需要，保留导出记录或发布到团队指定目标
- 注册
- 登录
- 退出登录
- 当前用户信息获取
- 创建工作区
- 查看工作区列表
- 邀请成员
- 成员加入工作区
- 查看成员列表
- 修改成员角色
- 移除成员
- 在工作区内创建项目
- 查看项目列表
- 归档项目
- 删除项目
- 项目成员管理
- 项目角色设置
- 项目文件树
- 创建文件与文件夹
- 上传文件
- 重命名、删除
- 打开并编辑 Typst 文件
- 保存内容
- 预览与诊断
- 导出 PDF
- 基于文件选区创建评论
- 评论线程
- 回复评论
- 关闭/重新打开评论
- 评论列表视图
- 手动保存检查点
- 自动修订记录
- 修订列表
- 查看修订详情
- 回滚到指定修订
- 操作审计日志
- 在线成员列表
- 当前活跃文件提示
- 文件占用或软冲突提示
- Docker Compose 部署
- 初始化配置文档
- 数据持久化方案
- 备份与恢复说明
- 实时多人光标协同
- CRDT 文档同步
- 审批流
- 发布站点
- Webhook / API Token
- 企业集成能力
为平台提供基本身份能力，让工作区与项目拥有明确归属。
- 用户可通过邮箱和密码注册
- 用户可登录并维持会话
- API 必须能够识别当前用户
- 未登录用户不能访问工作区和项目数据
- 新用户可注册并登录
- 登录后可访问自己的工作区数据
- 未登录访问受保护接口时返回鉴权错误
工作区是团队协作的组织容器，项目、成员和权限都在工作区内管理。
- 用户可以创建工作区
- 工作区 owner/admin 可以邀请成员
- 被邀请者可以接受邀请加入工作区
- owner/admin 可以修改成员角色或移除成员
- 用户可成功创建工作区
- 受邀用户加入后能看到工作区
- 不同角色用户看到的可执行操作符合权限限制
项目是文档协作的主要容器。
- 项目必须属于某个工作区
- 工作区内成员可按权限创建和访问项目
- 项目支持成员级角色分配
- 项目支持归档和删除
- 项目创建时必须挂在某个工作区下
- 无权限用户不能访问非授权项目
- 项目成员角色变更后权限立即生效
提供项目内部的文件管理和 Typst 编辑能力。
- 支持文件树浏览
- 支持创建、上传、重命名和删除
- 支持打开 Typst 文件并在线编辑
- 支持保存和预览
- 支持导出 PDF
- 编辑者能修改
.typ文件并保存 - 项目预览可正常更新
- 具备导出权限的用户可导出 PDF
- 无编辑权限的用户不能修改文件内容
让团队在项目内部围绕具体文本位置完成审阅和问题跟踪。
- 支持用户在编辑器中选中一段文本后发起评论
- 评论必须绑定到具体文件和具体选区锚点
- 评论在后续查看时应能定位回原始文本位置
- 支持评论线程回复
- 支持评论关闭与重新打开
- 评论记录需保留创建人和时间
- 评论区不是聊天室，不提供脱离文本上下文的泛聊天输入区
- 如选区内容发生变化，系统至少要保留原始引用文本和锚点信息，避免评论失去上下文
- 评论者可以通过“选中内容 -> 发起评论”的方式发表评论
- 打开评论时，系统可以定位到原文件中的对应选区或附近上下文
- 编辑者和评论者可以回复评论
- 评论关闭后可在界面中看到状态变化
提供可信的修订记录与回滚能力。
- 支持手动创建检查点
- 编辑保存时可生成修订记录
- 支持查看修订列表
- 支持查看修订详情
- 支持回滚到某个修订
- 用户可看到项目历史修订
- 回滚后当前文件状态正确恢复
- 修订记录可以追溯操作者和时间
在不做字符级实时协同的前提下，先降低多人协作冲突。
- 显示当前在线成员
- 显示当前谁在编辑哪个文件
- 用户打开已被他人活跃编辑的文件时给出提示
- 两名用户同时进入同一项目时可看到彼此在线
- 某个文件被其他人活跃编辑时系统有提示
对重要操作保留记录，满足团队协作的可追溯需求。
- 记录项目创建、删除、归档
- 记录成员邀请、加入、移除、角色变更
- 记录文件创建、删除、重命名
- 记录导出与回滚操作
- 管理员可查看关键操作日志
- 日志中包含操作者、时间、对象和动作
- 常规项目文件列表加载应在可接受范围内完成
- Typst 文本编辑不应出现明显卡顿
- 常规文档导出应在合理时间内完成
- 所有受保护 API 都必须做鉴权
- 权限判断必须在服务端完成
- 禁止通过路径构造越权访问其他项目文件
- 邀请链接和登录会话必须具备基本安全控制
- 保存失败时应明确提示
- 导出失败时应能返回可读错误
- 修订与评论数据不得因预览服务异常而丢失
- 提供标准 Docker Compose 方案
- 提供环境变量说明
- 提供持久化、备份、恢复文档
- 注册账号
- 创建工作区
- 邀请成员
- 创建项目
- 上传模板或初始文档
- 开始编辑与评论
- 成员进入项目
- 查看在线状态与活跃文件
- 编辑内容并保存
- 审阅者发表评论
- 编辑者处理评论
- 创建版本检查点
- 导出 PDF
- 发现错误修改
- 打开历史版本
- 确认目标修订
- 执行回滚
- 重新导出
目前用户可能使用这些替代方案：
- 本地 Typst + Git
- Overleaf 类协作平台
- 通用在线文档工具 + 离线排版
本产品的差异化方向应是：
- 更适合 Typst 工作流
- 团队自部署门槛低
- 模板、资产、导出链路统一
- 更适合结构化文档和 PDF 输出团队
MVP 阶段建议关注以下指标：
- 新建工作区数量
- 工作区成员邀请接受率
- 每周活跃项目数
- 每个项目的评论使用率
- 每个项目的修订创建次数
- PDF 导出成功率
- 自部署成功率
- 后端需要引入认证能力
- 数据模型需要从“项目文件”升级到“用户/工作区/项目/成员/修订/评论”
- 需要 PostgreSQL 作为核心元数据存储
- 需要明确文件内容和资产的最终存储策略
- 需要稳定的预览和导出服务接口
- 用户系统
- 工作区创建
- 成员邀请
- 基础角色模型
- 工作区下的项目管理
- 项目成员管理
- 服务端权限控制
- 评论系统
- 修订和回滚
- 审计日志
- 在线状态
- 活跃文件提示
- 生产部署方案
会显著增加复杂度，并拖慢 MVP 上线。
处理建议：
- 先做评论、修订、在线状态和占用提示
会导致权限、修订和审计难以扩展。
处理建议：
- 尽快把元数据中心迁移到 PostgreSQL
会造成团队环境中的数据安全问题。
处理建议：
- 先做服务端角色校验，再扩展更多协作功能
MVP 上线时，至少满足以下条件：
- 用户可以注册、登录、创建工作区
- 工作区可以邀请并管理成员
- 项目归属于工作区，并具备项目级角色控制
- 编辑者可以在线编辑 Typst 文件并导出 PDF
- 评论者可以基于选中文本发起评论和回复
- 用户可以查看版本历史并执行回滚
- 成员可以看到在线状态和活跃文件提示
- 团队可以按照文档完成 Docker Compose 自部署
PRD 之后建议立即补这几份文档：
DATABASE_SCHEMA.mdAUTH_AND_PERMISSIONS.mdREVISION_AND_COMMENT_MODEL.mdDEPLOYMENT_ARCHITECTURE.md
这四份文档会直接决定后续开发是否顺畅。