# 语初

**Repository Path**: fexcode/yuchu

## Basic Information

- **Project Name**: 语初
- **Description**: sxnote.top
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 随心一记 (suixinyiji)

全栈笔记应用。后端基于 Django REST Framework，前端基于 Flutter，支持 Web / Android / Windows 多平台。

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.12+, Django 6.0.3, Django REST Framework 3.17 |
| 数据库 | SQLite（默认）/ PostgreSQL / MySQL |
| 前端 | Flutter 3.11+（`flapp/` 目录），支持 Web / Android / Windows |
| 包管理 | [uv](https://docs.astral.sh/uv/) — 仅用 `uv`，禁止使用 pip 或 python -m |
| 认证 | TokenAuthentication（无 SessionAuth、BasicAuth） |
| 缓存 | DatabaseCache（用于限流） |

---

## 目录结构

| 目录 / 文件 | 用途 |
|-------------|------|
| `Sxyj/` | Django 项目配置（settings, urls, middleware, admin） |
| `accounts/` | 认证应用：登录、注册、登出、个人资料、签到、密码重置、邮箱验证 |
| `notes/` | 核心应用：笔记 CRUD、标签、图片、反馈、版本管理、AI 服务、访问日志 |
| `flapp/` | Flutter 前端源码 |
| `WebSite/` | 静态营销页面（HTML + Tailwind） |
| `web_deploy/` | Flutter Web 构建输出，通过 `/web/` 提供 |
| `docs/` | 项目文档（API 文档、重构计划等） |
| `scripts/` | PowerShell 运维脚本 |
| `templates/` | Django admin 模板 |
| `static/` | 收集的静态文件 |
| `staticfiles/` | 生产环境静态文件 |
| `media/` | 用户上传文件（图片等） |
| `ops.sh` | Linux 运维脚本（开发 / 生产） |
| `main.ps1` | Windows 项目管理入口脚本 |
| `build.ps1` | Flutter 构建入口（重定向到 `scripts/build.ps1`） |
| `pyproject.toml` | Python 项目配置与依赖声明 |

---

## 后端开发

### 环境准备

```bash
# 同步依赖（首次使用）
uv sync

# 数据库迁移
uv run python manage.py makemigrations
uv run python manage.py migrate

# 创建缓存表（限流所需）
uv run python manage.py createcachetable

# 启动开发服务器（后台，0.0.0.0:8000）
# Linux:
./ops.sh start
# Windows:
.\main.ps1 dev-start
# 或直接启动:
uv run python manage.py runserver 0.0.0.0:8000
```

### 常用命令

```bash
# 代码格式化
uv run black .

# 类型检查
uv run pyright

# 创建超级用户
./ops.sh createsuperuser        # Linux
# Windows: uv run python manage.py createsuperuser

# 生成 .env 模板
./ops.sh gen-env                # Linux
.\main.ps1 gen-env              # Windows

# 查看日志
./ops.sh log 50 prod            # Linux
.\main.ps1 log 50 prod          # Windows

# 数据库备份
./ops.sh backup                 # Linux
.\main.ps1 backup               # Windows
```

### 环境变量

生产环境（`DEBUG=False`）需要配置以下环境变量，可通过 `.env` 文件加载：

| 变量 | 说明 |
|------|------|
| `DJANGO_SECRET_KEY` | **必需** — Django 密钥 |
| `DB_ENGINE` | 数据库引擎：`sqlite3`（默认）、`postgresql`、`mysql` |
| `CORS_ALLOWED_ORIGINS` | 逗号分隔的允许跨域域名 |
| `EMAIL_HOST_USER` / `QQSMTP` | 邮箱验证服务 |
| `IMAGE_URL_SECRET` | 图片签名密钥（生产环境必须与 SECRET_KEY 不同） |
| `GUNICORN_WORKERS` | 生产 Worker 数（默认 3） |
| `AFDIAN_USER_ID` / `AFDIAN_API_TOKEN` | 爱发电充值功能 |

---

## 前端开发

```bash
# Flutter 构建
# Windows — Web 构建（生产模式，默认）
.\build.ps1 web

# Windows — Web 构建（开发模式，编译更快）
.\build.ps1 web -m dev

# Windows — APK 构建
.\build.ps1 apk

# Windows — 全部目标
.\build.ps1 all

# Linux
bash build.sh
```

构建输出位于 `web_deploy/`（Web）和 `flapp/build/`（APK），Web 构建后会自动提交到 `web_deploy/` 目录。

版本号管理：每次构建前更新 `flapp/pubspec.yaml` 中的三级版本号和构建号（如 `0.16.1+192`）。

---

## 测试

使用 Django 内置测试运行器（未安装 pytest）。

```bash
# 运行全部测试
uv run python manage.py test

# 运行单个应用测试
uv run python manage.py test accounts
uv run python manage.py test notes

# 运行单个测试方法
uv run python manage.py test accounts.tests.SomeTestCase.test_method
```

**注意**：Token 相关视图的测试中，需要在 `setUp()` 中创建 `ParamConfig.objects.create(pk=1)`。

日常开发只运行受影响应用的测试即可；全量测试仅在大规模重构或发布前运行。

---

## 部署

```bash
# Linux — 完整部署
./ops.sh deploy

# Windows — 完整部署
.\main.ps1 deploy

# 快速重启（git pull + 迁移 + 重启）
bash restart.sh
```

### 部署步骤

1. **提交代码**：`git add . && git commit -m "type: 描述" && git push`
2. **如修改了前端**：更新版本号后执行 `.\build.ps1 web`
3. **登录服务器重启**：`ssh www@sxnote.top "cd ~/yuchu && bash restart.sh"`
4. **如构建 APK**：重命名并上传到 `media/apks/`，然后在数据库中创建 `AppVersion` 记录
   - APK 命名格式：`v{version}_{build_number}.apk`（如 `v0.17.4_192.apk`）

---

## 文档索引

| 文档 | 路径 | 说明 |
|------|------|------|
| API 接口文档 | [`docs/api.md`](docs/api.md) | API 端点、请求/响应格式 |
| 后端重构计划 (P0–P2) | [`docs/refactor-plan-p0-p2.md`](docs/refactor-plan-p0-p2.md) | 当前后端重构的分阶段执行计划 |
| AI 服务配置 PRD | [`docs/PRD_AI_Service_Config.md`](docs/PRD_AI_Service_Config.md) | AI 服务可配置化方案产品需求 |
| Flutter 前端说明 | [`flapp/README.md`](flapp/README.md) | Flutter 项目起步说明 |

---

## 架构要点

- **软删除**：笔记使用 `is_deleted` + `deleted_at` 实现软删除，默认 queryset 过滤已删除记录
- **令牌经济**：用户通过每日签到和创建笔记赚取令牌，消耗于图片上传、超额字符和 AI 聊天
- **图片保护**：HMAC-SHA256 签名 URL，24 小时过期
- **限流**：每个作用域独立的 throttle 类，scope 命名统一管理
- **中间件栈**（按顺序）：CORS → Security → Session → Common → CSRF → Auth → Message → XFrame → Visit → Anti-Malicious → RequestLogging

---

## 开发规范

- 遵循原子提交原则：每个提交只做一件事
- 提交信息格式：`<type>(<scope>): <描述>`，如 `feat(notes): 添加笔记归档功能`
- 常用 type：`feat`、`fix`、`refactor`、`test`、`docs`、`chore`
- 修改完成后立即提交，禁止累积修改
- 包管理仅使用 `uv`，不使用 pip 或 python -m