Add MincedPad design spec for self-hosted share notepad.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-14 12:21:10 +08:00
commit 198a321c51
1 changed files with 242 additions and 0 deletions
@@ -0,0 +1,242 @@
+# MincedPad Design Spec
+
+**Date:** 2026-07-14  
+**Project:** MincedPad — 自托管公共数据共享与记事本平台  
+**Status:** Draft for review
+
+## 1. Overview
+
+MincedPad is a lightweight, self-hosted web tool for anonymously pasting text and uploading files, then sharing via a public wall and/or a direct link. No registration is required for visitors. An admin password gate provides moderation (delete content, ban IPs).
+
+### Goals
+
+- Zero-login create / share / view
+- Public wall by default, optional link-only
+- Markdown text + common file upload/preview/download
+- TTL (default 24h) and burn-after-read
+- Docker Compose one-shot deploy, low resource use
+- Rate limit, upload size cap, admin moderation
+
+### Non-goals (v1)
+
+- Multi-admin RBAC / audit export
+- Multi-node / object-storage backends
+- Real-time WebSocket wall updates
+- End-to-end encryption (content is readable by the server)
+
+## 2. Decisions (confirmed)
+
+| Topic | Choice |
+| --- | --- |
+| Name | MincedPad |
+| Stack | FastAPI + Vue3 + Element Plus SPA |
+| Architecture | Monorepo; frontend built into backend static hosting; one container |
+| Storage | SQLite metadata + local `data/uploads/` files |
+| Visibility | Default public on wall; optional “link only” |
+| Expiry | Default 24h; options 1h / 24h / 7d / never; optional burn-after-read |
+| Admin | Single password via env → JWT |
+| Rate limit | 2 create/upload requests per IP per second |
+| Max file | 200 MB (env configurable) |
+
+## 3. Architecture
+
+```
+Browser (Vue3 + Element Plus)
+        │
+        ▼
+ FastAPI (single process)
+  ├── /api/*          JSON API
+  ├── /admin UI routes (SPA)
+  ├── /*              SPA static (dist/)
+  ├── SQLite          data/mincedpad.db
+  └── Files           data/uploads/<random>
+  └── Cleaner thread  expire + burn cleanup
+```
+
+### Repository layout
+
+```
+MincedPad/
+├── backend/
+│   ├── app/
+│   │   ├── main.py
+│   │   ├── config.py
+│   │   ├── db.py
+│   │   ├── models.py
+│   │   ├── schemas.py
+│   │   ├── api/
+│   │   │   ├── public.py
+│   │   │   └── admin.py
+│   │   ├── services/
+│   │   │   ├── items.py
+│   │   │   ├── storage.py
+│   │   │   ├── rate_limit.py
+│   │   │   ├── bans.py
+│   │   │   └── cleaner.py
+│   │   └── security.py
+│   ├── requirements.txt
+│   └── Dockerfile
+├── frontend/
+│   ├── package.json
+│   ├── vite.config.ts
+│   └── src/
+│       ├── views/     # Home, ItemDetail, Admin
+│       ├── api/
+│       └── components/
+├── data/              # runtime volume (gitignored)
+├── docker-compose.yml
+├── README.md
+└── docs/superpowers/specs/
+```
+
+### Runtime
+
+- Default listen `:8080`
+- Compose mounts `./data:/data`
+- Env: `ADMIN_PASSWORD`, `SECRET_KEY`, `MAX_UPLOAD_MB=200`, `RATE_LIMIT_PER_SECOND=2`
+
+## 4. Data model
+
+### `items`
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| id | INTEGER PK | |
+| slug | TEXT UNIQUE | short public id (e.g. nanoid) |
+| kind | TEXT | `text` \| `file` |
+| title | TEXT | optional; default from first line or filename |
+| body | TEXT NULL | markdown/plain for text items |
+| file_name | TEXT NULL | original name |
+| file_path | TEXT NULL | relative path under uploads |
+| mime | TEXT NULL | |
+| size_bytes | INTEGER NULL | |
+| is_public | BOOLEAN | true = on wall; false = link only |
+| burn_after_read | BOOLEAN | |
+| expires_at | DATETIME NULL | null = never |
+| created_ip | TEXT | |
+| created_at | DATETIME | |
+| view_count | INTEGER | |
+| burned | BOOLEAN | true after burn consumed |
+
+### `banned_ips`
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| ip | TEXT PK | |
+| reason | TEXT | |
+| created_at | DATETIME | |
+
+Admin auth uses signed JWT (HS256) with `SECRET_KEY`; no separate sessions table in v1.
+
+## 5. API
+
+### Public
+
+| Method | Path | Description |
+| --- | --- | --- |
+| POST | `/api/items` | Create text item (JSON) |
+| POST | `/api/items/upload` | Create file item (multipart) |
+| GET | `/api/items/wall` | Paginated public wall (`page`, `page_size`) |
+| GET | `/api/items/{slug}` | Get item metadata + text body; may burn |
+| GET | `/api/items/{slug}/file` | Download/inline file |
+
+Create body (text) fields: `body`, `title?`, `is_public` (default true), `burn_after_read` (default false), `ttl` (`1h`\|`24h`\|`7d`\|`never`, default `24h`).
+
+Upload form fields: file + same options.
+
+Errors: `413` too large, `429` rate limited, `403` banned IP (writes), `404` missing/expired/burned.
+
+### Admin (Bearer JWT)
+
+| Method | Path | Description |
+| --- | --- | --- |
+| POST | `/api/admin/login` | `{ password }` → `{ token }` |
+| GET | `/api/admin/items` | All items, newest first |
+| DELETE | `/api/admin/items/{id}` | Force delete + file |
+| GET | `/api/admin/bans` | List bans |
+| POST | `/api/admin/bans` | `{ ip, reason? }` |
+| DELETE | `/api/admin/bans/{ip}` | Unban |
+
+## 6. Frontend
+
+### Pages
+
+1. **Home `/`**  
+   - Composer: Markdown textarea (Element Plus) + drag-and-drop upload zone  
+   - Options: TTL select (default 24h), burn-after-read switch, link-only switch  
+   - Actions: “发布文本” / 上传后自动生成结果  
+   - Result: copyable share URL  
+   - Wall: recent public items (poll every ~15s or on focus)
+
+2. **Detail `/p/:slug`**  
+   - Text: Markdown render  
+   - Image MIME: inline preview  
+   - Other files: download button (+ optional content-disposition inline for pdf when safe)  
+   - Burn warning before first view if applicable
+
+3. **Admin `/admin`**  
+   - Password login  
+   - Table of items with delete  
+   - Ban IP form + ban list with unban
+
+### UX constraints
+
+- Anonymous-first: landing page is immediately editable  
+- Clear toasts for size/rate/ban failures  
+- Friendly 404 for expired/burned content  
+
+## 7. Security & limits
+
+- **Upload cap:** default 200 MB via `MAX_UPLOAD_MB`  
+- **Rate limit:** 2 create/upload ops per IP per second (in-memory sliding window; acceptable for single-node)  
+- **Ban list:** banned IPs cannot create/upload; wall and read still allowed unless later tightened  
+- **Filename:** store as random UUID + safe extension; never trust client path  
+- **Extension allowlist (v1):** common images (`png/jpg/jpeg/gif/webp/svg`), text/docs (`txt/md/pdf/doc/docx/xls/xlsx/ppt/pptx/csv`), archives (`zip/7z/tar/gz/rar`), plus `json`  
+- **Admin:** `ADMIN_PASSWORD` required at startup in production; JWT expiry 12h  
+
+## 8. Background cleanup
+
+A lightweight loop (async task or thread) every 60s:
+
+1. Delete items where `expires_at < now`  
+2. Delete burned items already marked and past grace (immediate delete on burn read is OK)  
+3. Remove orphan files if item row gone  
+
+## 9. Docker / deploy
+
+```yaml
+# conceptual
+services:
+  mincedpad:
+    build: .
+    ports: ["8080:8080"]
+    environment:
+      ADMIN_PASSWORD: "change-me"
+      SECRET_KEY: "change-me"
+      MAX_UPLOAD_MB: "200"
+      RATE_LIMIT_PER_SECOND: "2"
+    volumes:
+      - ./data:/data
+    restart: unless-stopped
+```
+
+Multi-stage Dockerfile: build frontend → copy `dist` into backend image → run uvicorn.
+
+## 10. Acceptance criteria (v1)
+
+1. Unauthenticated users can create text and upload files and receive a share URL.  
+2. New items are on the public wall unless “link only” is set.  
+3. Default TTL is 24h; 1h / 7d / never and burn-after-read work.  
+4. Markdown renders; images preview; other allowed types download.  
+5. Admin can log in with env password, delete items, ban/unban IPs.  
+6. Uploads over 200 MB rejected; more than 2 create/upload requests per second per IP get 429.  
+7. `docker compose up -d` brings up a working instance on port 8080.
+
+## 11. Implementation order (for planning)
+
+1. Backend skeleton: config, DB models, create/get/wall, file storage  
+2. Rate limit + bans + cleaner  
+3. Admin auth + moderation APIs  
+4. Vue pages: Home, Detail, Admin  
+5. Docker multi-stage + compose + README  
+6. Smoke tests / manual acceptance checklist