# 家庭幸福药箱管理系统（Happy MedBox）

三端软件脚手架：**微信小程序端 + Node/SQLite 后端 + MCP 服务端 + A2A 提醒代理**。
核心全流程：拍摄识别 → 写入数据库 → 定时扫描过期 → MCP 提供数据接口 → A2A 触发提醒 → 小程序展示提醒与建议。

> 技术选型：后端与小程序均用原生/零外部依赖实现（Node 22 内置 `http` / `node:sqlite` / `node:test`），**离线即可 `node` 运行与测试**，无需 `npm install`。

## 目录结构
```
happy-medbox/
├─ prd.md / architecture.md      # 产品需求 + 系统架构（团队 SOP 产出）
├─ package.json / README.md
├─ src/                          # 后端：API + 数据库 + MCP + A2A
│  ├─ db.js          # SQLite 连接与建表（node:sqlite）
│  ├─ expiry.js      # 过期计算（纯函数，可单测）
│  ├─ ocr.js         # OCR 接口 + Mock（预留腾讯云/微信 OCR）
│  ├─ repository.js  # 数据访问层 CRUD
│  ├─ mcp-server.js  # MCP 工具 + JSON-RPC（stdio）
│  ├─ server.js      # REST API（小程序对接）
│  ├─ a2a-server.js  # 提醒代理 + 用户代理（双端口，A2A 推送）
│  ├─ seed.js        # 样例数据
│  └─ index.js       # 编排入口（启动 + 定时扫描）
├─ miniprogram/                  # 微信小程序端（原生）
│  ├─ pages/{index,capture,detail,knowledge,reminder}/
│  └─ utils/{api,ocr,format}.js
└─ test/                         # 单元测试（expiry/db/mcp/a2a）
```

## 快速开始
### 1. 启动后端 + A2A（默认端口 3000 / 4100 / 4200）
```bash
cd happy-medbox
node src/index.js
```
启动后：
- 小程序对接 REST：`http://localhost:3000`
- 提醒代理（AgentCard / 触发扫描）：`http://localhost:4100`
- 用户代理收件箱：`http://localhost:4200`

环境变量：`API_PORT` / `REMINDER_PORT` / `USER_PORT` / `WARNING_DAYS`(默认30) / `REMINDER_INTERVAL_MS`(默认60000) / `MEDBOX_DB`(默认 `data/medbox.db`，内存库用 `:memory:`)。

### 2. 运行测试（19 项，全过）
```bash
node --test
```

### 3. 单独启动 MCP 服务端（供 AI 助手 stdio 调用）
```bash
node src/mcp-server.js
# 支持 initialize / tools/list / tools/call
# 工具：query_medicines / recognize_medicine_image / compute_expiry /
#       get_medication_advice / add_medicine / list_expiring
```

### 4. 打开小程序
用**微信开发者工具**导入 `miniprogram/` 目录（`appid` 已设为 `touristappid` 游客模式可直接预览）。
真机调试时把 `miniprogram/app.js` 里的 `baseUrl` 改成电脑局域网 IP（如 `http://192.168.x.x:3000`），并在开发者工具勾选"不校验合法域名"。

## 关键流程说明
- **拍照识别**：`capture` 页 `wx.chooseMedia` → `POST /api/ocr` → 当前返回 Mock 结构化字段（名称/规格/生产日期/有效期），用户校对后 `POST /api/medicines` 入库。
- **倒计时过期**：后端 `expiry.js` 按当天实时计算剩余天数与状态（safe/warning/expired）；小程序首页与详情页展示。
- **定时扫描 + A2A 推送**：`a2a-server.js` 的提醒代理按间隔扫描临期药 → 写入 `reminders` 表并封装 A2A Task → HTTP 推送到用户代理 `/tasks`（跨代理消息流转）→ 小程序 `reminder` 页轮询展示，可标记已读。
- **MCP 数据接口**：AI 助手通过 stdio JSON-RPC 调用六个工具，按需查询药品 / 识别 / 计算效期 / 检索用药建议。

## 生产替换建议（接口契约不变）
- 数据库：`node:sqlite` → `better-sqlite3`（更快、同步）。
- MCP：`src/mcp-server.js` 自实现 JSON-RPC → 官方 `@modelcontextprotocol/sdk`。
- REST：内置 `http` → `Express/Fastify`。
- OCR：`ocr.js` 的 Mock 分支 → 接入腾讯云通用印刷体 OCR 或微信 OCR 插件（需密钥/资质）。

## 已知边界（MVP 范围）
- 提醒通道先用小程序内轮询，微信订阅消息留接口。
- 知识库为内置少量样例，管理员后台待做（P2）。
- 无账号体系，单家庭本地标识（P2 多端云同步）。