feat(libs): create library by name only; root_path derived server-side as BOOKS_DIR/SafeName(name), validated at creation; drop root_path input from admin UI; align changelogs to bilingual template; trim AGENTS.md to rules not derivable from repo layout
This commit is contained in:
@@ -1,125 +1,34 @@
|
||||
# AGENTS.md
|
||||
|
||||
@github.com/XingfenD/AGENTS.md:content/basic_agents_md/AGENTS.md
|
||||
## Safety Rules
|
||||
- Dev branch naming: `{feat|fix|docs|chore}/{branch-name}` (e.g. `feat/file-tag-done`, `fix/tree-render`).
|
||||
- Before `git commit`: run `git branch --show-current`. If on `master`, do NOT commit — ask user for a branch name (suggest one based on the changes), create it, commit there.
|
||||
- Every user-visible change gets a changelog entry: WebUI changes (files under `frontend/`) → `docs/CHANGELOG_web.md`, everything else → `docs/CHANGELOG.md`; never duplicate an entry across both. Higher versions on top.
|
||||
- CHANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line.
|
||||
- `docs/README.md` and `docs/README_zh.md` stay content-equivalent; update them in the same change.
|
||||
|
||||
## Docker deployment (dev & release)
|
||||
|
||||
### Deployment mode
|
||||
|
||||
Mode differences (dev = `deploy/docker-compose.dev.yml`, release = `deploy/docker-compose.yml`):
|
||||
|
||||
- dev: source dirs bind-mounted into containers (`../backend:/app`, `../frontend:/app`, `../collab*`), `target: dev` images, workers run `go mod download && go run ./cmd/...`, hot reload without rebuild; also exposes infra ports to the host (postgres 5432, redis 6379, ES 9200, rabbit 5672) and a delve debugger on 2345, and gates startup on healthchecks.
|
||||
- release: multi-stage `*.prod` Dockerfiles (`target: runner`) with compiled binaries, no source mounts — Go services only get config files mounted; infra ports stay on the internal network only.
|
||||
|
||||
### Volume mounts
|
||||
|
||||
- Named volumes (both modes, shared): `{$project_name}_{postgres,redis,consul,rabbitmq,minio,elasticsearch}_data` persist infra state to Docker volumes — identical names across the two compose files, so dev and release see the same data. Only `down -v` (i.e. `rebuild`/`clear`) wipes them.
|
||||
- Config/log bind mounts (both modes): rendered outputs `deploy/nginx/nginx.conf`, `deploy/nginx/conf.d/default.conf`, `deploy/redis/redis.conf`, `deploy/rabbitmq/rabbitmq.conf` (`:ro`) plus `deploy/logs/{nginx,rabbitmq}` are mounted from the host — these come from `prepare.sh`, so stale files in the container mean you forgot to rerun it.
|
||||
- Source mounts (dev only): `../backend:/app` (which run `go mod download && go run ./cmd/...`), `../frontend:/app` with an anonymous volume on `/app/node_modules` (so the image's deps survive the mount — delete containers with `down`, not `rm`, to avoid orphaning it).
|
||||
- The File Storage mounts: if the backend stores uploaded files directly instead of in an object storage, mount `deploy/{$service_name}/storage` as the storage path into the container.
|
||||
- dev = `deploy/docker-compose.dev.yml`: source bind-mounted (`../backend:/app`, `../frontend:/app` with an anonymous volume on `/app/node_modules`), `target: dev` images; api runs `go mod download && dlv debug ./cmd/webui` (delve on 2345), web runs `npm run dev` (hot reload, no rebuild needed); infra ports exposed to host (postgres 5432, redis 6379); startup gated on healthchecks.
|
||||
- release = `deploy/docker-compose.yml`: multi-stage `*.prod` Dockerfiles (`target: runner`) with compiled binaries, no source mounts; infra ports stay on the internal network only.
|
||||
- Persisted state lives only in named volumes `booklib_{postgres,redis}_data` — same names in both files, so dev and release see the same data. Only `down -v` wipes them.
|
||||
- Books on disk: host `deploy/api/storage` is mounted as `/data/books` (`BOOKS_DIR`); uploads land there and the scanner picks them up.
|
||||
- Rendered configs `deploy/nginx/nginx.conf`, `deploy/nginx/conf.d/default.conf`, `deploy/redis/redis.conf` (mounted `:ro`) come from their `*.tpl` via `deploy/prepare.sh` — edit the template, rerun `prepare.sh`, restart; stale files in a container mean you forgot to rerun. Host logs under `deploy/logs/`.
|
||||
- Tear down with `down`, not `rm`, or the web image's anonymous `node_modules` volume gets orphaned.
|
||||
|
||||
## Project structure
|
||||
Root: `docs` (docs + changelogs), `backend` (Go webui service), `frontend` (node app, served via nginx in release), `deploy` (compose stacks, rendered configs, host logs). Actual layout is visible via `ls`; only rules not derivable from it are listed here.
|
||||
|
||||
Basically, the project consists of the directories `docs`, `backend`, `frontend`, `deploy`, plus optional `collab*` services:
|
||||
### backend
|
||||
- `cmd/`: each subdir is exactly one `main` package; `main.go` only bootstraps (load config, wire deps, serve, graceful shutdown) — no business logic, and nothing outside `cmd` imports `cmd`.
|
||||
- `cmd/webui/api` is the single source of truth for the endpoint contract; the frontend aligns with it.
|
||||
- Handlers stay thin (bind/validate, call `internal`, map errors) — never touch the DB or implement domain rules; SQL and business rules live behind `internal` boundaries.
|
||||
- Business code defaults to `internal/`; `pkg/` is opt-in public surface shared with other repos — keep it small, never leak `internal` types through it.
|
||||
|
||||
```plaintext
|
||||
.
|
||||
├── docs # project documentation (see Documents layout)
|
||||
├── backend # golang services (see backend layout)
|
||||
├── frontend # node web app, built and served via nginx (see frontend layout)
|
||||
├── collab* # optional collaboration services, same layout as backend
|
||||
├── deploy # compose stacks, rendered configs, host-side logs (see deploy layout)
|
||||
├── .gitignore # repo-wide ignores only; module-specific ignores live inside each module
|
||||
├── AGENTS.md # agent guidance for this repo
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
### Documents layout
|
||||
|
||||
The documents' layout is expected to be like below:
|
||||
|
||||
```plaintext
|
||||
docs
|
||||
├── CHANGELOG.md # general (non-WebUI) changes; highest version on top
|
||||
├── CHANGELOG_web.md # WebUI changes only; highest version on top
|
||||
├── README.md # primary (English) entry doc
|
||||
└── README_zh.md # Chinese mirror of README.md — keep in sync
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- Every user-visible change gets a changelog entry: WebUI changes → `CHANGELOG_web.md`, everything else → `CHANGELOG.md`; never duplicate an entry across both.
|
||||
- `README.md` and `README_zh.md` stay content-equivalent; update them in the same change.
|
||||
- Documentation lives only under `docs/` — no stray `*.md` at the repo root besides `AGENTS.md` and `LICENSE`.
|
||||
|
||||
### backend (golang)
|
||||
|
||||
```plaintext
|
||||
backend
|
||||
├── cmd # executable entry points, one dir per binary
|
||||
├── internal # private packages: importable only within this module
|
||||
├── pkg # public packages: intentionally shared with other repos
|
||||
└── .gitignore # .gitignore inside backend
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- `cmd`: each subdirectory holds exactly one `main` package; `main.go` only bootstraps — load config, wire dependencies, start the server/CLI, handle graceful shutdown. No business logic here, and nothing outside `cmd` imports `cmd`.
|
||||
- `internal`: default home for all business code (domain, services, storage, config). If code is not meant to be imported by other repos, it goes here, not in `pkg`.
|
||||
- `pkg`: opt-in public API surface — keep it small and stable, and never leak `internal` types through its APIs.
|
||||
|
||||
```plaintext
|
||||
cmd
|
||||
├── cli # command-line binary
|
||||
│ ├── commands # one file/package per subcommand: flag parsing + dispatch into internal
|
||||
│ └── main.go # arg parsing and subcommand dispatch only
|
||||
└── webui # HTTP server binary
|
||||
├── api # route registration + request/response DTOs — the endpoint contract, no logic
|
||||
├── constant # webui-only constants (routes, keys, limits)
|
||||
├── handlers # thin HTTP handlers: bind/validate input, call internal services, map errors
|
||||
├── main.go # boot the HTTP server
|
||||
├── static # assets served as-is by webui
|
||||
└── templates # server-side HTML templates rendered by webui
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- Handlers never touch the database or implement domain rules — they delegate to `internal`; SQL and business rules live behind `internal` boundaries.
|
||||
- `api` is the single source of truth for the endpoint contract; the frontend aligns with it.
|
||||
- Code shared between `cli` and `webui` belongs in `internal` (or `pkg`), never imported from one command by the other.
|
||||
|
||||
### frontend (node)
|
||||
|
||||
```plaintext
|
||||
frontend
|
||||
├── src # all hand-written app source: pages, components, state, API client
|
||||
├── public # static assets copied into the build output as-is
|
||||
├── package.json # dev/build/lint/test scripts, runnable unchanged inside the container
|
||||
└── .gitignore # node_modules/ and build output (e.g. dist/) never committed
|
||||
```
|
||||
|
||||
Constraints (framework-agnostic — any stack that keeps the layout above):
|
||||
- The app talks to the backend only over the HTTP APIs defined in `backend/cmd/webui/api` — no direct access to infra (DB, ES, rabbit) from the frontend.
|
||||
- Build output is disposable and git-ignored; committed sources live only in `src`/`public`; nginx serves the built assets in release.
|
||||
- Dev runs from the source mount (`../frontend:/app`) with `node_modules` provided by the image's anonymous volume — install new deps inside the container and commit the lockfile.
|
||||
### frontend
|
||||
- Talks to the backend only over the HTTP APIs in `backend/cmd/webui/api` — no direct infra access (DB, redis) from the browser app.
|
||||
- Build output (`dist/`) is disposable and git-ignored; only `src`/`public` are committed.
|
||||
- Dev runs from the source mount with `node_modules` provided by the image — install new deps inside the container and commit the lockfile.
|
||||
|
||||
### deploy
|
||||
|
||||
```plaintext
|
||||
deploy
|
||||
├── docker-compose.yml # release stack: multi-stage *.prod images, infra internal-only
|
||||
├── docker-compose.dev.yml # dev stack: source mounts, target: dev, exposed ports, delve 2345
|
||||
├── prepare.sh # renders the config files below; rerun after changing templates
|
||||
├── nginx
|
||||
│ ├── nginx.conf # main config, mounted :ro
|
||||
│ └── conf.d/default.conf # site config, mounted :ro
|
||||
├── redis/redis.conf # mounted :ro
|
||||
├── rabbitmq/rabbitmq.conf # mounted :ro
|
||||
├── logs # host-side dirs bind-mounted into containers ({nginx,rabbitmq})
|
||||
├── {$service_name}/storage # file-storage path for services not using object storage
|
||||
└── .gitignore # ignores actual/rendered configs and logs/; tracks only *.example files
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- Only config examples (e.g. `*.conf.example`) are tracked by git; actual configs (rendered by `prepare.sh`) and log files are git-ignored.
|
||||
- Everything under `deploy/` that containers mount (`*.conf` and `prepare.sh` outputs) is config, not app code: edit it here, rerun `prepare.sh`, restart — never edit configs inside a running container.
|
||||
- Infra ports are exposed to the host only in `docker-compose.dev.yml`; release keeps them internal-network-only.
|
||||
- Persisted state lives only in the named `{$project_name}_*` volumes; bind-mounts are reserved for source, config, logs, and file storage.
|
||||
- Only config templates/examples are tracked by git; rendered `*.conf` and `logs/` are git-ignored.
|
||||
- Service-specific host dirs (storage, config) go under `deploy/{$service_name}/`, never loose at the repo root.
|
||||
|
||||
Reference in New Issue
Block a user