技术架构

本页面向维护者，说明请求、业务数据、文件和发布快照的边界。版本与模块定位以 2.6.10 源码及锁文件为准，不代表已验证所有部署拓扑。

技术栈与代码分层

TypeScript 锁定为 5.9.3。Next.js 构建使用 standalone 输出，并显式追踪三种 provider 的生成客户端、schema 与迁移文件；构建不依赖安装时已经选定数据库。

请求与数据流

浏览器页面／原生 MCP 宿主
          │
页面及 Route Handler／POST /mcp
          │
Session 或管理员 MCP Key 校验
          │
服务层：业务权限、输入与状态边界
          ├── Prisma／unitOfWork ── SQLite、MySQL 或 PostgreSQL
          ├── 文件访问与引用索引 ── 受控本地存储
          └── 明确存证流程 ────── Solana RPC

两种认证入口汇入现有业务服务，但不互相替代：网页登录使用 sv_session，MCP 仅接受管理员 Key。不是每次页面读取都会调用链上 RPC；公开凭证摘要可以读取已存状态，实时链上核验是显式操作。

核心数据模型

• 内容树：Project → ProjectVersion → Category → NoteInfo → NoteContent。NoteContent 保存正文历史及主版本，ProjectVersion 保存文档修订号、源码基线、发布快照等版本级状态。
• 独立文章：Article 不属于项目版本树，发布和更新规则单独处理。
• 身份与权益：User、Session、UserWallet、McpApiKey、PointTransaction、MembershipGrant。积分、会员和会话权威状态在数据库，不在进程临时缓存。
• 文件：FileManagement 保存托管元数据，FileReference 连接内容与文件，区分展示和下载引用。
• 发布凭证：ReleaseCredential 与尝试记录管理项目版本链上状态；合同与委托保留自己的冻结快照和存证流程。

SQLite、MySQL、PostgreSQL 使用相同逻辑模型和独立迁移集合。src/server/prisma.ts 延迟取得共享客户端，数据库工厂根据加密配置选择已生成客户端及对应 driver adapter。SQLite 配置 WAL、外键及 busy timeout，并使用实例锁限制同库多进程。

草稿同步与发布边界

src/server/services/project-documentation.ts 提供轻量 outline、批量正文读取和原子草稿同步。一次写入最多 20 项变更，正文 UTF-8 合计最多 512 KiB；expectedRevision 防止拿旧索引覆盖新修订。

首次批次声明 targetBaseline 与全部计划文档键。后续批次累计已完成键，最终确认前保留 pending；只有计划完整、文档树有效且集中更新日志包含准确版本时，finalize 才确认 sourceBaseline。确认基线不是发布：它不创建 releaseId，也不进行链上交易。

发布服务在事务中读取启用且未删除的文档树，要求每个参与的笔记有唯一启用主正文。正文 SHA-256 基于原始 UTF-8 字节，不裁剪、不改换行、不归一化 Unicode。分类名称、笔记标题和正文摘要形成规范排序的内部清单，其摘要为 contentHash。

对外 Manifest v3 仅含 schema、发布时项目名称、版本号和 contentHash；紧凑 Manifest 的 SHA-256 为 releaseHash。数据库 ID 与展示权重不参与正文树摘要，文件字节也不额外参与。变更附件地址会改变 Markdown 摘要，但相同地址背后的文件变化不能仅靠正文摘要发现。

安全与持久化

密码采用 Argon2id。网页登录 Session Cookie 设置 HttpOnly、SameSite=lax，生产环境使用 Secure；服务器查询会话是否过期、撤销以及账号是否启用。MCP Key 单独校验哈希、有效期、状态和管理员角色，不回退到网页 Cookie。

托管上传不放入 public，下载请求依据文件真实引用、内容可见性及读写规则授权；权限相关响应使用私有、不缓存策略。会员权限每次依据有效权益判断，currentMembership 兼容摘要和会员排序不能作为授权依据。

主数据库之外，应用配置、密钥、上传及备份目录需要持久化。登录挑战和限流属于进程内短期状态，重启即清空；若扩展多副本，需要单独设计共享短期状态方案。当前文档不宣称具备自动横向扩容或分布式一致性保障。