feat: 补充二步验证、标签管理、角色与权限文档

docs/development-guide.md

@@ -0,0 +1,189 @@
+---
+title: 开发指南
+description: Ikaros 本地开发环境搭建、编译打包和代码规范。
+---
+
+## 环境要求
+
+| 工具 | 版本 |
+|------|------|
+| JDK | 21 |
+| Gradle | 8.14.5（使用项目自带 wrapper） |
+| SpringBoot | 4.0.1 |
+| CheckStyle | 9.3 |
+| Node.js | 18+（编译前端需要） |
+| Vue | 3 |
+| Database | PostgreSQL 18+ |
+| IDE | IntelliJ IDEA（推荐） |
+| Docker | 本地开发建议安装（用于测试容器） |
+
+## 获取代码
+
+```shell
+git clone https://github.com/ikaros-dev/ikaros.git --recursive
+cd ikaros
+```
+
+> ⚠️ `--recursive` 是必须的，主题使用 git submodule 管理。如果已经 clone 但没加该参数，执行以下命令初始化：
+>
+> ```shell
+> git submodule init
+> git submodule update
+> ```
+
+`--recursive` 是必须的，主题使用 git submodule 管理。如果已经 clone 但没加该参数，执行以下命令：
+
+```shell
+git submodule init
+git submodule update
+```
+
+## 本地开发数据库
+
+推荐使用 Docker 启动 PostgreSQL 18：
+
+```shell
+docker run -d \
+  --name ikarosdb_dev \
+  -p 5432:5432 \
+  -e POSTGRES_DB=ikaros \
+  -e POSTGRES_USER=ikaros \
+  -e POSTGRES_PASSWORD=openpostgresql \
+  postgres:18.3-alpine
+```
+
+也可以直接在本地安装 PostgreSQL 18，下载地址：[EnterpriseDB PostgreSQL Downloads](https://www.enterprisedb.com/downloads/postgres-postgresql-downloads)
+
+安装后通过 psql 创建用户和数据库：
+
+```shell
+psql -U postgres -c "CREATE USER ikaros WITH PASSWORD 'openpostgresql';"
+psql -U postgres -c "CREATE DATABASE ikaros OWNER ikaros;"
+psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE ikaros TO ikaros;"
+```
+
+## 配置本地配置文件
+
+复制配置文件模板：
+
+```shell
+cp config/server/resource/application-local.yaml.example \
+  src/main/resources/application-local.yaml
+```
+
+根据本地环境修改 `application-local.yaml` 中的数据库连接等配置。
+
+## 编译
+
+> 执行 gradle 任务前，默认会走一遍单元测试，如需跳过，加上 `-x test` 即可。
+
+### 全量编译（含测试）
+
+```shell
+# Linux / Mac
+./gradlew clean build
+
+# Windows
+./gradlew.bat clean build
+```
+
+### 跳过测试编译
+
+```shell
+# Linux / Mac
+./gradlew clean build -x test
+
+# Windows
+./gradlew.bat clean build -x test
+```
+
+### 编译打包（生产用 Fast Jar）
+
+```shell
+# Linux / Mac
+./gradlew clean bootJar -x test
+
+# Windows
+./gradlew.bat clean bootJar -x test
+```
+
+打包后的文件在 `server/build/libs/ikaros-server.jar`。
+
+### 编译 Console 前端
+
+```shell
+./gradlew buildFrontend -x test
+```
+
+## 本地运行
+
+### IDEA 运行配置
+
+1. 打开 `run.ikaros.server.IkarosApplication` 运行配置
+2. **Active profiles** 设置为：`dev,local`
+3. 社区版 IDEA 在 VM options 中添加：`-Dspring.profiles.active=dev,local`
+
+运行后访问：
+- 控制台: `http://localhost:9999/console`
+- 默认账号: `tomoki` / 密码: `tomoki`
+
+### 命令行运行
+
+```shell
+java -jar server/build/libs/ikaros-server.jar \
+  --spring.profiles.active=dev,local
+```
+
+## 代码规范
+
+Ikaros 使用 Google Java Style（CheckStyle 9.3）作为代码规范标准。
+
+### IDEA 配置 CheckStyle
+
+1. 安装插件：`CheckStyle-IDEA`
+2. 打开 `Setting` → `Tools` → `Checkstyle`
+3. **Checkstyle version** 选择 `9.3`
+4. **扫描范围** 勾选包括测试代码
+5. **Configuration file** 选择项目下的 `config/checkstyle/checkstyle.xml`
+6. 添加变量值：
+
+   ```text
+   checkstyle-suppressions.xml
+   checkstyle-xpath-suppressions.xml
+   ```
+
+### IDEA 代码格式化
+
+1. 打开 `Setting` → `Editor` → `Code Style` → `Java`
+2. `Scheme` 选择 `Project`
+3. 点击右边齿轮 → `Import Scheme` → `Checkstyle configuration`
+4. 选择 `config/checkstyle/checkstyle.xml`
+5. 保存
+
+> 提交代码前务必用 CheckStyle 检查，**CI 会拦截未通过 CheckStyle 检查的 PR**。
+
+## 提交代码
+
+```shell
+git add .
+git commit -s -m "feat: 我的修改内容"
+```
+
+> Commit 需加 `-s`（Signed-off-by），参考 [DCO](https://developercertificate.org/)。
+
+## 项目模块结构
+
+| 模块 | 说明 |
+|------|------|
+| `api/` | 公共 API 和模型定义 |
+| `server/` | 服务端核心代码 |
+| `console/` | 前端控制台（Vue 3） |
+| `config/` | CheckStyle 配置等 |
+
+## 生成 API 文档
+
+项目启动后可通过 Swagger UI 查看 API 文档：
+
+```
+http://localhost:9999/swagger-ui.html
+```