53 lines
5.1 KiB
Markdown
53 lines
5.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
GYXX Flow is a Python 3.12 `src`-layout modular monolith: LangGraph workflow orchestration, a Python-resident scheduler, and per-run audit (journal, locks, effect ledger). Docs, commit messages, and config descriptions are largely Chinese — follow the existing language of each file.
|
|
|
|
- `src/gyxx_flow/core/`, `workflow/`, `adapters/` — shared framework: settings/`RunContext`/journal/locks (`core`), validated workflow models + `build_catalog_workflow` + `WorkflowEngine` (`workflow`), and the only sanctioned bridges to PostgreSQL/Feishu/Hermes/browser (`adapters`).
|
|
- `src/gyxx_flow/modules/<module>/` — business code for `content_marketing`, `product_commerce`, `shop_intelligence`, `supply_chain`. Modules depend only on shared contracts, never on another module's internals. The `runtime/` subpackages are legacy import-compatibility namespaces only; new production code goes directly in the module directory.
|
|
- `config/` — the validated configuration quartet: `workflows.json` (scheduled workflows only, exactly one schedule each), `schedules.json` (time rules), `commands.json` (manual-command whitelist), `runtime-bindings.json` (browser bindings + accounts).
|
|
- `tests/`, `docs/`, `deploy/` — tests, runbooks, deployment. `var/` is generated state (gitignored); production must set an external `GYXX_DATA_ROOT`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Everything runs through `uv` from the repository root:
|
|
|
|
```powershell
|
|
uv sync --python 3.12 --group dev # create/update the dev environment
|
|
uv run pytest # full suite
|
|
uv run pytest tests/test_cli.py # single file
|
|
uv run ruff check src tests # lint (E4, E7, E9, F, I)
|
|
uv build # distribution artifacts
|
|
uv run gyxx doctor --json # environment/config preflight
|
|
uv run gyxx acceptance status --json # acceptance evidence
|
|
uv run gyxx sources status --source-root <module>=<dir> # upstream drift check
|
|
```
|
|
|
|
Manual execution is dry-run by default; real external side effects require explicit `--execute`:
|
|
|
|
```powershell
|
|
uv run gyxx list # scheduled workflows only
|
|
uv run gyxx run product.daily --date 2026-08-01 [--execute]
|
|
uv run gyxx backfill content.metrics.daily --from <d> --to <d> [--execute]
|
|
uv run gyxx scripts run <script_id> --date <d> [--execute]
|
|
uv run gyxx schedule run [--dry-run] [--once] # executes enabled jobs unless --dry-run
|
|
uv run gyxx accounts login|sync [account_id]
|
|
```
|
|
|
|
## Constraints (preserve these contracts)
|
|
|
|
- `gyxx schedule run` is the only production scheduling path; never add Windows Task Scheduler entries or duplicate cron rules.
|
|
- Manual/backfill/maintenance commands must be declared in `config/commands.json`; never reintroduce recursive executable-script discovery.
|
|
- Each executable `workflow_id` compiles to a LangGraph `StateGraph`. Preserve the public contracts of the workflow model, `RunJournal`, `LockManager`, shadow comparison, and `EffectLedger` when changing graph execution.
|
|
- External systems: PostgreSQL via runtime-injected cloud DSN (`GYXX_POSTGRES_DSN`; no address/credential defaults in source, loopback rejected in cloud mode); Hermes loopback-only roles on `127.0.0.1:8642/8643` (key `GYXX_HERMES_API_KEY`); Feishu keeps its existing identity. Every browser binding keeps a unique CDP port plus isolated Profile/Cookie/storage-state; scripts sharing an account declare it under `accounts` in `runtime-bindings.json` — the vault `state/accounts/<id>/` is the single login authority (`gyxx accounts login/sync`) and its cookies merge read-only into member scripts while profiles stay isolated.
|
|
- 启动或重启工作流控制台（`gyxx console`）必须携带 `--env-file D:\product-collector-analyze-flow\.env`（与调度器进程一致），否则 `PG_HOST/PG_PORT/PG_DB/PG_USER/PG_PASSWORD` 等云端 PostgreSQL 凭据和账号配置不会注入，「商品经营日报采集」「聚水潭全店铺款式日报」等正式执行会报“缺少 PostgreSQL 运行时凭据”。参考启动脚本：`var/tmp/start-console.ps1`。
|
|
- Source sync (`gyxx sources status/apply`): manifest-driven three-way hash drift check; only untransformed, conflict-free one-sided changes may be auto-copied, and only with `--execute`. Credentials, cookies, logs, and collected data never enter sync manifests.
|
|
|
|
## Coding Style & Testing
|
|
|
|
- Ruff enforces `E4`, `E7`, `E9`, `F`, `I`. `pyproject.toml` excludes `src/gyxx_flow/modules/*/**` from lint (legacy baseline); CI additionally lints a focused list of critical module scripts — add newly critical module scripts there rather than removing the exclusion.
|
|
- Tests are pytest under `tests/` (`test_*.py`); never require live credentials or mutate production services. Changes to workflows, schedules, manifests, runtime paths, or CLI behavior need acceptance or boundary coverage.
|
|
- Commits use short Conventional Commit subjects (e.g. `feat: consolidate legacy workflows`); never commit secrets, cookies, `.env` files, or generated `var/` contents.
|
|
- Operational detail: `docs/architecture.md`, `docs/deployment.md`, `docs/runbook.md`, `docs/acceptance-report.md`.
|