# bxguwen

**Repository Path**: mindyleelyyAI/bxguwen

## Basic Information

- **Project Name**: bxguwen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI保顾问

AI保顾问是一个本地运行的保险客户工作日历。它把客户生日、保单续期和手动待办放到同一个日历里，帮助单个保险销售顾问每天知道该联系谁、为什么联系、做完了没有。

这个项目不是后台管理系统，也不是复杂 CRM。当前版本优先做好本地导入、提醒生成、完成状态记录、本地数据保护和脱敏同步。

## 适合谁用

- 手里有客户生日表、保单续期表或公司导出的 Excel。
- 每天需要跟进生日、续期、客户回访和临时待办。
- 希望数据先保存在本机，再按需要同步到飞书。
- 想要一个简单的工作日历，而不是复杂的后台系统。

## 当前能力

### 工作日历

- 以月历查看生日、续期和手动待办。
- 点击某一天后，右侧显示当天事项。
- 点击日历里的提醒，可以打开对应提醒详情。
- 支持按生日、续期、待办筛选，数量按当前月份统计。
- 支持单条完成和完成当天全部。

### 导入与待确认

- 支持一个入口上传客户表、保单表、CSV 或家庭保障分析表。
- 支持本地规则识别字段；表头不标准时，可以选择大模型辅助识别字段。
- 大模型 API Key 保存在本机 `data/ai-settings.json`，不提交到仓库。
- 支持正式导入前预检，预检不写入正式数据库。
- 正式导入前会自动创建本地备份。
- 关键字段缺失、生日缺失、生效日缺失、缴费期间无法解析或关键字段变化，会进入待确认。
- 待确认处理后，可以重新生成更可信的提醒。
- 家庭保障分析表会先记录字段维度，后续用于客户等级和家庭保障视图；当前不会直接生成提醒。

### 生日、续期和手动待办

- 生日提醒来自客户生日表。
- 续期提醒来自保单生效日和明确缴费期间，不从产品名猜测。
- 续期提醒只生成未来 60 天内真正需要跟进的事项；更远的续期保留在保单详情的下次续期和缴费结束年里。
- 支持 `1年`、`3年`、`5年`、`10年`、`20年`、`30年` 等固定缴费年期。
- 支持 `60周岁`、`65周岁`、`70周岁` 等年龄型缴费期间，前提是能取得生日和生效日。
- 手动待办可以在工作日历里新增、完成、编辑和删除。

### 飞书同步

当前版本提供本地飞书同步能力。同步依赖本机 `lark-cli` 授权，不是完整 SaaS OAuth。

同步目标：

- 客户
- 保单：包含下次续期和缴费结束年。
- 提醒：只同步本地已生成的提醒；续期提醒默认只包含未来 60 天内需要行动的事项。

同步说明见：

- `docs/AI_AGENT_SETUP.md`
- `docs/agent-feishu-sync.md`

飞书多维表格链接通常长这样：

```text
https://xxx.feishu.cn/base/...
```

这个链接必须满足：

- 是飞书多维表格，不是普通文档或电子表格。
- 当前飞书账号对这个多维表格有编辑权限。
- 本机 `lark-cli` 已完成飞书授权。

### 数据保护和云备份

- 维护页可以启用本地 SQLite 数据库加密。
- 已加密数据库启动后需要输入数据密码解锁。
- 修改数据密码必须输入当前数据密码，当前密码错误不会改密。
- 导入、清空和云端恢复前会优先生成本地备份。
- 支持把加密备份上传到坚果云 WebDAV，作为额外云备份。
- 坚果云云备份不是多设备实时同步，只上传加密备份文件。
- 坚果云 WebDAV 需要第三方应用密码，不能使用官网登录密码或验证码。

详细说明见 `docs/data-security-and-cloud-backup.md`。

## 快速启动

需要先安装 Node.js 20 或更新版本。macOS、Windows、Linux 都可以运行；当前主要在 macOS 上验证。

```bash
npm install
npm run start
```

启动成功后会打开：

```text
http://127.0.0.1:4173/
```

`npm run start` 会先构建前端，再同时启动本地 API 和网页预览。停止时按 `Ctrl+C`。

## 常用命令

```bash
npm run start      # 构建前端，并启动 API + 网页预览
npm run api        # 只启动 API，端口 3001
npm run dev        # 只启动网页开发服务，端口 5173
npm run preview    # 只启动构建后的网页预览，端口 4173
npm run typecheck  # TypeScript 检查
npm test           # 运行单元和接口测试
npm run build      # 构建前端
```

当前仓库的验收脚本是 `typecheck`、`test`、`build`。暂未提供 ESLint 和 Playwright E2E 配置。

