audit-external-api-port
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAudit External API Port
外部API移植审计
Reconstruct the expected behavior and public contract independently. The port packet, comments, docs, and tests are claims to verify, not authority. Stay read-only and findings-first: no edits, staging, commits, publishing, or thread resolution unless the user explicitly asks after seeing the findings.
Read audit-rubric.md before reviewing the diff; it holds the per-area checklists this workflow walks.
独立重构预期行为与公共契约。移植包、注释、文档和测试均为需验证的声明,而非权威依据。保持只读且以问题发现为核心:除非用户在查看发现结果后明确要求,否则不得进行编辑、暂存、提交、发布或线程处理操作。
在查看差异前,请阅读audit-rubric.md;其中包含本工作流程需遵循的各领域检查清单。
1. Lock scope and evidence
1. 锁定范围与证据
Read repository instructions, coding standards, testing rules, architecture maps, and working-tree state. Determine the exact base-to-head or user-specified diff; report unrelated dirty files and keep them out of scope.
Pin: the initiating GitHub issue with its requirements and accepted decisions; target branch/commit and external surface; authoritative and/or commits; the user-designated commit; the port packet path; claimed mappings and readiness state; and the OpenAPI/runtime evidence available. Resolve ambiguous source authority from repository evidence first; ask only when the ambiguity would change a material conclusion.
I-###apps/apiapps/core-apitagmango-web-platformM-###阅读仓库说明、编码标准、测试规则、架构图和工作树状态。确定准确的基准到头部差异或用户指定的差异;报告无关的未提交文件并将其排除在范围之外。
固定以下内容:包含需求和已接受决策的发起GitHub议题;目标分支/提交和外部暴露面;权威的和/或提交;用户指定的提交;移植包路径;声明的映射关系和就绪状态;以及可用的OpenAPI/运行时证据。优先从仓库证据中解决模糊的源权威问题;只有当模糊性会改变重要结论时才提出询问。
I-###apps/apiapps/core-apitagmango-web-platformM-###2. Reconstruct behavior independently
2. 独立重构行为
Trace the full backend decision path and the frontend flow (rubric §2 lists the areas). Classify each frontend restriction as business invariant, entitlement gate, normalization/default, UI convenience, or ambiguity.
Build your own ledger of externally meaningful scenarios: negative combinations, lifecycle states, permissions, ownership, tenant/host binding, side effects, ordering, idempotency, retries, and absent/null/false/zero/empty semantics. Define the scoped capability independently of the external contract — including modes the external API intentionally omits but a future core replacement needs. If the legacy route bundles several capabilities, verify the declared decomposition.
Compare your ledger against the target and the packet; never downgrade a rule you found because the packet omitted it. Verify the issue was treated as a starting brief, and that every – dimension was resolved by the developer or justified , with the implementation matching those resolutions.
G-001G-008N/A追踪完整的后端决策路径和前端流程(评审准则§2列出了相关领域)。将每个前端限制归类为业务不变量、权限门控、归一化/默认值、UI便利性或模糊项。
构建自己的外部有意义场景台账:负面组合、生命周期状态、权限、所有权、租户/宿主绑定、副作用、排序、幂等性、重试,以及缺失/空值/假值/零值/空语义。独立于外部契约定义范围内的能力——包括外部API有意省略但未来核心替换所需的模式。如果旧版路由捆绑了多个能力,请验证声明的分解是否正确。
将你的台账与目标和移植包进行对比;绝不要因为移植包遗漏了你发现的规则而降低该规则的优先级。验证议题是否被视为初始简报,且–的每个维度都已由开发者解决或合理标记为,并且实现与这些解决方案一致。
G-001G-008N/A3. Audit the wire contract
3. 审计网络契约
Judge from the generated OpenAPI document and, when a running server or captured integration response is available, real runtime responses. Never infer the public URL from a controller fragment or the response shape from Swagger DTO metadata. Walk rubric §3 and §5: complete versioned URL, honest method and resource boundaries, deliberate parameter placement, per-field semantics, allowlisted grouped responses, stable documented errors, and retry/idempotency/pagination/compatibility semantics where material.
For every resource concept the response returns or embeds, locate its canonical representation elsewhere on the external surface and diff the shapes — an embedded resource whose fields, names, or null semantics differ from the standalone representation without a recorded tier decision is a contract finding.
Acid test: write the minimal valid request, an important optional combination, and an invalid combination from the docs alone. If that fails, record a contract finding.
从生成的OpenAPI文档以及(如果有运行中的服务器或捕获的集成响应)实际运行时响应进行判断。绝不要从控制器片段推断公共URL,也不要从Swagger DTO元数据推断响应形状。遵循评审准则§3和§5:完整的版本化URL、准确的方法和资源边界、明确的参数位置、每个字段的语义、允许列表化的分组响应、稳定的已记录错误,以及重要场景下的重试/幂等性/分页/兼容性语义。
对于响应返回或嵌入的每个资源概念,在外部暴露面的其他位置找到其规范表示并对比形状——如果嵌入资源的字段、名称或空值语义与独立表示不同,且没有记录的层级决策,则属于契约问题发现。
严格测试:仅根据文档编写最小有效请求、一个重要的可选组合请求和一个无效组合请求。如果测试失败,则记录为契约问题发现。
4. Audit validation and enforcement
4. 审计验证与执行
Build a decision table from every discriminator and dependent field, then reason through combinations the first-party frontend never emits — external callers send anything schema-valid. Walk rubric §4: conditional requirements and prohibitions, contradictory values, actor/tenant/currency/entitlement/ownership/state rules, boundaries and encodings, create-versus-patch absent/null semantics, race-safe uniqueness, promoted frontend business rules, and UI conveniences that must not have been promoted.
Documentation without enforcement is a defect, and a DTO decorator cannot enforce a rule that needs authenticated or database context — check the layer, not just the presence.
从每个判别器和依赖字段构建决策表,然后推理第一方前端从未发出的组合——外部调用者会发送任何符合 schema 的请求。遵循评审准则§4:条件需求与禁止项、矛盾值、参与者/租户/货币/权限/所有权/状态规则、边界与编码、创建与补丁的缺失/空值语义、防竞态的唯一性、前端业务规则的升级,以及绝不能升级的UI便利性。
无执行力度的文档属于缺陷,且DTO装饰器无法执行需要认证或数据库上下文的规则——检查实现层级,而不仅仅是是否存在。
5. Audit exposure and security
5. 审计暴露面与安全性
Trace every response field to its source and treat exposure as an allowlist exercise (rubric §6). Verify authentication, API-key scope, host/tenant binding, permission, resource ownership, rate/quota policy, and non-enumeration separately — test or inspect revoked keys, wrong hosts, other-owner resources, and failure messages. For mutations, inspect atomicity, duplicate submission, timeout/retry behavior, and whether side effects can double-run.
追踪每个响应字段的来源,并将暴露视为允许列表操作(评审准则§6)。分别验证认证、API密钥范围、宿主/租户绑定、权限、资源所有权、速率/配额策略,以及不可枚举性——测试或检查已撤销的密钥、错误的宿主、其他所有者的资源和失败消息。对于变更操作,检查原子性、重复提交、超时/重试行为,以及副作用是否可能重复执行。
6. Audit architecture and core-replacement readiness
6. 审计架构与核心替换就绪度
Verify the shared-capability shape: controller owns parsing/auth and delegates one meaningful use case; business rules, transactions, and side-effect orchestration live in ; typed persistence in ; equivalent core and external controllers call the same use case; exposure policy stays in transport mappers/DTOs; domain types are transport-neutral with no -versus- branching; every added file is kebab-case with conventional role suffixes. Rubric §7 lists the full flag set. Blocking findings include: new app-local business or repository code, an unrewired equivalent core caller, an external-shaped partial domain model, or a future core replacement that still needs business or data work.
libs/serviceslibs/repositoryexternalcoreIndependently trace every scoped / rule through its row into shared code, adapters, and tests. If adding a core route would need more than authentication, DTO/mapping, and wiring, the readiness claim fails.
B-###V-###M-###Verify pattern conformity against the repository, not the packet's word: each row's exemplar must be a recent intentional port, the named primitive must actually cover the concern (cache keys, TTL units, and serialization — not just method signatures), and the implementation must match its decision. A new wrapper, adapter, parser, pipe, interface, or factory with an unproven justification is a finding.
P-###ADOPTEDP-###Then reverse-trace: flag any branch, default, or mutation in new domain code with no corresponding ledger rule or recorded decision — unmapped logic is invented behavior. Verify any optimization carries an equivalence note covering ordering, rounding, projection, and null handling, and that the drift watchlist names every legacy route keeping a live duplicated implementation as a directly callable entry — prose descriptions the testing workflow cannot call verbatim are a finding.
<apps/api | core-api> METHOD /full/path验证共享能力的架构:控制器负责解析/认证并委托一个有意义的用例;业务规则、事务和副作用编排位于中;类型化持久化位于中;等效的核心控制器和外部控制器调用同一个用例;暴露策略保留在传输映射器/DTO中;领域类型与传输无关,不存在与分支;每个新增文件均采用短横线命名法并带有常规角色后缀。评审准则§7列出了完整的检查项。阻塞性问题发现包括:新增的应用本地业务或仓库代码、未重新连接的等效核心调用者、外部形状的部分领域模型,或未来核心替换仍需业务或数据工作的情况。
libs/serviceslibs/repositoryexternalcore独立追踪每个范围内的/规则通过其行进入共享代码、适配器和测试。如果添加核心路由需要的不仅仅是认证、DTO/映射和连接工作,则就绪度声明不成立。
B-###V-###M-###验证模式是否符合仓库规范,而非移植包的描述:每个行的示例必须是近期的有意移植,指定的原语必须实际覆盖相关关注点(缓存键、TTL单位和序列化——而不仅仅是方法签名),且实现必须与其决策一致。带有未经验证的理由的新包装器、适配器、解析器、管道、接口或工厂属于问题发现。
P-###ADOPTEDP-###然后反向追踪:标记新领域代码中任何没有对应台账规则或记录决策的分支、默认值或变更——未映射的逻辑属于自创行为。验证任何优化都带有涵盖排序、舍入、投影和空值处理的等价说明,且漂移监视列表将每个保留实时重复实现的旧版路由命名为可直接调用的条目——测试工作流无法直接调用的 prose 描述属于问题发现。
<apps/api | core-api> METHOD /full/path7. Audit tests and documentation
7. 审计测试与文档
Map reviewer rules to tests using rubric §8. Reject construction-only, handler-existence, broad-snapshot, mock-choreography, and happy-path-only tests as parity evidence; require behavior-focused tests at the correct seams, real Mongo where persistence matters, and faked external infrastructure. Verify generated docs against runtime. Typecheck, lint, build, and coverage are supporting signals, not behavior certification.
使用评审准则§8将评审规则映射到测试。拒绝仅构建、仅检查处理器存在、宽泛快照、模拟编排和仅快乐路径的测试作为一致性证据;要求在正确的层面进行以行为为中心的测试,在持久化重要的场景使用真实Mongo,伪造外部基础设施。验证生成的文档与运行时是否一致。类型检查、代码 lint、构建和覆盖率是辅助信号,而非行为认证依据。
8. Report findings
8. 报告问题发现
Order by severity and confidence:
text
[P1] <concise violated promise> — <target file:line>
Scenario: <concrete request/state/actor>
Expected: <source-backed behavior or public contract, with evidence>
Actual: <what target does, with evidence>
Impact: <consumer, data, security, compatibility, or operability consequence>
Remediation: <smallest sound direction; do not patch>
Missing test: <observable test that would catch it>- — exploitable security/privacy, cross-tenant access, irreversible corruption, or catastrophic side effects.
P0 - — broken business parity, auth/ownership, public compatibility, data integrity, required shared-layer reuse, or commonly unusable contract behavior.
P1 - — important edge cases, misleading docs/examples, response exposure, maintainability, or material test gaps.
P2 - — low-risk clarity or consistency issues worth fixing.
P3
Do not flood the report with style nits while behavioral or contract risks remain. Label hypotheses as such and name the missing evidence.
按严重性和置信度排序:
text
[P1] <简洁的违反承诺描述> — <目标文件:行号>
场景: <具体的请求/状态/参与者>
预期: <基于源的行为或公共契约,附证据>
实际: <目标的实际行为,附证据>
影响: <对消费者、数据、安全、兼容性或可操作性的影响>
整改方向: <最小可行的合理方向;不要提供补丁>
缺失测试: <可发现该问题的可观察测试>- — 可利用的安全/隐私问题、跨租户访问、不可逆损坏或灾难性副作用。
P0 - — 业务一致性破坏、认证/所有权问题、公共兼容性问题、数据完整性问题、必需的共享层复用缺失,或契约行为普遍不可用。
P1 - — 重要边缘案例、误导性文档/示例、响应暴露问题、可维护性问题,或重大测试缺口。
P2 - — 低风险的清晰度或一致性问题,值得修复。
P3
在存在行为或契约风险时,不要在报告中充斥风格细节问题。将假设标记为假设,并指出缺失的证据。
9. Certify
9. 认证
Conclude with exactly one:
- — no blocking findings; behavior, contract, enforcement, exposure, core-replacement readiness, docs, runtime, and tests are adequately evidenced.
APPROVED - — one or more valid findings block approval.
CHANGES REQUIRED - — source-backed behaviors conflict and a product decision is required.
BLOCKED BY DECISION - — required source/runtime/test evidence was unavailable.
NOT CERTIFIED
List the source pins, checks actually run, core-migration readiness result, unverified areas, and residual risks. Never convert a partial static review into a parity certification.
最终给出以下结论之一:
- — 无阻塞性问题发现;行为、契约、执行力度、暴露面、核心替换就绪度、文档、运行时和测试均有充分证据支持。
APPROVED - — 一个或多个有效问题发现阻碍批准。
CHANGES REQUIRED - — 基于源的行为存在冲突,需要产品决策。
BLOCKED BY DECISION - — 所需的源/运行时/测试证据不可用。
NOT CERTIFIED
列出源固定项、实际执行的检查、核心迁移就绪度结果、未验证的领域和残留风险。绝不要将部分静态评审转换为一致性认证。