# 数据架构

## 1. 事实源

关系数据库保存角色、社区、协作、交易、插件和运行的权威状态；对象存储保存媒体与交付物；全文、向量、图投影、推荐特征和缓存都是派生数据。

```mermaid
flowchart LR
  DB[(Relational Source of Truth)] --> FTS[Full-text Index]
  DB --> V[Vector Index]
  DB --> G[Graph Projection]
  DB --> C[Cache]
  FS[(Object Storage)] --> DB
  FTS & V & G & C --> Q[Query and Retrieval]
```

任何索引可从数据库和对象存储重建，不能反向覆盖角色、记忆、社区来源、许可或交易账。

## 2. 核心关系

```mermaid
erDiagram
  PERSONAL_DOMAIN ||--o{ CHARACTER : owns
  CHARACTER ||--o{ CHARACTER_VERSION : versions
  CHARACTER ||--o{ CHARACTER_ASSET : presents
  CHARACTER ||--o{ MEMORY : remembers
  CONVERSATION ||--o{ BRANCH : contains
  BRANCH ||--o{ MESSAGE : orders
  CONVERSATION ||--o{ RUN : triggers
  RUN ||--o{ TURN : contains
  TURN ||--o{ MODEL_CALL : attempts
  TURN ||--o{ TOOL_CALL : invokes
  RUN }o--|| PLUGIN_SNAPSHOT : pins
  WORKSPACE ||--o{ WORKSPACE_MEMBER : authorizes
  WORKSPACE ||--o{ PROJECT_ASSET : contains
  USER ||--o{ COMMUNITY_CONTENT : publishes
  COMMUNITY_CONTENT ||--o{ INTERACTION : receives
  PUBLISHER ||--o{ PLUGIN_VERSION : releases
  MARKETPLACE_LISTING }o--|| RELEASE_VERSION : sells
  ORDER ||--o{ ORDER_ITEM : contains
  ORDER ||--o{ LEDGER_ENTRY : posts
  ORDER_ITEM ||--|| ENTITLEMENT : grants
  SETTLEMENT_BATCH ||--o{ LEDGER_ENTRY : settles
```

## 3. 数据分区

| 范围 | 典型数据 | 默认可见性 |
| --- | --- | --- |
| Personal Domain | 私密角色、记忆、对话、设备授权 | owner only |
| Workspace | 协作角色、世界、资产、评审 | member RBAC |
| Community | 已发布内容、互动、公开版本 | visibility policy |
| Marketplace | 商品、许可和公开交付摘要 | regional catalog |
| Finance | 订单、支付、退款、账务、结算 | buyer/seller/finance roles |
| Diagnostics | Run、工具、上下文和敏感支持包 | scoped grant |

公开角色 Release 不包含 Personal Domain 中的私密记忆、关系、对话和密钥。

## 4. 角色、记忆与资产

- CharacterVersion：不可变角色设定版本。
- CharacterAsset：图像、声音、Live2D、3D、动作和场景版本，引用对象与许可。
- Memory/MemoryVersion：长期状态、来源、敏感度、置信度、有效期、审批和纠正链；所有权、写入、版本、检索与装配见[记忆与知识架构](memory-and-knowledge.md)。
- KnowledgeDocument：外部资料、世界设定和共享知识，不等于人物经历。
- ReleaseVersion：面向社区/市场发布的不可变物料清单与内容哈希。

## 5. 社区与协作

- CommunityContent 使用统一发布对象加类型化 payload；互动独立记录并支持软删除与治理状态。
- Follow、Block、Report 和 ModerationCase 为一等对象。
- WorkspaceMember 和资源 ACL 双重约束；关键权限变更写审计。
- 协同编辑使用版本号/乐观锁；高频富文本或场景编辑确有需要时采用 CRDT，快照仍落关系事实源。
- 推荐特征保存来源和版本，允许用户清除；Restricted 数据不得进入。

## 6. 插件 Registry

Plugin、PluginVersion、PackageBlob、Signature、PermissionManifest、Compatibility、Review、Installation 和 PluginSnapshot 分开保存。PluginVersion 不可变；下架修改可分发状态，不改历史包摘要和 Run 快照。

## 7. 订单与账务

- Listing 可变；OrderItem 固定购买时的版本、价格、税、许可和卖家快照。
- PaymentAttempt、Refund、Dispute、Entitlement 与 Order 分离。
- LedgerEntry 不可变，使用平衡分录或等价会计模型；修正写反向分录。
- CreatorBalance 是 Ledger 聚合，不是独立可编辑事实。
- SettlementBatch 固定结算项；PayoutAttempt 记录 Provider 结果和幂等键。
- 金额使用整数最小单位或 Decimal，记录币种、汇率来源和价格版本。

## 8. Run 与诊断

Run 只保存聚合状态。Turn、ModelCall、ToolCall、ContextSnapshot、PluginSnapshot 和 AuditEvent 独立查询。Provider 原始正文默认不保存；支持需要时进入加密、限期对象并受 Sensitive DiagnosticGrant 控制。

## 9. 删除与许可传播

```mermaid
flowchart TD
  D[Delete or revoke request] --> A[Authorize and audit]
  A --> P[Update authoritative source]
  P --> I[Remove indexes and caches]
  P --> O[Delete or redact derived objects]
  P --> R[Evaluate releases and entitlements]
  R --> N[Stop new distribution or updates]
  O --> B[Apply backup retention]
  B --> T[Keep minimal tombstone]
```

删除私密源数据不等于撤销所有已合法发布许可；撤架、许可撤销、安全强制停用和用户删除分别建模。墓碑不保存被删原文。

## 10. 一致性与事件

- 权威状态和 Outbox 在同一事务写入；完整 1.0 的媒体、索引、通知、支付、社区和插件消费者需要 Outbox。
- Webhook/ToolCall 在副作用前写 pending 与幂等键，完成后写结果。
- 支付事件不依赖到达顺序；重复事件返回已有处理结果。
- 搜索、推荐、媒体和向量失败可重建，不影响权威状态。

## 11. 存储选择

- SQLite：本地开发与个人轻量自托管。
- PostgreSQL：正式部署的关系事实源和全文检索。
- Redis：队列、限流、实时会话和短期状态。
- S3-compatible：媒体、插件包、交付物和加密支持包。
- pgvector：默认语义检索起点；规模或评测需要时替换为专用向量库。
- 图关系先使用 PostgreSQL；多跳规模证明需要时启用 Neo4j/NebulaGraph 投影。
- 分析/搜索引擎按社区规模引入，不成为交易或身份事实源。