docs: restructure server and web documentation into ADR files and a

routing table
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
@@ -0,0 +1,24 @@
+# ADR-0001: Use a Client-Rendered Web Foundation
+
+Status: Accepted  
+Date: 2026-07-14
+
+## Context
+
+MyGO needs a browser client and expects native clients to consume the same application API.
+
+## Decision
+
+- Build a client-side application with Vite, React, and strict TypeScript.
+- Use React Router for navigation and TanStack Query for remote state.
+- Use Ant Design for reusable controls and theme tokens.
+- Use Tailwind CSS for layout, spacing, and responsive utilities.
+- Keep business API contracts client-neutral.
+- Select additional dependencies when their feature is designed.
+
+## Consequences
+
+- Vite emits static assets for same-origin deployment.
+- The Web project contains no SSR, React Server Components, or Node application server.
+- Browser and native clients share the versioned REST API.
+- MyGO components own file-browser and transfer behavior; Ant Design supplies presentation controls.
@@ -0,0 +1,26 @@
+# ADR-0002: Implement Browser Auth and the Root File Workflow
+
+Status: Accepted  
+Date: 2026-07-14
+
+## Context
+
+The first Web milestone needed an authenticated workflow over the existing login, file listing, upload, and download APIs.
+
+## Decision
+
+- Use same-origin `/api/v1` requests.
+- Store the access and refresh token pair in `sessionStorage`.
+- Coordinate one refresh request across concurrent `401` responses.
+- Retry each failed protected request once after refresh.
+- Clear the session when refresh or the retry fails.
+- List root entries and upload one file at a time to the root directory.
+- Download authenticated file responses as browser blobs.
+
+## Consequences
+
+- Reloading the tab preserves the session; closing the tab clears it.
+- Query caches clear when the authenticated session ends.
+- Directories appear as non-interactive root rows in the first milestone.
+- Handwritten wire types remain until a shared OpenAPI contract is available.
+- Directory management and large-transfer workflows require later feature decisions.
@@ -0,0 +1,22 @@
+# ADR-0003: Keep Browser Testing Resources Project-Local
+
+Status: Accepted  
+Date: 2026-07-14
+
+## Context
+
+Browser tests and diagnostics run in a headless Debian development container. The toolchain needs repeatable versions and repository-scoped resources.
+
+## Decision
+
+- Use Playwright Test with bundled Chromium for repeatable E2E tests.
+- Keep E2E tests separate from `npm run check` because browser installation is an explicit setup step.
+- Run Chromium headlessly with profile isolation and sandboxing.
+- Store npm and browser caches under `.cache/`.
+- Store traces, screenshots, videos, and CLI output under `.artifacts/`.
+
+## Consequences
+
+- A fresh environment installs npm dependencies, browser libraries, and the pinned Chromium revision before browser work.
+- Browser failures can retain diagnostics without adding generated files to source control.
+- Repository configuration controls browser versions and artifact locations.
@@ -0,0 +1,12 @@
+# ADR-0004: Use Playwright MCP for Agent Debugging
+
+Status: Superseded by [ADR-0005](0005-playwright-cli-debugging.md)  
+Date: 2026-07-14
+
+## Historical Decision
+
+The project initially selected a repository-scoped Playwright MCP process for interactive agent debugging.
+
+## Current Guidance
+
+[ADR-0005](0005-playwright-cli-debugging.md) defines the current browser-debugging entry point. [ADR-0003](0003-project-local-browser-testing.md) defines the browser test and resource policy that remains active.
@@ -0,0 +1,23 @@
+# ADR-0005: Use the Pinned Playwright CLI for Agent Debugging
+
+Status: Accepted  
+Date: 2026-07-15
+
+## Context
+
+The Playwright MCP package introduced a second Playwright core, a second Chromium revision, and a larger agent tool surface. The pinned test runner provides the required interactive commands through its CLI.
+
+## Decision
+
+- Use the `playwright:cli` npm script as the browser-debugging entry point.
+- Use `@playwright/test` as the Playwright dependency for tests and diagnostics.
+- Use the bundled Chromium revision selected by the pinned package.
+- Load `.playwright/cli.config.json` for headless, isolated, and sandboxed execution.
+- Use the repository-scoped `$playwright-cli` skill for agent browser work.
+- Limit CLI output under `.artifacts/playwright-cli/`.
+
+## Consequences
+
+- E2E tests and interactive diagnostics share one Playwright core and Chromium revision.
+- The npm script isolates operators and agents from upstream CLI entry-point changes.
+- The repository skill keeps the main workflow concise and exposes detailed references on demand.