wangyunlong
dc8be88e60
workflows/schedules/commands/notification-routing 与 source-manifests 四模块 清单同步登录统一化与新工作流(product.hk_anpei_public_inventory.daily 等)； docs 运维手册、控制台与耗时分布文档、CI 关键脚本清单、AGENTS 指南更新； 测试与模块注册对齐。
54 lines
5.9 KiB
Markdown
54 lines
5.9 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.
|
||
- 登录统一管理：正式执行的工作流由 `src/gyxx_flow/cookie_gate.py` 在采集步骤前注入每账号 `cookie-gate.<id>` 步骤（blocking 账号失效→阻断并飞书通知人工重登；`login_command_id` 账号先自动账密恢复；`credential_env_names` 账号 defer 给脚本内账密登录）。阻断记录 `pending_reruns`，由调度器维护循环里的 `CookieGateRecoveryManager` 在登录态恢复后按原业务日期自动重跑并发飞书确认。采集脚本不得内嵌扫码/验证码等待——失效时抛 `CookieExpiredError`（`adapters/browser.py`）退出 75；编排器工作流在 `workflows.json` 用 `required_accounts` 声明账号依赖。不要重新引入 relogin_*/批量补采里的扫码重登子进程。
|
||
- 启动或重启工作流控制台（`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`.
|