From 054eed50e94871eef3c075942dda2b98817adea2 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 21 Feb 2026 07:31:00 +0000 Subject: [PATCH] Initial commit: project plan --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4f95027..d85a0a0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,68 @@ -# HarborForge +# HarborForge Project Plan -Agent/人类协同任务管理平台 - Python/FastAPI + React + MySQL \ No newline at end of file +## Overview +HarborForge is a dual UI/automation platform where humans + AI agents operate through a unified issue-driven workflow. The plan below tracks the Python/FastAPI backend, React frontend, and Python CLI, designed to run on a 1 vCPU + 1 GB RAM Docker Compose stack with MySQL persistence. + +## Workstreams & Task Breakdown + +### 1. Architecture & Platform Foundation +- Document system components: API service, React SPA, Python CLI/bot runner, MySQL, webhook dispatcher, optional worker queue. +- Define communication contracts (REST+webhook) and env/secret management. +- Create Docker Compose template with lightweight images, explicit resource limits, and volumes for logs/database. +- Include `AbstractWizard` initializer as part of deploy script; link to `https://git.hangman-lab.top/hzhang/AbstractWizard` and capture expectations from its README. +- Set up logging/metrics hooks (stdout, log file rotation) and persistence directories on shared volume. + +### 2. Authentication & Role-Based Access +- Integrate OIDC standard login flow for UI; CLI uses credential files with no interactive login. +- Establish credential lifecycle: + - Credentials have expiry timestamps and remain in DB flagged as expired. + - On usage of expired credential, return new credential + confirmation requirement. + - Confirmation must reach backend within 1 minute. + - Any random reuse of old credential 3–5 times before confirmation results in deletion; future calls require re-authentication (password/OIDC) to issue a new credential. +- Store credential files via `--creds /path` or `HARBORFORGE_CREDENTIAL` env, support rotation via API. +- Define RBAC model per project (roles: admin/dev/mgr/ops); admin user created during initialization. +- Build admin-only endpoints/UI/CLI to manage roles, permissions, and project assignments. + +### 3. Core Issue/Work Item Platform +- Design issue model that supports multiple types (task/story/test), state transitions, dependencies, tags, priority, comments. +- Support multi-account/role membership per project and enforce permission matrix at API layer. +- Guarantee every user-facing action can be invoked via API/CLI. +- Catalog automation touchpoints (issue lifecycle updates, script triggers, deployment actions) for future extension. + +### 4. Frontend (React) +- Define app routes: dashboard, board/list, issue detail, role/project admin, audit/log viewer, automation console. +- Implement state management (React Query or equivalent) matching API structure. +- Provide UI components for admin role management + webhook configuration. +- Surface webhook events and automation status, letting users inspect audit entries. + +### 5. CLI & Automation Surface +- Build interactive Python CLI mirroring UI flows; commands are rendered differently but invoke same backend APIs. +- CLI uses credential files or env tokens; includes runtime prompts for confirmation when credential rotation occurs. +- Bot agent runner polls API for pending automations, executes scripts, and emits callbacks via webhook. +- Document CLI command set (issue CRUD, role management, automation triggers, logs) and error handling. + +### 6. API Coverage & Webhooks +- Enumerate APIs for all core operations: issues, comments, projects, roles, credentials, automation scripts, audit logs. +- Design webhook schema and catalog events to support: issue lifecycle, authentication events, automation/script completion. +- Ensure webhook delivery is authenticated and configurable; details to be defined during implementation. +- Provide API for credential confirmation flows and for requesting new credentials after deletion. + +### 7. Observability & Logging +- Log all API invocations to a file on Docker-mounted volume, capped at 10 MB with rotation. +- Keep a webhook audit log (which event, trigger source, response status) for troubleshooting. +- Provide endpoints/UI to browse recent logs (within retention threshold). + +### 8. Deployment & Security Posture +- Keep `ufw` locked down on `vps.t1` and rely on SSH tunnels (`ssh -L`) for UI/CLI testing. +- Document CLI/agent testing setup (SSH tunnel commands, env vars) so Zhi/Hangman can coordinate. +- Outline backup strategy for MySQL data directory within the Compose stack. +- Confirm `AbstractWizard` handles initial admin/project creation; fall back to Zhi if issues arise. + +### 9. Collaboration & Delivery Rhythm +- Maintain the new channel with templates for requirements, story cards, milestones, and progress updates. +- Use channel to publish deliverables (architecture doc, API spec, deployment instructions, automation scenarios). +- Record testing points for UI/CLI without prescribing steps; let Hangman/Zhi define the execution details. + +--- + +Need any section expanded into user stories or backlog cards next? \ No newline at end of file