91846a201e
feat(auth): /auth/me returns workspaces[] with id/name/slug/role
...
GET /auth/me now responds with the new UserMeResponse: the existing
user fields plus default_workspace_id and a workspaces list that
joins WorkspaceRepository.list_by_user with the caller's role from
WorkspaceMembershipRepository.list_by_user. Stage 0 every user has
exactly one entry there, but the shape is forward-compatible for
Stage 2 multi-workspace memberships.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:37:29 +08:00
634e5119e1
feat(auth): login + change_password re-issue JWTs with wid + role
...
After PR4 every protected request demands wid. Three JWT-issue paths
must encode it; T4.8/T4.9 covered /initialize and /register, and this
commit closes the remaining two:
- login_local calls _ensure_default_workspace (idempotent — returns
the existing default_workspace_id when set) so users who pre-date
PR4 are backfilled at login time, and signs the new cookie with
wid + role='owner'.
- change_password does the same, ensuring a password change does not
strip the workspace claim and lock the user out on their next
request.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:35:06 +08:00
84701730da
feat(auth): /register auto-creates default workspace + owner membership
...
Mirrors T4.8: the regular registration path now invokes the same
_ensure_default_workspace helper so every new user lands with a
1-person workspace (owner) and a JWT carrying wid + role='owner'.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:32:39 +08:00
a657d17995
feat(auth): /initialize auto-creates default workspace + owner membership
...
initialize_admin now seeds a 1-person workspace immediately after the
admin user is created: WorkspaceRepository.create(name, slug, owner_id)
+ WorkspaceMembershipRepository.add(role='owner') + writes the new
workspace id back to users.default_workspace_id. The session JWT is
re-issued with wid + role='owner' so subsequent requests pass the
T4.7 workspace gate.
Mechanical pieces:
- SQLiteUserRepository row<->user mapping now includes
default_workspace_id (sql update_user too) so the column persists.
- workspace.sql.SLUG_BLACKLIST is now public (was _SLUG_BLACKLIST) and
the registration helper treats blacklisted slugs as "taken" so the
walker steps past reserved names like "admin" instead of crashing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:31:53 +08:00
a06e88d58b
feat(auth): workspace slug helpers — auto_slug_from_email + next_available_slug
...
auto_slug_from_email maps an email's local-part to a schema-valid base
slug (lowercase, [+_.]→'-', alphanumeric-and-hyphen, clamp 32 chars,
fallback to user-{token_hex(4)} for pathological inputs).
next_available_slug walks the {base, base-2, base-3, ...} sequence
against a caller-supplied async exists_check until it lands on a free
slot, truncating base when the suffix would push past 32 chars.
Pulled forward of T4.8/T4.9 because both /auth/initialize and
/auth/register need it. Lives in app.gateway.auth (not persistence)
since "email → slug" is a registration-time concern.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:27:42 +08:00
2145d36744
feat(auth): AuthMiddleware injects workspace ContextVar from JWT wid/role
...
deps.get_current_user_from_request now stashes the decoded payload on
request.state.auth_payload so AuthMiddleware can populate the
workspace_context ContextVar without a second decode. Reset is paired
in the same try/finally as user_context to keep teardown atomic.
Also adds:
- auth.models.ActiveWorkspace — minimal proxy that satisfies the
CurrentWorkspace protocol (id + role only).
- auth.models.User.default_workspace_id — surfaces the DB column added
in T4.4 so the eventual /auth/me payload can reference it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:25:43 +08:00
b4bef65079
feat(auth): decode_token rejects legacy 4-field JWTs as WORKSPACE_MISSING
...
After PR4 every JWT must carry wid (workspace_id). decode_token now
returns the new TokenError.WORKSPACE_MISSING when the signature is
valid but the payload lacks wid; expired tokens still report EXPIRED
first so /auth/refresh logic stays correct. AuthErrorCode gains a
matching WORKSPACE_REQUIRED for middleware to surface to clients.
Updates 13 existing test sites that issued tokens without wid to pass
workspace_id="ws-test" + role="owner", reflecting the new contract.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:22:10 +08:00
54cb94c30f
feat(auth): JWT TokenPayload accepts wid + role
...
TokenPayload gains optional wid (workspace_id) and role claims;
create_access_token accepts them as keyword-only args and only
encodes them when provided. Existing tokens and existing callers
keep working unchanged — the contract that protected requests
must carry wid is enforced by middleware (PR4 T4.6/T4.7), not by
the JWT type system.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:17:55 +08:00
54762f491c
feat(persistence): UserRow.default_workspace_id
...
Adds a nullable FK column to mirror alembic 0001. On fresh deployments
metadata.create_all() will create users with this column; existing
deployments rely on the alembic migration to add it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:15:05 +08:00
917d8fbeaf
test(persistence): alembic 0001 round-trip on SQLite + Postgres
...
Verifies alembic upgrade 0001 adds users.default_workspace_id (with FK
to workspaces) and that downgrade cleanly removes it. Runs on both
dialects because the migration uses op.batch_alter_table for SQLite
ALTER compatibility.
Tests are intentionally sync — alembic's command layer is sync and
env.py calls asyncio.run(); running under pytest-anyio would deadlock
on the inner event loop.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:11:11 +08:00
8efbb2f9e5
feat(persistence): alembic 0001 — users.default_workspace_id
...
First Alembic revision for the DeerFlow application schema. Adds a
nullable users.default_workspace_id column with an ON DELETE SET NULL
FK to workspaces(id), so newly-registered users can be routed back to
their default workspace on next login without consulting memberships.
Uses op.batch_alter_table for SQLite ALTER compatibility (sqlite is
still a supported dev fallback).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:08:44 +08:00
d98498b705
docs(impl): T4.1 — confirm alembic baseline is not needed
...
alembic heads/history both empty, versions/ dir empty: 0001 can be the
first revision with down_revision=None. alembic_version table will be
auto-created on first upgrade head. doctor.py needs no new check.
Also records T4 preparation grep findings on _ensure_admin_user current
behavior (open issue #3 resolved).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:07:34 +08:00
c70c6594de
docs(impl): STATUS — record LOCK sign-off and origin push
...
Two unblocking events on 2026-05-12: team signed off all 7 irreversible
schema decisions, and docs branch was finally pushed to origin (38 commits,
via SSH-over-443 to bypass local proxy). PR4 is now unblocked.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 22:02:33 +08:00
a592319e3c
docs(impl): STATUS update after PR3 merge
...
PR3 ✅ merged 进 docs branch（7 commits, T3.1-T3.10）+ RDS live 验证通过
（11 张表含 workspaces/workspace_memberships，partial unique on owner 索引
建出来）。测试基线 3134 passed + 25 skipped + 0 failed。
下一个 PR4（auth 改造）plan 推荐 Inline 模式（跨 jwt.py/auth_middleware.py/
routers/auth.py 多文件耦合紧）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:34:05 +08:00
dda8264057
docs(impl): PR3 implementation note + acceptance checklist
...
记录 Stage 0 PR3 的实施落点、LOCK 决策、跟进项与 6 commit 列表。
验收：3134 passed + 25 skipped + 0 failed（PR2 末 3087 + 47 新 ws_context/
ws_repo/membership_repo 测试 + 2 PG-only skipped）。RDS live 验证通过：
workspaces / workspace_memberships 表 + partial unique on owner 都建出来。
T3.6 (membership ORM) 提前到 T3.4-T3.5 (workspace repo) 之前，因为
WorkspaceRepository.get/list_by_user 会 JOIN memberships。
Stage 0 PR3 T3.10. PR3 完成。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:18:19 +08:00
3313047ff1
test(workspace): partial unique on owner — Postgres twin test
...
新建 test_workspace_partial_unique_postgres.py，2 个 @pytest.mark.postgres
test，用 PR1 的 testcontainers postgres_url fixture 验：
- test_partial_unique_on_owner_enforced_on_postgres：第 2 个 owner
IntegrityError（SQLite twin 在 test_workspace_membership_repo 已覆盖）
- test_multiple_admins_allowed_on_postgres：多个 admin/member 不触发约束
为什么 PG 单独写：sqlite_where vs postgresql_where 是两份 DDL；SQLAlchemy
能 emit 不代表 PG 真的执行。本测试 pin 两边语义一致。
本地无 docker daemon → SKIPPED；CI workflow backend-postgres-tests 会实跑。
Stage 0 PR3 T3.8。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:15:25 +08:00
36ffe2713f
feat(persistence): WorkspaceMembershipRepository + 8 unit tests
...
新建 backend/packages/harness/deerflow/persistence/workspace_membership/sql.py，方法：
- add(workspace_id, user_id, role, invited_by=None) 校验 role ∈
{owner, admin, member}（Stage 0 仅写 owner，schema 已支持其余）
- remove(workspace_id, user_id) → bool（rowcount > 0）
- list_by_user(user_id) 按 joined_at desc
- list_by_workspace(workspace_id) 按 joined_at asc
- get_role(workspace_id, user_id) → str | None
- change_role(workspace_id, user_id, new_role) → bool
MembershipValidationError 自定义异常（role 非法）。
8 test 覆盖：
- add → get_role round-trip
- remove 命中/未命中返回 True/False
- 同 workspace 第 2 个 owner 触发 IntegrityError（partial unique）
- 同 workspace 多个 admin 不触发（Stage 2 forward compat）
- CASCADE: 删 user 自动清理 memberships
- list_by_user 按 joined_at desc 排序（多 workspace）
- role 校验拒绝 'viewer'
- change_role 命中改值 + 未命中返 False
注：owner 转让需要事务内两行原子 swap（先把现 owner 改 admin，再把新 owner
插 owner），放 PR4+ auth router 内做带权限检查的版本；本仓储不暴露
transfer_ownership 方法以保持单一职责。
Stage 0 PR3 T3.7。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:13:52 +08:00
a40df03521
feat(persistence): WorkspaceRepository + 23 unit tests
...
新建 backend/packages/harness/deerflow/persistence/workspace/sql.py，方法：
- create(name, slug, owner_id, *, workspace_id=None, status='active')
UUID v4 自动生成；强校验 slug 格式（regex ^[a-z0-9](-?[a-z0-9])*\$ + 3-32
长度）+ slug 黑名单（25 个保留字）+ status 枚举
- get(workspace_id, *, user_id=AUTO) JOIN workspace_memberships 做成员校验；
user_id=None 显式 bypass（迁移/admin）
- get_by_slug(slug) 不带成员校验（path-based routing 用：先 slug→workspace_id
再到 route handler 里查成员）
- list_by_user(*, user_id=AUTO) 列 user 所属所有 workspace
- update_status / delete platform-admin 操作，不带成员校验
WorkspaceValidationError 自定义异常（slug 格式 / 黑名单 / status）。
23 test 覆盖：
- CRUD smoke + get_by_slug missing
- 重复 slug → IntegrityError
- 8 个 invalid slug pattern（短/长/大写/空格/破折号位置/连续破折号/下划线）
- 6 个 blacklisted slug
- status 状态机 + 非法值拒绝
- delete CASCADE 到 memberships（SQLite FK PRAGMA 已开启）
- get/list 成员过滤（user-A 看不见 user-B 的 workspace）
- list user_id=None 显式 bypass
全部在 SQLite ephemeral DB 上跑（< 1s）。partial-unique 双驱动验证留给 T3.8。
Stage 0 PR3 T3.4 + T3.5。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:11:28 +08:00
d2d2d29c34
feat(persistence): add WorkspaceMembershipRow ORM model
...
新建 backend/packages/harness/deerflow/persistence/workspace_membership/
{__init__.py, model.py}，注册到 Base.metadata。
WorkspaceMembershipRow schema（来自 workspace-schema-design §2.2 锁定版）：
- workspace_id String(36) FK workspaces.id ON DELETE CASCADE — PK part
- user_id String(36) FK users.id ON DELETE CASCADE — PK part
- role String(16) NOT NULL（Stage 0 仅写 'owner'，schema 允许 'admin'/'member'
为 Stage 2 RBAC 准备）
- invited_by String(36) FK users.id ON DELETE SET NULL nullable（Stage 2
invitation 流程用）
- joined_at DateTime(tz=True)
索引：
- idx_workspace_memberships_user (user_id, workspace_id) — 倒查索引让
/auth/me 列 user 所属 workspaces 走索引
- idx_one_owner_per_workspace partial UNIQUE on workspace_id WHERE role='owner'
—— 一 workspace 严格 1 个 owner；sqlite_where + postgresql_where 双驱动
并存（实测两边都识别）
Stage 0 PR3 T3.6（提前到 T3.4-T3.5 之前；WorkspaceRepository.list_by_user
等会 JOIN 这张表）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:09:19 +08:00
8323bf68d2
feat(persistence): add WorkspaceRow ORM model
...
新建 backend/packages/harness/deerflow/persistence/workspace/{__init__.py, model.py}
+ 在 persistence.models.__init__ 注册 WorkspaceRow 让 Base.metadata.create_all
能自动建表。
WorkspaceRow schema（来自 workspace-schema-design §2.1 锁定版）：
- id String(36) PK（UUID v4 字符串，与 users.id 对齐）
- name String(64) NOT NULL（显示名）
- slug String(32) NOT NULL UNIQUE（URL 标识，正则 ^[a-z0-9](-?[a-z0-9])*$）
- status String(16) default 'active'（active/suspended/deleted）
- owner_id String(36) FK users.id ON DELETE RESTRICT（删 owner 时阻拦，
必须先转让所有权）
- created_at / updated_at DateTime(tz=True)
每列 + 表都带中文 comment（沿用 commit 9ff79055noreply@anthropic.com >
2026-05-12 21:07:30 +08:00
f63089aea8
feat(runtime): add workspace_context module + tests
...
新建 backend/packages/harness/deerflow/runtime/workspace_context.py，仿
user_context.py 的 API 形态：
- CurrentWorkspace Protocol（要求 .id: str + .role: str）
- _current_workspace ContextVar + set/reset/get/require
- DEFAULT_WORKSPACE_ID = "default" + get_effective_workspace_id（fallback
友好，不抛错；用于文件系统路径）
- AUTO 哨兵 + resolve_workspace_id 三态（AUTO/str/None）
与 user_context 的区别：CurrentWorkspace 额外要求 .role 字段，让 Protocol 同时
约束"workspace 是哪个"和"caller 在该 workspace 内的角色"（Stage 0 只见 'owner'，
Stage 2 RBAC 打开 admin/member）。
backend/tests/test_workspace_context.py 16 个 test，覆盖：
- 4 个 set/reset/require 行为
- 3 个 Protocol structural check（接受 .id+.role / 拒少 .role / 拒少 .id）
- 4 个 get_effective_workspace_id（含 UUID → str 强转）
- 5 个 resolve_workspace_id 三态（AUTO/AUTO 无 ctx 抛错/explicit str/explicit
None/AUTO 强转 str）
Stage 0 PR3 T3.1 + T3.2。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-12 21:04:49 +08:00
cbbb83a706
docs(impl): STATUS update after PR2 live verification on RDS
...
PR1 + PR2 已 live 验证：远程 Aliyun RDS (PostgreSQL 17.9) 上 9 张表
(DeerFlow 5 + LangGraph 4) 全部 create_all 成功。
记 3 个 PR2 follow-up commits（不在原 plan task list 但 live 必需）：
- testcontainers image 16→17 对齐 RDS 大版本
- serve.sh auto-add --extra postgres 防 uv sync 卸 asyncpg
- async_provider 剥 +asyncpg dialect 前缀让 LangGraph saver 能解析 URL
更新"一句话状态" + 标 PG live 验证（区分 testcontainers 路径仍未实跑）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 18:01:22 +08:00
39f8e117e8
fix(checkpointer): strip SQLAlchemy dialect prefix before passing to LangGraph
...
DeerFlow 用同一个 \`postgres_url\` 喂两条路径：
- SQLAlchemy 引擎（需 \`postgresql+asyncpg://\`）
- LangGraph AsyncPostgresSaver（psycopg 直连，需 libpq 风格 \`postgresql://\`）
PR2 把 .env / config.example.yaml 默认 URL 改成 \`+asyncpg\` 形态后，LangGraph
saver from_conn_string 会被 psycopg parser 直接抛 ProgrammingError
'missing "=" after "postgresql+asyncpg://..."'。
修：在 async_provider.py 传给 AsyncPostgresSaver 之前用正则剥掉
\`postgresql+\\w+://\` → \`postgresql://\`。一行修复，让同一个 URL 同时满足
SQLAlchemy 和 LangGraph 两条路径。
实测：make dev-daemon 起 gateway 成功，远程 RDS 上 9 张表（DeerFlow 5 +
LangGraph 4）全部 create_all 出来。
Stage 0 PR2 follow-up（不在原 plan task list 内，是 live make dev 触发的）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 17:54:57 +08:00
bdef6c6b9f
fix(serve): auto-install postgres extras when config.yaml selects postgres
...
scripts/serve.sh 在 \`uv sync --quiet\` 前 grep config.yaml 探测
\`database.backend: postgres\`；若是则追加 \`--extra postgres\`，否则保持原状。
修一个 PR1+PR2 没覆盖到的隐患：serve.sh 每次 dev 启动都跑 uv sync，会把
之前手动 \`uv sync --extra postgres\` 装的 asyncpg 卸掉，导致 gateway
启动时 ImportError。
Stage 0 PR2 follow-up（不在原 plan task list 内，是 live 验证时发现）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 17:35:23 +08:00
7f17cb8fee
chore(test): bump testcontainers Postgres to 17-alpine
...
\`make doctor\` 实测远程 Aliyun RDS = PostgreSQL 17.9。把
backend/tests/fixtures/postgres.py 的 testcontainers 镜像从
postgres:16-alpine 调到 postgres:17-alpine，与生产对齐。
同步把 STATUS.md "RDS 大版本对齐" 项标 done。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 17:29:16 +08:00
ad22242ecc
docs(impl): add Stage 0 progress dashboard (STATUS.md)
...
新增 docs/multi-tenant-redesign/03-impl/STATUS.md 作为 Stage 0 唯一的"现在
到哪了"权威来源：
- 8 PR 状态表（PR0-PR2 ✅ merged，PR3-PR8 🟡 pending）
- 用户必须跟进的事（live PG 实跑 / RDS 大版本对齐 / push origin / LOCK
review / 远程 RDS 密码轮换）
- 跳过/推迟的子任务（T1.10 docker-pending、T2.7 acked、T2.8 optional
skipped、T2.9 backend/CLAUDE.md 待补）
- 即将遇到的开放问题（PR4 alembic baseline / _ensure_admin_user 现状 /
PG 大版本）
- PR3 模式选择 trade-off（Inline vs Subagent-Driven）
- 维护规则：完成 PR 后必更新；新 session 首先读本文件
填补 plan/impl notes 之外的空白：plan 是静态的，impl notes 是 per-PR
快照；STATUS 是跨 PR 的执行状态视图。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 16:44:09 +08:00
1112a1971b
docs(impl): PR2 implementation note + acceptance checklist
...
记录 Stage 0 PR2 的实施落点、关键 LOCK 决策、跟进项与 7 commit 列表。
验收：3087 passed + 23 skipped + 0 failed（vs PR1 基线 3085 + 2 新
default-backend 测试）。
Stage 0 PR2 T2.10. PR2 完成。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 09:23:16 +08:00
c53295dfee
docs(readme): add Database backend section in Quick Start
...
Quick Start 加 Step 3 "Database backend (Stage 0+ defaults to Postgres)"：
- 说明 config.example.yaml 默认 postgres + DATABASE_URL 写 .env
- 给本地 dev 起 docker compose postgres 一行命令
- 提示 make doctor / make dev preflight 行为
- <details> 折叠 SQLite fallback 说明（offline dev 用）
Stage 0 PR2 T2.9（README 部分；backend/CLAUDE.md follow-up）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 09:20:26 +08:00
745a33e05d
chore: T2.7 acknowledgement (covered by T1.8)
...
Plan T2.7 = "setup_wizard.py 推荐 postgres，引导填 DATABASE_URL"。
T1.8 commit eae01901noreply@anthropic.com >
2026-05-11 09:17:51 +08:00
83b680b2ea
feat(check): postgres preflight in scripts/check.py
...
新增 check_postgres_preflight() —— make dev 链 (check.py → serve.sh) 的最后一道
preflight：
- config.yaml 不存在 → silent skip（让 setup_wizard 引导）
- backend != postgres → silent skip
- DATABASE_URL 未设 → FAIL with hint
- postgres 设了但 host:port 3s socket 不通 → FAIL with 启 docker 提示
- 通则 OK + 显示 host:port
不在 serve.sh 里加：Makefile 已经把 check.py 串在 serve.sh 之前，FAIL 会
自然阻断启动；避免 bash + python 两处实现 PG 探测。
doctor.py 的 check_database 是事后诊断（make doctor）；本 check 是事前
preflight（make dev/start）—— 互补。
Stage 0 PR2 T2.6.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 09:17:19 +08:00
3e62a0f6ef
feat(docker): gateway depends_on postgres healthcheck (dev only)
...
dev compose gateway 段加 depends_on: { postgres: { condition: service_healthy } }，
确保 postgres 通过 pg_isready 后 gateway 才启 uvicorn。
prod compose 不动：production 用远程 RDS（不在 compose 内），无 postgres
service 可 depend；docker-compose.yaml 不加此 depends_on。
YAML 通过 docker compose config 校验。
Stage 0 PR2 T2.5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 09:13:44 +08:00
d312bdf968
test(config): pin default postgres backend + sqlite regression
...
新建 backend/tests/test_default_database_backend.py 两个测试：
- test_explicit_sqlite_backend_still_works (T2.3)
显式 database.backend=sqlite 仍生效；防 PR2 改默认后 SQLite 用户
悄无声息 regression
- test_config_example_default_backend_is_postgres (T2.4)
直接读 on-disk config.example.yaml，断言 database.backend == 'postgres'
且 postgres_url == '\$DATABASE_URL'（不允许硬编码凭据）
Stage 0 PR2 T2.3 + T2.4.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 09:12:28 +08:00
7d3d3560ad
feat(env): activate DATABASE_URL with local-dev default
...
.env.example DATABASE_URL 行从注释改为活值（指向 docker compose 起的本地
postgres）。同时加 RDS 示例注释作为参考。psycopg2 风格 URL 升级到
postgresql+asyncpg:// 与 SQLAlchemy 异步 dialect 对齐。
Stage 0 PR2 T2.2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-11 04:24:32 +08:00
404135a16a
feat(config): default database backend to postgres
...
config.example.yaml database 段：postgres 成为活跃默认（postgres_url=\$DATABASE_URL），
SQLite 改为注释掉的 fallback 块（offline dev 用）。bump config_version 9→10。
为什么默认改 postgres：Stage 0+ 已要求 ALTER 4 张表加 workspace_id；
SQLite 加列后再迁 PG 是返工。Stage 0 没有生产数据，迁移阻力最小。
Stage 0 PR2 T2.1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 23:03:52 +08:00
85a14f4c05
docs(impl): PR1 implementation note + acceptance checklist
...
记录 Stage 0 PR1 的实施落点、关键 LOCK 决策、fixture 用法示例、跟进项与
10 commit 列表。验收：3085 passed + 23 skipped + 0 failed（无 regression），
PG smoke 在 docker daemon 起来后实跑（CI workflow 已配）。
Stage 0 PR1 T1.10. PR1 完成。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:58:21 +08:00
a33b46b4af
ci(postgres): add Postgres workflow running @pytest.mark.postgres tests
...
新增 .github/workflows/backend-postgres-tests.yml，独立于现有
backend-unit-tests workflow：
- GitHub runner (ubuntu-latest) 自带 docker daemon
- testcontainers 在 runner 上起 postgres:16-alpine 容器
- uv sync --extra postgres-test 拉 testcontainers + asyncpg + psycopg
- pytest -m postgres 仅跑 PG 标签的 4 个 smoke test (+ 后续 PR 增量)
为什么独立 workflow 而不是合到 backend-unit-tests：
- 现有 fast 测试不受 PG container 启动延迟影响
- 可独立 fail-soft（早期 Stage 0 rollout 期间需要时加 continue-on-error）
- fork 用户不强制承担 docker infra 成本
Stage 0 PR1 T1.9.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:55:53 +08:00
eae0190184
feat(wizard): add Postgres backend question to setup wizard
...
setup_wizard.py 在 Step 3 (Execution) 之后新增一个 Database 问答：
"Use Postgres? (y = postgres, n = sqlite)"，默认 y（Stage 0+ 推荐 PG）。
选 y 时引导填 DATABASE_URL（可留空稍后写 .env）；DATABASE_URL 进 .env，
config.yaml 写入 database.backend=postgres + postgres_url=\$DATABASE_URL。
writer.py build_minimal_config 加 database_backend 参数，postgres 时
覆盖 base_config 的 database 段；默认 sqlite 时沿用 base_config 行为
(继承 config.example.yaml 的 sqlite_dir 等)。
minimal pattern：不新建 wizard/steps/database.py，inline 在 main 里加 1
问答 + writer 加 1 参数。后续如果需要更复杂数据库选项再升为完整 step 模块。
Stage 0 PR1 T1.8.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:55:19 +08:00
e6f5ba53bd
feat(doctor): add Database section probing configured backend
...
scripts/doctor.py 新增 check_database()：
- sqlite → OK + 显示 sqlite_dir
- memory → WARN（数据非持久化）
- postgres → 解析 database.postgres_url 中的 \$DATABASE_URL，asyncpg
实际连接 + SELECT version() → OK with server version；连接失败时
FAIL 给出可执行 fix（启 docker compose postgres / 检查 DATABASE_URL）
- 未知 backend → WARN
Database section 插在 LLM Provider 与 Sandbox 之间。SQLite 部署不会触发
PG 探测（不破坏现有 dev 体验）。
Stage 0 PR1 T1.7.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:52:26 +08:00
8f480cd76f
test(persistence): postgres smoke tests for init_engine + ThreadMetaRepo
...
新建 backend/tests/test_postgres_smoke.py，4 个 test 用 postgres_url fixture：
- test_postgres_url_creates_isolated_database (T1.4)
asyncpg 直连验证 fixture 落到 test_<hex> DB
- test_postgres_url_isolates_between_tests (T1.4)
手动起第 2 个 DB 比对，证明每 test 隔离
- test_init_engine_postgres_creates_tables (T1.5)
init_engine('postgres', postgres_url) 跑完后 information_schema
出现 5 张现有表（users/threads_meta/runs/feedback/run_events）
- test_thread_meta_repo_postgres_round_trip (T1.6)
ThreadMetaRepository.create + get 完整 round-trip，验证 PG 上仓储行为
与 SQLite 对齐
全部 @pytest.mark.postgres 门控；Docker 不可用时由 fixture 跳过。本次本地
docker daemon 未起，4 测试 SKIP；CI workflow（T1.9）将带 docker service
触发实跑。
Regression：跑全套 `pytest tests/` 3085 passed + 23 skipped + 0 failed
（基线 3086 passed + 18 skipped；diff = 4 新 postgres skip + 1 env 相关
live test 偶发 skip）。
Stage 0 PR1 T1.4 + T1.5 + T1.6.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:50:10 +08:00
31361e2dcf
test(fixtures): add testcontainers Postgres fixture for Stage 0
...
新建 backend/tests/fixtures/postgres.py，提供两层 fixture：
- postgres_container (session 级)：用 PostgresContainer 起 postgres:16-alpine
- postgres_url (function 级)：每 test 一个 ephemeral DB，teardown 时
pg_terminate_backend 清掉残连后 DROP DATABASE
为什么 per-DB 而不是 per-schema：asyncpg + SQLAlchemy 不通过 URL 传 search_path，
per-DB 一次 ~50ms 开销可接受，让 test 代码不感知 schema。
Docker 不可用时 fixture 自动 pytest.skip 而非 error，dev 环境无 Docker
仍能跑其余 3086 个测试。
注册 pytest mark `postgres`、把 tests/ 加 sys.path 让 pytest_plugins
按 `fixtures.postgres` 路径解析（不加 tests/__init__.py 避免干扰
现有 pytest 发现行为）。
Stage 0 PR1 T1.3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:44:02 +08:00
ae4ea46be2
feat(docker): add postgres service to dev compose
...
新增 postgres:16-alpine service + named volume + healthcheck，作为 Stage 0+
默认 DB backend。生产可通过 DATABASE_URL 指向远程 RDS 时跳过此 service。
端口 / 用户 / 密码 / 库名都走 env var 覆盖（POSTGRES_USER/PORT/...
默认 deerflow/5432/deerflow_dev）。
YAML 通过 `docker compose config` 校验；live healthcheck 待 docker daemon 起后由
T1.3 testcontainers 路径覆盖。
Stage 0 PR1 T1.2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:40:12 +08:00
fab85b14a6
build(deps): add postgres-test optional extra for testcontainers
...
新增 postgres-test extra（harness + backend），引入 testcontainers[postgres]
4.14.2 用于 Stage 0 PR1 的 PG fixture。复用现有 postgres extra 的
asyncpg/psycopg/langgraph-checkpoint-postgres，pytest-asyncio 沿用 dev group。
Stage 0 PR1 T1.1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:38:50 +08:00
a74b88a45c
docs(superpowers): add Stage 0 multi-tenant foundation master plan
...
8 PR 串成的 stage-level 拆解（Postgres 切换 + workspaces schema + auth
扩字段 + 入口路由强校验 + CI boundary + headless schema 预留）。每个 PR
含 commit-sized TDD task list 和验收清单。执行时各 PR 独立 review
checkpoint。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 22:33:25 +08:00
89fe54cc07
docs(multi-tenant): 加入汇总索引、跨文档一致性修订、Postgres 切换前移到 Stage 0
...
* 新增 README.zh-CN.md 汇总索引：ADR 状态表 + Stage 0-4 业务目标 / 技术路径 /
验证方式 + Stage↔ADR 对照矩阵 + 不可逆决策一览 + 用语映射 + FAQ + 阅读路径
* 新增 workspace-schema-design.zh-CN.md（Stage 0 schema 锁定版）一并入库
* 7 份 ADR 顶部加"代码命名"映射行（tenant_id ↔ workspace_id）
* ADR-002 §1 加分期落地提示，明确 K8s 推迟到 Stage 3
* ADR-005 §5"第 1/2 阶段"补出与 rollout Stage 2/3 的映射
* ADR-007 §4 加 /api/v1/ 反向链接；§8 加 tid → wid 字段名映射
* headless-api §0/§7 把"SaaS + on-prem 双主线"改为"SaaS 主线、schema 兼容 on-prem"
* phased-rollout 去除重复的"Go/No-Go 进入 Stage 2"段
Postgres 切换从 Stage 1 提前到 Stage 0：Stage 0 已要 ALTER 4 张表加
workspace_id，先 SQLite 再 PG 是纯返工；Stage 0 没有生产数据，迁移阻力最小。
同步调整 phased-rollout / headless-api / phase-0-plan / workspace-schema-design /
README 中的时间盒（Stage 0: 3-4→4-5 周；Stage 1: 10-15→8-13 周）、不可逆决策
清单、PR 顺序、轨道前置依赖。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 21:39:58 +08:00
9ff790554d
docs(persistence): 给 ORM 表/字段补充中文注释
...
通过 SQLAlchemy 的 comment= 给 5 张持久化表（users / threads_meta / runs /
run_events / feedback）的所有字段以及表本身加上中文注释，便于读代码、
生成文档与未来切到 Postgres 时直接落库为 COMMENT ON。
SQLite 引擎本身不支持 COMMENT ON，运行时不会改变 .schema 输出。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 18:50:17 +08:00
ecc9339ede
docs(multi-tenant): 加入 Headless API 改造轨道（Pattern A/B）+ Stage 1 双轨修订
...
新增 headless-api-track 文档，把 DeerFlow 作为后端服务的两种集成
pattern 全部纳入设计：
- Pattern A（业务 backend 代理）：业务系统 backend 用 API key 调，
浏览器走他们的 backend。覆盖 IM channels + server-to-server 集成。
- Pattern B（自研 web 浏览器直连）：业务 backend 调
/api/v1/auth/exchange-token 换 5-15 min 短期 JWT → 浏览器拿 JWT 直连
含 SSE。核心 4 件事：exchange-token endpoint、ServiceTokenAuthBackend
（AuthMiddleware 第三条路径）、workspaces.allowed_origins + CORS
中间件、SSE 跨域验证。
- 不做 widget / iframe（纯 API）。
数据模型：service_accounts / api_keys / external_users 表（schema 在
Stage 0 末加上不阻塞）；身份模式三态（collapsed / external_passthrough
/ both）按 endpoint 分支。
Stage 1 改为三轨并行：付费 SaaS / Pattern A / Pattern B；时间盒从
6-10 周延到 10-15 周。Pattern B 依赖 Pattern A 完成，建议 Stage 1
末 1-2 周做。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 23:29:46 +08:00
fd8d0d637d
docs(multi-tenant): 加入 Stage 0 代码地图
...
把 Stage 0 必做项落到具体文件 + 行号，覆盖 7 个子系统：
auth、user 数据模型、thread 入口路由、ThreadDataMiddleware + 路径系统、
仓储访问模式、setup / 注册流程、CSRF + ContextVar 注入。
文档结构：每节有【关键文件 + 行号】、【关键函数 / 类】、【当前数据流】、
【Stage 0 改动锚点】；外加改动影响面总览（每条 Stage 0 必做项映射到
具体代码位置）、不可逆决策落点、推荐阅读顺序（11 个文件，1.5-2.5h
粗读）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 23:29:27 +08:00
35ae97d0a6
docs(multi-tenant): Stage 2 加入 per-user skill 覆盖与 config 设计
...
补充团队 workspace 内不同成员的 skill 区分模型：
- 启用状态：workspace 级默认 + per-user 覆盖
(final_enabled = user_override ?? workspace_default)
- skill 私有配置（API key 等）：per-user 强制隔离 + KMS 加密
- 上传权限：仅 owner / admin，成员只能 enable/disable + 填自己 config
PR 顺序新增第 8 步，依赖 RBAC + KMS 已就位。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 22:47:05 +08:00
e78ed687a6
docs(multi-tenant): 加入按规模分期的落地方案（02-rollout）
...
基于已收敛的目标客户画像（个人用户为主 + 小团队 / 中心化 SaaS /
freemium）把 7 份 ADR 拆成 5 期落地：
- Stage 0：workspace 模型立起来 + auth 收紧（不可逆决策集中在此）
- Stage 1：Postgres + Quota 必落（freemium 不上 quota = 信用卡递给攻击者）
- Stage 2：DeerFlow 表 RLS、KMS、ObjectStorage S3、付费分层
- Stage 3：K8s sandbox + BYO key + audit DB 拆分
- Stage 4：SSO / custom domain / per-tenant DB（按 enterprise 客户合同驱动）
关键取舍：① Stage 0 末就把 workspace_id 列加到 SQLite，避免 Stage 1
切 Postgres 时再补；② Quota 比 ADR-003 原稿提前一档到 Stage 1；③ K8s
sandbox 推到 Stage 3，AioSandbox + 出网白名单 + 资源限额撑到几千用户。
时间盒：最小可付费 4 个月（Stage 0+1）/ 风险可控增长 8 个月（+Stage 2）
/ 全功能 14 个月（+Stage 3）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 22:28:55 +08:00
8bdd308ea0
docs(multi-tenant): 据审计对齐 ADR-002/003/004/005 与 phase-0 计划
...
非 spike 驱动的对齐改动：
- ADR-002/004/005：头部加现状提示 + 链接审计报告（沙箱出网/资源缺位、
token_version 已存在 MembershipCache 全新建、ObjectStorage/7 表/KMS
全部从 0 起）
- ADR-003 LLM 计费：修正 TokenUsageMiddleware 当前只 log 不持久化的描述；
补充 create_chat_model sync→async 改造的连带影响说明
- phase-0 计划：新增 §3.5 底座先行（Postgres 测试夹具 / ObjectStorage
Protocol / KMS 抽象 3 件并行做），时间盒 2 → 3 周；ADR-006/007 摘要
对齐；DoD 加底座骨架检查项
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 21:03:32 +08:00
1445043649