## 数据安全

本项目默认把数据保存在本机 SQLite：

```text
data/customer-reminders.sqlite
```

这个文件可能包含客户姓名、手机号、证件号、保单信息和提醒状态，已经被 `.gitignore` 排除，不应提交到 git。

维护页可以启用数据库加密。启用后需要输入数据密码才能打开本地数据库；已有明文库会先生成一份迁移前备份，再转换为加密库。

备份文件默认保存在：

```text
data/backups/
```

维护页还提供额外的坚果云云备份能力。云备份不是多设备实时同步，只会把本机生成的加密备份文件上传到坚果云 WebDAV 目录；从云端恢复会覆盖当前数据，恢复前会自动再做一次本地备份。数据库未启用加密时，不允许连接或上传云备份。

坚果云 WebDAV 不能使用官网登录密码。需要先登录坚果云官网，进入“账户信息”里的“安全选项”，在“第三方应用管理”中添加应用密码，再把生成的应用密码粘贴到本工具。应用密码默认只在本次连接使用，不写入本地数据库；如果勾选“记住在本机浏览器”，会保存到当前浏览器 Cookie，清理浏览器数据或换浏览器后需要重新输入。

可以通过环境变量开启本地访问密码：

```bash
CUSTOMER_REMINDERS_PASSWORD="你的密码" npm run start
```

访问密码只保护网页入口；数据库加密使用维护页设置的数据密码。本地数据库仍会保存必要的完整身份字段用于匹配；网页详情和飞书同步默认脱敏展示手机号和证件号。

本仓库不附带真实客户 Excel 或真实数据库。导入测试请使用自己准备的表格，或参考 `docs/sample-data.md` 里的字段说明制作合成数据。

当前 Excel/CSV 解析依赖 `xlsx`。npm audit 对该依赖有已知高危提示且暂无官方修复版本；当前版本只建议导入自己可信来源的本地文件，不建议把本工具改造成公开上传服务。更多说明见 `SECURITY.md`。

## 技术结构

```text
src/
  api/        本地 HTTP API
  cloud/      WebDAV 云备份适配
  db/         SQLite 连接、迁移和仓储
  domain/     纯业务规则：ID、匹配、生日、续期
  importers/  表格读取、字段识别和归一化
  sync/       飞书多维表格和飞书日历同步
  web/        React + FullCalendar 前端
tests/        domain、importers、db、api、sync、contracts 测试
docs/         使用说明、安全说明和测试清单
```

核心边界：

- `src/domain/` 不读文件、不碰数据库、不调用飞书。
- `src/importers/` 可以理解表格列名，但不直接写 UI。
- `src/ai/` 只做大模型提供方配置和字段识别，不直接写数据库。
- `src/db/` 只负责持久化和迁移。
- `src/cloud/` 只负责云备份协议适配，不读取业务规则。
- `src/sync/` 使用已生成的本地快照，不重新计算提醒。
- `src/web/` 只通过 API 操作数据，不直接导入数据库或领域服务。

## 维护说明

后续修改这个项目时，先读：

- `AGENTS.md`：公开版 AI 协作和代码边界指引。
- `SPEC.md`：当前业务规则和成功标准。
- `SECURITY.md`：安全边界和已知限制。
- `docs/data-security-and-cloud-backup.md`：数据库加密、本地备份、坚果云云备份说明。
- `docs/OPEN_SOURCE_ALPHA.md`：开源发布边界和检查清单。
- `docs/OPEN_SOURCE_RELEASE_PROCESS.md`：私有开发区到公开发布区的白名单导出流程。
- `docs/sample-data.md`：导入字段说明。

## 发布前检查

常规代码改动至少运行：

```bash
npm run typecheck
npm test
npm run build
```

涉及日历、按钮、弹窗等界面改动时，还要打开 `http://127.0.0.1:4173/` 做浏览器验证，确认文字不重叠、入口不重复、完成状态真实生效。

开源或分享前，不要直接推送或压缩日常开发目录。必须先用白名单导出公开发布区：

```bash
npm run export:open-source -- --clean
```

然后进入公开发布区重新安装、测试、构建、扫描敏感内容，并清理 `node_modules`、`dist`、`.omx` 等本地产物。确认公开发布区没有敏感数据后，才从公开发布区提交和推送 GitHub。

导出流程见 `docs/OPEN_SOURCE_RELEASE_PROCESS.md`。

## 当前未包含

- 多人账号和权限体系。
- PDF、图片、Word 等非表格文件识别。
- 面向普通用户的飞书网页一键授权。
- 多设备实时双向同步。
- Playwright E2E 和 ESLint 配置。