统一服务启动入口至 Makefile（dev-core/dev-*/db-*/test-*），Alembic 迁移改为 000 起三位顺序编号并经 make db-revision 生成

2026-08-21 22:12:34 +08:00
1 parent 8ebcc11a8a
commit c090893e63
@@ -224,6 +224,18 @@ Compose 文件不使用顶部 `version` 字段。

 ## 开发命令

+### 本地开发（Makefile 统一入口）
+
+所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）：
+
+```bash
+make dev-core                 # 核心三服务并行：灵台 + 神识 + 照壁
+make dev-backend              # 灵台（另有 dev-shenshi / dev-bff / dev-frontend / dev-sandbox / dev-tianmu / dev-yuanqi）
+make db-upgrade               # Alembic 升级到 head（迁移编号 000/001/002…）
+make db-revision m="说明"     # 生成下一号迁移（自动编号 + autogenerate，禁手写哈希 id）
+make test                     # 全部测试（backend / shenshi / bff / frontend）
+```
+
 ### Docker

 编排按职责解耦为两个文件，容器名统一以 `hunjing-` 开头，通过共享网络 `hunjing-net` 互通，详细说明见 `docker/README.md`：
@@ -1,30 +1,142 @@
-# Makefile for cleaning Python cache files and empty directories
-# Author: AI Assistant
-# Usage: make clean or make clean-all
+# ==============================
+# 魂镜 · 统一开发入口（rewrite/1.0）
+# 所有本地服务的启动 / 测试 / 数据库迁移统一经本文件；
+# Docker 编排（基础设施与应用容器）见 AGENTS.md「开发命令」与 docker/README.md。
+# ==============================

