mindfulness/spec_kit/Project Bootstrap/plan.md

Project Bootstrap（技术计划）

1. 目标与约束（来自 spec）

• 目标：完成项目初始化可落地的工程与基础设施约定（client/server + dev/prod 隔离 + MySQL/Redis 命名与访问边界）。
• 关键选择：
  • 后端依赖：requirements.txt + pip
  • 定时/异步：Celery + Redis
  • 环境：仅 dev / prod
  • Redis 隔离：ACL + key 前缀（dev:* / pro:*）
  • 部署：不在本需求中提供 Docker 起 MySQL/Redis（MySQL/Redis 已部署），后端通过环境变量连接
  • 数据库迁移：Alembic
  • Redis 生产环境：maxmemory=256MB 硬限制

2. 总体方案

2.1 MySQL（schema 隔离）

• prod schema：mindfulness
• dev schema：mindfulness_dev
• 字符集：utf8mb4
• 连接方式：后端通过 DATABASE_URL（SQLAlchemy Async）连接到对应 schema

2.2 Redis（ACL + 前缀隔离 + 内存限制）

• 单 Redis 实例（同机同容器可行）。
• 通过 ACL 用户限制不同环境只能访问各自前缀：
  • dev 用户：只能访问 dev:*
  • prod 用户：只能访问 pro:*
• 应用侧硬约束：所有 Redis key 必须带环境前缀（dev: / pro:）。
• 生产 maxmemory：256mb，并采用“少用 Redis、短 TTL、避免任务积压”的策略。

重要：Celery broker 以“可靠投递”为优先，计划中默认 不启用 Celery result backend（或启用时必须设置 TTL）。

2.3 运行方式（不限定部署形态）

本需求只要求：

• MySQL 与 Redis 已可访问
• 后端通过 .env.dev/.env.prod（或等价环境变量注入方式）获取连接信息
• API/Celery/Beat 以任意进程管理方式运行（Docker/systemd/进程托管均可），但需满足验收项

3. 目录与文件落地清单

本计划只定义“应该创建/调整什么”，具体文件内容在 tasks 阶段逐项实现。

3.1 后端依赖与启动入口（server）

• server/requirements.txt
• server/app/main.py（FastAPI 入口）
• server/app/core/config.py（pydantic-settings，按 APP_ENV 加载 .env.dev/.env.prod）
• server/app/worker.py（Celery app 入口）
• server/alembic.ini + server/alembic/（迁移脚手架）
• server/.env.example（字段结构，不含真实值）

3.2 基础设施（infra）

本需求不强制创建 infra/（因为 MySQL/Redis 已部署）。

可选新增（仅用于“文档化配置/备份参考”，不要求参与部署）：

• infra/redis/users.acl（ACL 用户定义备份）
• infra/redis/redis.prod.conf（prod 配置备份，包含 maxmemory=256mb）
• infra/mysql/init/00-create-schemas.sql（创建 mindfulness_dev/mindfulness 的 SQL 备份）

4. Redis ACL 与 maxmemory 的落地方案

4.1 ACL 文件（infra/redis/users.acl）

若 Redis 已在服务器配置完成，本节用于“约定与验收”。

• 定义 dev_user、pro_user 两个账号
• 分别限制 key pattern：
  • dev：~dev:*
  • prod：~pro:*
• 建议禁用默认用户，避免未授权访问（推荐）：user default off

4.2 Redis 配置（infra/redis/redis.prod.conf）

若 Redis 已在服务器配置完成，本节用于“约定与验收”。

• maxmemory 256mb
• maxmemory-policy noeviction（队列场景优先“不丢任务”，宁可让写入失败报警）
• 开启 ACL（例如 aclfile .../users.acl）

4.3 应用侧约束（在代码实现时落地）

为确保 ACL 真的起作用，需要做到：

• 所有业务 key 带前缀：例如 dev:cache:... / pro:cache:...
• Celery 队列名带前缀：例如 dev:push / pro:push
• 禁用或限制 result backend：默认不启用；如启用必须设置短 TTL（例如 1 小时/1 天）
• 任务参数保持小：只传 id，不传长文本/大 payload，避免队列膨胀导致 Redis 触顶

5. 环境变量与配置约定

5.1 后端 .env.dev/.env.prod（字段示例）

• APP_ENV=dev|prod
• DATABASE_URL=.../mindfulness_dev（dev）或 .../mindfulness（prod）
• REDIS_URL=redis://<user>:<pass>@redis:6379/0
• CELERY_BROKER_URL=redis://<user>:<pass>@redis:6379/0
• CELERY_RESULT_BACKEND：默认不配置（或仅在 dev 开启）

5.2 密钥管理

• .env.dev/.env.prod 不进仓库
• 提供 .env.example 仅展示字段结构

6. 实施步骤（建议顺序）

阶段 A：验证现有 MySQL/Redis 与隔离策略

• Redis：ACL 生效验证（dev 用户无法访问 pro:*，prod 用户无法访问 dev:*）
• Redis：prod 配置验证（maxmemory=256mb 生效）
• MySQL：确认 mindfulness_dev 与 mindfulness 两个 schema 已创建（若未创建则创建）

阶段 B：后端最小可运行骨架

• requirements.txt 固化依赖
• FastAPI 最小健康检查接口（如 /healthz）
• SQLAlchemy 连接与基础会话
• Alembic 初始化与一次空迁移验证

阶段 C：Celery 最小闭环

• Celery app 初始化，broker 指向 Redis（按环境选择 dev_user/pro_user）
• 1 个示例任务（例如打印/写库）验证 worker 可消费
• 如需要定时：beat 定时触发任务验证

7. 验收与自检清单（plan 阶段定义）

• 环境隔离
  • dev 连接 mindfulness_dev，prod 连接 mindfulness
  • dev 的 Redis 凭证无法读写 pro:*，反之亦然
• 资源约束
  • prod Redis maxmemory=256mb 生效
  • 不启用（或短 TTL）result backend，避免长期堆积
• 可运行性
  • FastAPI 能启动并提供基础接口
  • Celery worker 能消费任务，beat（如启用）能触发定时任务

8. 风险与应对

• Redis 256MB 触顶风险：
  • 控制队列积压（worker 数量/并发）
  • 禁用或缩短结果存储 TTL
  • 任务 payload 只传 id
• 多环境同机误用风险：
  • 强制不同 ACL 用户 + 前缀
  • Celery 队列名带前缀，避免互相消费