# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Language

使用中文作为自然语言对话和注释等语言类工作。

## Project Overview

Noval 是一个本地Web形式的小说创作应用，集成AI Agent辅助创作。用户运行Python后端 + 浏览器前端。

## Development Commands

### Backend
```bash
cd backend
# 首次安装
py -3 -m venv .venv && .venv/Scripts/pip install -r requirements.txt
# 启动（Windows上用 py -3，不要用 python3）
.venv/Scripts/uvicorn app.main:app --port 8000
# API文档
http://localhost:8000/docs
```

### Frontend
```bash
cd frontend
npm install
npm run dev          # 开发服务器 http://localhost:5173
npm run build        # 生产构建
npm run type-check   # TypeScript类型检查
```

前端Vite代理 `/api` → `http://127.0.0.1:8000`，开发时需同时运行后端。

## Architecture

```
backend/app/
├── main.py              # FastAPI入口，CORS，lifespan初始化DB
├── database.py          # SQLite (backend/data/noval.db)，SQLModel engine
├── models.py            # ORM: Novel, Outline, AIConfig, ChatMessage
├── schemas.py           # Pydantic请求/响应模型
├── routers/             # REST API路由
│   ├── novels.py        # /api/novels — 小说CRUD
│   ├── outlines.py      # /api/novels/{id}/outlines — 大纲CRUD+排序
│   ├── ai_config.py     # /api/ai/config — AI服务配置
│   └── chat.py          # /api/chat/stream — SSE流式对话
└── services/
    └── ai_provider.py   # AI抽象层：OpenAI兼容 + Anthropic原生，httpx直调无SDK

frontend/src/
├── api/                 # Axios封装 + 各资源API（novels, outlines, chat）
├── types/               # TypeScript接口定义
├── composables/         # Vue组合式函数（useChatAgent, useToast）
├── components/
│   ├── ui/              # 基础组件：BaseButton, BaseInput, BaseModal等
│   ├── novel/           # 小说卡片、网格、空状态
│   ├── outline/         # 卷轴时间线、节点卡片、表单
│   └── chat/            # 聊天面板、消息气泡、AI配置弹窗
├── views/               # 页面视图
└── style/               # CSS变量、重置、排版、动画
```

### Key Patterns

- **后端**：FastAPI + SQLModel + SQLite，同步Session，路由按资源分文件
- **前端**：Vue 3 Composition API + TypeScript，纯手写UI组件（无组件库）
- **AI集成**：不用SDK，httpx直调OpenAI/Anthropic HTTP API，SSE流式输出
- **聊天状态**：`useChatAgent()` 使用模块级ref实现全局共享
- **流式处理**：后端 `StreamingResponse` → 前端 `fetch` + `ReadableStream` 解析SSE

### Design System — "墨韵书斋"

CSS变量定义在 `frontend/src/style/variables.css`：
- 墨色系(--ink-*)、纸色系(--paper-*)、朱砂红(--vermilion)、竹青(--bamboo)
- 字体：Noto Serif SC（标题）、Crimson Pro（正文）

## API Structure

| 前缀 | 说明 |
|------|------|
| `/api/novels` | 小说CRUD，PATCH部分更新 |
| `/api/novels/{id}/outlines` | 大纲CRUD + `PUT /reorder` 排序 |
| `/api/ai/config` | AI配置读写 + `POST /test` 测试连接 |
| `/api/chat/stream` | SSE流式对话，返回content/usage/done事件 |
| `/api/chat/messages` | 历史消息查询和清空 |