# Shiguang

**Repository Path**: attacker/shiguang

## Basic Information

- **Project Name**: Shiguang
- **Description**: Shiguang
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拾光 · 个人效率工具

> 拾起时光 —— 解决"不分主次熬夜"问题：任务优先级 + 专注计时 + 每日计划 + 作息纪律 + 数据统计。

## 功能

| 模块 | 说明 |
|---|---|
| **今日看板** | 每日 Top 3 重点任务、时间线排程、昨日回顾、"现在做这一件"下一步建议 |
| **任务管理** | 四象限 / 列表 / **日历**三视图；P0-P3 优先级、截止日期、标签、预估番茄、状态流转；未排期任务一键排期、拖拽改期、`n` 键随时新建、过期任务强提醒 |
| **专注模式** | 番茄钟计时（专注/短休/长休循环），关联任务、会话恢复（刷新不丢）、历史记录 |
| **统计看板** | 专注趋势、任务完成、优先级分布、睡眠时长、专注热力图，支持 7/14/30 天窗口 |
| **作息纪律** | 工作截止倒计时、目标睡眠、收尾提醒、睡眠打卡、近 14 天睡眠趋势 |

深色/浅色双主题，SQLite 单文件存储。**内置多账号登录与数据隔离**（JWT + bcrypt）：`INIT_USER` 播种的账号为**管理员**（自动升级），可开放注册（可选邀请码），注册用户默认普通角色；管理员后台 `/admin` 查看运营指标并管理用户（禁用/重置密码/调整角色），登录带 IP 限流 + 账号锁定（连续失败 5 次锁 15 分钟）。

**数据安全**：任务/睡眠打卡备注以 AES-256-GCM 静态加密落库（密钥零配置持久化，防数据库文件泄露后裸读），密码 bcrypt，登录带 IP 限流 + 账号锁定。

**专注体验**：番茄钟教练档位（经典 25+5 / 深度 50+10 / 超长沉浸 120+15，一键切换）；锁屏沉浸倒计时（标签页标题实时倒数）；四种护眼壁纸动效（暮林萤火/深海波纹/极光/星空）+ 自定义图片；可选浏览器全屏与屏幕常亮（Wake Lock 防系统锁屏）。

**效率细节**：快捷睡眠打卡（按使用轨迹自动推断入睡/起床，一键确认）；键盘快捷键（`1-5` 切页、`/` 聚焦搜索、`?` 帮助）；四象限拖拽归类；昼夜双主题（中性石墨 / 暖纸白）；PWA 可安装（离线应用壳）+ 版本更新自动提示；可访问性（键盘焦点环 / 减少动效偏好）。

**管理后台**（admin 专属 `/admin`）：运营仪表盘（6 指标 + 近 14 天注册/日活趋势）、系统状态（版本/运行时长/库大小/开关）、用户管理（禁用/重置密码/角色调整、最近活跃、专注排序）——只看聚合指标，不窥用户私密内容。

## 技术栈

- 后端：Go + Gin + GORM + SQLite（`backend/`，CGO）
- 前端：React 19 + Vite + TypeScript + Tailwind + shadcn/ui + Recharts（`frontend/`）
- 交付：前端嵌入 Go 单二进制 `shiguang`，Docker 支持

## 快速开始

```bash
# 方式一：开发模式（后端 9020 + 前端 5190，热更新）
make install
make dev            # 或 ./run.sh start
# 前端 http://localhost:5190，/api 自动代理到后端

# 方式二：单二进制（生产，前端嵌入 Go 二进制）
./run.sh build      # 构建前端 + 嵌入编译 → ./shiguang
./run.sh serve      # 启动 http://localhost:9020

# 方式三：Docker
docker build -t shiguang .
docker run -d -p 9020:9020 -v shiguang-data:/data --name shiguang shiguang
```

首次启动自动建表并播种一周演示数据（任务/计划/专注/睡眠），可随时删除。

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `9020` | 监听端口 |
| `GIN_MODE` | `debug` | `release` 关闭调试日志 |
| `DATA_DIR` | `data` | 数据目录（相对 backend/） |
| `DB_PATH` | `$DATA_DIR/shiguang.sqlite3` | SQLite 文件路径 |
| `JWT_SECRET` | 自动生成 | token 密钥；默认读取/生成 `data/.jwt_secret`（重启不掉登录态） |
| `TOKEN_HOURS` | `72` | 登录有效期（小时） |
| `INIT_USER` | `logan` | 初始管理员账号（仅首次启动创建，始终为 admin 角色） |
| `INIT_PASSWORD` | 随机生成并打印 | 初始账号密码（仅首次启动创建） |
| `INVITE_CODE` | 空 | 注册邀请码；为空则注册无需邀请码 |
| `DATA_KEY` | 自动生成 | 敏感字段（任务/打卡备注）AES-256-GCM 加密密钥；默认读取/生成 `data/.data_key` |
| `SMS_API_KEY` | 空 | 云片 API Key；配置后开启短信验证码登录（未注册手机号自动注册） |
| `SMS_TEMPLATE_ID` | 空 | 云片短信模板 ID（内容含 #code# 变量） |

> 已有单用户旧库首次升级会自动迁移到多用户结构，并把存量数据归属给初始账号。

## 项目结构

```
shiguang/
├── backend/                 # Go 后端
│   ├── main.go / embed.go   # 入口 + 前端静态资源嵌入
│   ├── config/              # 配置加载
│   ├── database/            # SQLite 初始化 + 种子数据
│   ├── router/              # 路由集中注册
│   ├── middleware/          # CORS
│   ├── internal/
│   │   ├── model/           # GORM 模型
│   │   ├── dto/             # 请求/响应结构
│   │   ├── service/         # 业务逻辑
│   │   └── controller/      # HTTP 处理层
│   └── static/              # 构建时填充的前端产物（go:embed）
├── frontend/                # React 前端
│   └── src/
│       ├── api/             # 接口封装（按域）
│       ├── components/      # 布局 + shadcn/ui 组件
│       ├── hooks/           # useApi / useTheme
│       ├── lib/             # api 客户端 / 类型 / 格式化
│       ├── pages/           # Today / Tasks / Focus / Stats / Routine
│       └── sections/        # 页面子组件
├── docs/api.md              # API 契约
├── Makefile / run.sh        # 开发与部署脚本
└── Dockerfile
```

## API 概览

统一前缀 `/api`，响应格式 `{ code, message, data }`（`code=0` 成功）。完整契约见 [docs/api.md](docs/api.md)。

```
GET/POST /api/tasks    PATCH/DELETE /api/tasks/:id     任务 CRUD
GET/POST /api/plans    POST /api/plans/reorder         今日计划
POST /api/focus/start  POST /api/focus/:id/stop        专注会话
GET /api/focus/active  GET /api/focus/sessions         进行中/历史
GET/POST /api/sleep/checkins                          睡眠打卡（按日 upsert）
GET/PUT   /api/settings                                作息/番茄钟设置
GET       /api/stats/summary?days=7                    统计汇总
```

## 常用命令

```bash
./run.sh start|stop|restart|status   # 开发服务管理
./run.sh build && ./run.sh serve     # 单二进制构建与启动
make test                            # 全部测试（后端 go test + 前端 vitest）
make clean                           # 清理构建产物
```