# arrowlist

**Repository Path**: Yogile/arrowlist

## Basic Information

- **Project Name**: arrowlist
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <br>
  <img src="docs/assets/logo/ic_launcher.png" alt="ArrowList" width="128">
  <br>
  <h1>ArrowList 箭簿</h1>
  <p>射箭训练辅助工具</p>
  <br>
  <a href='https://gitee.com/Yogile/arrowlist/stargazers'><img src='https://gitee.com/Yogile/arrowlist/badge/star.svg?theme=white' alt='Gitee stars' /></a>
  <a href='https://gitee.com/Yogile/arrowlist/members'><img src='https://gitee.com/Yogile/arrowlist/badge/fork.svg?theme=white' alt='Gitee forks' /></a>
  <br>
  <img alt="License" src="https://img.shields.io/badge/License-AGPLv3-green.svg">
  <a href='https://flutter.dev'><img alt="Flutter" src="https://img.shields.io/badge/Flutter-3.22+-02569B.svg"></a>
  <a href='https://go.dev'><img alt="Go" src="https://img.shields.io/badge/Go-1.22+-00ADD8.svg"></a>
</div>

---

## 项目简介

ArrowList（箭簿）是一款面向射箭爱好者的训练辅助工具，采用 Flutter 跨平台客户端 + Go 后端架构，支持完全离线使用，也可搭配后端服务实现云端数据同步。

## 功能特性

| 模块 | 功能说明 |
|------|----------|
| **射箭记分** | 键盘输入模式（4×3 数字键盘）+ 靶面落点模式（触摸靶面自动识别环数），支持标准/竞赛计分 |
| **射箭计数器** | 5 位翻牌器样式、点击计数、滑动清零、历史记录 |
| **计时器** | 练习模式（正计时）/ 比赛模式（倒计时）/ 通用模式，预警提示音 |
| **控弓训练** | 多组计划配置、语音播报提示（准备/保持/休息）、训练记录追踪 |
| **数据统计** | 趋势折线图、靶面散点图、环数分布、数据导出/分享 |
| **用户体系** | 匿名本地使用 + 可选注册登录 + 云端数据同步 |

## 技术栈

- **前端**：Flutter 3.22+ / Dart 3.4+（Riverpod 状态管理、GoRouter 路由、sqflite 本地数据库）
- **后端**：Go 1.22+（Gin Web 框架、SQLite 数据库、JWT 认证）
- **数据库**：SQLite（前后端统一）

## 截图展示

### 前端 APP

<img src="./docs/assets/README/截图展示-前端.png" alt="截图展示-前端" style="zoom:50%;" />

### 后端服务

<img src="./docs/assets/README/截图展示-后端.png" alt="截图展示-后端" style="zoom:50%;" />

## 下载与安装

### 前端 APP

#### 发布地址

