# 小程序联调操作手册

> 将 AI 药典模块接入「开邻药惠购」uni-app 小程序

---

## 一、文件拷贝

将本项目 `miniprogram/` 下的 5 个文件复制到现有 uni-app 项目对应目录：

```
本项目的 miniprogram/                      你现有的 uni-app 项目/
├── api/ai.js                        →     src/api/ai.js（或 api/ai.js）
├── utils/sse.js                     →     src/utils/sse.js
├── pages/ai-yaodian/index.vue       →     src/pages/ai-yaodian/index.vue
└── components/ai-chat/index.vue     →     src/components/ai-chat/index.vue
```

---

## 二、注册页面路由

编辑 `pages.json`，在 `pages` 数组末尾追加：

```json
{
  "path": "pages/ai-yaodian/index",
  "style": {
    "navigationBarTitleText": "AI 药典查询",
    "navigationBarBackgroundColor": "#002FA7",
    "navigationBarTextStyle": "white"
  }
}
```

---

## 三、配置 API 地址

编辑 `api/ai.js` 第 6-7 行：

```javascript
// 生产环境 — 替换为实际部署的后端域名
const BASE_URL = 'https://api.your-domain.com/api/v1'

// 本地调试 — 开发阶段使用（需关闭小程序域名校验）
// const BASE_URL = 'http://localhost:8000/api/v1'
```

---

## 四、微信登录 → JWT Token

### 方式 A：在 App.vue 的 onLaunch 中获取 token

```javascript
// App.vue — onLaunch 生命周期
onLaunch() {
  // 现有微信登录逻辑
  wx.login({
    success: (res) => {
      uni.request({
        url: BASE_URL + '/auth/login/wechat',
        method: 'POST',
        data: { code: res.code },
        success: (r) => {
          uni.setStorageSync('access_token', r.data.access_token)
        }
      })
    }
  })
}
```

### 方式 B：开发阶段用固定 token 跳过登录

在 `api/ai.js` 的 `getToken()` 函数中：

```javascript
function getToken() {
  // 开发阶段：直接返回固定token
  return 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'  // 用你后端生成的token替换
  // 正式上线：改回下面的
  // return uni.getStorageSync('access_token') || ''
}
```

生成 token：
```bash
cd backend && source ../.venv/bin/activate
python3 -c "from app.core.security import create_access_token; print(create_access_token({'sub':'test-user'}))"
```

---

## 五、导航入口

在现有首页加一个入口跳转到 AI 页面。任选一处：

### 5.1 底部 Tab（pages.json 的 tabBar.list 里加）

```json
{ "pagePath": "pages/ai-yaodian/index", "text": "AI 药典", "iconPath": "..." }
```

### 5.2 悬浮按钮（在首页 WXML/Vue 模板中加）

```html
<navigator url="/pages/ai-yaodian/index" class="ai-fab">
  💊 AI 药典
</navigator>
```

### 5.3 药品详情页嵌入（使用 AiChatPanel 组件）

```html
<!-- 在药品详情页 template 中 -->
<ai-chat-panel :drugName="drugName" />
```

```javascript
// pages/drug-detail/index.vue — script
import AiChatPanel from '@/components/ai-chat/index.vue'
export default {
  components: { AiChatPanel },
  data() { return { drugName: '阿莫西林' } }
}
```

---

## 六、调试检查清单

| # | 检查项 | 操作 |
|---|--------|------|
| 1 | 后端是否运行 | `curl http://localhost:8000/health` |
| 2 | Token 是否有效 | 小程序控制台 `uni.getStorageSync('access_token')` |
| 3 | 域名校验 | 开发工具中勾选「不校验合法域名」 |
| 4 | API 地址 | `api/ai.js` 中 BASE_URL 是否正确 |
| 5 | 文件路径 | pages.json 中 path 与文件实际路径一致 |
| 6 | SSE 流式 | 发一个问题看是否流式输出 |

---

## 七、生产部署前需完成

| 事项 | 操作 |
|------|------|
| 后端部署 | 将 FastAPI 部署到公网服务器，配置 HTTPS |
| 小程序域名 | 在微信后台「开发管理-服务器域名」添加后端域名 |
| Token 过期 | 在 `api/ai.js` 中增加 401 自动刷新 token 逻辑 |
| 内容安全 | 接入微信内容安全 API 过滤违规内容 |
| 药品数据 | 确保知识库覆盖常用药品（建议 500+ 条目） |