-.PHONY: clean clean-all clean-pyc clean-pytest clean-mypy clean-empty-dirs help
-
-# Colors for pretty output
 GREEN  := \033[0;32m
 YELLOW := \033[0;33m
-RED    := \033[0;31m
-NC     := \033[0m # No Color
+NC     := \033[0m

-# Default target
+.PHONY: help \
+  dev-backend dev-shenshi dev-bff dev-frontend dev-sandbox dev-tianmu dev-yuanqi dev-core dev-all \
+  db-upgrade db-downgrade db-revision db-current \
+  test test-backend test-shenshi test-bff test-frontend \
+  vet-shenshi typecheck-bff \
+  infra-up app-up app-down \
+  clean clean-all clean-pyc clean-pytest clean-mypy clean-empty-dirs clean-dry-run
+
+# 默认目标
 help:
-	@echo "$(GREEN)Available targets:$(NC)"
-	@echo "  $(YELLOW)make clean$(NC)        - Remove Python cache files, pytest cache, mypy cache, and empty directories"
-	@echo "  $(YELLOW)make clean-pyc$(NC)    - Remove Python cache files (__pycache__, .pyc, .pyo)"
-	@echo "  $(YELLOW)make clean-pytest$(NC) - Remove pytest cache (.pytest_cache)"
-	@echo "  $(YELLOW)make clean-mypy$(NC)   - Remove mypy cache (.mypy_cache)"
-	@echo "  $(YELLOW)make clean-empty-dirs$(NC) - Remove empty directories"
-	@echo "  $(YELLOW)make clean-all$(NC)    - Remove everything (cache, logs, coverage, build, dist, etc.)"
+	@echo "$(GREEN)魂镜统一开发入口$(NC)"
+	@echo ""
+	@echo "$(YELLOW)服务启动（开发）$(NC)"
+	@echo "  make dev-backend     灵台（uvicorn 热重载，:8000）"
+	@echo "  make dev-shenshi     神识（go run，:8080）"
+	@echo "  make dev-bff         照壁（tsx watch，:3000）"
+	@echo "  make dev-frontend    琉璃镜（next dev，:3001）"
+	@echo "  make dev-sandbox     乾坤沙箱（cargo run，:8090）"
+	@echo "  make dev-tianmu      天目 OCR（:8101，可选）"
+	@echo "  make dev-yuanqi      元炁本地推理（:11434，可选）"
+	@echo "  make dev-core        核心三服务并行（灵台+神识+照壁）"
+	@echo "  make dev-all         前述全部并行（不含沙箱/天目/元炁）"
+	@echo ""
+	@echo "$(YELLOW)数据库（Alembic，迁移编号 000/001/002…）$(NC)"
+	@echo "  make db-upgrade      升级到最新（head）"
+	@echo "  make db-downgrade    回退一步"
+	@echo "  make db-revision m=\"说明\"  生成下一号迁移（自动编号+autogenerate）"
+	@echo "  make db-current      查看当前版本"
+	@echo ""
+	@echo "$(YELLOW)测试与检查$(NC)"
+	@echo "  make test            全部（后端+神识+照壁+前端）"
+	@echo "  make test-backend / test-shenshi / test-bff / test-frontend"
+	@echo "  make vet-shenshi     go vet"
+	@echo "  make typecheck-bff   tsc --noEmit"
+	@echo ""
+	@echo "$(YELLOW)Docker 编排快捷方式$(NC)"
+	@echo "  make infra-up / app-up / app-down"
+	@echo ""
+	@echo "$(YELLOW)清理$(NC)"
+	@echo "  make clean / clean-all / clean-dry-run"
+
+# ============================== 服务启动（开发） ==============================
+
+dev-backend:
+	cd backend && uv run python -m app.main
+
+dev-shenshi:
+	cd shenshi && go run .
+
+dev-bff:
+	cd bff && npm run dev
+
+dev-frontend:
+	cd frontend && pnpm dev
+
+dev-sandbox:
+	cd sandbox && cargo run
+
+dev-tianmu:
+	cd tianmu && uv run python -m src.main
+
+dev-yuanqi:
+	cd yuanqi && uv run python -m src.main
+
+# 核心三服务并行：灵台 + 神识 + 照壁（M0 验收链路）
+dev-core:
+	$(MAKE) -j3 dev-backend dev-shenshi dev-bff
+
+dev-all:
+	$(MAKE) -j4 dev-backend dev-shenshi dev-bff dev-frontend
+
+# ============================== 数据库（Alembic） ==============================
+
+# 迁移约定：revision id 与文件名前缀用三位顺序号（000、001、002…），生成统一走
+# `make db-revision`（自动取最大号+1 并传 --rev-id）；不要手写哈希 id。
+db-upgrade:
+	cd backend && uv run alembic upgrade head
+
+db-downgrade:
+	cd backend && uv run alembic downgrade -1
+
+db-revision:
+	@next=$$(ls backend/alembic/versions 2>/dev/null | grep -E '^[0-9][0-9][0-9]_.*\.py$$' | cut -c1-3 | sort -n | tail -1); \
+	if [ -z "$$next" ]; then echo "未找到顺序编号迁移，请先确认基线 000 存在"; exit 1; fi; \
+	next=$$(printf '%03d' $$((10#$$next + 1))); \
+	echo "$(GREEN)生成迁移 $(NC)$$next：$(m)"; \
+	cd backend && uv run alembic revision --autogenerate --rev-id $$next -m "$(m)"
+
+db-current:
+	cd backend && uv run alembic current
+
+# ============================== 测试与检查 ==============================
+
+test-backend:
+	cd backend && uv run pytest -q
+
+test-shenshi:
+	cd shenshi && go test ./...
+
+test-bff:
+	cd bff && npm test --silent
+
+test-frontend:
+	cd frontend && pnpm test
+
+test: test-backend test-shenshi test-bff test-frontend
+
+vet-shenshi:
+	cd shenshi && go vet ./...
+
+typecheck-bff:
+	cd bff && npm run type-check --silent
+
+# ============================== Docker 编排快捷方式 ==============================
+
+infra-up:
+	docker compose -f docker/docker-compose.infra.yml up -d
+
+app-up:
+	docker compose -f docker/docker-compose.app.yml up -d --build
+
+app-down:
+	docker compose -f docker/docker-compose.app.yml down
+
+# ============================== 清理（保留原有能力） ==============================

-# Main clean target
 clean: clean-pyc clean-pytest clean-mypy clean-empty-dirs
 	@echo "$(GREEN)✓ Cleanup completed successfully!$(NC)"

-# Clean Python cache files
 clean-pyc:
 	@echo "$(YELLOW)Removing Python cache files...$(NC)"
 	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
@@ -33,55 +145,35 @@ clean-pyc:
 	@find . -type f -name "*.pyd" -delete 2>/dev/null || true
 	@echo "$(GREEN)✓ Python cache files removed$(NC)"

-# Clean pytest cache
 clean-pytest:
 	@echo "$(YELLOW)Removing pytest cache...$(NC)"
 	@rm -rf .pytest_cache 2>/dev/null || true
 	@find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
 	@echo "$(GREEN)✓ Pytest cache removed$(NC)"

-# Clean mypy cache
 clean-mypy:
 	@echo "$(YELLOW)Removing mypy cache...$(NC)"
 	@rm -rf .mypy_cache 2>/dev/null || true
 	@find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
 	@echo "$(GREEN)✓ Mypy cache removed$(NC)"

-# Remove empty directories
 clean-empty-dirs:
 	@echo "$(YELLOW)Removing empty directories...$(NC)"
-	@# Remove empty directories (including hidden ones), excluding .git and .venv
 	@find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" -not -path "./venv/*" -not -path "./env/*" -not -path "./.env/*" -delete 2>/dev/null || true
-	@# Second pass to remove newly created empty parent directories
 	@find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" -not -path "./venv/*" -not -path "./env/*" -not -path "./.env/*" -delete 2>/dev/null || true
 	@echo "$(GREEN)✓ Empty directories removed$(NC)"

-# Clean everything (extended cleanup)
 clean-all: clean
 	@echo "$(YELLOW)Removing additional files...$(NC)"
-	@# Coverage reports
 	@rm -rf htmlcov .coverage coverage.xml .coverage.* 2>/dev/null || true
-	@# Build artifacts
 	@rm -rf build/ dist/ *.egg-info .eggs/ 2>/dev/null || true
-	@# Log files
 	@find . -type f -name "*.log" -delete 2>/dev/null || true
-	@# Jupyter notebooks checkpoint
 	@find . -type d -name ".ipynb_checkpoints" -exec rm -rf {} + 2>/dev/null || true
-	@# IDE files (optional, uncomment if needed)
-	# @rm -rf .vscode/ .idea/ 2>/dev/null || true
 	@echo "$(GREEN)✓ Extended cleanup completed!$(NC)"

-# Dry run - show what would be deleted (for safety)
 clean-dry-run:
-	@echo "$(YELLOW)Dry run - files that would be deleted:$(NC)"
-	@echo "\nPython cache files:"
+	@echo "$(YELLOW)Dry run - files that would be deleted (run 'make clean' to delete):$(NC)"
 	@find . -type d -name "__pycache__" 2>/dev/null || echo "None"
 	@find . -type f -name "*.pyc" 2>/dev/null || echo "None"
-	@find . -type f -name "*.pyo" 2>/dev/null || echo "None"
-	@echo "\nPytest cache:"
 	@find . -type d -name ".pytest_cache" 2>/dev/null || echo "None"
-	@echo "\nMypy cache:"
 	@find . -type d -name ".mypy_cache" 2>/dev/null || echo "None"
-	@echo "\nEmpty directories:"
-	@find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" 2>/dev/null || echo "None"
-	@echo "$(YELLOW)\nRun 'make clean' to actually delete these files$(NC)"
@@ -15,6 +15,10 @@ script_location = %(here)s/alembic
 # Or organize into date-based subdirectories (requires recursive_version_locations = true)
 # file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s

+# 魂镜迁移编号约定（rewrite/1.0）：revision id 与文件名前缀使用三位顺序号（000、001、002…），
+# 生成统一走根目录 `make db-revision m="说明"`（自动取最大号+1 并传 --rev-id），不手写哈希 id。
+file_template = %%(rev)s_%%(slug)s
+
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.  for multiple paths, the path separator
 # is defined by "path_separator" below.
@@ -12,7 +12,7 @@ import sqlalchemy as sa


 # revision identifiers, used by Alembic.
-revision: str = '843abf719fde'
+revision: str = '000'
 down_revision: Union[str, Sequence[str], None] = None
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
@@ -12,13 +12,13 @@

 ## 运行

-```bash
-npm install
-npm run dev          # 开发（tsx watch）
-BACKEND_URL=http://127.0.0.1:8000 BFF_PORT=3000 npm start
+统一经根目录 Makefile：

-npm test             # vitest
-npm run type-check
+```bash
+make dev-bff          # 开发（tsx watch，:3000）
+make test-bff         # vitest
+make typecheck-bff    # tsc --noEmit
+# 首次进入 bff/ 需 npm install；环境变量默认值见 src/config.ts
 ```

 环境变量：`BFF_PORT`（默认 3000）、`BACKEND_URL`（默认 http://127.0.0.1:8000）、`BFF_BODY_LIMIT`、`BFF_LOG_LEVEL`。
@@ -168,7 +168,7 @@ erDiagram

 **退役删除**（旧模型，开发数据随 db 丢弃）：personality、personality_emotion、personality_versions/proposals、mood_events、character_emotion_states、drive、evolution、wuxing 相关、big_cycle、goals、plans、time_anniversaries、idle_window、suspension、uncertainty_states、curiosity_questions、exploratory_subgoals、chat_sessions/chat_messages（被镜树取代）、memory_timelines/timeline_events、knowledge_documents/memory_chunks/embedding_refs（并入记忆域新表）、candidates（并入灵胚审核）、character_situational_entries、avatar 旧表（并入形仪）。

-Alembic 基线重建：丢弃现有 4 个迁移，以本模型为新基线 `0001`；迁移与退役的执行顺序见[重写执行计划](../operations/rewrite-plan.md)。
+Alembic 基线重建：丢弃现有 4 个迁移，以本模型为新基线 `000`；迁移编号使用三位顺序号（000、001、002…），生成统一经根目录 `make db-revision m="说明"`（自动编号，不手写哈希 id）；迁移与退役的执行顺序见[重写执行计划](../operations/rewrite-plan.md)。

 ## 10. 隐私与删除的落库规则

@@ -56,7 +56,7 @@

 ### 3.2 数据库

- 丢弃 Alembic 4 个旧迁移与 `db/hunjing.db` 开发数据；按[数据模型](../architecture/data-model.md) §9 清单重建基线 `0001`。
+- 丢弃 Alembic 4 个旧迁移与 `db/hunjing.db` 开发数据；按[数据模型](../architecture/data-model.md) §9 清单重建基线 `000`（三位顺序编号，经 `make db-revision` 生成）。
 - 表处置以该清单为准（保留改造 / 新建 / 退役删除三列）。

 ### 3.3 frontend 旧页面 → 新去处
@@ -23,9 +23,13 @@ shenshi/

 ## 本地运行

+统一经根目录 Makefile：
+
 ```bash
-SHENSHI_PORT=8080 go run .
-# 灵台侧配置（backend .env）：SHENSHI_BASE_URL=http://127.0.0.1:8080
+make dev-shenshi          # SHENSHI_PORT=8080
+make vet-shenshi          # go vet
+make test-shenshi         # go test ./...
+# 灵台侧联调配置（根目录 .env）：SHENSHI_BASE_URL=http://127.0.0.1:8080
 ```

 ## 测试