Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
b063215
docs: add PR QA pipeline and a functional review of the running system
TyperBody Nov 7, 2026
96aff88
docs: rebase the review onto the current tree and re-verify its findings
TyperBody Nov 7, 2026
a0d5148
chore: point CODEOWNERS at the maintainers team
TyperBody Nov 7, 2026
354109f
feat(message): wire the inbound chain end to end (B2/B3/B4/B5)
TyperBody Nov 7, 2026
8e764e7
ci: run on stacked PRs, not only PRs whose base is main
TyperBody Nov 7, 2026
12dff05
ci: retrigger (base gained stacked-PR workflow trigger after this PR …
TyperBody Nov 7, 2026
7a674c7
fix(api): truthful status codes and live instance metrics
TyperBody Nov 7, 2026
db6f53d
config: add the origin allow-list and HTTP hardening knobs
TyperBody Nov 7, 2026
9944972
middleware, server: enforce the origin allow-list, WS auth and timeouts
TyperBody Nov 7, 2026
00b2ddb
docs, handlers, adapters: follow the new origin, token and body contract
TyperBody Nov 7, 2026
44e791f
Merge pull request #4 from E-SPower/fix/p2-status-codes-and-metrics
TyperBody Nov 7, 2026
fa4a45b
Merge pull request #7 from E-SPower/feat/p1-security-cors-ws-timeouts
TyperBody Nov 7, 2026
3f7e05c
Merge main (919a90b) to clear the PR #3 conflict
TyperBody Nov 7, 2026
051c454
Merge the P0 message pipeline
TyperBody Nov 7, 2026
92da0d0
fix: drop two symbols the merge left dead
TyperBody Nov 7, 2026
eae98fa
fix: 413 on the two ingest routes, and drop the dead `backend/` paths
TyperBody Nov 7, 2026
c863b75
feat: instance log drawer, message ingest dialog, runtime labels
TyperBody Nov 7, 2026
24394ff
fix(web): 侧栏标签换行、侧栏宽度下限、页面纵向留白按视口封顶
TyperBody Nov 7, 2026
5b0d128
fix(web): 仪表盘两栏改用 items-start,活动卡不再被右栏撑出大片空白
TyperBody Nov 8, 2026
059716e
fix(web): 表格单元格纵向内边距 py-3 -> py-4;恢复 /messages 路由
TyperBody Nov 8, 2026
cabfa6f
docs: re-verify the functional review against the merged tree
TyperBody Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
44 changes: 44 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -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 `maintainers` team, which exists and has `@TyperBody` as a
# maintainer. A reference to something that does not exist fails silently:
# GitHub requests nobody and the PR merely looks owned. Add people to the team
# rather than swapping the handle here.
#
# Every change needs a named reviewer from that team.

* @E-SPower/maintainers

# 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/ @E-SPower/maintainers
/backend/internal/messagefields/ @E-SPower/maintainers
/docs/developer-guide/protocol-v3.md @E-SPower/maintainers
/docs/developer-guide/message-fields.md @E-SPower/maintainers

# 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 @E-SPower/maintainers
/scripts/gen_platformspec.py @E-SPower/maintainers
/scripts/gen_capabilities.py @E-SPower/maintainers
/scripts/check_generated.py @E-SPower/maintainers
/backend/internal/platformspec/ @E-SPower/maintainers

# The merge gate itself — workflows, template, labels, this file. A broken CI
# config is invisible until it is on `main`.
/.github/ @E-SPower/maintainers

# Front end design tokens and the shared component library: a UI-SPEC violation
# is review feedback, not a nit.
/web/tailwind.config.js @E-SPower/maintainers
/web/src/components/ui/ @E-SPower/maintainers
/web/UI-SPEC.md @E-SPower/maintainers

# Auth, secrets and the security policy.
/backend/internal/middleware/ @E-SPower/maintainers
/backend/internal/service/auth.go @E-SPower/maintainers
/.github/SECURITY.md @E-SPower/maintainers
88 changes: 88 additions & 0 deletions .github/CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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
165 changes: 165 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
# 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: `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
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 `migrations/` with their own [README](../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

The Go module is the repository root (`go.mod`, `main.go`).

```
internal/
├── adapter/ # adapter registry, manager and bridge
├── adapters/ # embedded adapter bundles
├── adaptergateway/ # gateway client for the bridges
├── 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
adapters/ # per-platform bridge implementations
cmd/esp-desktop/ # desktop shell
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 `.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/):

```
<type>(<scope>): <subject>

<body>

<footer>
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`. Scope is the area touched (`adapter`, `router`, `web`, `docs`). Subject in the imperative mood, lowercase, no trailing period.

```
feat(adapter): add Pinduoduo adapter package

- implement the Pinduoduo message client
- add the product card message type
- cover the normalizer with unit tests

Closes #123
```

One logical change per commit. Do not commit `node_modules`, build output or a local database with real credentials.

### Branches

`feat/<short-name>`, `fix/<short-name>`, `docs/<short-name>` off `main`. Rebase on `main` rather than merging it in, so history stays linear.

## 5. Tests

- A new feature needs tests; a bug fix needs a regression test that fails without it.
- Backend: `go test ./...` (table-driven, `httptest` for handlers). Front end: whatever the page exercises — at minimum the API client and the reducer-ish logic around it.
- Do not call a real Taobao or Xianyu endpoint from a unit test. Fixture the raw payload and pass it through the normalizer.
- If a change alters the v3 envelope, message chain or signing, say so in the PR and update [docs/developer-guide/protocol-v3.md](../docs/developer-guide/protocol-v3.md).

## 6. Pull requests

- Keep a PR to one concern. Unrelated cleanup goes in its own PR.
- Describe what changed, why, and how you verified it. Link the issue.
- Update the docs the change invalidates — README, the matching `docs/` page, or the UI spec.
- CI must be green. `.github/workflows/ci.yml` runs the commands above, and `format-lint` is part of the gate: a red job is answered by fixing the code, not by disabling the job. A maintainer reviews for correctness, layering, test coverage and security; an unreviewed PR does not merge just because it is small.
- The full reviewer checklist, merge gate and exception process is [docs/developer-guide/pr-qa.md](../docs/developer-guide/pr-qa.md).
- Do not force-push after review starts unless asked; reviewers lose the diff.

## 7. Reporting bugs and proposing features

A good bug report has the version or commit, OS, Go/Node versions, exact reproduction steps, what you expected, what happened, and the relevant log lines with Cookies and tokens stripped. A good feature request states the problem first and the proposed solution second, plus alternatives you considered.

## 8. Sign-off

By contributing you agree your contribution is licensed under the terms in [LICENSE](../LICENSE) and [LICENSE-CUSTOM.md](../LICENSE-CUSTOM.md).

## 9. Getting help

Comment on the issue you are working on, or open a discussion. Do not @-mention a maintainer for a status nudge before a few days have passed.
Loading
Loading