add README.md

README.md

@@ -0,0 +1,145 @@
+# 小财记账 (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