Initialize super-admin plan and task card
ci / svc-realcombo (pull_request) Successful in 2m26s
ci / test-pg (pull_request) Failing after 3m23s
ci / test (pull_request) Successful in 8m15s

Why: Set up the task card and approved implementation plan for environment-configured super-admin.

Evidence: make precheck and task-start validated.

Impact: Establishes task metadata and implementation baseline.

Refs: #0
This commit is contained in:
2026-10-19 01:41:12 +00:00
parent 4efb28443e
commit 5fa2ecbc74
2 changed files with 165 additions and 22 deletions
+41 -22
View File
@@ -1,6 +1,6 @@
# feature/super-admin 任务卡
任务主记录:<PR 链接,交付前填写>;状态:进行中;owner:weichen
任务主记录:待提 PR;状态:进行中;owner:weichen
## 基线与授权
@@ -9,17 +9,26 @@
- 分支类型:standalone;root_target:main;immediate_target:main;accepting_requirements:false
- 需求分流:verdict=NEW;selected_initiative=无;requirement_sha256=6d60f1f804e671045b7a395a470576eb8d89a9f30dda4b80885921b5296ca639;triage_receipt=/tmp/task-triage-super-admin.json;receipt_sha256=0018c29af8c89053d28c7163733bb37e4c9c21e344541bf805a8745f886b9048
- 授权与交付终点:<本次允许的动作与终点;未授权事项写明>
- 授权与交付终点:用户 2026-10-19 要求“按照方案开始实施”,依据 docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md。范围:将超级管理员建模为独立身份,覆盖 .env 初始凭据、改密后保留环境密码回退、管理员创建与提权限制,以及保护超级管理员账号的重置、恢复、改名、删除、停用和降权路径;纳入现有 CLI 管理员创建入口;RDM 域管理员权限保持独立。终点:完成 U1~U4 四个实施单元,通过对应单元测试、数据库测试、浏览器端验证、独立 Review、代码合入与安全清理。凭据不入仓。
- 交付模式:goal-first(目标、范围和交付终点一次确认;范围内连续推进)
- 实施执行:agent-per-unit(配置:AGENT-EXECUTION.md)
- 合入执行:agent(已授权交付范围内,Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入)
- 人工决策点:仅限目标/范围/验收变更、重大取舍、高后果操作或无法自动判定的业务验收
- 当前阶段:需求拆解;当前增量:I1(待定义)
- 当前阶段:实施与自检;当前增量:U1~U4
- 流程依据:仓库根目录 policy/delivery.md(归档后仍按仓库根目录定位)
## 目标与非目标
<预期结果、受影响入口/模块/契约;明确不做什么。>
- 目标:
1. 通过 .env 中 SUPER_ADMIN_OWNER 与 SUPER_ADMIN_PASSWORD 配置唯一的超级管理员身份(R1, R2);
2. 超级管理员改密后,支持新密码与 .env 回退密码登录,且回退密码不持久化(R6, R7);
3. 超级管理员可创建管理员或提权普通账号;普通管理员只能创建普通用户,所有服务端提权与管理创建路径均拦截普通管理员(R3, R4);
4. 保护超级管理员账号免受普通管理员重置、恢复、改名、删除、停用或降权,现有 CLI 创建入口纳入统一限制(R5);
5. UI 界面展示超级管理员身份并按权限显示管理员创建/提权控件(R8)。
- 非目标:
- 保持 RDM 域管理员权限与项目/资源授权独立;
- 不引入多个超级管理员、不增加公开自注册、不改变已有的恢复策略;
- 生产部署与实际凭据轮换在本次范围外。
## Agent 实施收据
@@ -27,40 +36,50 @@
| 单元 ID | 预期范围 | 配置摘要 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 |
|---|---|---|---|---|---|---|---|---|---|---|
| 待定义 | — | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
| dev-superadmin-u1-bootstrap | modules/backend/cmd/agent-system/main.go, modules/backend/internal/app/, modules/backend/internal/store/account_model.go, modules/backend/internal/store/migrate.go, modules/backend/internal/server/server.go, scripts/svc.sh | AGENT-EXECUTION.md | implementation | cursor → agy → pi | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
| dev-superadmin-u2-login-fallback | modules/backend/internal/server/accounts.go, modules/backend/internal/store/auth.go, modules/backend/internal/server/auth.go, modules/backend/internal/server/login_recovery_test.go | AGENT-EXECUTION.md | implementation | cursor → agy → pi | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
| dev-superadmin-u3-privilege-protection | modules/backend/cmd/agent-system/main.go, modules/backend/internal/app/, modules/backend/internal/server/accounts.go, modules/backend/internal/server/roles.go, modules/backend/internal/store/account_model.go, modules/backend/internal/store/role_policy.go, modules/backend/internal/authz/ | AGENT-EXECUTION.md | implementation | cursor → agy → pi | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
| dev-superadmin-u4-ui-surface | modules/backend/internal/server/accounts.go, modules/frontend/src/components/AdminZone.tsx, modules/frontend/src/components/AccountUsersPanel.tsx, modules/frontend/src/components/adminSections.tsx, modules/frontend/e2e/admin-user-create.playwright.ts, modules/frontend/e2e/iam-role-authority.playwright.ts | AGENT-EXECUTION.md | implementation | cursor → agy → pi | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
## 关联方向与规划
- 适用状态:待核对(无适用规划时说明原因)
- 主记录路径/版本:待核对(路径按仓库根目录定位,归档后不变;只引用唯一正文)
- 对应里程碑:待核对
- 适用状态:独立实施计划已完成评审(docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md)
- 主记录路径/版本:docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md
- 对应里程碑:U1(配置与引导)→ U2(回退登录与改密)→ U3(权限边界与保护)→ U4(UI 界面)
## 需求分析
| ID | 描述 | 项目符合度及依据 | 优先级 | 验收条件 | 依赖 | 结论 |
|---|---|---|---|---|---|---|
| R1 | 待填写 | 待评估 | 待定 | 待定义 | 待确认 | 待评审 |
| R1 | .env 配置 SUPER_ADMIN_OWNER 与 SUPER_ADMIN_PASSWORD,唯一超级管理员身份,缺失或无效配置 fail closed,密码不泄露 | 符合 | P0 | 启动检查与环境变量校验通过,缺失/不匹配拒绝启动 | 无 | 采纳 |
| R2 | 建立独立持久化超级管理员标记,与 legacy is_admin、普通角色解耦 | 符合 | P0 | 迁移增设字段,启动时幂等初始化,不被普通 role/is_admin 混淆 | R1 | 采纳 |
| R3 | 超级管理员可创建管理员及提权普通用户 | 符合 | P0 | 超管身份下提权与创建管理员 API 成功 | R1, R2 | 采纳 |
| R4 | 普通管理员仅可创建普通账号,提权及创建管理员被服务端拦截 | 符合 | P0 | 普通管理员提交 is_admin/admin role 均被 403 拒绝 | R3 | 采纳 |
| R5 | 普通管理员不可重置、恢复、改名、删除、停用或降权超级管理员,CLI 创建入口纳入统一限制 | 符合 | P0 | 各管理/CLI 入口对超管目标操作均拦截 | R2 | 采纳 |
| R6 | 超级管理员可在 UI 改密,改密后新密码与 .env 回退密码均可登录,回退密码不落库 | 符合 | P0 | 登录校验支持双凭据,改密后旧库密失效、新库密与环境变量密均可登入 | R1, R2 | 采纳 |
| R7 | 超级管理员登录失败遵循原有限流与会话版本策略,审计与安全策略完整 | 符合 | P0 | 登录限流、审计事件与会话版本测试通过 | R6 | 采纳 |
| R8 | 前端界面展示超级管理员标识,仅向超级管理员暴露提权/管理员创建控件 | 符合 | P0 | 前端 AccountUsersPanel/AdminZone 条件渲染,直接 API 调用亦受服务端保护 | R3, R4 | 采纳 |
## 方案与计划
- 方案引用:待填写(含对象版本)
- 实施计划引用:待填写(含增量与需求 ID)
- 测试计划引用:待填写(含需求 ID 与验收条件)
- 方案引用:docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md
- 实施计划引用:docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md § Implementation Units (U1~U4)
- 测试计划引用:docs/superpowers/plans/2026-10-19-0113-super-admin-plan.md § Verification Contract
## 阶段记录
| 阶段 | 对象版本 | 状态 | 决策/执行者 | 时间 | 依据 |
|---|---|---|---|---|---|
| 需求拆解 | 待定 | 待执行 | — | — | — |
| 需求评估 | 待定 | 待执行 | — | — | — |
| 需求表确认 | 待定 | 待执行 | — | — | — |
| 方案设计 | 待定 | 待执行 | — | — | — |
| 实施计划 | 待定 | 待执行 | — | — | — |
| 实施与自检 | 待定 | 待执行 | — | — | — |
| 正式测试与验收 | 待定 | 待执行 | — | — | — |
| 代码 Review | 待定 | 待执行 | — | — | — |
| 合入 | 待定 | 待执行 | — | — | — |
| 合入核验与收口 | 待定 | 待执行 | — | — | — |
| 需求拆解 | d9ac28f891 | 已完成 | host / 用户授权 | 2026-10-19T01:40:00Z | 用户指令及计划文档 |
| 需求评估 | d9ac28f891 | 已完成 | host | 2026-10-19T01:40:00Z | 计划文档 R1~R8 |
| 需求表确认 | d9ac28f891 | 已完成 | host | 2026-10-19T01:40:00Z | 计划文档 |
| 方案设计 | d9ac28f891 | 已完成 | host | 2026-10-19T01:40:00Z | 2026-10-19-0113-super-admin-plan.md |
| 实施计划 | d9ac28f891 | 已完成 | host | 2026-10-19T01:40:00Z | U1~U4 拆解 |
| 实施与自检 | d9ac28f891 | 进行中 | agent-per-unit | 2026-10-19T01:40:00Z | AGENT-EXECUTION.md |
| 正式测试与验收 | 待定 | 待执行 | host | — | — |
| 代码 Review | 待定 | 待执行 | 独立会话 | — | — |
| 合入 | 待定 | 待执行 | host | — | — |
| 合入核验与收口 | 待定 | 待执行 | host | — | — |
## 探索试验与迭代
@@ -0,0 +1,124 @@
---
title: Environment-configured super administrator
date: 2026-10-19
type: plan
artifact_contract: ce-unified-plan/v1
product_contract_source: ce-plan-bootstrap
execution: code
---
## Goal Capsule
- **Objective:** The system has one environment-configured super administrator who can appoint system administrators, while administrators can create ordinary accounts but cannot elevate accounts or reset the super administrator's password.
- **Means:** Add an explicit super-administrator identity and apply its authority in server-side authentication and account-management checks (KTD1).
- **Authority:** The user request in this session; preserve current project and RDM domain authorization boundaries.
- **Execution profile:** Implement in bounded Backend and Frontend units, with focused SQLite/PostgreSQL tests and browser coverage for changed account-management flows.
- **Stop conditions:** Stop when the requirements and direct verification pass. Do not change RDM domain-admin authority, general recovery policy, deployment state, or unrelated role capabilities.
- **Delivery owner:** Host owns planning, scope review, integration, authoritative verification, review, PR/CI, and safe closure under repository policy; implementation units use the configured agent-per-unit route.
## Product Contract
### Summary
Configure a single highest-privilege system administrator using credentials supplied through `.env`. This account may create administrator accounts or promote an existing account. Other administrator accounts may create ordinary accounts only and cannot reset the super administrator's password. The super administrator may change their password in the product; the configured environment password remains a separate fallback login credential.
### Problem Frame
The system currently has `is_admin` accounts and delegated system actions, but no distinct super-administrator identity. That makes it impossible to reserve administrator appointment and super-administrator protection to one bootstrap authority while retaining ordinary administrator account creation.
### Requirements
- R1. In authentication-enabled account-management deployments, exactly one system super-administrator identity is configured by `SUPER_ADMIN_OWNER` and `SUPER_ADMIN_PASSWORD` in the process environment sourced from the protected `.env` configuration. Missing, partial, invalid, or unavailable configuration must fail closed with a clear startup error; the unauthenticated embedded single-user mode must not expose account-administration operations. Secret values must never be logged or returned by APIs.
- R2. The configured identity is established as a distinct super-administrator in persistent account state. It is never inferred from legacy `is_admin`, a role, a project membership, or RDM domain-admin state.
- R3. The super administrator can create ordinary accounts and can create administrator accounts or promote an existing account to administrator.
- R4. An ordinary administrator can create ordinary accounts, but every server-side path that creates or grants administrator authority rejects that actor, regardless of UI visibility or supplied request fields.
- R5. An ordinary administrator cannot reset, recover, rename, delete, disable, or demote the super-administrator account through account-management or CLI paths. Ordinary administrators cannot change their own or another account's administrative authority through account creation, role assignment, system-grant APIs, or CLI commands. The super administrator can change their own password through R6 but cannot remove or transfer the unique super-administrator identity through product account-management paths.
- R6. The super administrator can change their password through the existing authenticated password-change flow. The changed password and configured environment fallback password both authenticate that same identity; changing the database password does not remove the fallback.
- R7. Failed super-administrator password checks follow the existing login throttling and session-version rules. Successful login and password changes continue to use HttpOnly sessions and existing credential/audit safeguards.
- R8. The UI identifies the super administrator and exposes administrator creation/promotion controls only to that identity. Server authorization remains authoritative.
### Scope Boundaries
- Preserve existing RDM domain-admin separation and project/resource authorization.
- Do not add multiple super administrators, self-registration, a new recovery channel, an alternate CLI administrator-bootstrap path, or production deployment/migration operations.
- Do not reduce unrelated permissions of delegated users beyond the account-elevation and super-administrator-protection rules in R4-R5.
## Planning Contract
### Key Technical Decisions
- KTD1. **Model super-administrator as a separate system identity flag.** Keep `is_admin` for compatibility and ordinary system-admin behavior, while a dedicated persisted marker identifies the single highest-privilege account. `is_admin` remains true for the super administrator, but never implies super-administrator status.
- KTD2. **Use the database password and environment fallback as two valid credentials for the configured owner.** Verify both only for the super-administrator identity, retain the environment secret only in process memory, and never overwrite it when the UI changes the database password.
- KTD3. **Enforce privilege boundaries on the server and within account-write transactions.** Apply one consistent super-admin-aware authorization rule to account creation, role assignment, system-grant changes, state changes, resets, and recovery entry points that can affect administrator or super-administrator authority.
- KTD4. **Bootstrap idempotently and fail closed on identity conflict.** Startup may establish the configured account and its initial password when absent or uninitialized; if the owner already belongs to another account or a second super-admin marker exists, startup must stop instead of silently promoting, replacing credentials, or creating a second authority.
### High-Level Technical Design
Backend startup reads the two required settings from `.env` through the supported runtime environment-file path, validates them, and passes an immutable secret-bearing configuration object into account initialization and the authentication service. The database stores the designated account identity and the ordinary password hash; the configured fallback is not persisted. Login checks the normal password hash first, then the fallback only when the requested owner matches the configured super administrator. Account authorization resolves the persisted marker from trusted server state and applies actor/target constraints before each write. Frontend account screens consume a server-provided `isSuperAdmin` field and conditionally show the elevation controls.
The Backend currently reads configuration from process environment but no dotenv parser was found. U1 must verify the actual service launcher and make its protected `.env` values available to the Backend through that supported runtime path. If no such path exists, add one narrowly scoped `.env` loading mechanism at the existing configuration boundary; do not silently fall back to missing credentials or duplicate parsing across modules.
### Assumptions
- `SUPER_ADMIN_OWNER` is a stable account identifier; renaming it or transferring super-admin authority is outside this change.
- `.env` remains protected from source control and has restrictive filesystem permissions in deployments.
- If the fallback secret is exposed, an operator must rotate `SUPER_ADMIN_PASSWORD` in `.env` and restart the service; the UI password change does not revoke this fallback.
- Existing account password hashing, password policy, lockout, session revocation, and audit mechanisms remain the authoritative primitives.
## Implementation Units
### U1. Configure and bootstrap the single super administrator
- **Goal:** Load validated super-administrator settings and establish exactly one persistent super-administrator identity without silently taking over a conflicting account.
- **Requirements:** R1, R2
- **Files:** `modules/backend/cmd/agent-system/main.go`, `modules/backend/internal/app/`, `modules/backend/internal/store/account_model.go`, `modules/backend/internal/store/migrate.go`, `modules/backend/internal/server/server.go`, `scripts/svc.sh`
- **Approach:** Trace and wire the protected `.env` startup path; pass credentials via a dedicated config boundary; add a schema migration and idempotent bootstrap operation; reject account-admin operations when authentication is disabled; keep secrets out of persistent storage, diagnostics, and JSON projections.
- **Test Scenarios:** Both values absent, only one present, invalid password, first bootstrap, repeated bootstrap, conflicting existing owner, duplicate marker, and legacy databases with administrators but no super administrator.
- **Verification:** Focused Backend config, store migration/bootstrap, and startup tests on SQLite and PostgreSQL.
### U2. Add fallback login and password-change behavior
- **Goal:** Let the configured super administrator authenticate with either the database password or the `.env` fallback, including after changing the database password in the UI.
- **Requirements:** R6, R7
- **Files:** `modules/backend/internal/server/accounts.go`, `modules/backend/internal/store/auth.go`, `modules/backend/internal/server/auth.go`, `modules/backend/internal/server/login_recovery_test.go`
- **Approach:** Extend the login verifier at the authentication boundary; fallback comparison is limited to the configured super-admin owner; retain current rate limiting, verified-session version checks, and normal password-change behavior.
- **Test Scenarios:** Initial environment password works; UI password change makes both new and fallback passwords valid; old database password stops working; fallback fails for every other owner; disabled/missing account and throttled attempts remain rejected.
- **Verification:** Focused login/password tests covering password-change session handling and audit effects, plus existing account serialization tests where verifier changes affect session races.
### U3. Enforce super-admin-only appointment and target protection
- **Goal:** Restrict admin creation/promotion to the super administrator and make the super-administrator account untouchable by ordinary admin maintenance paths.
- **Requirements:** R3, R4, R5
- **Files:** `modules/backend/cmd/agent-system/main.go`, `modules/backend/internal/app/`, `modules/backend/internal/server/accounts.go`, `modules/backend/internal/server/roles.go`, `modules/backend/internal/store/account_model.go`, `modules/backend/internal/store/role_policy.go`, `modules/backend/internal/authz/`
- **Approach:** Audit every account/admin elevation and target mutation route, including `user create --admin`, `user create --role admin`, and `user bootstrap-admin`; only configured startup bootstrap may establish the super administrator, and no CLI path may appoint another administrator. Enforce actor and target checks in the authorization/write boundary, including transactional rechecks for race safety. Preserve the ordinary-admin path for creating pending user accounts.
- **Test Scenarios:** Super admin creates/promotes admin; ordinary admin creates user; ordinary admin cannot create/promote admin by request payload, role assignment, grants, or CLI commands; neither ordinary admin nor legacy admin can reset/recover/rename/delete/disable/demote the super admin; super admin can change their own password but cannot transfer or remove the unique super-admin identity; auth-disabled mode exposes no account-administration operations; unauthorized and concurrent changes are rejected without partial writes.
- **Verification:** Focused account, role-policy, and recovery authorization tests on SQLite and PostgreSQL.
### U4. Surface identity and available account actions in the UI
- **Goal:** Make super-administrator status and allowed administrator-management actions clear in account-management screens.
- **Requirements:** R3, R4, R8
- **Files:** `modules/backend/internal/server/accounts.go`, `modules/frontend/src/components/AdminZone.tsx`, `modules/frontend/src/components/AccountUsersPanel.tsx`, `modules/frontend/src/components/adminSections.tsx`, `modules/frontend/e2e/admin-user-create.playwright.ts`, `modules/frontend/e2e/iam-role-authority.playwright.ts`
- **Approach:** Add a non-secret `isSuperAdmin` identity projection and show admin-create/promotion actions only for that user. Keep ordinary account creation available to authorized admins and avoid exposing environment credentials or fallback status details.
- **Test Scenarios:** In the primary `AccountUsersPanel`, super admin sees admin-promotion controls and can complete promotion; ordinary admin sees ordinary-account creation without elevation controls; direct API calls remain rejected when controls are hidden; layout remains usable at supported viewport sizes.
- **Verification:** Focused Frontend typecheck and Playwright coverage for the account-management flow.
## Verification Contract
| Scope | Verification | Proves |
|---|---|---|
| Backend account/auth changes | Focused `go test` packages under `modules/backend/internal/server`, `internal/store`, `internal/app`, and `cmd/agent-system` | Bootstrap, dual-credential login, account elevation boundaries, and compatibility |
| Database portability | Relevant PostgreSQL integration tests in the affected Backend packages | Migration/bootstrap and transactional authorization behavior on PostgreSQL |
| UI behavior | Focused Frontend typecheck and admin-user Playwright tests | Correct controls and browser-visible account flow |
| Final candidate | `make test` when required by the selected delivery tier and exact repository gate | Fixed Dev/component composition and repository-required checks |
No production deployment or live `.env` credential test is included in this plan. Runtime acceptance requires a separately authorized environment and must use test credentials without recording secret values.
## Definition of Done
- Exactly one environment-configured super administrator can be established, and startup rejects ambiguous or conflicting identity state.
- The super administrator can appoint administrators; other administrators can create ordinary accounts but cannot grant administrative authority.
- Ordinary administrators cannot mutate the super-administrator account through supported account-management or recovery paths.
- The super administrator can change the database password in the UI and can continue to log in with the configured fallback.
- Server tests, affected database coverage, focused browser verification, code review, and repository delivery gates pass for the exact candidate; secrets are absent from logs, responses, and committed files.
- Abandoned implementation attempts are removed, and no production deployment, credential rotation, or history-changing action is performed without its required authorization.