chore: establish development baseline

2026-07-22 04:06:44 +08:00 · 2026-06-28 01:27:09 +08:00
commit dd53e3054e
131 changed files with 19327 additions and 0 deletions
@@ -0,0 +1,98 @@
+# 稳定工程基线指南
+
+**更新时间**：2026-06-28  
+**目标**：让工作区处于可继续开发核心功能的可信状态。
+
+---
+
+## 1. 基线定义
+
+当前阶段的稳定基线不是完整产品完成，而是满足以下条件：
+
+1. Git 仓库可用，`git status --short --branch` 能正常执行。
+2. 根目录只保留入口文档和工程配置。
+3. 旧报告归档，且不再和当前状态混淆。
+4. Rust workspace 成员显式列出。
+5. Go 尚未实现时，Makefile 不误报失败。
+6. 当前缺口有集中清单和关闭顺序。
+7. 架构边界有 ADR 记录。
+8. 基础验证命令通过。
+
+---
+
+## 2. 当前验证命令
+
+必须通过：
+
+```bash
+make test
+make check
+make lint
+```
+
+等价底层命令：
+
+```bash
+cargo test --workspace
+cargo check --workspace
+cargo clippy --workspace -- -D warnings
+```
+
+说明：
+
+1. 当前没有 Go package，因此 Go build/test/check/fmt/lint 会明确跳过。
+2. 如果后续新增 Go package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
+3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入 CI。
+
+---
+
+## 3. Git 基线
+
+当前工作区原 `.git/` 是空目录，无法恢复原历史。本基线采用新初始化仓库，并以首次提交作为后续开发起点。
+
+首次提交信息：
+
+```text
+chore: establish development baseline
+```
+
+提交前检查：
+
+```bash
+git status --short --branch
+git check-ignore -v Cargo.lock CLAUDE.md
+```
+
+`Cargo.lock` 和 `CLAUDE.md` 必须纳入版本控制。
+
+---
+
+## 4. 不纳入基线的内容
+
+以下内容应继续忽略：
+
+1. `target/`
+2. `.env`
+3. `*.db`
+4. `*.sqlite`
+5. `logs/`
+6. `node_modules/`
+7. 构建压缩包
+8. 本地 CAS 数据目录
+
+---
+
+## 5. 下一阶段入口
+
+基线建立后，下一阶段只推进两件事：
+
+1. 冻结核心接口。
+2. 完成 CAS V1。
+
+优先阅读：
+
+1. `PROJECT_PLAN.md`
+2. `CURRENT_STATUS.md`
+3. `docs/reports/CURRENT_GAPS.md`
+4. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
+5. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
@@ -0,0 +1,175 @@
+# 部署指南
+
+## 架构概览
+
+BlueArchive Toolkit 支持多种部署模式：
+
+1. **本地开发模式**：代码在本地，连接远程数据库
+2. **单机部署**：所有组件运行在一台服务器
+3. **分布式部署**：多实例 API Server + 独立数据库服务器
+
+---
+
+## 模式 1：本地开发 + 远程数据库
+
+适用场景：本地开发，数据库部署在有公网 IP 的远程服务器
+
+### 步骤
+
+#### 1. 在远程服务器上部署数据库
+
+```bash
+# SSH 登录到服务器
+ssh user@your.server.com
+
+# 创建部署目录
+mkdir -p ~/bat/deployments
+cd ~/bat/deployments
+
+# 上传配置文件（在本地执行）
+scp -r deployments/* user@your.server.com:~/bat/deployments/
+
+# 配置环境变量
+cp .env.example .env
+nano .env  # 设置强密码
+
+# 启动数据库
+docker compose -f docker-compose.remote-db.yml up -d
+
+# 查看状态
+docker compose -f docker-compose.remote-db.yml ps
+```
+
+#### 2. 配置防火墙
+
+```bash
+# 开放 PostgreSQL 端口
+sudo ufw allow 5432/tcp
+
+# 开放 Redis 端口
+sudo ufw allow 6379/tcp
+
+# 查看状态
+sudo ufw status
+```
+
+#### 3. 本地连接配置
+
+在本地项目根目录创建 `.env`：
+
+```env
+DB_HOST=your.server.ip.address
+DB_PORT=5432
+DB_USER=bat_user
+DB_PASSWORD=your_secure_password
+DB_NAME=bluearchive_toolkit
+
+REDIS_HOST=your.server.ip.address
+REDIS_PORT=6379
+REDIS_PASSWORD=your_redis_password
+```
+
+#### 4. 测试连接
+
+```bash
+# 测试 PostgreSQL 连接
+psql -h your.server.ip.address -U bat_user -d bluearchive_toolkit
+
+# 测试 Redis 连接
+redis-cli -h your.server.ip.address -p 6379 -a your_redis_password ping
+```
+
+---
+
+## 模式 2：本地数据库（开发）
+
+适用场景：完全本地开发，不需要远程服务器
+
+```bash
+# 启动本地数据库
+docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
+
+# 配置 .env
+DB_HOST=localhost
+DB_PORT=5432
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+---
+
+## 模式 3：生产环境部署
+
+待补充（Phase 6 实现 API Server 后）
+
+---
+
+## 数据库备份
+
+### 手动备份
+
+```bash
+# PostgreSQL
+pg_dump -h your.server.com -U bat_user -d bluearchive_toolkit > backup.sql
+
+# Redis
+redis-cli -h your.server.com -p 6379 -a password BGSAVE
+```
+
+### 自动备份
+
+启动备份服务：
+```bash
+docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d
+```
+
+备份文件位置：`deployments/backups/`
+
+---
+
+## 监控
+
+### 查看日志
+
+```bash
+# 数据库日志
+docker logs bat-postgres
+
+# Redis 日志
+docker logs bat-redis
+```
+
+### 健康检查
+
+```bash
+# 检查容器状态
+docker compose -f deployments/docker-compose.remote-db.yml ps
+
+# 检查 PostgreSQL
+docker exec bat-postgres pg_isready -U bat_user
+
+# 检查 Redis
+docker exec bat-redis redis-cli ping
+```
+
+---
+
+## 故障排查
+
+### 无法连接数据库
+
+1. 检查防火墙是否开放端口
+2. 检查 `pg_hba.conf` 配置
+3. 检查密码是否正确
+4. 检查数据库是否启动
+
+### 性能问题
+
+1. 查看数据库连接数
+2. 检查慢查询日志
+3. 优化索引
+4. 调整数据库参数
+
+---
+
+更多问题请查看 [故障排查指南](./troubleshooting.md)（待创建）
@@ -0,0 +1,179 @@
+# 开发指南
+
+## 环境准备
+
+### 安装依赖
+
+#### Go
+```bash
+# 安装 Go 1.22+
+# 参考：https://golang.org/doc/install
+
+go version  # 验证安装
+```
+
+#### Rust
+```bash
+# 安装 Rust 1.75+
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+rustc --version  # 验证安装
+cargo --version
+```
+
+#### Docker
+```bash
+# 安装 Docker 和 Docker Compose
+# 参考：https://docs.docker.com/get-docker/
+
+docker --version
+docker compose version
+```
+
+---
+
+## 项目结构
+
+请参考 [架构文档](../architecture/README.md) 了解完整的项目结构。
+
+---
+
+## 开发工作流
+
+### 1. 创建功能分支
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. 开发
+
+```bash
+# 实时编译检查
+make check
+
+# 运行测试
+make test
+
+# 格式化代码
+make fmt
+```
+
+### 3. 提交
+
+```bash
+git add .
+git commit -m "feat: 添加新功能"
+```
+
+提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+- `feat:` 新功能
+- `fix:` 修复 bug
+- `docs:` 文档更新
+- `style:` 代码格式（不影响功能）
+- `refactor:` 重构
+- `test:` 测试相关
+- `chore:` 构建工具或辅助工具
+
+### 4. 推送和 PR
+
+```bash
+git push origin feature/your-feature-name
+# 然后在 GitHub 创建 Pull Request
+```
+
+---
+
+## 代码规范
+
+### Go
+- 遵循 [Effective Go](https://golang.org/doc/effective_go)
+- 使用 `gofmt` 格式化
+- 使用 `golangci-lint` 进行静态检查
+
+### Rust
+- 遵循 [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- 使用 `cargo fmt` 格式化
+- 使用 `cargo clippy` 进行静态检查
+
+### TypeScript
+- 遵循 [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
+- 使用 ESLint 和 Prettier
+
+---
+
+## 测试
+
+### 单元测试
+
+```bash
+# Go
+go test ./...
+
+# Rust
+cargo test
+```
+
+### 集成测试
+
+```bash
+# 需要先启动数据库
+make dev
+
+# 运行集成测试
+go test -tags=integration ./...
+```
+
+### 基准测试
+
+```bash
+make bench
+```
+
+---
+
+## 调试
+
+### Go
+使用 Delve 调试器：
+```bash
+go install github.com/go-delve/delve/cmd/dlv@latest
+dlv debug ./cmd/bat
+```
+
+### Rust
+使用 rust-lldb 或 rust-gdb：
+```bash
+rust-lldb target/debug/bat-cas-engine
+```
+
+---
+
+## 常见问题
+
+### 1. 编译失败
+
+确保安装了所有依赖：
+```bash
+go mod download
+cargo fetch
+```
+
+### 2. 测试失败
+
+确保数据库已启动：
+```bash
+make dev
+```
+
+### 3. FFI 绑定问题
+
+重新生成绑定：
+```bash
+cd crates/bat-ffi
+cargo build
+```
+
+---
+
+更多问题请查看 [FAQ](./faq.md)（待创建）或提交 Issue。