CynthiaOmovoiye/ai-advisory-platform

# AI 咨询平台 [](https://github.com/CynthiaOmovoiye/ai-advisory-platform/actions/workflows/ci.yml) 本仓库是一个**最初以设计为导向，现已完全实现的作品集项目**。 它的构建方式与真实系统一致：首先是设计和决策（`docs/` 包）， 然后是基于该设计开发可运行的全栈应用程序。这两部分是共同交付的 —— ADR/威胁模型解释了*为什么*这么做，而代码（140 个后端测试，CI 通过， 可运行的 `docker compose` 栈）则是具体的*成果*。 如果你只打算阅读三个文件，请读这些： 1. [`docs/architecture/system-architecture.md`](docs/architecture/system-architecture.md) — 系统的架构方式及其原因。 2. [`docs/portfolio-story.md`](docs/portfolio-story.md) — 每个重大决策背后的逻辑。 3. [`docs/security/threat-model.md`](docs/security/threat-model.md) — 系统可能如何受到攻击以及如何进行防御。 刚接触本应用并想*使用*它？请从[**用户指南**](docs/user-guide.md)开始 —— 这是一份包含操作流程和各个页面的分步手册。 ## 核心理念 大多数“AI 产品”将 LLM 放在关键路径上并寄予厚望。而这个项目恰恰相反。 ``` Structured assessment data │ ▼ ┌───────────────┐ deterministic, auditable, testable │ RULE ENGINE │ ──► findings + recommendations (the source of truth) └───────────────┘ │ ▼ ┌───────────────┐ LLM *explains* and *narrates* findings — │ LLM ENHANCEMENT│ ──► it never invents them └───────────────┘ │ ▼ Reviewed report (consultant-in-the-loop) ──► PDF ``` LLM 是**基于确定性核心的表示与推理层**，而不是 决策者。每一条建议都可以追溯到特定的规则、输入和 规则版本。这是本项目中最重要的一项设计决策，它的影响贯穿始终 —— 参见 [ADR-0003](docs/adr/0003-rule-engine-then-llm.md)。 ## 本项目展示了什么 | 能力 | 查看位置 | |---|---| | AI 系统设计（规则 → LLM，而不是 LLM → 一切） | [ADR-0003](docs/adr/0003-rule-engine-then-llm.md), [系统架构](docs/architecture/system-architecture.md) | | 生产级 AI 评估（准确性、一致性、幻觉、回归） | [ADR-0005](docs/adr/0005-evaluation-framework.md) | | LLM 网关 / 提供商抽象 (OpenRouter) | [ADR-0004](docs/adr/0004-openrouter-llm-gateway.md) | | AI 的可观测性（延迟、token、成本、评估得分） | [系统架构](docs/architecture/system-architecture.md#observability) | | 多租户隔离 | [ADR-0006](docs/adr/0006-multi-tenancy-isolation.md) | | 安全优先的工程实践 | [安全审查](docs/security/security-review.md), [威胁模型](docs/security/threat-model.md) | | 分层架构与领域边界 | [ADR-0002](docs/adr/0002-layered-architecture.md) | | 数据建模 (Postgres, JSONB, pgvector) | [ERD](docs/architecture/erd.md), [schema](db/schema.sql), [ADR-0008](docs/adr/0008-postgres-jsonb-pgvector.md) | ## 技术栈 **前端** — Next.js (App Router), TypeScript, TailwindCSS, React Query, Zod **后端** — FastAPI, Python 3.12+, Pydantic v2, SQLAlchemy 2.x, Alembic **数据** — PostgreSQL (JSONB + `pgvector`), Redis (缓存 + Celery broker) **任务** — Celery (报告生成、评估运行、LLM 增强) **存储** — 本地使用 MinIO，生产环境中使用兼容 S3 的抽象层 **LLM** — 使用 OpenRouter 作为跨提供商的单一网关 ([ADR-0004](docs/adr/0004-openrouter-llm-gateway.md)) **报告** — 通过 Playwright (Chromium) 实现 HTML → PDF 转换 **基础设施** — Docker + Docker Compose **质量保证** — Pytest, Playwright, Ruff, Black, MyPy 特意选用这些成熟稳定的技术。每一个组件都有其存在的价值；参见 [portfolio-story.md](docs/portfolio-story.md)。 ## 系统模块 1. **身份与访问管理** — 注册、登录、密码重置、个人资料、RBAC。 2. **组织管理** — 组织、成员、邀请；严格的租户隔离。 3. **评估引擎** — 跨越 7 个类别的动态、版本化评估 schema。 4. **规则引擎** — 基于数据库驱动，无需部署即可编辑的确定性建议。 5. **AI 建议层** — 通过 OpenRouter 在规则输出之上进行 LLM 增强。 6. **评估框架** — 准确性、一致性、完整性、幻觉率；回归测试。 7. **可观测性层** — 请求/LLM 延迟、token、成本、评估得分、仪表盘。 8. **报告生成** — 执行摘要、风险、安全、治理、路线图 → PDF。 9. **顾问工作区** — 审查、编辑发现、批准、发布。 10. **管理仪表盘** — 组织/评估/报告/AI 使用情况/评估/系统健康指标。 ## 仓库结构 ``` ai-advisory-platform/ ├── README.md ← you are here ├── docker-compose.yml ← local dev topology (design) ├── .env.example ← required configuration surface ├── db/ │ └── schema.sql ← canonical PostgreSQL schema (DDL) └── docs/ ├── portfolio-story.md ← why every decision was made ├── architecture/ │ ├── system-architecture.md ← C4-ish views + data flow │ └── erd.md ← entity-relationship model ├── adr/ ← Architecture Decision Records │ ├── 0001 … record ADRs │ ├── 0002 … layered architecture │ ├── 0003 … rule engine → LLM │ ├── 0004 … OpenRouter gateway │ ├── 0005 … evaluation framework │ ├── 0006 … multi-tenancy isolation │ ├── 0007 … auth choice │ └── 0008 … Postgres / JSONB / pgvector ├── security/ │ ├── security-review.md │ └── threat-model.md ← STRIDE ├── api/ │ └── openapi.yaml ← contract-first API surface ├── deployment-guide.md └── onboarding-guide.md ``` ## 状态 所有十个模块均已**实现并可运行**（`docker compose up --build` → 点击演示）。已完成的内容： - **规则引擎领域核心** — 安全的条件评估器、基础事实检查、LLM 提供商 接口、评估框架（阶段 6）。 - **授权 + 租户隔离内核** 以及分层的服务/存储库 `complete-assessment` 用例（阶段 4-5）。 - **真实的 OpenRouter 提供商**（重试、退避、token/成本遥测）， **SQLAlchemy 存储库 + Alembic**，以及带有默认拒绝防护的 **FastAPI API**、 经过净化处理的错误信息和安全标头（阶段 7 + 应用组装）。 - **Celery worker + 报告生成**（通过 Playwright 实现 HTML→PDF，位于渲染器 接口之后；XSS 转义内容），在 API 中验证的**真实 session-token 身份验证** （Next-BFF 契约，[ADR-0009](docs/adr/0009-auth-bff-session-token.md)），以及 **Next.js 前端**（App Router, React Query, Zod, Auth.js），其 BFF token 生成 与后端验证器完全对应。 - **顾问工作区**（编辑/批准/拒绝建议），在报告发布前带有**批准 门禁**，**管理 + 评估仪表盘**（真实的指标聚合 + 持久化的评估运行），以及 接入 API 的**报告端点**。 领域核心在**零依赖**下运行；完整的后端包含 **140 个通过的 测试**，全部离线运行（httpx `MockTransport`, SQLite, FastAPI `TestClient`，伪造的 PDF 渲染器）。整个 评估→审查→发布 的生命周期通过 HTTP 执行： ``` cd backend # domain core，无 install： PYTHONPATH=. python3 scripts/demo.py # rule engine → grounded enhancement → eval gate # full suite： python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" pytest -q # 140 passed ``` 前端 ([`frontend/`](frontend/README.md)) 是一个 Next.js App Router 应用；其 `lib/` 核心类型检查无误，可以通过 `npm install && npm run dev` 运行。 这些测试将安全模型证明为*可执行*的行为：失败即拒绝（fail-closed）的身份验证、 默认拒绝的 RBAC，以及跨租户访问在**两个**独立的层 （授权层**和**租户范围存储库）被阻止 —— 这一切均通过 HTTP 层 验证。 详见 [`backend/README.md`](backend/README.md)。构建顺序、验证门禁以及 每个阶段产生的成果均在 [`docs/portfolio-story.md`](docs/portfolio-story.md#build-phases) 中定义。代码是基于 该设计提交的，而不是超前于设计。 ## 运行整个项目 仅需一条命令即可在 Postgres 上启动全栈 —— 无需 `OPENROUTER_API_KEY` （未设置密钥时，LLM 层会回退到确定性的、基于事实的 mock）： ``` cp .env.example .env docker compose up --build # postgres + redis + minio + api + worker + web ``` `api` 入口点会运行 Alembic 迁移并植入一个演示组织 + 评估，然后： | 服务 | URL | |---|---| | Web 应用 | http://localhost:3000 | | API + OpenAPI 文档 | http://localhost:8000/v1 · http://localhost:8000/docs | | MinIO 控制台 | http://localhost:9001 | **点击演示：** 植入的种子数据创建了一个真实的、持久化的本地账号： `demo@example.com` / `ChangeMe123!`，位于 `Demo Organization` 中，并具有组织范围的 `consultant` 角色。打开 Web 应用 → **登录** → **评估** → 打开植入的 评估 → **完成**（规则引擎 + 基于事实的 LLM 增强）→ 审查并 **批准**发现的问题 → **发布报告**（HTML→PDF，存储在 MinIO 中）。平台 管理仪表盘需要真实的 `admin` 角色，不能通过注册或演示 登录获得。 有关生产环境的拓扑结构、密钥和操作，请参阅 [`docs/deployment-guide.md`](docs/deployment-guide.md) 和 [`docs/onboarding-guide.md`](docs/onboarding-guide.md)。 ## 许可证 作品集 / 教育用途。

标签：DLL 劫持, 云计算, 人工智能, 企业治理, 大语言模型, 搜索引擎查询, 测试用例, 特征检测, 用户模式Hook绕过, 规则引擎, 评估平台, 请求拦截, 逆向工具