# lingxi

**Repository Path**: Fortuitous/lingxi

## Basic Information

- **Project Name**: lingxi
- **Description**: 灵犀（Lingxi）—— 双端同步的个人效率工作台：专注、番茄钟、习惯打卡、心情与日历提醒。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵犀（Lingxi）

> 一个温暖治愈系的个人每日成长应用 —— 待办 / 专注 / 记账 / 运动 / 英语 / 阅读 / 生理期 / 情侣空间 / 成长打卡 / 心情日记 / 周报月报，全模块覆盖，助你践行「一次一件事」的每日节奏。

**当前状态：** V1~V12 全部交付（产品 v5.1 / 技术方案 v2.13），V13 移动端方案已定稿待实现（见 [`docs/product/mobile-app.md`](docs/product/mobile-app.md)）。

## ✨ 功能特性

- **待办 & 专注**：番茄钟、任务热区、GTD 流程、全局快捷键 `N` 快速建任务。
- **健康管理**：生理期记录与预测、今日状态打卡（可补录）、周期长度趋势图、排卵期/易孕期展示、经前综合征备忘。
- **财务**：记账（微信/支付宝/银行 CSV 账单一键导入、周期性账单）、多维图表、支出异常提醒。
- **学习**：英语背单词打卡、阅读进度与笔记、每日 10 词词卡复习。
- **运动**：运动打卡、近 7 天热力图、年度目标进度。
- **成长**：习惯追踪、年度目标打卡、心情日记、家庭纪念日，AI 助手区块。
- **情侣空间**：在一起天数、纪念日提醒、甜蜜打卡（带悄悄话 + 历史回看）、100 件一起做的事、愿望清单、留言墙、AI 洞察。
- **回顾**：周报 / 月报自动生成、专注数据大屏、年度打卡热力图、CSV 导出。
- **AI 集成**：全局 AI 助手 + 各模块「AI 洞察」一键生成分析摘要，支持「预览 → 确认 → 执行」的 AI 写操作。
- **提醒**：每日提醒（Web Notification）+ PWA 后台推送（页面关闭也能收到），经期 / 纪念日 / 目标到期独立子开关。

## 🛠 技术栈

- **前端**：React 19 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4 + shadcn/ui + Recharts + Framer Motion
  - 路由 React Router 7，数据缓存 TanStack Query，动效 CSS 变量主题系统（4 套主题）
  - **双模数据源**：优先走本地 `/api/db/*` 直连后端 PostgreSQL；数据库不可用时 localStorage 降级保底
- **后端**：Node.js + Express + TypeScript（tsx 开发热重载，`node dist/index.js` 生产运行）
  - `node-postgres`（pg）直连本地/自建 PostgreSQL，启动自动建表（**19 张**），单用户 `user_id='owner'` 模式
  - `/api/db|ai|push` 全部 Bearer Token 鉴权，CORS 白名单，pg 参数化查询
- **AI**：DeepSeek / Kimi / 混元 / 商汤多模型网关（OpenAI 兼容，Key 仅存服务端 .env）
- **测试**：前端 vitest（87 例）+ 后端 jest（16 例）
- **移动端（V13 待实现）**：Capacitor 套壳（安卓/iOS）+ 鸿蒙 ArkWeb，前端 100% 复用

## 📂 Monorepo 结构

```
.
├── backend/                 # Express 后端（端口 18084，仅绑定 127.0.0.1）
│   └── src/
│       ├── modules/db.ts        # pg 直连 + 自动建表 + /api/db/* 端点
│       ├── modules/ai.ts        # AI 多模型代理 + 工具调用
│       ├── modules/ai-tools.ts  # 工具注册表 + pendingOp 令牌
│       ├── modules/scheduler.ts # 定时推送调度
│       └── index.ts             # 服务入口
├── frontend/                # Vite 前端（开发端口 50817）
│   └── src/
│       ├── lib/cloudbase.ts     # 双模数据接入（中继 → localStorage）
│       ├── lib/backend-relay.ts # /api/db/* 中继客户端
│       ├── lib/ai.ts            # chatAi（tools + pendingOps）
│       ├── lib/ai-insights/     # 各模块 AI 洞察注册表
│       └── components/          # 业务组件（layout/dashboard/couple/...）
└── docs/
    ├── product/             # 产品文档：solution / features / roadmap / mobile-app / api
    └── project-rule/        # 工程规范：commit / code-review / build / deploy / push-to-gitee 等
```

## 📦 仓库地址

开源仓库托管于 Gitee（代号 `Fortuitous/lingxi`，公开 `lingxi` 仓库）：

```
https://gitee.com/Fortuitous/lingxi
```

- **Fork / Code**：右上角 `克隆/下载` 或直接：
  ```bash
  git clone https://gitee.com/Fortuitous/lingxi.git
  ```

## 🚀 快速开始

### 0. 克隆仓库

```bash
git clone https://gitee.com/Fortuitous/lingxi.git
cd lingxi
```

### 1. 本地 PostgreSQL

```bash
# 初始化数据目录（仅首次）
mkdir -p .pgdata
initdb -D .pgdata -U lingxi --auth=trust

# 启动（端口 5433；非 postgres 系统用户须 -k /tmp 指定 socket 目录）
pg_ctl -D .pgdata -o "-p 5433 -k /tmp" -l .pgdata/server.log -w start

# 建库
createdb -p 5433 -U lingxi lingxi
```

> `.pgdata/` 已加入 `.gitignore`。

### 2. 后端

```bash
cd backend
npm install
cp .env.example .env   # 配置 DATABASE_URL / API_TOKEN / AI Keys
npm run dev            # tsx watch，端口 18084
```

> `API_TOKEN` 必填（`openssl rand -hex 24` 生成，与前端 `VITE_API_TOKEN` 同值），未配置时后端拒绝启动；数据库不可用时不报错，自动降级 localStorage。启动时自动创建 19 张表。

### 3. 前端

```bash
cd frontend
npm install
npm run dev            # Vite，端口 50817
```

前端开发服务器已配置 `/api` 代理到 `http://localhost:18084`。打开 `http://localhost:50817` 开始使用。

### 4. 提交前验证

```bash
npx tsc -b --noEmit      # 类型零错误
npm run lint             # ESLint 零错误
npm run test             # vitest 全绿
node scripts/i18n-check.mjs  # i18n 护栏
```

根目录 `Makefile` 提供统一命令：`make install / build / test / lint / preflight / dev-backend / dev-frontend`（`preflight` 收敛全部提交门槛）。

## 📖 文档索引

| 文档 | 说明 |
|------|------|
| [`docs/product/solution.md`](docs/product/solution.md) | 技术方案：架构、数据模型（技术债历史表见 §6，新问题走 Gitee issue） |
| [`docs/product/features.md`](docs/product/features.md) | 功能规格（PRD）：V1~V13 需求清单 |
| [`docs/product/roadmap.md`](docs/product/roadmap.md) | 交付路线图：版本计划与状态 |
| [`docs/product/mobile-app.md`](docs/product/mobile-app.md) | 移动端三平台方案（V13） |
| [`docs/product/api.md`](docs/product/api.md) | API 说明文档 |
| [`docs/project-rule/`](docs/project-rule/) | 工程开发规范（commit / code-review / build / deploy / i18n / ui / logging / push-to-gitee） |
| [`AGENTS.md`](AGENTS.md) | AI 编码代理工程规范入口 |
| [`CHANGELOG.md`](CHANGELOG.md) | 变更日志（Keep a Changelog） |

## 📜 开源协议

[MIT License](./LICENSE) © 洛晨