Add initial framework of configuration.

feat: configuration file system of app. Note: still work in progress.
2026-04-27 16:55:58 +08:00
parent e8a0c48658
commit 54f0deadbc
9 changed files with 515 additions and 40 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,22 +1,67 @@
 # Architecture

-## Code Layout
+## Layered Design

 ```
-main.go              — entrypoint, calls cmd.Execute()
-cmd/                  — cobra commands (root + subcommands)
-internal/             — private application packages
-docs/                 — project documentation
+Handler (Gin handlers)          ← translates HTTP ↔ Service calls
+    ↓
+Service (business logic)        ← orchestrates, authorizes, validates
+    ↓                        ↓
+Repository (GORM data access)   Storage (file I/O)
+    ↓                        ↓
+[SQLite / PostgreSQL]        [Local FS / S3]
 ```

-## Packages
+Rules:
+- Handler has no business logic — parse request, call service, write response.
+- Service has no HTTP awareness — operates on domain models and interfaces.
+- Repository abstracts the database; Storage abstracts where bytes live.
+- `internal/server` is the composition root — wires all dependencies together.

-| Package | Purpose | Status |
-|---------|---------|--------|
-| `cmd` | CLI command definitions | ✅ skeleton |
-| `internal/config` | Configuration loading and parsing | ⬜ planned |
-| `internal/controllers` | HTTP request handlers | ⬜ planned |
-| `internal/auth` | Authentication (JWT) | ⬜ planned |
-| `internal/storage` | File storage abstraction | ⬜ planned |
+## Package Map

-Add new rows as packages are created.
+| Layer | Package | Purpose | Status |
+|-------|---------|---------|--------|
+| **CLI** | `cmd` | Cobra root command | ✅ skeleton |
+| | `cmd/serve.go` | `mygo serve` — wire deps, start HTTP | ⬜ plan |
+| | `cmd/config.go` | `mygo config` — config subcommand | ⬜ plan |
+| | `cmd/status.go` | `mygo status` — health check | ⬜ plan |
+| **Config** | `internal/config` | Viper load (YAML + env + flags) | ⬜ plan |
+| **HTTP** | `internal/server` | Gin engine init, route registration, middleware chain | ⬜ plan |
+| | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | ⬜ plan |
+| | `internal/middleware` | Gin middleware (requestid, logger, cors, auth) | ⬜ plan |
+| **Business** | `internal/service` | Business logic (auth, file, admin) | ⬜ plan |
+| | `internal/model` | Domain types (User, File, errors) | ⬜ plan |
+| **Data** | `internal/repository` | Repository interfaces + GORM implementations | ⬜ plan |
+| | `internal/storage` | Storage backend interface + local disk impl | ⬜ plan |
+| **Util** | `internal/auth` | JWT sign/verify, context helpers | ⬜ plan |
+| | `internal/api` | JSON response writer, error code helpers | ⬜ plan |
+
+## API Routes (v0)
+
+```
+POST /api/v1/auth/register
+POST /api/v1/auth/login
+POST /api/v1/auth/refresh
+
+GET   /api/v1/users/me
+PATCH /api/v1/users/me
+
+GET    /api/v1/files
+POST   /api/v1/files
+GET    /api/v1/files/:id
+GET    /api/v1/files/:id/content
+PUT    /api/v1/files/:id
+DELETE /api/v1/files/:id
+
+GET    /api/v1/admin/users
+GET    /api/v1/admin/users/:id
+PUT    /api/v1/admin/users/:id
+DELETE /api/v1/admin/users/:id
+```
+
+## Middleware Chain
+
+Applied globally: requestid → logger → cors
+
+Applied to protected groups: auth (JWT validation, inject user into gin.Context)
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -1,19 +1,28 @@
 # Technical Decisions

-Record significant technical decisions as they are made. Use the format below.
+## 2026-04-25: v0 Tech Stack & Architecture

-## Template
+**Context**: Project skeleton was created with only cobra CLI. We needed a concrete tech stack and package layout to begin implementation.

