feat(backend): add FastAPI service

.env.example

@@ -0,0 +1,7 @@
+# Docker Compose development defaults. Do not use these credentials in production.
+POSTGRES_DB=timeapp
+POSTGRES_USER=timeapp
+POSTGRES_PASSWORD=timeapp
+POSTGRES_PORT=5432
+API_PORT=8000
+TIMEAPP_ENVIRONMENT=docker

.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/.dockerignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+tests/

backend/.env.example

@@ -0,0 +1,5 @@
+TIMEAPP_APP_NAME=TimeApp
+TIMEAPP_ENVIRONMENT=development
+TIMEAPP_DEBUG=false
+TIMEAPP_API_V1_PREFIX=/api/v1
+TIMEAPP_DATABASE_URL=postgresql+psycopg://timeapp:timeapp@127.0.0.1:5432/timeapp

backend/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11.15-slim-bookworm
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/app/.venv/bin:$PATH"
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir uv==0.11.28
+
+COPY pyproject.toml uv.lock README.md alembic.ini docker-entrypoint.sh ./
+COPY src ./src
+COPY alembic ./alembic
+RUN uv sync --frozen --no-dev \
+  && chmod +x /app/docker-entrypoint.sh
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=10s --timeout=5s --start-period=15s --retries=5 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health')"
+
+ENTRYPOINT ["/app/docker-entrypoint.sh"]

backend/README.md

@@ -0,0 +1,83 @@
+# Timeflow API
+
+后端使用 Python 3.11、uv、FastAPI、SQLAlchemy、Alembic 和 PostgreSQL。
+
+## 本地启动
+
+```bash
+cp .env.example .env
+uv sync --locked --all-groups
+uv run alembic upgrade head
+uv run uvicorn timeapp.main:app --reload
+```
+
+如果本机没有 PostgreSQL，使用仓库根目录的 Compose（容器启动时会自动执行迁移）：
+
+```bash
+docker compose up --build
+```
+
+健康检查：<http://127.0.0.1:8000/api/v1/health>
+
+## Agent 目录边界
+
+```text
+src/timeapp/
+├── agents/                 # 主 Agent 和专项 Agent
+│   ├── main_agent/         # 唯一 Agent HTTP 入口和内部调度
+│   │   ├── router.py
+│   │   ├── schemas.py
+│   │   └── dispatcher.py
+│   ├── schedule_todo_agent/    # schemas.py + service.py + prompts.py
+│   ├── task_breakdown_agent/   # schemas.py + service.py + prompts.py
+│   ├── replanning_agent/       # schemas.py + service.py + prompts.py
+│   ├── review_agent/           # schemas.py + service.py + prompts.py
+│   └── feedback_agent/         # schemas.py + service.py + prompts.py
+├── basic/                  # 手动业务、事项展示和 OCR/ASR
+│   ├── identity/
+│   ├── timeline/
+│   ├── reminders/
+│   ├── multimodal/
+│   └── usage_management/
+├── common/                 # 跨 Agent 契约与共享能力
+│   ├── contracts/          # 统一响应、会话等契约
+│   ├── data/               # 公共事实数据读写
+│   ├── confirmation/       # 确认
+│   ├── questioning/        # 反问
+│   ├── llm/                # LLM 边界
+│   ├── task_profile/       # 任务级画像
+│   └── context/            # 上下文
+├── api/                    # HTTP 路由聚合和基础设施探活
+└── core/                   # 配置、数据库连接和基础设施
+```
+
+专项 Agent 是进程内能力包，不暴露 HTTP Router。它们只接收主 Agent 整理好的完整参数，返回 `AgentResponse`；不直接访问数据库、不负责追问，也不直接执行 `db_action`。所有写操作必须由主 Agent 在用户确认和公共数据校验后落盘。
+
+## 数据库迁移（Alembic）
+
+连接串来自 `TIMEAPP_DATABASE_URL`（见 `.env.example`），不要写进 `alembic.ini`。
+
+```bash
+# 应用迁移到最新
+uv run alembic upgrade head
+
+# 模型变更后生成迁移（需先在 alembic/env.py 导入新 models 模块）
+uv run alembic revision --autogenerate -m "describe change"
+
+# 查看当前版本
+uv run alembic current
+```
+
+迁移脚本位于 `alembic/versions/`。禁止手改已提交的历史迁移；禁止用 `Base.metadata.create_all` 走生产建表路径。
+Docker 镜像通过 `docker-entrypoint.sh` 在启动 uvicorn 前自动执行 `alembic upgrade head`。
+
+## 测试与检查
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+或在仓库根目录执行官方门禁：`bash scripts/check-all.sh backend`。

backend/alembic.ini

@@ -0,0 +1,148 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# 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
+
+# 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.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL is supplied by alembic/env.py via TIMEAPP_DATABASE_URL / Settings.
+# Do not put credentials here.
+# sqlalchemy.url =
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/README

@@ -0,0 +1,5 @@
+Alembic migration scripts for timeapp.
+
+- Generate: `uv run alembic revision --autogenerate -m "describe change"`
+- Apply: `uv run alembic upgrade head`
+- Import new ORM modules in `env.py` so autogenerate sees them.