chenxin
5da1efe921
- 新增 ADR-024：服务端关系主库统一 PostgreSQL，不设 SQLite 档（pgvector 与中文全文无法在 SQLite 承载，双档必然残缺或第二实现）；端侧离线缓存不受约束 - AGENTS.md：权威事实源与部署句更新；8.6 固化 pk_/uk_/idx_/fk_ 索引命名约定 - system-architecture、data-architecture、memory-and-knowledge、roadmap WP-01、handoff（决策 29）同步清理 SQLite 引用
124 lines
5.8 KiB
Markdown
124 lines
5.8 KiB
Markdown
# 数据架构
|
||
|
||
## 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. 存储选择
|
||
|
||
- 统一 PostgreSQL（ADR-024）：开发、测试、自托管与正式部署共用同一引擎；个人自托管以 Compose 附带 PostgreSQL 容器。
|
||
- PostgreSQL：正式部署的关系事实源和全文检索。
|
||
- Redis：队列、限流、实时会话和短期状态。
|
||
- S3-compatible：媒体、插件包、交付物和加密支持包。
|
||
- pgvector：默认语义检索起点；规模或评测需要时替换为专用向量库。
|
||
- 图关系先使用 PostgreSQL；多跳规模证明需要时启用 Neo4j/NebulaGraph 投影。
|
||
- 分析/搜索引擎按社区规模引入，不成为交易或身份事实源。
|