feat: 前端组件准备

README.md

@@ -1,75 +1,126 @@
-# Nuxt Minimal Starter
+# OCS Nuxt AI Answer Service
 
-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+这是一个基于 Nuxt/Nitro 的 OCS AI 答题服务，迁移自旧版 Python Flask 服务。服务端使用 OpenAI 兼容的 Chat Completions 流式接口生成答案，对 OCS 仍返回普通 JSON。
 
-## Setup
+## 功能
 
-Make sure to install dependencies:
+- 兼容 OCS AnswererWrapper 题库接口。
+- 支持 `GET`、JSON `POST`、表单 `POST` 调用 `/api/search`。
+- 支持单选、多选、判断、填空题提示词处理。
+- 支持可选访问令牌校验。
+- 支持内存缓存、健康检查、缓存清理和运行统计。
+- OpenAI API Key 只在服务端读取，不返回给前端。
+
+## 环境变量
+
+复制 `.env.example` 为 `.env`，然后填写自己的配置：
 
 ```bash
-# npm
-npm install
+cp .env.example .env
+```
 
-# pnpm
+必填：
+
+```env
+OPENAI_API_KEY=your-api-key-here
+```
+
+常用配置：
+
+```env
+OPENAI_API_BASE=https://api.openai.com/v1
+OPENAI_MODEL=gpt-3.5-turbo
+MAX_TOKENS=500
+TEMPERATURE=0.7
+ENABLE_CACHE=true
+CACHE_EXPIRATION=86400
+```
+
+如需限制访问：
+
+```env
+ACCESS_TOKEN=your-access-token
+```
+
+启用后，请求需要带 `X-Access-Token` 请求头或 `?token=...` 查询参数。
+
+## 启动
+
+```bash
 pnpm install
-
-# yarn
-yarn install
-
-# bun
-bun install
-```
-
-## Development Server
-
-Start the development server on `http://localhost:3000`:
-
-```bash
-# npm
-npm run dev
-
-# pnpm
 pnpm dev
-
-# yarn
-yarn dev
-
-# bun
-bun run dev
 ```
 
-## Production
+默认 Nuxt dev server 地址为 `http://localhost:3000`。
 
-Build the application for production:
+## OCS 配置示例
 
-```bash
-# npm
-npm run build
-
-# pnpm
-pnpm build
-
-# yarn
-yarn build
-
-# bun
-bun run build
+```json
+[
+  {
+    "name": "AI智能题库",
+    "homepage": "http://localhost:3000",
+    "url": "http://localhost:3000/api/search",
+    "method": "get",
+    "type": "GM_xmlhttpRequest",
+    "contentType": "json",
+    "data": {
+      "title": "${title}",
+      "type": "${type}",
+      "options": "${options}"
+    },
+    "handler": "return (res)=> res.code === 1 ? [res.question, res.answer] : [res.msg, undefined]"
+  }
+]
 ```
 
-Locally preview production build:
+如果使用自定义域名，请按 OCS 文档把 `homepage` 和 `url` 涉及的域名加入脚本 `@connect`。
 
-```bash
-# npm
-npm run preview
+## API
 
-# pnpm
-pnpm preview
+### `GET|POST /api/search`
 
-# yarn
-yarn preview
+参数：
 
-# bun
-bun run preview
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `title` | 是 | 题目内容 |
+| `type` | 否 | `single`、`multiple`、`judgement`、`completion` |
+| `options` | 否 | 选项文本 |
+
+成功：
+
+```json
+{
+  "code": 1,
+  "question": "中国的首都是哪个城市？",
+  "answer": "北京"
+}
 ```
 
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+失败：
+
+```json
+{
+  "code": 0,
+  "msg": "未提供问题内容"
+}
+```
+
+### `GET /api/health`
+
+返回服务状态、版本、缓存开关和模型名。
+
+### `POST /api/cache/clear`
+
+清空内存缓存。若配置了 `ACCESS_TOKEN`，需要携带访问令牌。
+
+### `GET /api/stats`
+
+返回 uptime、模型、缓存大小和最近问答记录数量。若配置了 `ACCESS_TOKEN`，需要携带访问令牌。
+
+## 注意
+
+- 多选题答案按 OCS 要求返回 `#` 分隔字符串。
+- OpenAI 调用使用服务端流式请求，但接口对 OCS 返回普通 JSON。
+- 内部或上游异常不会透传给 OCS，只返回本地错误文案。