发布于 Gitee 项目仓库（ [Yogile/arrowlist-server](https://gitee.com/Yogile/arrowlist-server)）：[Releases - arrowlist-server](https://gitee.com/Yogile/arrowlist-server/releases) 。

1. Android 设备直接安装 APK 。
2. 首次使用无需登录，所有功能本地可用 。
3. 如需云同步，在设置中配置后端服务器地址后注册/登录 。

### 后端服务

#### 发布地址

发布于 Gitee 项目仓库（ [Yogile/arrowlist-app](https://gitee.com/Yogile/arrowlist-app)）：[Releases - arrowlist-app](https://gitee.com/Yogile/arrowlist-app/releases) 。

- 使用详见：[后端管理系统使用指南](docs/admin-guide.md)。 

#### 预编译文件（Windows / Linux）

预编译文件下载：[Releases - arrowlist-server](https://gitee.com/Yogile/arrowlist-server/releases) 。

#### Docker（Docker Compose）

镜像可选：

- Docker Hub：`yogile/arrowlist-server:latest`
- 阿里云镜像：`crpi-f09joc9dynkt3kyp.cn-beijing.personal.cr.aliyuncs.com/yogile/arrowlist-server:latest`

```yaml
services:
  arrowlist-server:
    container_name: arrowlist-server
    image: yogile/arrowlist-server:latest
    ports:
      - "8080:8080"
    volumes:
      - ./arrow-data:/app/data
      - ./configs:/app/configs
    environment:
      - ARROW_SERVER_PORT=8080 # 容器内部服务端口
      - ARROW_SERVER_MODE=release
      - ARROW_DB_PATH=/app/data/arrow.db
      - ARROW_JWT_SECRET=${JWT_SECRET:-change-me-in-production}
      - TZ=Asia/Shanghai
    restart: unless-stopped
    # 可选健康检测
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/api/v1/health"]
      interval: 30s
      timeout: 5s
      retries: 3
```

注意：

- 尽可能保持容器映射端口内外保持一致。

- 变量 `ARROW_SERVER_PORT` 为容器内部服务端口，将作为后端服务“概览”页面中“公网访问地址”显示依据，以及邮件验证链接中指向的验证地址。若要修改，请一并修改容器映射内部地址。

  示例：

  ```yaml
  services:
    arrowlist-server:
      container_name: arrowlist-server
      image: arrowlist-server:latest
      ports:
        - "9090:8081"
      volumes:
        - ./arrow-data:/app/data
        - ./configs:/app/configs
      environment:
        - ARROW_SERVER_PORT=8081 # 容器内部服务端口
        - ARROW_SERVER_MODE=release
        - ARROW_DB_PATH=/app/data/arrow.db
        - ARROW_JWT_SECRET=${JWT_SECRET:-14cce21e74b2cdc31fb75}
        - TZ=Asia/Shanghai
      restart: unless-stopped
  ```

  > 此时，外部通过 `http://example.com:9090/` 可访问，但后端服务“概览”页面中“公网访问地址”显示 `http://100.0.0.1:8081/admin` ，且发送邮件中也为 `http://100.0.0.1:8081` （除非在邮件功能中指定）。

- 变量 `ARROW_JWT_SECRET` ：

  `${JWT_SECRET:-14cce21e74b2cdc31fb75}` 后面`14cce21e74b2cdc31fb75`之前的 `-` （短横线）不可省略。

#### 源码运行

1. 克隆项目源码：
```bash
git clone https://gitee.com/Yogile/arrowlist.git
cd arrowlist
```

2. 运行后端服务：
```bash
cd backend
go mod download
go run ./cmd/arrowlist
```

3. 运行前端应用：
```bash
cd frontend
flutter pub get
flutter run
```

> **环境要求**：
> - Flutter 3.22+ / Dart 3.4+
> - Go 1.22+
> - Android Studio / Xcode（移动端开发）
> 
> 详细开发环境搭建请参阅 [开发指南](docs/development-guide.md)
## 快速开始

开发环境搭建与项目运行请参阅 [开发指南](docs/development-guide.md)。

```bash
# 前端
cd frontend
flutter pub get
flutter run

# 后端
cd backend
go mod download
go run ./cmd/arrowlist
```

## 项目结构

```
ArrowList/
├── frontend/           # Flutter 前端应用
│   ├── lib/
│   │   ├── app/        # 应用配置、主题、路由
│   │   ├── core/       # 核心模块（网络、认证、同步、数据库）
│   │   ├── features/   # 功能模块（记分、计数、计时、训练、统计、设置）
│   │   ├── shared/     # 共享组件
│   │   └── main.dart
│   └── pubspec.yaml
├── backend/            # Go 后端服务
│   ├── cmd/arrowlist/  # 程序入口
│   ├── internal/       # 内部模块（handler/service/repository/model/middleware/router）
│   ├── configs/        # 配置文件
│   ├── migrations/     # 数据库迁移
│   └── web/            # Web 管理系统（模板+静态资源）
├── docs/               # 文档
└── README.md
```

## 相关文档

- [开发指南](docs/development-guide.md)
- [开发路线图](docs/development-roadmap.md)
- [前端 APP 使用指南](docs/app-guide.md)
- [后端管理系统使用指南](docs/admin-guide.md)
- [构建发布指南](docs/build-guide.md)
  - [Docker 构建发布指南](docs/docker-guide.md)
- [构建备份与恢复指南](docs/backup-guide.md)
- [API 接口文档](docs/api-reference.md)
- [用户协议](docs/terms-of-service.md)
- [隐私政策](docs/privacy-policy.md)
- [版本发布说明模板](docs/release-notes-template.md)

## 许可证

本项目基于 [AGPLv3 License](LICENSE) 开源。

## 免责声明

- **使用免责**：本软件按"原样"提供，不提供任何明示或暗示的担保。在任何情况下，作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责。
- **数据隐私**：用户数据仅存储在用户设备或其自行部署的服务端，开发者不收集任何用户数据。