# reality-glitch
**Repository Path**: rorop/reality-glitch
## Basic Information
- **Project Name**: reality-glitch
- **Description**: Reality Glitch（现实漏洞局）是一个面向 iOS、Android 与 Web 的低压力现实创作产品。产品通过每日观察任务，引导用户使用图片、短音频或文字重新注意真实世界，并在完成创作后进入同题展览，看见不同的人如何理解同一个题目。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-18
## Categories & Tags
**Categories**: Uncategorized
**Tags**: Android, IOS, React-native, expo
## README
---
Reality Glitch（现实漏洞局）是一个面向 iOS、Android 与 Web 的低压力现实创作产品。产品通过每日观察任务，引导用户使用图片、短音频或文字重新注意真实世界，并在完成创作后进入同题展览，看见不同的人如何理解同一个题目。
| 维度 | 项目概览 |
|---|---|
| 产品闭环 | 今日任务 → 三媒介创作 → 草稿与上传 → 审核 → 同题展览 → 创作档案 |
| 用户端 | Expo 57、React Native 0.86、Expo Router、HeroUI Native、Uniwind |
| 服务端 | Java 21、Spring Boot 4.1、Sa-Token、PostgreSQL、Redis、Reality OSS |
| 交付形态 | iOS、Android、Web、Reality API、运营管理前端 |
## 项目背景
### 为什么要做这个产品
移动互联网提供了近乎无限的内容，但用户越来越容易停留在被动浏览、快速反馈和重复推荐中。很多人有拍照、记录声音或写下片段的愿望，却经常遇到三个问题：不知道创作什么、担心作品不够专业、发布后只得到由热度和排名驱动的反馈。
现实漏洞局从这些问题出发，把创作拆解成每天五分钟内可以理解和完成的小任务。任务不是专业命题，也不是强制打卡，而是一种重新观察日常环境的提示。例如寻找一个“正在假装成另一种东西”的物品、描述一处影子的轮廓，或记录一段容易被忽略的声音。
产品希望完成一次方向转换：
```mermaid
flowchart LR
A["被动浏览内容"] --> B["收到一个明确的今日任务"]
B --> C["离开信息流，观察现实"]
C --> D["用图片、声音或文字表达"]
D --> E["看见同题作品的不同答案"]
E --> F["形成个人现实观察档案"]
classDef start fill:#EEF4F1,stroke:#1F746B,color:#15201C,stroke-width:1.5px;
classDef signal fill:#FFF2EE,stroke:#F36B4F,color:#15201C,stroke-width:1.5px;
class A,F start;
class B,C,D,E signal;
```
### 产品定位
现实漏洞局不是传统摄影社区、效率打卡工具或完整社交网络。它更接近一间每天发布观察任务、收录现实样本的轻型机构：
- 用明确限制降低“我不知道创作什么”的启动成本。
- 用图片、声音和短文字覆盖不同表达习惯。
- 用同题展览呈现差异，而不是用粉丝数或公开排名评价用户。
- 用本地草稿、可靠上传和审核状态保护创作过程。
- 用创作日历、周报和分享卡帮助用户回顾自己的观察轨迹。
### 目标用户
| 用户类型 | 典型问题 | 产品提供的价值 |
|---|---|---|
| 轻创作者 | 有表达欲，但缺少具体题目并担心作品不专业 | 可立即执行、没有专业门槛的每日任务 |
| 城市观察者 | 熟悉的生活路线逐渐失去新鲜感 | 重新注意声音、光线、物品和空间细节的理由 |
| 内容参与者 | 想参与有趣活动，但不愿制作复杂内容 | 五分钟内可完成、容易理解和分享的共同主题 |
| 创作习惯建立者 | 记录分散，难以持续或回顾 | 草稿恢复、创作日历、周报和个人档案 |
### 核心产品原则
1. **先行动，后消费**：首页优先展示今日任务，展览位于创作动作之后。
2. **限制产生创意**：每个任务只包含清晰动作、媒介和安全边界。
3. **低压力表达**：不使用粉丝排名、公开评分、自由评论和惩罚性连续签到。
4. **尊重现实边界**：不鼓励偷拍、危险地点探索或不必要的精确定位。
5. **允许不完美**：作品可以简单，但应来自用户真实完成的观察。
6. **创作过程可恢复**：普通断网、应用重启和上传失败不应导致内容丢失。
---
## 项目截图
以下截图均已再真机和模拟器验证通过。
### 产品入口与主题
 |
 |
 |
