# 技术架构

## 当前架构

当前是无构建静态前端 + Python 标准库 API：

```text
index.html
styles.css
script.js
backend/app.py
backend/ai_provider.py
assets/
docs/
deploy/
```

部署方式：

```text
GitHub main
  -> GitHub Actions
  -> SSH 到服务器
  -> /opt/jiajilvai/app 执行 deploy/git-deploy.sh
  -> 同步静态文件到 /var/www/jiajilvai.top
  -> 安装并重启 jiajilvai-api.service
  -> Nginx 对外提供 HTTPS，并将 /api/ 代理到 127.0.0.1:8787
```

生产域名：

```text
https://jiajilvai.top/
https://www.jiajilvai.top/
```

## 服务器路径

```text
/opt/jiajilvai/app       正式 Git 工作目录
/var/www/jiajilvai.top   Nginx 静态站目录
/var/lib/jiajilvai       SQLite 数据目录
/root/.ssh               部署 SSH key
```

## 当前 API

API 服务使用 Python 标准库 `http.server` + SQLite，避免在当前服务器上引入 Node 或额外 Python 依赖。

```text
GET  /api/health
GET  /api/auth/me
POST /api/auth/register
POST /api/auth/login
POST /api/auth/logout
POST /api/ai/fortune
POST /api/ai/dream
POST /api/ai/fortune/stream
POST /api/ai/dream/stream
```

账号密码使用 PBKDF2-SHA256 加盐哈希；登录态使用 HttpOnly、Secure、SameSite=Lax cookie。

AI 能力通过 `backend/ai_provider.py` 封装。当前 provider 调用：

```text
codex exec --ephemeral --sandbox read-only --output-last-message ...
```

后续新增 AI 功能应复用这个 Provider 层，不要在业务代码里直接拼命令。

流式输出使用 `text/event-stream`。当前 Codex CLI JSON 事件只提供最终文本，Provider 会先发送状态事件，再在拿到最终文本后按小片段输出 `chunk` 事件；如果未来 Codex CLI 提供 token delta，只需要替换 Provider 的流式实现。

## 后续建议架构

当开始接入真实 AI、实验记录和资料管理后，建议迁移为：

```text
apps/web       React + Vite + TypeScript
apps/api       Fastify + TypeScript
packages/*     共享类型和工具
PostgreSQL     实验记录、资料、用户和历史记录
Redis          明确有缓存/队列需求后再加入
Docker Compose 单机编排
Nginx          HTTPS 和反向代理
```

建议 API 路径：

```text
/api/auth/*
/api/ai/*
/api/reagents/*
/api/experiments/*
/api/notes/*
/api/history/*
```

## 新增功能约定

新增甲基绿相关功能时至少补充：

- 功能入口卡片
- 工具页面
- 表单输入
- 结果展示区域
- 必要的实验字段和资料字段
- `docs/CHANGELOG.md` 变更记录
- 必要时更新 `docs/ROADMAP.md`