feat(backend): add FastAPI service

.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.cache/
+*.db
+*.sqlite
+*.sqlite3
+
+# Node / Expo / React Native
+node_modules/
+.expo/
+dist/
+build/
+web-build/
+expo-env.d.ts
+.metro-health-check*
+*.tsbuildinfo
+.kotlin/
+ios/
+android/
+
+# Native signing / secrets
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+*.pem
+
+# Env (keep .env.example)
+.env
+.env.*
+!.env.example
+
+# Logs & debug
+*.log
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# OS / IDE / local tooling
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+.claude/
+.cursor/

backend/.env.example

@@ -0,0 +1,4 @@
+TIMEAPP_APP_NAME=TimeApp
+TIMEAPP_ENVIRONMENT=development
+TIMEAPP_DEBUG=false
+TIMEAPP_API_V1_PREFIX=/api/v1

backend/README.md

@@ -0,0 +1,54 @@
+# TimeApp API
+
+一个小而清晰的 FastAPI 项目，使用 `src` 布局与按功能领域分层的模块结构。
+
+## 环境要求
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+## 启动
+
+```bash
+cd backend
+cp .env.example .env  # 可选
+uv sync
+uv run uvicorn timeapp.main:app --reload
+```
+
+服务启动后可访问：
+
+- 健康检查：http://127.0.0.1:8000/api/v1/health
+- OpenAPI 文档：http://127.0.0.1:8000/docs
+
+## 测试
+
+```bash
+uv run pytest
+```
+
+## 目录结构
+
+```text
+src/timeapp/
+├── main.py                          # 创建 FastAPI，注册总路由
+├── api/
+│   ├── router.py                    # 聚合各领域模块的 router
+│   ├── health.py                    # 运维探活（非业务域）
+│   └── dependencies.py              # 登录用户、数据库会话等公共依赖
+├── core/
+│   └── config.py                    # 环境变量、系统配置
+└── modules/
+    ├── identity/                    # 个人信息
+    ├── scheduling/                  # 调度：日程、待办
+    ├── reminders/                   # 智能提醒
+    ├── multimodal/                  # 多模态：文字、语音、图片解析
+    ├── goal_planning/               # 任务拆分：长期目标、计划对话、草稿、子任务
+    ├── feedback/                    # 执行反馈
+    ├── replanning/                  # 智能时间重排
+    ├── unified_items/               # 统一确认分发与事项展示
+    ├── reviews/                     # 目标复盘、周期复盘
+    └── usage_management/            # 应用使用管理
+tests/
+└── test_health.py
+```

backend/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "timeapp"
+version = "0.1.0"
+description = "A small, extensible FastAPI service."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "alembic",
+    "fastapi",
+    "pydantic-settings",
+    "sqlalchemy",
+    "uvicorn[standard]",
+]
+
+[dependency-groups]
+dev = [
+    "httpx2",
+    "mypy>=2.3.0",
+    "pytest",
+    "ruff>=0.15.21",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "S",   # flake8-bandit（安全）
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+    "T20", # flake8-print（禁止 print）
+    "RUF", # ruff 专属规则
+]
+ignore = [
+    "RUF001", # 中文注释使用全角标点，属于项目约定
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]  # 测试中允许 assert
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+files = ["src", "tests"]
+plugins = ["pydantic.mypy"]

backend/src/timeapp/__init__.py

@@ -0,0 +1,3 @@
+"""TimeApp API package."""
+
+__version__ = "0.1.0"

backend/src/timeapp/api/__init__.py

@@ -0,0 +1 @@
+"""API routing package."""

backend/src/timeapp/api/dependencies.py

@@ -0,0 +1 @@
+"""Shared FastAPI dependencies (auth, DB session, etc.)."""

backend/src/timeapp/api/health.py

@@ -0,0 +1,22 @@
+"""Infrastructure health-check route (not a business domain)."""
+
+from typing import Literal
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    """Health-check response body."""
+
+    status: Literal["ok"] = "ok"
+
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    """Report that the application process is available."""
+
+    return HealthResponse()

backend/src/timeapp/api/router.py