| 欢迎与新手任务 |
今日任务 · 浅色模式 |
今日任务 · 深色模式 |
### 账号与任务流程
 |
 |
 |
| 邮箱账号登录 |
运营账号今日任务 |
任务说明与安全边界 |
### 作品、展览与官方灵感
### 创作档案与账户设置
---
## 产品能力
| 能力域 | 主要能力 |
|---|---|
| 账号与任务 | 游客试用、邮箱注册/登录、会话恢复、当地日期任务、每日一次换题 |
| 三媒介创作 | 图片拍摄与压缩、短音频录制与试听、短文字输入与自动保存 |
| 草稿与上传 | Zustand 本地草稿、文件持久化、启动恢复、私有上传会话、进度和重试 |
| 发布与治理 | 幂等发布、自动/人工审核、公开派生媒体、举报、作品屏蔽和作者屏蔽 |
| 展览与档案 | 同题展览、预设回应、收藏、创作日历、作品档案、本周现实报告和分享 |
| 运营与体验 | 官方灵感、通知 Outbox、远程开关、埋点、Beta 反馈、Light/Dark 与无障碍基础 |
---
## 核心用户流程
```mermaid
flowchart TD
A["打开现实漏洞局"] --> B{"游客试用或邮箱登录"}
B -->|"游客"| C["查看任务示例与本机草稿"]
B -->|"登录"| D["领取当地日期的今日任务"]
C --> D
D --> E{"保留任务或使用一次换题"}
E -->|"保留"| F["阅读任务详情与安全边界"]
E -->|"换题"| G["服务端原子更换任务"]
G --> F
F --> H{"选择创作媒介"}
H -->|"图片"| I["拍摄 / 相册 / 压缩"]
H -->|"声音"| J["录音 / 暂停 / 试听"]
H -->|"文字"| K["输入 / 计数 / 自动保存"]
I --> L["本地草稿"]
J --> L
K --> L
L --> M["可恢复上传队列"]
M --> N["Reality 私有上传与幂等发布"]
N --> O{"安全审核结果"}
O -->|"通过"| P["生成公开派生内容"]
O -->|"等待复核"| Q["保持私有并展示处理中"]
O -->|"可编辑拒绝"| R["返回草稿修改"]
Q --> O
R --> L
P --> S["同题展览"]
S --> T["回应 / 收藏 / 举报 / 屏蔽"]
T --> U["创作档案 / 本周现实报告 / 分享"]
classDef action fill:#EEF4F1,stroke:#1F746B,color:#15201C,stroke-width:1.2px;
classDef decision fill:#FFF2EE,stroke:#F36B4F,color:#15201C,stroke-width:1.2px;
classDef trusted fill:#EEF6FB,stroke:#2C6E9A,color:#15201C,stroke-width:1.2px;
class B,E,H,O decision;
class N,P trusted;
class A,C,D,F,G,I,J,K,L,M,Q,R,S,T,U action;
```
未审核内容始终保持私有；网络失败、应用重启或上传超时不得导致草稿丢失或产生重复作品。
---
## 总体架构
```mermaid
flowchart TB
subgraph Client["用户端 · reality-app"]
Router["Expo Router"]
UI["HeroUI Native + Uniwind"]
Query["TanStack Query + Zod"]
Local["Zustand + AsyncStorage + FileSystem"]
Native["Camera + Audio + Notifications + SecureStore"]
Router --> UI
UI --> Query
Query --> Local
Local --> Native
end
Gateway["HTTPS · /app/v1"]
subgraph Reality["可信服务端 · reality"]
Auth["Reality Auth / Sa-Token"]
Service["Spring 事务应用服务"]
Data["MyBatis-Plus / PostgreSQL"]
Cache["Redis / Redisson"]
Contract["OpenAPI / Reality 响应 / 请求 ID"]
Auth --> Service
Contract --> Service
Service --> Data
Service --> Cache
end
subgraph Media["媒体与异步能力"]
Private["私有原始媒体"]
Moderation["自动审核 / 人工复核"]
Public["公开派生媒体"]
Push["通知 Outbox / Push"]
Private --> Moderation
Moderation -->|"审核通过"| Public
end
Query --> Gateway
Gateway --> Auth
Service --> Private
Service --> Push
Public --> Query
Push --> Native
classDef client fill:#EEF4F1,stroke:#1F746B,color:#15201C,stroke-width:1.2px;
classDef server fill:#EEF6FB,stroke:#2C6E9A,color:#15201C,stroke-width:1.2px;
classDef media fill:#FFF2EE,stroke:#F36B4F,color:#15201C,stroke-width:1.2px;
class Router,UI,Query,Local,Native client;
class Gateway,Auth,Service,Data,Cache,Contract server;
class Private,Moderation,Public,Push media;
```
### 架构原则
1. 页面保持轻量，业务规则集中在 `src/features/`。
2. TanStack Query 管理服务端状态，Zustand 只管理草稿、上传队列和本地偏好。
3. 所有 API 响应使用 Zod 进行运行时校验。
4. 用户归属、任务发放、作品发布、审核和公开状态由 Reality 服务端决定。
5. 原始媒体上传到私有 Bucket，审核通过后才生成公开派生资源。
---
## 多项目工作区
本仓库采用多项目工作区，而不是把移动端、服务端和管理端放入一个运行时工程。这样可以让三类交付物保持独立依赖、独立构建和清晰的安全边界，同时在同一仓库内共享接口约定、数据库迁移、CI 配置和品牌规范。
```text
demo/
├─ reality-app/ 用户使用的 Expo / React Native 应用
├─ reality/ 可信 Reality Java 服务与 reality-glitch 领域模块
├─ reality-admin/ 面向运营和管理人员的独立 Web 管理端
├─ .github/ CI 工作流与 README 截图资源
├─ .codex/ 项目级开发、质量和协作规则
└─ .agents/ HeroUI Native 等工程能力说明
```
### 工作区调用关系
```mermaid
flowchart LR
Repo["Reality Glitch Workspace"]
subgraph Products["产品交付工程"]
App["reality-app
iOS · Android · Web"]
Admin["reality-admin
运营与系统管理前端"]
end
Backend["reality
Reality Auth + Glitch Services"]
subgraph Infrastructure["可信数据与基础设施"]
PG["PostgreSQL"]
Redis["Redis / Redisson"]
OSS["Reality OSS"]
end
subgraph Shared["仓库共享能力"]
CI[".github
CI 与 README 资产"]
Rules[".codex / .agents
工程协作规则"]
end
Repo --> App
Repo --> Admin
Repo --> Backend
Repo --> CI
Repo --> Rules
Repo --> Records
App -->|"HTTPS · /app/v1"| Backend
Admin -->|"受权限控制的管理 API"| Backend
Backend --> PG
Backend --> Redis
Backend --> OSS
classDef product fill:#EEF4F1,stroke:#1F746B,color:#15201C,stroke-width:1.2px;
classDef backend fill:#EEF6FB,stroke:#2C6E9A,color:#15201C,stroke-width:1.2px;
classDef shared fill:#FFF2EE,stroke:#F36B4F,color:#15201C,stroke-width:1.2px;
class App,Admin product;
class Backend,PG,Redis,OSS backend;
class Repo,CI,Rules,Records shared;
```
移动端和管理端不会互相引用源码。两者通过不同的服务端 API 边界协作：移动端只调用 `/app/v1`，管理端使用受权限控制的系统管理接口。任务发放、资源归属、审核决定、公开状态和数据清理由 Reality 服务端统一负责。
### `reality-app/`：用户端应用
`reality-app` 是用户直接安装或访问的产品工程，使用 Expo Router 管理页面，使用 HeroUI Native 与 Uniwind 构建设计系统，并通过 TanStack Query、Zustand 和 Zod 管理远程状态、本地工作流与运行时数据校验。
主要职责：
- 欢迎、游客、邮箱账号和会话恢复。
- 今日任务、换题、任务详情和安全提示。
- 图片、短音频和文字创作。
- 本地草稿、上传队列和失败恢复。
- 作品审核状态、同题展览和互动。
- 创作档案、周报、通知、分享和官方灵感。
- Light/Dark 主题、字体缩放和无障碍语义。
客户端只保存完成交互所需的公开配置和本地状态。所有可信业务判断通过 Reality API 完成。
### `reality/`：可信后端与基础设施
`reality` 是 Java 21 / Spring Boot 4 模块化后端。工作区在既有 Reality 基础能力上增加 `reality-modules/reality-glitch` 领域模块，复用 Sa-Token、MyBatis-Plus、PostgreSQL、Redis/Redisson、Reality OSS、OpenAPI、日志和审计能力。
主要职责：
- 移动邮箱账号、会话和 Profile。
- 当地日期任务发放、一次换题和并发控制。
- 私有上传会话、幂等作品创建和状态机。
- 自动审核、人工复核和公开派生媒体。
- 展览、回应、收藏、举报和屏蔽。
- 档案、周报、通知 Outbox、远程配置和分析事件。
- 官方灵感内容、可靠排期和后台调度。
- 数据库迁移、环境部署、冒烟脚本和运维配置。
后端运行入口位于 `reality/reality-admin`，现实漏洞局业务代码集中在独立领域模块中，避免把移动产品规则散落到系统公共模块。
### `reality-admin/`：运营与管理前端
根目录的 `reality-admin` 是独立的 Vue 3、Vite、TypeScript、Pinia 和 Ant Design Vue 系管理端工程，使用 pnpm 管理依赖。它面向运营、审核和系统管理场景，不参与移动端 Bundle，也不能被移动端直接导入。
规划职责包括：
- 任务模板、内容排期和官方灵感管理。
- 待复核作品、举报、申诉和审核记录。
- 用户限制、内容下架和安全审计。
- 运营配置、通知和数据看板。
- Reality 系统配置与权限管理。
移动端功能不应通过修改管理端前端来实现；管理端操作也必须经过 Reality 权限与审计接口。
### 工程边界
| 事项 | 所属项目 |
|---|---|
| 页面、组件、设备能力、本地草稿 | `reality-app` |
| API、认证、事务、数据库、Redis、OSS | `reality` |
| 运营审核和系统管理界面 | `reality-admin` |
---
## 技术栈
### 客户端
| 分类 | 技术 |
|---|---|
| 基础框架 | Expo 57、React 19、React Native 0.86、TypeScript 6 |
| 路由 | Expo Router Typed Routes |
| UI | HeroUI Native、Uniwind、Tailwind CSS v4 |
| 服务端状态 | TanStack Query |
| 本地状态 | Zustand |
| 数据校验 | Zod |
| 原生能力 | Expo Camera、Image Picker、Image Manipulator、Audio、FileSystem |
| 会话与设备 | SecureStore、AsyncStorage、Notifications、Linking |
| 分享 | Expo Sharing、React Native View Shot |
| 动画与手势 | Reanimated、Gesture Handler、Worklets、Screens |
### 服务端
| 分类 | 技术 |
|---|---|
| 运行时 | Java 21、Spring Boot 4.1 |
| 认证 | Sa-Token、移动端 `clientid` |
| 数据访问 | MyBatis-Plus、PostgreSQL |
| 缓存与并发 | Redis、Redisson、数据库约束与事务 |
| 对象存储 | S3 Compatible Reality OSS / MinIO |
| 接口契约 | Reality `R` 响应信封、Springdoc OpenAPI |
| 可靠性 | 请求 ID、幂等键、Outbox、定时任务、审计日志 |
| 构建 | Maven Wrapper |
## 移动端模块
移动端入口位于 `reality-app/`，Expo Router 路由文件只负责页面组合，领域实现集中在 `reality-app/src/features/`。
| 模块 | 职责 |
|---|---|
| `auth` | 游客、注册、登录、会话恢复与认证边界 |
| `today` / `challenges` | 今日任务、领取、换题、详情与错误映射 |
| `capture` | 图片、声音、文字编辑和媒体准备 |
| `drafts` | 本地草稿索引、持久化和启动恢复 |
| `uploads` | 上传状态机、重试、取消、进度和恢复 |
| `submissions` | 发布预览、幂等发布、审核状态和作品详情 |
| `gallery` | 同题展览、多媒介作品卡和互动入口 |
| `archive` | 创作日历、作品与收藏归档 |
| `recaps` | 周报、代表作品、公共分享和分享卡 |
| `notifications` | 通知偏好、设备注册和深链 |
| `inspirations` | 官方灵感主题与编辑部回答 |
| `profile` / `beta` | 用户资料、设置和 Beta 反馈 |
公共 UI 包装位于 `reality-app/src/components/ui/`，根 Provider 位于 `reality-app/src/providers/`，Reality API Client、会话、埋点和通用工具位于 `reality-app/src/lib/`。
## Reality 后端
后端入口位于 `reality/`，现实漏洞局领域模块为：
```text
reality/reality-modules/reality-glitch/
└─ src/main/java/com/xscha/reality/glitch/
├─ controller/app/ # /app/v1 移动端接口
├─ domain/ # Entity、BO、VO
├─ mapper/ # MyBatis-Plus Mapper
├─ service/ # 领域服务接口
├─ service/impl/ # 事务应用服务
├─ job/ # 清理、通知、灵感等调度任务
├─ event/ # 领域事件与异步协作
└─ config/ # 领域配置
```
移动端 Controller 覆盖认证、Profile、任务、上传、作品、展览、互动、档案、周报、通知、官方灵感、配置和 Beta 反馈。所有用户资源必须经过登录上下文、`clientid`、Service 层归属检查、事务和数据库约束保护。
数据库迁移位于 `reality/script/sql/postgres/`，当前包含核心表、工作流、账号资料、任务、上传、作品/展览、档案/周报、可靠性优化、文案、官方灵感和正式运行数据脚本。执行迁移前必须先备份并确认目标环境。
---
## 环境要求
### 通用
- Git。
- Node.js：Expo 57 支持的 Node 20.19.4、22.13.0、24.3.0 或更高兼容版本。
- npm：仓库使用 `package-lock.json`。
- Java 21：Reality 后端构建与测试。
- PostgreSQL、Redis 和 S3 Compatible OSS：运行完整后端时需要。
### Android
- Android Studio / Android SDK。
- Compile SDK 36、Target SDK 36、Build Tools 36.0.0。
- Android 模拟器或物理设备。
### iOS
- macOS、Xcode 和受支持的 iOS SDK。
- Windows/Linux 只能执行 iOS JavaScript Bundle 导出，不能完成本地原生构建。
## 快速启动移动端
```powershell
cd reality-app
npm ci
Copy-Item .env.example .env.local
npm start
```
`.env.local` 仅填写公开配置：
```dotenv
EXPO_PUBLIC_REALITY_API_URL=https://api.example.com
EXPO_PUBLIC_REALITY_CLIENT_ID=reality-glitch-mobile
EXPO_PUBLIC_SHARE_BASE_URL=https://example.com
EXPO_PUBLIC_APP_ENVIRONMENT=development
```
常用启动命令：
```powershell
npm start # Expo Go
npm run start:clear # 清理 Metro 缓存后启动
npm run start:dev-client # Development Build
npm run android # 生成/运行 Android 原生项目
npm run ios # macOS 上生成/运行 iOS 原生项目
npm run web # Web 开发服务器
```
相机、录音、通知、系统分享、后台中断和文件系统行为必须使用 Development Build 或真实设备验证，Expo Go 和模拟器不能代替完整原生验收。
## 客户端验证与构建
```powershell
cd reality-app
npm run typecheck
npm run lint
npm run test:unit
npm run verify
```
`npm run verify` 依次执行 TypeScript、ESLint、Node 单元测试和 Expo Doctor。
导出三端 Bundle：
```powershell
npm run export:web
npm run export:android
npm run export:ios
```
本地 Android Release：
```powershell
$env:NODE_ENV = 'production'
npx expo run:android --variant release
```
EAS Profile：
- `development`：Development Client，内部使用。
- `preview`：内部安装 APK。
- `production`：Google Play AAB，自动递增版本号。
正式发布前必须配置 EAS Project、Upload Key、Play App Signing、正式域名、推送凭据、Data Safety、隐私政策和 Google Play 测试轨道。
## CI
根目录 `.github/workflows/ci.yml` 在 Pull Request 和 `main` 分支推送时执行：
1. Node 24 环境初始化。
2. `npm ci` 安装锁定依赖。
3. `npm run verify`。
4. Web 静态导出冒烟。
后端 Maven 测试、数据库迁移检查、真实 API 冒烟和原生设备测试仍需在对应开发/发布流程中执行。
---
## License
Copyright © 2026 [xscha.com](https://xscha.com). All rights reserved.
本项目基于 [Apache License 2.0](./LICENSE) 授权发布，版权与归属声明见 [NOTICE](./NOTICE)。项目使用的第三方库、框架和资源继续遵循其各自许可证。 
