Initial commit: InternalAuditInterprise

docs/adr/ADR-0001-tech-stack.md

@@ -0,0 +1,43 @@
+# ADR-0001 · 技术选型决策记录
+
+> 项目：AIAudit（本地私有化大模型电信运营商 AI 全域内审平台）
+> 状态：已接受（MVP 基线）
+> 日期：2026-06
+> 关联：`0-req-AIAudit.md`、`1-prd-AIAudit.md`、`2-task-AIAudit.md`（任务 P0.1）
+
+## 背景
+平台需在本地内网部署、数据零出域，具备本体/知识图谱、双时态/时序、本地 LLM 推理、向量检索等能力，并需信创适配。技术选型需在"能力完整"与"组件最少、出域面最小、便于信创"之间取得平衡。
+
+## 决策
+
+| 层 | 选型 | 说明 |
+| --- | --- | --- |
+| 后端 | Python 3.12 + FastAPI | 贴近 LLM/数据/ML 生态，异步任务友好 |
+| 前端 | React + TypeScript + Vite | 看板/下钻交互成熟 |
+| 主存储 | PostgreSQL 16 | 一库多能，降低组件数与出域面 |
+| 知识图谱 | PostgreSQL + Apache AGE | 免独立图库，信创友好，满足 MVP 多跳穿透 |
+| 双时态/时序 | PostgreSQL 时态列 + TimescaleDB | 双时态回放 + 时间序列一体 |
+| 向量检索 | pgvector | 与主库同栈，免独立向量库 |
+| 任务调度 | Celery + Redis | 全量扫描异步任务、进度反馈 |
+| 文件/对象 | MinIO（本地 S3） | 凭证/底稿存储，不出域 |
+| LLM 推理 | Provider 抽象：开发期 DashScope 公网千问；生产 vLLM + 本地 70B | 见下"LLM 抽象与红线" |
+| 部署 | 本地 Homebrew 安装（开发）→ 生产内网裸机/信创环境 | 不使用 Docker；开发直接用本机 PostgreSQL 16 + 本地服务 |
+
+## LLM 抽象与数据零出域红线（关键约束）
+- LLM 通过统一 `LLMProvider` 接口接入，至少实现两种：`DashScopeProvider`（公网千问，**仅开发/测试**）、`VllmProvider`（本地，生产）。
+- **红线：公网 Provider 只允许处理脱敏/样例假数据，严禁传入任何真实审计数据。** 通过配置开关 + 环境标识（dev/prod）强约束；prod 环境禁用任何公网 Provider。
+- 切换 Provider 仅改配置，不改业务代码。
+
+## 本机环境结论（开发机）
+- Mac mini · Apple M4 · 16GB · macOS 26.5.1（ARM64）；磁盘可用 ~170GB。
+- 开发 MVP 够用（样例数据 + 公网千问 API + Docker 组件）。
+- **不能本地运行 70B**；生产推理需独立 GPU 服务器（A100/H100/国产 GPU）跑 vLLM。
+
+## 备选与未选原因
+- 独立 Neo4j 图库：能力更强但增加组件与信创/授权负担，MVP 暂不引入；图谱压力增大时再评估。
+- 独立时序库 / 独立向量库：同理，先用 PG 一体化，后续按压力拆分。
+- 后端 Java Spring Boot：企业集成习惯好，但 LLM/数据/ML 生态以 Python 为主，会多一层；若团队为 Java 班底可改为"Java 主服务 + Python 分析/推理服务"。
+
+## 影响
+- 开发环境：本机 Homebrew 安装 PostgreSQL 16 + TimescaleDB + pgvector，不使用 Docker（已移除 docker-compose 与自定义镜像）；初始化脚本见 `infra/postgres/setup_local.sh`。
+- 生产部署需规划独立 GPU 推理节点（任务 P3.5 信创适配同步评估）。

docs/adr/ADR-0002-data-platform-modeling.md

@@ -0,0 +1,33 @@
+# ADR-0002 · 数据中台建模决策（本体 / 双时态 / 时序 / 图谱）
+
+> 项目：AIAudit　状态：已接受（MVP）　日期：2026-06
+> 关联：`0-req-AIAudit.md`（R2、R3）、任务 P1.2 / P1.3
+
+## 背景
+审计数据中台需同时满足：①按审计本体组织实体与关系（知识图谱穿透）；②双时态建模（业务时间+系统时间，可回放历史）；③时间序列（时序造假识别）。需在能力与可靠性/组件数之间平衡。
+
+## 决策
+
+### 1. 本体与知识图谱：关系表 + 递归 CTE（MVP）
+- 用 `entity`（实体）+ `entity_relationship`（关系边）两张通用表承载审计本体，实体类型与关系类型由 `ontology_entity_type` / `ontology_relationship_type` 字典定义。
+- 多跳穿透（如实控人识别）用 PostgreSQL **递归 CTE** 实现。
+- 不在 MVP 引入 Apache AGE，规避源码编译的构建脆弱性；后续多跳压力增大再评估迁移到 AGE/Neo4j。
+
+### 2. 双时态建模
+- 关键审计对象采用双时态：
+  - 业务有效期：`valid_from` / `valid_to`（应用时间）。
+  - 系统记录期：`system_from` / `system_to`（事务时间）。
+- 用 `tstzrange` + `btree_gist` 排他约束防止同一实体业务有效期重叠。
+- "按任意历史时点回放"= 给定 `(as_of_valid, as_of_system)` 过滤两条时间线。
+
+### 3. 时间序列
+- 行为/指标类数据（用户生命周期事件、回款、话务、佣金、资源使用）写入 `metric_event` 等表。
+- 生产环境（Linux）用 TimescaleDB `create_hypertable` 转为超表，按时间分区/压缩。
+- **本地开发（macOS）**：因 TimescaleDB 在 macOS 上 Homebrew 编译不稳定，本地跳过该扩展，`metric_event` 作为普通索引表使用；超表转换在迁移中条件执行（扩展存在才转），**不影响功能**，仅少了规模优化。
+
+### 4. 数据版本与可追溯
+- 每批数据落地登记 `data_version`（来源、批次、时间、行数），业务记录引用 `data_version_id`，使任一结论可回溯到当时数据版本（R3）。
+
+## 影响
+- MVP 仅依赖 TimescaleDB + pgvector + btree_gist，镜像可靠（`timescaledb-ha:pg16` 内置）。
+- 图能力以关系建模实现，接口层（统一穿透查询服务）对上层屏蔽底层是关系还是图库，便于将来替换。