@@ -0,0 +1,28 @@
+"""Aggregate routers from infrastructure and domain modules."""
+
+from fastapi import APIRouter
+
+from timeapp.api.health import router as health_router
+from timeapp.modules.feedback.router import router as feedback_router
+from timeapp.modules.goal_planning.router import router as goal_planning_router
+from timeapp.modules.identity.router import router as identity_router
+from timeapp.modules.multimodal.router import router as multimodal_router
+from timeapp.modules.reminders.router import router as reminders_router
+from timeapp.modules.replanning.router import router as replanning_router
+from timeapp.modules.reviews.router import router as reviews_router
+from timeapp.modules.scheduling.router import router as scheduling_router
+from timeapp.modules.unified_items.router import router as unified_items_router
+from timeapp.modules.usage_management.router import router as usage_management_router
+
+api_router = APIRouter()
+api_router.include_router(health_router)
+api_router.include_router(identity_router)
+api_router.include_router(scheduling_router)
+api_router.include_router(reminders_router)
+api_router.include_router(multimodal_router)
+api_router.include_router(goal_planning_router)
+api_router.include_router(feedback_router)
+api_router.include_router(replanning_router)
+api_router.include_router(unified_items_router)
+api_router.include_router(reviews_router)
+api_router.include_router(usage_management_router)

backend/src/timeapp/core/__init__.py

@@ -0,0 +1 @@
+"""Application configuration and shared infrastructure."""

backend/src/timeapp/core/config.py

@@ -0,0 +1,28 @@
+"""Environment-backed application settings."""
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime settings loaded from environment variables or a local .env file."""
+
+    app_name: str = "TimeApp"
+    environment: str = "development"
+    debug: bool = False
+    api_v1_prefix: str = "/api/v1"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="TIMEAPP_",
+        extra="ignore",
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return one settings instance per process."""
+
+    return Settings()

backend/src/timeapp/main.py

@@ -0,0 +1,23 @@
+"""FastAPI application entry point."""
+
+from fastapi import FastAPI
+
+from timeapp import __version__
+from timeapp.api.router import api_router
+from timeapp.core.config import get_settings
+
+
+def create_app() -> FastAPI:
+    """Create and configure a FastAPI application instance."""
+
+    settings = get_settings()
+    application = FastAPI(
+        title=settings.app_name,
+        version=__version__,
+        debug=settings.debug,
+    )
+    application.include_router(api_router, prefix=settings.api_v1_prefix)
+    return application
+
+
+app = create_app()

backend/src/timeapp/modules/__init__.py

@@ -0,0 +1 @@
+"""Domain modules grouped by business feature."""

backend/src/timeapp/modules/feedback/__init__.py

@@ -0,0 +1 @@
+"""反馈模块。"""

backend/src/timeapp/modules/feedback/router.py

@@ -0,0 +1,8 @@
+"""反馈模块路由。
+
+负责执行反馈的采集与处理相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/feedback", tags=["feedback"])

backend/src/timeapp/modules/goal_planning/__init__.py

@@ -0,0 +1 @@
+"""任务拆分模块。"""

backend/src/timeapp/modules/goal_planning/router.py

@@ -0,0 +1,8 @@
+"""任务拆分模块路由。
+
+负责长期目标、计划对话、计划草稿与子任务相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/goal-planning", tags=["goal-planning"])

backend/src/timeapp/modules/identity/__init__.py

@@ -0,0 +1 @@
+"""个人信息模块。"""

backend/src/timeapp/modules/identity/router.py

@@ -0,0 +1,8 @@
+"""个人信息模块路由。
+
+负责用户资料、偏好等个人信息相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/identity", tags=["identity"])

backend/src/timeapp/modules/multimodal/__init__.py

@@ -0,0 +1 @@
+"""多模态处理模块。"""

backend/src/timeapp/modules/multimodal/router.py

@@ -0,0 +1,8 @@
+"""多模态处理模块路由。
+
+负责文字、语音、图片等输入的解析与结构化相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/multimodal", tags=["multimodal"])

backend/src/timeapp/modules/reminders/__init__.py

@@ -0,0 +1 @@
+"""智能提醒模块。"""

backend/src/timeapp/modules/reminders/router.py

@@ -0,0 +1,8 @@
+"""智能提醒模块路由。
+
+负责提醒规则、触发与通知相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/reminders", tags=["reminders"])

backend/src/timeapp/modules/replanning/__init__.py

@@ -0,0 +1 @@
+"""重排模块。"""

backend/src/timeapp/modules/replanning/router.py

@@ -0,0 +1,8 @@
+"""重排模块路由。
+
+负责智能时间重排相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/replanning", tags=["replanning"])

backend/src/timeapp/modules/reviews/__init__.py

@@ -0,0 +1 @@
+"""复盘模块。"""

backend/src/timeapp/modules/reviews/router.py

@@ -0,0 +1,8 @@
+"""复盘模块路由。
+
+负责目标复盘与周期复盘相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/reviews", tags=["reviews"])

backend/src/timeapp/modules/scheduling/__init__.py

@@ -0,0 +1 @@
+"""调度模块。"""

backend/src/timeapp/modules/scheduling/router.py

@@ -0,0 +1,8 @@
+"""调度模块路由。
+
+负责日程（Schedule）与待办（Todo）相关接口。
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/scheduling", tags=["scheduling"])