📝 docs: 统一 PostgreSQL 主库并固化索引命名约定

- 新增 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 引用
This commit is contained in:
chenxin committed 2026-09-09 21:14:10 +08:00
1 parent 42513d13c6
commit 5da1efe921
7 files changed
+27 -8

No files matched your search

+3 -3
View File
@@ -86,7 +86,7 @@
### 4.4 数据
- PostgreSQL/SQLite 关系数据是权威事实源;对象存储保存媒体;全文、向量、图投影、推荐特征和缓存均可重建。
- PostgreSQL 关系数据是权威事实源(ADR-024,不设 SQLite 主库档);对象存储保存媒体;全文、向量、图投影、推荐特征和缓存均可重建。
- 角色、消息、记忆、知识、社区发布、许可、订单、支付和 Ledger 分离建模。
- Ledger 不可变,修正写反向分录;支付 Provider Adapter 不直接写账。
- 删除传播到主存储、索引、缓存和派生数据;墓碑不保存被删原文。
@@ -216,7 +216,7 @@ message.completed
### 8.6 SQL 与存储
- 表/列/index 使用 `snake_case`;外键、唯一约束、检查约束和租户条件在数据库层落实。
- 表/列/index 使用 `snake_case`;索引命名使用 `pk_`/`uk_`/`idx_`/`fk_` 前缀加表名与字段;外键、唯一约束、检查约束和租户条件在数据库层落实。
- 所有 Query 明确 PersonalDomain/Workspace/Finance scope;禁止先全表读后应用层过滤。
- N+1、无界列表和 `%keyword%` 全表扫描必须在实现前处理或有量化例外。
- 向量、图、搜索和缓存只保存可重建投影,删除和权限变化必须传播。
@@ -252,7 +252,7 @@ message.completed
- `docs/`:文档;`logs/`:本地日志;`db/`:本地数据库;`config/`:应用配置;`docker/`:Docker 文件。
- `.env.example` 位于根目录,列出环境变量和中文说明;只提交 `.env.example` 和其他不含秘密的 `*.example.*` 配置,不提交真实 `.env`、密钥、数据库、日志和用户数据。
- 代码导入使用语言包/alias 的项目根路径;运行时文件路径通过统一项目根解析器或配置解析,不依赖进程当前目录。
- Docker 容器名以 `hunjing-` 开头;Compose 不使用顶部 `version`;本地默认 SQLite,正式环境按完整 1.0 能力启用 PostgreSQL、Redis、对象存储和 Worker。
- Docker 容器名以 `hunjing-` 开头;Compose 不使用顶部 `version`;开发、测试与自托管统一 PostgreSQL(ADR-024),正式环境按完整 1.0 能力启用 Redis、对象存储和 Worker。
- 本地启动、测试、迁移、生成和检查统一通过根 `Makefile`;新增命令同步 `make help`。
## 13. Git 与交付
+1 -1
View File
@@ -114,7 +114,7 @@ flowchart TD
## 11. 存储选择
- SQLite:本地开发与个人轻量自托管。
- 统一 PostgreSQL(ADR-024):开发、测试、自托管与正式部署共用同一引擎;个人自托管以 Compose 附带 PostgreSQL 容器。
- PostgreSQL:正式部署的关系事实源和全文检索。
- Redis:队列、限流、实时会话和短期状态。
- S3-compatible:媒体、插件包、交付物和加密支持包。
+1 -1
View File
@@ -144,7 +144,7 @@ ContextSnapshot 不保存隐藏推理。普通 Run API 只返回用户可理解
## 8. 索引与故障语义
- PostgreSQL/SQLite 中的 Memory、MemoryVersion 和来源关联是权威事实;全文、pgvector 和图关系是可重建投影。
- PostgreSQL 中的 Memory、MemoryVersion 和来源关联是权威事实;全文、pgvector 和图关系是可重建投影。
- 权威事务通过 Outbox 驱动索引更新。索引延迟时,新版本可暂时降级为关系数据库检索,旧版本不得继续被召回。
- 删除与撤权事件优先于普通重建任务;消费者按 event ID 幂等。
- 无法证明索引已清除时,对目标 Memory fail closed,并记录待修复状态,不能继续返回旧结果。
+1 -1
View File
@@ -77,7 +77,7 @@ flowchart TD
PersonalDomain 创建或迁移时绑定一个固定数据区域:权威数据、密钥、对象、索引和备份在该区域驻留,不因流量路由、故障转移或用户旅行自动跨区漂移;跨区只能走正式迁移协议。跨区模型处理按地区规则、数据敏感度和用户授权单独治理,且必须经用户明确披露与授权;高敏数据(含私箧)可完全禁止跨区模型处理。
自托管遥测默认关闭。本地开发可用 SQLite、本地对象和单 Worker;完整 1.0 正式云与社区/交易部署使用 PostgreSQL、Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择,不因技术清单强制引入。灵台引擎默认进程内嵌入;满足独立扩缩容、故障域或资源隔离标准时可启用 `hunjing-lingtai-server` 独立服务形态(见[灵台引擎架构](lingtai-engine.md))。
自托管遥测默认关闭。关系主库在开发、测试与自托管中统一 PostgreSQL([ADR-024](../decisions/README.md#adr-024关系主库统一-postgresql不设-sqlite-档));正式云与社区/交易部署按完整 1.0 能力启用 Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择,不因技术清单强制引入。灵台引擎默认进程内嵌入;满足独立扩缩容、故障域或资源隔离标准时可启用 `hunjing-lingtai-server` 独立服务形态(见[灵台引擎架构](lingtai-engine.md))。
## 4. 客户端边界
+18
View File
@@ -379,3 +379,21 @@ UUIDv7 为高写入关系表提供索引局部性和大致创建顺序;请求
- 阶段记忆(`_phase_memory`)持久化每阶段输入输出摘要,供审计、幂等与用户可见的演化谱系。
- 触发条件为可配置阈值组合并逐角色设频率上限;用户手动触发始终可用,关闭大周天后不再触发新 cycle,已有历史保留。
- "天工"(任务对象)与"小周天"(运转过程)为同一 `run` 的两个视角,不新增运行时对象;`run` 工程值与 `run_` 前缀不变。
## ADR-024:关系主库统一 PostgreSQL,不设 SQLite 档
**状态**:采纳
**决策**
服务端关系主库在开发、测试、个人自托管与正式部署中统一使用 PostgreSQL;不提供 SQLite 主库档。Alembic 迁移只在 PostgreSQL 上定义与验证。SQLite 不作为服务端主库出现;端侧(Tauri)加密离线缓存属客户端本地存储,不受本决策约束。
**理由**
1.0 记忆与知识检索依赖 PostgreSQL 全文(中文分词扩展)与 pgvector 语义检索;SQLite 档无法承载,双档必然功能残缺或形成第二实现,违反"单一真源"与最小实现原则。双方言还使迁移与测试矩阵翻倍(JSONB/TEXT、向量、并发写锁、部分索引差异)。容器时代个人自托管以 Docker Compose 附带 PostgreSQL 容器即可,运维成本可接受;开发与 CI 用本地容器或嵌入式 PostgreSQL 保持一致性。
**后果**
- 开发环境用 `docker compose`(或嵌入式 PostgreSQL)启动数据库;测试统一在 PostgreSQL 上运行,不用 SQLite 内存库替代,避免方言差异掩盖缺陷。
- 自托管两档(单机/标准服务器)均含 PostgreSQL 容器;单机档降低的是资源规格,不是能力面。
- 迁移与性能优化只需针对 PostgreSQL(JSONB、pgvector、tsvector、事务性 DDL、行级锁);索引命名按工程规范执行(见 AGENTS.md 第 8.6 节)。
+2 -1
View File
@@ -44,6 +44,7 @@
26. **叩心进入 1.0(ADR-022)**:角色主动联系先成叩心候选,受静默、频率、渠道与预算控制;不回应不降关系;不以追逐式消息换回流。
27. **周天体系统一(ADR-023)**:小周天=Run 可追踪认知闭环(完成信号为大周天唯一输入面),大周天=`cycle_` 聚合根 + 四阶段评估(回顾/对照/提议/提交)+ 阶段记忆;吸收旧版契约骨架并补全其缺失的架构设计。
28. **数据权与开放核心**:PersonalDomain 数据默认不用于模型训练(自愿贡献需独立、明确、可撤销同意);前台化名与法定身份分离核验;高敏数据可完全禁止跨区模型处理;核心 Apache-2.0 开放、品牌与官方资产单独保护、DCO 贡献、自托管遥测默认关闭;模型配置按"平台硬边界→目录→用户 BYOK→角色覆写→会话临时"继承。
29. **统一 PostgreSQL(ADR-024)**:服务端关系主库在开发、测试、自托管与正式部署统一 PostgreSQL,不设 SQLite 主库档(pgvector/中文全文无法在 SQLite 承载,双档必然残缺);索引命名 `pk_/uk_/idx_/fk_` 前缀。
正式 ADR 见[架构决策记录](../decisions/README.md)。
@@ -195,7 +196,7 @@ tool_call tool_result agent_status approval_request artifact citation error
1. 建立仓库目录、Makefile、Python/Next.js/Tauri 最小可运行工程;
2. 把当前 Markdown 契约转换为 OpenAPI 3.1 和 JSON Schema;
3. 先定义并生成通用 ID、错误、分页、Money、ContentBlock、Event 和认证 DTO;
4. 建立 SQLite/PostgreSQL 基线、Alembic、User/PersonalDomain/Session/ServiceAccount;
4. 建立 PostgreSQL 基线(统一引擎,ADR-024)、Alembic、User/PersonalDomain/Session/ServiceAccount;
5. 实现 OAuth 2.1 边界和 Header/CSRF/Origin/Scope 校验;
6. 实现一个不调用模型的 Conversation→Message→Run 事务和 SSE 空状态闭环;
7. 再进入 `WP-02` 与 `WP-03`,不要先实现插件市场、支付或 3D 页面。
+1 -1
View File
@@ -21,7 +21,7 @@
- [ ] 实现私箧:用户独立持钥加密区,平台仅存密文不可恢复;账户恢复、管理员与诊断均不可读(ADR-021)。
- [ ] 实现 RBAC/ABAC、资源归属校验和跨域失败关闭。
- [ ] 实现 W3C Trace Context、结构化日志、审计和 Outbox。
- [ ] 实现 SQLite 开发档与 PostgreSQL 正式档迁移。
- [ ] 实现 PostgreSQL 基线与 Alembic 迁移(开发/测试/自托管/正式统一,ADR-024;测试不使用 SQLite 替代)。
- [ ] 验证跨用户、跨角色、跨 Workspace IDOR 测试。
## WP-02 角色、导入与可携