146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
# 小财记账 (XiaoCai Accounting)
|
||
|
||
AI 驱动的内部群聊记账系统，通过自然语言对话自动记录采购信息。
|
||
|
||
## 功能特性
|
||
|
||
- **AI 自然语言记账** — 聊天中输入"打印纸一包，30元，已付"即可自动创建采购记录
|
||
- **采购清单管理** — 按月汇总，支持编辑、删除、附件管理，状态追踪（待付款→已付款→已收货→已完成）
|
||
- **多群聊支持** — 每个项目独立群聊，支持白名单权限控制
|
||
- **实时推送** — WebSocket 实时同步消息和采购变更
|
||
- **移动端适配** — 响应式设计，支持滑动手势、图片双指缩放拖拽
|
||
- **管理员功能** — 群聊管理、采购导出 CSV、全局汇总
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| 后端 | Node.js + Express + WebSocket (ws) |
|
||
| 数据库 | SQLite (better-sqlite3) |
|
||
| AI | DeepSeek API |
|
||
| 前端 | 原生 HTML/CSS/JS，无框架 |
|
||
| 部署 | Docker + Docker Compose |
|
||
| 认证 | JWT |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
xiaocai-ai-server/
|
||
├── docker-compose.yml # Docker 编排
|
||
├── build.sh # 构建脚本
|
||
├── server/
|
||
│ ├── server.js # 入口
|
||
│ ├── db.js # 数据库初始化 + 迁移
|
||
│ ├── utils.js # 时间工具函数
|
||
│ ├── handlers.js # AI 结果处理 + 对话状态
|
||
│ ├── package.json
|
||
│ ├── Dockerfile
|
||
│ ├── ai/
|
||
│ │ ├── prompt.js # Prompt 模板
|
||
│ │ ├── validator.js # JSON Schema 校验
|
||
│ │ └── client.js # DeepSeek API 客户端
|
||
│ ├── middleware/
|
||
│ │ └── auth.js # JWT 认证 + 管理员中间件
|
||
│ ├── routes/
|
||
│ │ ├── auth.js # 登录 / 用户信息
|
||
│ │ ├── rooms.js # 群聊 CRUD
|
||
│ │ ├── messages.js # 消息 + AI 分析
|
||
│ │ └── purchases.js # 采购 CRUD / 汇总 / 导出
|
||
│ ├── ws/
|
||
│ │ └── index.js # WebSocket 连接管理 + 广播
|
||
│ └── public/
|
||
│ ├── index.html # 单页应用
|
||
│ ├── css/style.css # 样式
|
||
│ └── js/
|
||
│ ├── store.js # 全局状态管理
|
||
│ ├── chat.js # 消息渲染 + 图片处理
|
||
│ ├── ws.js # WebSocket + 聊天列表
|
||
│ ├── purchases.js # 采购清单 + 编辑 + 手势
|
||
│ └── auth.js # 登录 / 初始化
|
||
└── docs/
|
||
└── v2.md # 重构设计文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境变量
|
||
|
||
创建 `.env` 文件：
|
||
|
||
```bash
|
||
# 用户账号（username:password 逗号分隔）
|
||
USERS=admin:admin123,user1:pass1
|
||
|
||
# 管理员列表（逗号分隔）
|
||
ADMINS=admin
|
||
|
||
# DeepSeek API Key
|
||
DEEPSEEK_API_KEY=sk-xxx
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
# 构建并启动
|
||
./build.sh
|
||
|
||
# 或手动
|
||
docker compose up -d
|
||
```
|
||
|
||
服务默认监听 `3000` 端口。
|
||
|
||
## API 概览
|
||
|
||
### 认证
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| POST | `/api/login` | 登录获取 JWT |
|
||
|
||
### 群聊
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/rooms` | 群聊列表（按活跃时间排序） |
|
||
| POST | `/api/rooms` | 新建群聊 |
|
||
| PUT | `/api/rooms/:id` | 编辑群聊 |
|
||
| DELETE | `/api/rooms/:id` | 删除群聊（管理员） |
|
||
|
||
### 消息
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/rooms/:id/messages` | 获取消息历史 |
|
||
| POST | `/api/rooms/:id/messages` | 发送消息（触发 AI 分析） |
|
||
| POST | `/api/upload` | 上传图片 |
|
||
|
||
### 采购
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/rooms/:id/purchases` | 群聊采购清单 |
|
||
| GET | `/api/purchases/:id` | 采购详情（含历史 + 附件） |
|
||
| PUT | `/api/purchases/:id` | 更新采购记录 |
|
||
| DELETE | `/api/purchases/:id` | 删除采购记录 |
|
||
| POST | `/api/purchases/:id/attachments` | 添加附件 |
|
||
| DELETE | `/api/purchases/:id/attachments` | 删除附件 |
|
||
| GET | `/api/summary` | 全局采购汇总 |
|
||
| GET | `/api/rooms/:id/purchases/export` | 导出 CSV |
|
||
|
||
## 采购状态流转
|
||
|
||
```
|
||
待付款 → 已付款 → 已收货 → 已完成
|
||
```
|
||
|
||
- **聊天 AI** — 仅负责新建记录，修改操作引导用户去采购清单手动完成
|
||
- **采购清单** — 点击条目进入详情，可编辑所有字段、管理附件、查看操作历史
|
||
|
||
## 设计原则
|
||
|
||
- AI 不负责更新已有记录，所有修改由用户手动完成
|
||
- 新建记录通过聊天自然语言输入
|
||
- 移动端优先：滑动手势、数字键盘、双指缩放
|
||
- 操作历史自动记录所有变更，可追溯
|
||
|
||
## License
|
||
|
||
MIT
|