# yao-note

**Repository Path**: yao-coder/yao-note

## Basic Information

- **Project Name**: yao-note
- **Description**: Yao Note 是一款“个人工作记录与待办便签”，附带多空间隔离、周期汇总、文档导出和团队管理员只读查看能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YaoNote

个人与团队工作记录 Web 应用。响应式 React SPA + Spring Boot 模块化单体。

## 仓库结构

```text
yao-note/
├─ frontend/            React 19 + TypeScript + Vite SPA
├─ backend/             Spring Boot 3.5 模块化单体（API 与 Worker 同制品）
│  └─ database/
│     └─ init.sql       唯一、完整的空库初始化 DDL（44 张表）
└─ docs/
   ├─ PRD.md                          产品需求文档
   ├─ architecture/                   整体架构设计（含 ADR-001..021）
   ├─ overview-design/                概要设计
   ├─ detailed-design/                详细设计（六卷）
   └─ design-concepts/                视觉稿与四套皮肤资产
```

文档链的优先级为 **PRD → 整体架构 → 概要设计 → 详细设计 → 实现**。发现上游缺口
必须回补对应文档，不由代码自行选择。详见 [详细设计索引](docs/detailed-design/README.md)。

**接手开发前先读 [开发交接说明](docs/HANDOFF.md)** —— 它记录当前真实进度、已知临时状态
与已经踩过的坑，比从头翻设计文档快得多。

## 环境要求

| 组件 | 版本 | 说明 |
| --- | --- | --- |
| JDK | 21 LTS | `JAVA_HOME` 必须指向 21，Maven 只认这个变量 |
| Maven | 3.8+ | 仓库镜像已在 `backend/pom.xml` 中配置，不需改全局 settings.xml |
| Node.js | 24 LTS | 偶数版号才是 LTS |
| pnpm | 11+ | 提交 `pnpm-lock.yaml` |
| MySQL | 9.6.x | 见 [ADR-020](docs/architecture/OVERALL-ARCHITECTURE-DESIGN.md#27.3) |
| Redis | 7.2 | 会话加速、限流；不保存业务事实 |

**不需要 Docker**——集成测试打预置 MySQL 上的专用测试库（[ADR-021](docs/architecture/OVERALL-ARCHITECTURE-DESIGN.md#27.3)）。

## 快速开始

### 数据库

`init.sql` 只用于**空库初始化**，不可对已有库重复执行：

```bash
mysql -u root -p -e "CREATE DATABASE yaonote CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_as_cs"
```

```bash
mysql -u root -p yaonote < backend/database/init.sql
```

### 后端

连接凭据只来自环境变量，**绝不写入仓库任何文件**：

```bash
export YAONOTE_DB_URL="jdbc:mysql://127.0.0.1:3306/yaonote?serverTimezone=UTC&connectionTimeZone=UTC"
export YAONOTE_DB_USER="yaonote_app"
export YAONOTE_DB_PASSWORD="<你的密码>"
```

```bash
cd backend && ./mvnw spring-boot:run
```

### 前端

```bash
cd frontend && pnpm install && pnpm dev
```

开发服务器把 `/api` 与 `/downloads` 代理到 `127.0.0.1:8080`，使 Cookie 的
`SameSite=Lax` 与 `__Host-` 前缀行为与生产同源部署一致。

## 测试

单元测试与架构规则不需要数据库：

```bash
cd backend && ./mvnw test
```

集成测试需要 MySQL。测试库名**必须**匹配 `^yaonote_test_[a-z0-9_]+$`——
`TestDatabase.assertDroppable` 会在 `DROP DATABASE` 前强制校验，防止误删业务库：

```bash
export YAONOTE_TEST_DB_URL="jdbc:mysql://127.0.0.1:3306/yaonote_test_main?serverTimezone=UTC&connectionTimeZone=UTC"
export YAONOTE_TEST_DB_USER="root"
export YAONOTE_TEST_DB_PASSWORD="<你的密码>"
```

```bash
cd backend && ./mvnw verify
```

前端：

```bash
cd frontend && pnpm test && pnpm typecheck && pnpm build
```

## 当前状态

已完成：

- 完整文档链（PRD / 整体架构 / 概要设计 / 详细设计六卷）
- `init.sql` 44 张表，已在真实 MySQL 上通过空库验证
- 后端骨架：包结构、ArchUnit 模块边界规则、Snowflake ID、时钟抽象、文本规范化
- 前端骨架：路由树、倒计时推导、设计令牌、构建与测试链路

尚未开始：

- 业务模块实现（identity / workspace / worklog / todo / summary / export / growth / notification / lifecycle / audit）
- OpenAPI 契约冻结与前端客户端生成
- 七项前置 POC（中文搜索、DOCX/PDF 渲染、WORM 墓碑、自动保存、响应式/Dock、高级交互、团队删除）

七项 POC 是**开发前置条件**，详见[卷 05 §13.1](docs/detailed-design/05-TEST.md)。在它们通过之前，
相关设计章节属于「按预期路线编写的基线」，而非已验证结论。