Assign every v2 route and service file to a layer and enforce the doc-only v2 layer rules

未关闭
  • 哪里不对？
#4,190 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 2 天内回复

@anth-volk 已经在做这个了。

开始于 2026年11月4日。

  • #4191 来自 @anth-volk —— 未关闭

评估

难度
4/5
预计耗时
3-5 天
新手友好度
20/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
停滞
技术栈
python
领域
backend-api-design, testing

调研方向

Start with scripts/run_quality_guards.py, the rules under scripts/rules/, and the existing checks in tests/unit/v2/test_data_crud_boundaries.py; read rules/registry.toml and v2-code-organization.md for the current rule setup. Discover and classify all Python files under policyengine_api/services/v2 and policyengine_api/fastapi_routes/v2, then add the guard, rule citations, and proof fixtures. Done means every file has a layer, the listed layer rules are enforced or ratcheted, and the fixtures cover receiver-aware calls, TYPE_CHECKING imports, connector imports in routes, and an unassigned file.

由索引模型根据 Issue 内容生成。

描述

enhancement

Four API v2 layer rules in rules/registry.toml are doc-only: nothing checks them.

  • api.v2.routes-no-sessions-or-sql
  • api.v2.services-no-sql
  • api.v2.connectors-never-commit
  • api.v2.connectors-no-cross-calls

The existing structural tests in tests/unit/v2/test_data_crud_boundaries.py match any call by method name (.add counts whether it is session.add or set.add), and nothing makes sure a new v2 file is checked at all.

Change

A v2-layers quality guard in the rules tool (scripts/rules/, run by scripts/run_quality_guards.py), standard library only:

  • Discover every .py file under policyengine_api/services/v2 and policyengine_api/fastapi_routes/v2 and assign it to a layer by its file name (services.py, validators.py, database_connectors/reads.py, routes.py, and so on), or by a small manifest, rules/v2-layer-manifest.toml, for the few files with other names. Fail on any file that has no layer. This is new rule api.v2.files-assigned-to-layers.

  • Check calls by their receiver (session.add, not any .add) and SQL builders by where they are imported from, per layer:

    • route modules open no session and build no SQL;
    • services build no SQL and call no data-access session method;
    • connectors never open, commit, roll back or close a session.

    Imports under TYPE_CHECKING count.

  • Make the three rules above enforced, or ratcheted with a baseline of today's findings. api.v2.connectors-no-cross-calls became ratcheted with the Import Linter contracts in #4181.

  • Give each rule a proof fixture, including a route that imports a connector and a file with no layer.

  • Cite each rule id in v2-code-organization.md.

Open pull requests that add v2 files will have to give each new file a layer once this merges.

主要语言
Python
星标
18
派生
33
平均合并
2 天 21 小时
30 天内合并 PR
93

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

PolicyEngine/policyengine-api 的其他 Issue

查看 PolicyEngine/policyengine-api 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。