-```
-## YYYY-MM-DD: Title
+**Decisions**:

-**Context**: Why this decision was needed.
+| Area | Choice | Rationale |
+|------|--------|-----------|
+| HTTP framework | Gin | Most widely adopted Go web framework, mature middleware ecosystem |
+| ORM | GORM | SQLite-first dev, PostgreSQL option later; GORM abstracts dialect differences |
+| Config management | Viper | YAML + env vars + CLI flags three-way merge, built for cobra integration |
+| Database | SQLite (v0) → PostgreSQL (future) | SQLite zero setup for dev; repo interface isolates the switch |
+| File storage | Local disk (v0) → S3 (future) | Backend interface (`internal/storage`) hides implementation |
+| File identity | UUID | Distributed-friendly, no coordination needed; cost is negligible for file metadata |
+| Token strategy | JWT, refresh token stored in DB | Enables server-side revocation (admin kick, logout-all-devices) |
+| Pagination | OFFSET/LIMIT | Simple, sufficient for v0; migrate to cursor-based if needed |
+| API response format | `{code, message, data}` | Consistent envelope across all endpoints |

-**Decision**: What was decided.
+**Architecture**: Four-layer model — Handler (Gin) → Service (business logic) → Repository (GORM data access) + Storage (file I/O). Each layer depends only on interfaces of the layer below.

-**Consequences**: What this means for the project.
-```
-
-## Decisions
-
-*(None yet. Add entries as decisions are made.)*
+**Consequences**:
+- Handler layer has no business logic; Service layer is reusable across REST API, WebDAV, and future Nextcloud API.
+- Repository interfaces keep DB swappable; future PostgreSQL implementation only needs a new package.
+- Refresh token in DB adds a `sessions` table and a `repository.SessionRepository` interface.
+- UUID dependency: `github.com/google/uuid` to be added.
+- Gin middleware chain: requestid → logger → cors → auth (route-group-scoped).
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -1,24 +1,37 @@
 # Roadmap

-See `README.md` for high-level feature list. This file tracks detailed progress.
-
 ## v0

 | Feature | Status | Notes |
 |---------|--------|-------|
-| CLI config management | ⬜ planned | |
-| JWT authentication | ⬜ planned | |
-| File upload/download/manage APIs | ⬜ planned | |
-| Admin endpoints | ⬜ planned | |
-| WebDAV | ⬜ planned | |
+| CLI config management | ⬜ plan | |
+| JWT authentication | ⬜ plan | access + refresh tokens, refresh token in DB |
+| File upload/download/manage APIs | ⬜ plan | REST API via Gin |
+| Admin endpoints | ⬜ plan | user CRUD for superusers |
+| WebDAV | ⬜ plan | future v0 or v1 |
+
+## Implementation Tasks
+
+Package-level implementation order (each task includes unit tests):
+
+1. `internal/config` — Viper loader, config struct
+2. `internal/model` — domain types, error codes
+3. `internal/api` — JSON response helpers
+4. `internal/auth` — JWT utils
+5. `internal/storage` — backend interface + local fs
+6. `internal/repository` — interfaces + GORM/SQLite impl
+7. `internal/service` — auth, file, admin services
+8. `internal/middleware` — requestid, logger, cors, auth
+9. `internal/handler` — auth, file, admin handlers
+10. `internal/server` — Gin wiring, route registration
+11. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go`
+12. Integration tests

 ## Future

 | Feature | Status | Notes |
 |---------|--------|-------|
-| Image server | ⬜ planned | |
-| Pastebin & code snippets | ⬜ planned | |
-| S3 storage backend | ⬜ planned | |
-| Nextcloud-compatible API | ⬜ planned | |
-
-Update status after completing related work.
+| Image server | ⬜ plan | thumbnail generation |
+| Pastebin & code snippets | ⬜ plan | in sharing context |
+| S3 storage backend | ⬜ plan | new storage impl |
+| Nextcloud-compatible API | ⬜ plan | new handler layer on existing services |