From b063215e46b7fb92ba2cb44dbaa4142cf480201c Mon Sep 17 00:00:00 2001 From: TyperBody Date: Sat, 7 Nov 2026 15:59:22 +0800 Subject: [PATCH 01/17] docs: add PR QA pipeline and a functional review of the running system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewer-facing material the repo was missing, rebased onto the current layout (Go module at the root, adapters/ and cmd/ present): - .github/workflows/ci.yml + labeler.yml — the CI CONTRIBUTING §6 already promised; offline, four gates - .github/pull_request_template.md, CODEOWNERS, labels.yml, labeler.yml - docs/developer-guide/pr-qa.md — merge gate, reviewer checklist, exception process - docs/developer-guide/functional-review.md — severity-ranked review of the running system with file:line and reproduced output - web/.eslintrc.cjs — the lint gate had no config, so `npm run lint` exited 2 before linting anything Paths follow the root-module layout: no `backend/` prefix, `gofmt -l .`, generators point at `internal/platformspec`. Incidental fixes the gates exposed on this tree: - 12 pre-existing unformatted Go files (`gofmt -l` would have failed the first PR) - one staticcheck QF1012 in dependency_installer.go - three lint errors in main's newer components (prefer-const, stale react-hooks disable directives) and two helper exports added to the eslint allowExportNames list - messagefields/platformspec tests resolved docs and scripts with three `..` segments, one too many now the module root moved `--max-warnings` is raised once to the measured 65 rather than rewritten; the ratchet rule then holds from here. The review's blockers were re-checked against this tree: B1 (JWT validation) and M1 (user scoping) are already fixed upstream and are noted as such; B2/B3/B4 still stand. --- .github/CODEOWNERS | 44 + .github/CODE_OF_CONDUCT.md | 88 + .github/CONTRIBUTING.md | 160 + .github/SECURITY.md | 78 + .github/labeler.yml | 76 + .github/labels.yml | 71 + .github/pull_request_template.md | 69 + .github/workflows/ci.yml | 171 + .github/workflows/labeler.yml | 38 + .golangci.yml | 34 + LICENSE-CUSTOM.md | 80 +- LICENSE-MIT | 21 + NOTICE-catbus.md | 39 + README.md | 195 +- README.zh-CN.md | 181 + cmd/esp-desktop/console_windows.go | 6 +- docs/developer-guide/adapter-development.md | 286 +- docs/developer-guide/api-reference.md | 428 ++- docs/developer-guide/catbus-migration.md | 74 + docs/developer-guide/contributing.md | 273 +- docs/developer-guide/functional-review.md | 478 +++ docs/developer-guide/message-fields.md | 449 +++ docs/developer-guide/platform-capabilities.md | 510 +++ docs/developer-guide/pr-qa.md | 136 + docs/developer-guide/protocol-v3.md | 390 +-- docs/user-guide/adapters.md | 258 +- docs/user-guide/getting-started.md | 129 +- docs/user-guide/routing.md | 276 +- docs/user-guide/troubleshooting.md | 340 +- internal/adapter/adapters.go | 271 +- internal/adapter/adapters_test.go | 183 + internal/adapter/main_test.go | 16 + internal/adapter/platform_adapters.go | 233 ++ internal/adapter/sync.go | 108 + internal/adapter/sync_test.go | 72 + internal/config/config.go | 6 +- internal/handler/adapter.go | 2 +- internal/handler/auth.go | 2 +- internal/handler/platform.go | 2 +- internal/handler/platformspec.go | 131 + internal/handler/user.go | 2 +- internal/message/dispatcher.go | 20 +- internal/message/dispatcher_test.go | 103 + internal/message/hub.go | 2 +- internal/messagefields/catalog.go | 374 ++ internal/messagefields/doc.go | 8 + internal/messagefields/docs_test.go | 64 + internal/messagefields/fields.go | 138 + internal/messagefields/fields_test.go | 88 + internal/models/adapter.go | 26 +- internal/models/adapter_token.go | 22 +- internal/platformspec/commands.go | 1132 ++++++ internal/platformspec/doc.go | 9 + internal/platformspec/generated_test.go | 19 + internal/platformspec/platform_12306.go | 25 + internal/platformspec/platform_bilibili.go | 45 + internal/platformspec/platform_douyin.go | 42 + internal/platformspec/platform_jd.go | 38 + internal/platformspec/platform_jimeng.go | 29 + internal/platformspec/platform_kuaishou.go | 43 + internal/platformspec/platform_maoyan.go | 37 + internal/platformspec/platform_mteam.go | 38 + internal/platformspec/platform_taobao.go | 36 + internal/platformspec/platform_tiktok.go | 42 + internal/platformspec/platform_weibo.go | 35 + internal/platformspec/platform_x.go | 38 + internal/platformspec/platform_xhs.go | 42 + internal/platformspec/platform_xianyu.go | 36 + internal/platformspec/platform_youtube.go | 58 + internal/platformspec/spec.go | 221 ++ internal/platformspec/spec_test.go | 113 + internal/server/server.go | 9 + internal/service/adapter.go | 4 +- internal/service/adapter_catalog.go | 18 +- internal/service/auth.go | 6 +- internal/service/command.go | 5 + internal/service/dependency_installer.go | 16 +- internal/service/instance.go | 8 +- internal/service/instance_dir.go | 2 +- internal/service/message.go | 5 + internal/service/python_runner.go | 48 +- internal/service/services.go | 6 + internal/service/user.go | 2 +- main_fatal_windows.go | 6 +- matrix.json | 3085 +++++++++++++++++ scripts/README.md | 19 + scripts/check_generated.py | 58 + scripts/gen_capabilities.py | 125 + scripts/gen_platformspec.py | 249 ++ web/.eslintrc.cjs | 72 + web/.gitignore | 2 + web/DOCS.md | 11 + web/UI-SPEC.en.md | 250 ++ web/UI-SPEC.md | 250 ++ web/index.html | 30 +- web/package.json | 5 +- web/public/apple-touch-icon.png | Bin 0 -> 1853 bytes web/public/favicon.ico | Bin 0 -> 15086 bytes web/public/favicon.svg | 5 + web/src/components/ConnectionMonitor.tsx | 4 +- web/src/components/EntityModal.tsx | 1 - web/src/components/Layout.tsx | 460 ++- web/src/components/Markdown.tsx | 2 +- web/src/components/connection-badge.tsx | 38 + web/src/components/theme-provider.tsx | 147 + web/src/components/ui/badge.tsx | 64 + web/src/components/ui/button.tsx | 79 + web/src/components/ui/card.tsx | 90 + web/src/components/ui/confirm-dialog.tsx | 90 + web/src/components/ui/dialog.tsx | 95 + web/src/components/ui/empty-state.tsx | 49 + web/src/components/ui/error-state.tsx | 42 + web/src/components/ui/form-field.tsx | 119 + web/src/components/ui/page-header.tsx | 41 + web/src/components/ui/select.tsx | 116 + web/src/components/ui/skeleton.tsx | 63 + web/src/components/ui/stat-card.tsx | 55 + web/src/components/ui/table-shell.tsx | 93 + web/src/index.css | 501 ++- web/src/lib/cn.ts | 12 + web/src/locales/en-US.json | 258 +- web/src/locales/zh-CN.json | 250 +- web/src/main.tsx | 5 +- web/src/pages/Adapters.tsx | 498 ++- web/src/pages/Dashboard.tsx | 491 +-- web/src/pages/Docs.tsx | 237 +- web/src/pages/Instances.tsx | 986 ++---- web/src/pages/Login.tsx | 250 +- web/src/pages/Messages.tsx | 280 +- web/src/pages/Monitoring.tsx | 433 +-- web/src/pages/Platforms.tsx | 430 ++- web/src/pages/Routes.tsx | 524 +-- web/src/pages/Settings.tsx | 1001 ++---- web/tailwind.config.js | 173 +- web/vite.config.ts | 41 +- 135 files changed, 17183 insertions(+), 4460 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md create mode 100644 .github/labeler.yml create mode 100644 .github/labels.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/labeler.yml create mode 100644 .golangci.yml create mode 100644 LICENSE-MIT create mode 100644 NOTICE-catbus.md create mode 100644 README.zh-CN.md create mode 100644 docs/developer-guide/catbus-migration.md create mode 100644 docs/developer-guide/functional-review.md create mode 100644 docs/developer-guide/message-fields.md create mode 100644 docs/developer-guide/platform-capabilities.md create mode 100644 docs/developer-guide/pr-qa.md create mode 100644 internal/adapter/adapters_test.go create mode 100644 internal/adapter/main_test.go create mode 100644 internal/adapter/platform_adapters.go create mode 100644 internal/adapter/sync.go create mode 100644 internal/adapter/sync_test.go create mode 100644 internal/handler/platformspec.go create mode 100644 internal/message/dispatcher_test.go create mode 100644 internal/messagefields/catalog.go create mode 100644 internal/messagefields/doc.go create mode 100644 internal/messagefields/docs_test.go create mode 100644 internal/messagefields/fields.go create mode 100644 internal/messagefields/fields_test.go create mode 100644 internal/platformspec/commands.go create mode 100644 internal/platformspec/doc.go create mode 100644 internal/platformspec/generated_test.go create mode 100644 internal/platformspec/platform_12306.go create mode 100644 internal/platformspec/platform_bilibili.go create mode 100644 internal/platformspec/platform_douyin.go create mode 100644 internal/platformspec/platform_jd.go create mode 100644 internal/platformspec/platform_jimeng.go create mode 100644 internal/platformspec/platform_kuaishou.go create mode 100644 internal/platformspec/platform_maoyan.go create mode 100644 internal/platformspec/platform_mteam.go create mode 100644 internal/platformspec/platform_taobao.go create mode 100644 internal/platformspec/platform_tiktok.go create mode 100644 internal/platformspec/platform_weibo.go create mode 100644 internal/platformspec/platform_x.go create mode 100644 internal/platformspec/platform_xhs.go create mode 100644 internal/platformspec/platform_xianyu.go create mode 100644 internal/platformspec/platform_youtube.go create mode 100644 internal/platformspec/spec.go create mode 100644 internal/platformspec/spec_test.go create mode 100644 matrix.json create mode 100644 scripts/README.md create mode 100644 scripts/check_generated.py create mode 100644 scripts/gen_capabilities.py create mode 100644 scripts/gen_platformspec.py create mode 100644 web/.eslintrc.cjs create mode 100644 web/.gitignore create mode 100644 web/DOCS.md create mode 100644 web/UI-SPEC.en.md create mode 100644 web/UI-SPEC.md create mode 100644 web/public/apple-touch-icon.png create mode 100644 web/public/favicon.ico create mode 100644 web/public/favicon.svg create mode 100644 web/src/components/connection-badge.tsx create mode 100644 web/src/components/theme-provider.tsx create mode 100644 web/src/components/ui/badge.tsx create mode 100644 web/src/components/ui/button.tsx create mode 100644 web/src/components/ui/card.tsx create mode 100644 web/src/components/ui/confirm-dialog.tsx create mode 100644 web/src/components/ui/dialog.tsx create mode 100644 web/src/components/ui/empty-state.tsx create mode 100644 web/src/components/ui/error-state.tsx create mode 100644 web/src/components/ui/form-field.tsx create mode 100644 web/src/components/ui/page-header.tsx create mode 100644 web/src/components/ui/select.tsx create mode 100644 web/src/components/ui/skeleton.tsx create mode 100644 web/src/components/ui/stat-card.tsx create mode 100644 web/src/components/ui/table-shell.tsx create mode 100644 web/src/lib/cn.ts diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..88c76406 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,44 @@ +# CODEOWNERS — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# +# Rules are matched bottom-up: the LAST matching pattern wins, so the broad +# default comes first and the narrow overrides below it. Only the last match is +# used, not a union — putting a specific path above `*` does nothing. +# +# The default is the one handle that is certainly a member of the org. A team +# (`@E-SPower/maintainers`) is the better shape once it exists and its members +# are maintainers, but a handle that does not exist fails silently: GitHub +# requests nobody and the PR looks owned. Replace all entries together, then. +# +# Every change needs a named reviewer. + +* @TyperBody + +# Protocol v3, signing and the message field contract. A break here is expensive +# to undo, so it does not ride along in a larger PR unreviewed. +/backend/internal/protocol/ @TyperBody +/backend/internal/messagefields/ @TyperBody +/docs/developer-guide/protocol-v3.md @TyperBody +/docs/developer-guide/message-fields.md @TyperBody + +# Platform registry: matrix.json generates public Go code and a public doc, so a +# matrix edit is a code change even when the diff is one JSON line. +/matrix.json @TyperBody +/scripts/gen_platformspec.py @TyperBody +/scripts/gen_capabilities.py @TyperBody +/scripts/check_generated.py @TyperBody +/backend/internal/platformspec/ @TyperBody + +# The merge gate itself — workflows, template, labels, this file. A broken CI +# config is invisible until it is on `main`. +/.github/ @TyperBody + +# Front end design tokens and the shared component library: a UI-SPEC violation +# is review feedback, not a nit. +/web/tailwind.config.js @TyperBody +/web/src/components/ui/ @TyperBody +/web/UI-SPEC.md @TyperBody + +# Auth, secrets and the security policy. +/backend/internal/middleware/ @TyperBody +/backend/internal/service/auth.go @TyperBody +/.github/SECURITY.md @TyperBody diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..be8c9210 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,88 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as members, contributors and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive and healthy community. + +## Our standards + +Examples of behaviour that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologising to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behaviour include: + +- The use of sexualised language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behaviour and will take appropriate and fair corrective action in response to any behaviour that they deem inappropriate, threatening, offensive or harmful. + +Community leaders have the right and responsibility to remove, edit or reject comments, commits, code, wiki edits, issues and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing or otherwise unacceptable behaviour may be reported to the community leaders responsible for enforcement: + +- General questions: open an issue on [GitHub Issues](https://github.com/E-SPower/E-SP-Line2/issues); +- Anything private: contact the maintainers through GitHub. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community impact**: use of inappropriate language or other behaviour deemed unprofessional or unwelcome in the community. + +**Consequence**: a private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community impact**: a violation through a single incident or series of actions. + +**Consequence**: a warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary ban + +**Community impact**: a serious violation of community standards, including sustained inappropriate behaviour. + +**Consequence**: a temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent ban + +**Community impact**: demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: a permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][faq]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..c89d6678 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,160 @@ +# Contributing to E-SP-Line2 + +Thanks for wanting to make E-SP-Line2 better. This guide covers setting up a dev environment, the conventions for code and commits, and how to get a change merged. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) first — it applies to every issue, PR and review. + +## 1. Before you start + +- Search the [open issues](https://github.com/E-SPower/E-SP-Line2/issues) before you file one; a duplicate splits the discussion. +- For anything larger than a bug fix or a small docs patch, open an issue describing the problem and the shape of your fix first. It saves you from building something the project does not want. +- Report security problems privately — see [SECURITY.md](SECURITY.md), not a public issue. + +## 2. Development environment + +| Tool | Version | Purpose | +|---|---|---| +| Go | 1.22+ | build, test and run the backend | +| Node | 20.11+ | build and run the web front end (`web/package.json` `engines`; CI reads it) | +| npm or pnpm | current | front-end dependencies | +| Git | any recent | | + +Component versions matter: `backend/go.mod` and `web/package.json` pin what maintainers and the toolchain use. Do not bump a dependency just because — bump it in its own PR with a reason. + +### Backend + +```bash +git clone https://github.com/E-SPower/E-SP-Line2.git +cd E-SP-Line2/backend +go mod download +go run main.go # reads ./config/config.yaml, then ./config.yaml, then /etc/e-sp-line2 +``` + +The API listens on `:8080`. Before you expose it beyond localhost, change `jwt.secret` in the config — see [SECURITY.md](SECURITY.md). + +```bash +make build # build to bin/e-sp-line2 +make test # go test ./... — needs CGO_ENABLED=1 and gcc, see below +make fmt # go fmt ./... +make lint # golangci-lint, config in .golangci.yml +``` + +`make lint` is not optional: it is a CI step. The linter is not vendored, so install the pinned version once: + +```bash +go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 +# ~/go/bin must be on PATH +``` + +Backend tests need a C toolchain: `gorm.io/driver/sqlite` is cgo, and with cgo off the driver compiles against a stub that fails at `Open`, so the database tests die with an error that looks like a code defect. Run `export CGO_ENABLED=1` (and install `gcc`) before `make test`. + +### Front end + +```bash +cd web +npm install +npm run dev # vite on :3000, proxying /api and /ws to :8080 +``` + +```bash +npm run build # tsc then vite build +npm run lint # eslint +``` + +Read [web/UI-SPEC.md](../web/UI-SPEC.md) before you touch a page. Every colour comes from a token; every state uses the shared component (`Badge`, `Card`, `Skeleton`, `EmptyState`, `ErrorState`, `PageHeader`, `FormField`). Do not hand-roll `bg-blue-600` into a page, and do not add a dependency without a reason. + +### Database + +GORM `AutoMigrate` creates the schema on startup, so a fresh checkout needs nothing. Hand-written SQL migrations live in `backend/migrations/` with their own [README](../backend/migrations/README.md); note that `main.go` does not currently expose a `migrate` subcommand, so the SQL files are reference material until it does. Add a migration when you change a persisted model, and keep `IF NOT EXISTS` / `ON CONFLICT` so re-runs are safe. + +## 3. Project layout + +``` +backend/ +├── internal/ +│ ├── adapter/ # adapter registry, manager and bridge +│ ├── config/ # configuration loading +│ ├── handler/ # HTTP and WebSocket handlers +│ ├── message/ # event hub, router and dispatcher +│ ├── middleware/ # auth, CORS and logging middleware +│ ├── models/ # GORM models +│ ├── protocol/v3/ # v3 envelope, message chain, signing +│ ├── repository/ # data access +│ ├── server/ # server wiring and routes +│ └── service/ # business logic +├── migrations/ # SQL migrations +└── pkg/logger/ # shared logging helpers +web/src/ +├── api/ # typed API client +├── components/ # layout and UI component library +├── locales/ # zh-CN / en-US strings +└── pages/ # one file per route +docs/ # user and developer guides +``` + +Backend layering is `handler → service → repository`; handlers do not touch GORM directly, and the message layer does not import handlers. New adapters follow the contract in [docs/developer-guide/adapter-development.md](../docs/developer-guide/adapter-development.md). + +## 4. Conventions + +### Code + +- **Go**: [Effective Go](https://go.dev/doc/effective_go) and [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments). Run `make fmt` and `make lint` before pushing — CI runs both, and `make lint` uses `backend/.golangci.yml`. +- **TypeScript/React**: the repo's ESLint config (`web/.eslintrc.cjs`), `npm run lint` must be clean, and `tsc` must pass — `npm run build` runs it. The `--max-warnings` budget in `web/package.json` is a ratchet: a new `any` over it is red, and removing one means lowering the number in the same PR. +- **Comments and user-facing strings in English.** User-facing text goes through i18next; add the key to both `web/src/locales/zh-CN.json` and `en-US.json`, and never delete an existing key. +- Keep error returns wrapped with context (`fmt.Errorf("...: %w", err)`) rather than logged and swallowed. + +### Commits + +[Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + + +