From c192c77c7af0092e53e74b5c1a30c805f53ed43f Mon Sep 17 00:00:00 2001 From: shunli Date: Fri, 29 May 2026 09:56:22 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B2=BB=E7=90=86=20Trellis=20spec=20=E5=8D=A0?= =?UTF-8?q?=E4=BD=8D=E5=99=AA=E9=9F=B3=E4=B8=8E=E8=A7=84=E5=88=99=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=EF=BC=8805-29-spec-governance-cleanup=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .trellis/spec/backend/database-guidelines.md | 51 --------- .trellis/spec/backend/directory-structure.md | 54 --------- .trellis/spec/backend/error-handling.md | 51 --------- .trellis/spec/backend/index.md | 26 ++--- .trellis/spec/backend/logging-guidelines.md | 51 --------- .trellis/spec/backend/quality-guidelines.md | 51 --------- .../spec/frontend/component-guidelines.md | 59 ---------- .trellis/spec/frontend/directory-structure.md | 54 --------- .trellis/spec/frontend/hook-guidelines.md | 51 --------- .trellis/spec/frontend/index.md | 25 ++--- .trellis/spec/frontend/quality-guidelines.md | 51 --------- .trellis/spec/frontend/state-management.md | 51 --------- .trellis/spec/frontend/type-safety.md | 51 --------- .trellis/spec/hyb-oa/deployment-trialrun.md | 6 +- .../spec/hyb-oa/frontend-react-vite-design.md | 6 +- .../spec/hyb-oa/reimbursement-invoice-ocr.md | 4 +- .../05-29-spec-governance-cleanup/check.jsonl | 4 + .../implement.jsonl | 4 + .../implement.md | 50 +++++++++ .../05-29-spec-governance-cleanup/prd.md | 103 ++++++++++++++++++ .../research/spec-audit.md | 87 +++++++++++++++ .../05-29-spec-governance-cleanup/task.json | 26 +++++ 22 files changed, 306 insertions(+), 610 deletions(-) delete mode 100644 .trellis/spec/backend/database-guidelines.md delete mode 100644 .trellis/spec/backend/directory-structure.md delete mode 100644 .trellis/spec/backend/error-handling.md delete mode 100644 .trellis/spec/backend/logging-guidelines.md delete mode 100644 .trellis/spec/backend/quality-guidelines.md delete mode 100644 .trellis/spec/frontend/component-guidelines.md delete mode 100644 .trellis/spec/frontend/directory-structure.md delete mode 100644 .trellis/spec/frontend/hook-guidelines.md delete mode 100644 .trellis/spec/frontend/quality-guidelines.md delete mode 100644 .trellis/spec/frontend/state-management.md delete mode 100644 .trellis/spec/frontend/type-safety.md create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/check.jsonl create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/implement.jsonl create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/implement.md create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/prd.md create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md create mode 100644 .trellis/tasks/05-29-spec-governance-cleanup/task.json diff --git a/.trellis/spec/backend/database-guidelines.md b/.trellis/spec/backend/database-guidelines.md deleted file mode 100644 index b61aa784..00000000 --- a/.trellis/spec/backend/database-guidelines.md +++ /dev/null @@ -1,51 +0,0 @@ -# Database Guidelines - -> Database patterns and conventions for this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Query Patterns - - - -(To be filled by the team) - ---- - -## Migrations - - - -(To be filled by the team) - ---- - -## Naming Conventions - - - -(To be filled by the team) - ---- - -## Common Mistakes - - - -(To be filled by the team) diff --git a/.trellis/spec/backend/directory-structure.md b/.trellis/spec/backend/directory-structure.md deleted file mode 100644 index 9bb253df..00000000 --- a/.trellis/spec/backend/directory-structure.md +++ /dev/null @@ -1,54 +0,0 @@ -# Directory Structure - -> How backend code is organized in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Directory Layout - -``` - -src/ -├── ... -└── ... -``` - ---- - -## Module Organization - - - -(To be filled by the team) - ---- - -## Naming Conventions - - - -(To be filled by the team) - ---- - -## Examples - - - -(To be filled by the team) diff --git a/.trellis/spec/backend/error-handling.md b/.trellis/spec/backend/error-handling.md deleted file mode 100644 index bcd55337..00000000 --- a/.trellis/spec/backend/error-handling.md +++ /dev/null @@ -1,51 +0,0 @@ -# Error Handling - -> How errors are handled in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Error Types - - - -(To be filled by the team) - ---- - -## Error Handling Patterns - - - -(To be filled by the team) - ---- - -## API Error Responses - - - -(To be filled by the team) - ---- - -## Common Mistakes - - - -(To be filled by the team) diff --git a/.trellis/spec/backend/index.md b/.trellis/spec/backend/index.md index 829ed679..beb426ef 100644 --- a/.trellis/spec/backend/index.md +++ b/.trellis/spec/backend/index.md @@ -1,30 +1,26 @@ -# Backend Development Guidelines +# Backend Spec Redirect --- ## Overview -hyb-oa backend work uses Fastify, Prisma and PostgreSQL under `server/`. -The project-specific backend rules live in `../hyb-oa/backend-fastify-prisma.md`; -the files in this directory are Trellis default scaffolding and may be expanded -only when a later task needs deeper backend conventions. +hyb-oa backend work uses Fastify, Prisma and PostgreSQL under `server/`. The +active backend rules live in `../hyb-oa/backend-fastify-prisma.md`. ---- +This directory intentionally contains no separate backend guideline files. The +old default scaffold files were removed because placeholder specs are noise for +future agents. -## Guidelines Index +## Read | Guide | Description | Status | |-------|-------------|--------| | [hyb-oa Backend Rules](../hyb-oa/backend-fastify-prisma.md) | Current project backend rules | Current | -| [Directory Structure](./directory-structure.md) | Module organization and file layout | Scaffold | -| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | Scaffold | -| [Error Handling](./error-handling.md) | Error types, handling strategies | Scaffold | -| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Scaffold | -| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | Scaffold | --- -## Language +## Rule -Project rules are Chinese-first where they are user-facing. Short English files -generated by Trellis may remain when they are tool-facing scaffolding. +Add a new backend spec file only when a later Trellis task discovers concrete, +source-backed backend conventions that do not belong in the project-level +backend spec. diff --git a/.trellis/spec/backend/logging-guidelines.md b/.trellis/spec/backend/logging-guidelines.md deleted file mode 100644 index bb930df8..00000000 --- a/.trellis/spec/backend/logging-guidelines.md +++ /dev/null @@ -1,51 +0,0 @@ -# Logging Guidelines - -> How logging is done in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Log Levels - - - -(To be filled by the team) - ---- - -## Structured Logging - - - -(To be filled by the team) - ---- - -## What to Log - - - -(To be filled by the team) - ---- - -## What NOT to Log - - - -(To be filled by the team) diff --git a/.trellis/spec/backend/quality-guidelines.md b/.trellis/spec/backend/quality-guidelines.md deleted file mode 100644 index c1e1065a..00000000 --- a/.trellis/spec/backend/quality-guidelines.md +++ /dev/null @@ -1,51 +0,0 @@ -# Quality Guidelines - -> Code quality standards for backend development. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Forbidden Patterns - - - -(To be filled by the team) - ---- - -## Required Patterns - - - -(To be filled by the team) - ---- - -## Testing Requirements - - - -(To be filled by the team) - ---- - -## Code Review Checklist - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/component-guidelines.md b/.trellis/spec/frontend/component-guidelines.md deleted file mode 100644 index 6836c3fb..00000000 --- a/.trellis/spec/frontend/component-guidelines.md +++ /dev/null @@ -1,59 +0,0 @@ -# Component Guidelines - -> How components are built in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Component Structure - - - -(To be filled by the team) - ---- - -## Props Conventions - - - -(To be filled by the team) - ---- - -## Styling Patterns - - - -(To be filled by the team) - ---- - -## Accessibility - - - -(To be filled by the team) - ---- - -## Common Mistakes - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/directory-structure.md b/.trellis/spec/frontend/directory-structure.md deleted file mode 100644 index 1eb57d16..00000000 --- a/.trellis/spec/frontend/directory-structure.md +++ /dev/null @@ -1,54 +0,0 @@ -# Directory Structure - -> How frontend code is organized in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Directory Layout - -``` - -src/ -├── ... -└── ... -``` - ---- - -## Module Organization - - - -(To be filled by the team) - ---- - -## Naming Conventions - - - -(To be filled by the team) - ---- - -## Examples - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/hook-guidelines.md b/.trellis/spec/frontend/hook-guidelines.md deleted file mode 100644 index 60c6bb6a..00000000 --- a/.trellis/spec/frontend/hook-guidelines.md +++ /dev/null @@ -1,51 +0,0 @@ -# Hook Guidelines - -> How hooks are used in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Custom Hook Patterns - - - -(To be filled by the team) - ---- - -## Data Fetching - - - -(To be filled by the team) - ---- - -## Naming Conventions - - - -(To be filled by the team) - ---- - -## Common Mistakes - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/index.md b/.trellis/spec/frontend/index.md index 9f4393d6..7fbe87e6 100644 --- a/.trellis/spec/frontend/index.md +++ b/.trellis/spec/frontend/index.md @@ -1,32 +1,29 @@ -# Frontend Development Guidelines +# Frontend Spec Redirect --- ## Overview hyb-oa frontend work uses React, TypeScript, Vite and Tailwind under `client/`. -The project-specific frontend implementation rules live in -`../hyb-oa/frontend-react-vite-design.md`; product experience facts remain in +The active frontend implementation rules live in +`../hyb-oa/frontend-react-vite-design.md`. Product experience facts remain in `docs/产品设计规则.md`. Visual and interaction design authority comes from the installed `frontend-design` skill. ---- +This directory intentionally contains no separate frontend guideline files. The +old default scaffold files were removed because placeholder specs are noise for +future agents. -## Guidelines Index +## Read | Guide | Description | Status | |-------|-------------|--------| | [hyb-oa Frontend Rules](../hyb-oa/frontend-react-vite-design.md) | Current project frontend/design rules | Current | -| [Directory Structure](./directory-structure.md) | Module organization and file layout | Scaffold | -| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | Scaffold | -| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | Scaffold | -| [State Management](./state-management.md) | Local state, global state, server state | Scaffold | -| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Scaffold | -| [Type Safety](./type-safety.md) | Type patterns, validation | Scaffold | --- -## Language +## Rule -Project rules are Chinese-first where they are user-facing. Short English files -generated by Trellis may remain when they are tool-facing scaffolding. +Add a new frontend spec file only when a later Trellis task discovers concrete, +source-backed frontend conventions that do not belong in the project-level +frontend/design spec. diff --git a/.trellis/spec/frontend/quality-guidelines.md b/.trellis/spec/frontend/quality-guidelines.md deleted file mode 100644 index 05a14112..00000000 --- a/.trellis/spec/frontend/quality-guidelines.md +++ /dev/null @@ -1,51 +0,0 @@ -# Quality Guidelines - -> Code quality standards for frontend development. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Forbidden Patterns - - - -(To be filled by the team) - ---- - -## Required Patterns - - - -(To be filled by the team) - ---- - -## Testing Requirements - - - -(To be filled by the team) - ---- - -## Code Review Checklist - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/state-management.md b/.trellis/spec/frontend/state-management.md deleted file mode 100644 index b4fc9662..00000000 --- a/.trellis/spec/frontend/state-management.md +++ /dev/null @@ -1,51 +0,0 @@ -# State Management - -> How state is managed in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## State Categories - - - -(To be filled by the team) - ---- - -## When to Use Global State - - - -(To be filled by the team) - ---- - -## Server State - - - -(To be filled by the team) - ---- - -## Common Mistakes - - - -(To be filled by the team) diff --git a/.trellis/spec/frontend/type-safety.md b/.trellis/spec/frontend/type-safety.md deleted file mode 100644 index 1b1b19e0..00000000 --- a/.trellis/spec/frontend/type-safety.md +++ /dev/null @@ -1,51 +0,0 @@ -# Type Safety - -> Type safety patterns in this project. - ---- - -## Overview - - - -(To be filled by the team) - ---- - -## Type Organization - - - -(To be filled by the team) - ---- - -## Validation - - - -(To be filled by the team) - ---- - -## Common Patterns - - - -(To be filled by the team) - ---- - -## Forbidden Patterns - - - -(To be filled by the team) diff --git a/.trellis/spec/hyb-oa/deployment-trialrun.md b/.trellis/spec/hyb-oa/deployment-trialrun.md index d5ee59ac..42501e38 100644 --- a/.trellis/spec/hyb-oa/deployment-trialrun.md +++ b/.trellis/spec/hyb-oa/deployment-trialrun.md @@ -15,10 +15,10 @@ operations require explicit approval and evidence. if the example contract drifts. - After deployment, report commit hash, `/ready`, public smoke results and whether the user can test. -- Real business writes are manual unless an Issue explicitly authorizes a - controlled test write. +- Real business writes are manual unless the current Trellis task explicitly + authorizes a controlled test write. - Do not execute real payments, import bank statements, connect payment - providers or write ERP without a separate approved Issue. + providers or write ERP without a separate approved Trellis task. ## Scenario: Deployment Env Contract diff --git a/.trellis/spec/hyb-oa/frontend-react-vite-design.md b/.trellis/spec/hyb-oa/frontend-react-vite-design.md index ed8718da..58b18028 100644 --- a/.trellis/spec/hyb-oa/frontend-react-vite-design.md +++ b/.trellis/spec/hyb-oa/frontend-react-vite-design.md @@ -8,6 +8,10 @@ experience and business-boundary fact source, not a visual, brand or aesthetic rulebook. For PC/mobile/WeCom pages, add Playwright or visual verification when reasonable. +This spec keeps hyb-oa-specific React/Vite, shared-component, business-boundary +and verification contracts. Do not copy broad aesthetic guidance from +`frontend-design` into this file; use the skill directly for design judgment. + ## Rules - Use existing React/Vite/Tailwind patterns and shared components before adding @@ -26,7 +30,7 @@ reasonable. ## Frozen / Boundary Items Frozen modules and Enterprise WeChat-owned HR/attendance entries must be labeled -or hidden according to the active Issue; do not silently re-enable them. +or hidden according to the current Trellis task; do not silently re-enable them. - Use the shared `WorkspaceNotice` pattern for trial boundaries, safety notes, and post-trial capabilities instead of page-local warning blocks. - Trial-facing PC lists must hide obvious TEST/SMOKE records by default when a diff --git a/.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md b/.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md index 39c141a6..77b610e1 100644 --- a/.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md +++ b/.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md @@ -8,9 +8,9 @@ duplicate detection or attachment behavior. ## Rules - PDF invoice OCR is the maintained main path. -- Image OCR remains frozen unless a later Issue explicitly reopens it. +- Image OCR remains frozen unless a later Trellis task explicitly reopens it. - Do not write raw invoice images, sensitive form values or full OCR payloads to repo docs, Issue CSV, Trellis task files or chat. - Reimbursement flow tests should cover upload/OCR, duplicate handling, submission, approval, payment batch, receipt attachment and AP export when the - Issue scope touches those areas. + Trellis task scope touches those areas. diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/check.jsonl b/.trellis/tasks/05-29-spec-governance-cleanup/check.jsonl new file mode 100644 index 00000000..7dc44f8e --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/check.jsonl @@ -0,0 +1,4 @@ +{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Verify Trellis-only and commit governance remain consistent"} +{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Verify docs/spec/evidence boundary after cleanup"} +{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Verify frontend-design authority and local UI contracts remain clear"} +{"file": ".trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md", "reason": "Check implementation matches approved audit findings"} diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/implement.jsonl b/.trellis/tasks/05-29-spec-governance-cleanup/implement.jsonl new file mode 100644 index 00000000..8a8351be --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/implement.jsonl @@ -0,0 +1,4 @@ +{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Trellis-only task and commit governance for spec cleanup"} +{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Document/spec/evidence boundary rules for spec governance"} +{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Frontend-design authority and local frontend spec boundary"} +{"file": ".trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md", "reason": "Audit findings and recommended spec cleanup scope"} diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/implement.md b/.trellis/tasks/05-29-spec-governance-cleanup/implement.md new file mode 100644 index 00000000..ec001ba5 --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/implement.md @@ -0,0 +1,50 @@ +# Implementation Notes + +## Decision + +Use `trellis-spec-bootstarp` for the full spec audit and `trellis-update-spec` +for targeted, incremental edits. Do not rebuild the whole spec tree because +the `hyb-oa/` project specs are already high-signal and source-backed. + +## Changes + +- Removed Trellis default placeholder specs under `.trellis/spec/backend/` and + `.trellis/spec/frontend/`. +- Kept `.trellis/spec/backend/index.md` and `.trellis/spec/frontend/index.md` + as short redirect indexes pointing to the real project specs. +- Updated `frontend-react-vite-design.md` to clarify that it keeps + hyb-oa-specific React/Vite/component/business-boundary contracts and should + not copy broad `frontend-design` aesthetic guidance. +- Replaced old new-work “Issue” authorization wording with “Trellis task” in: + - `frontend-react-vite-design.md` + - `deployment-trialrun.md` + - `reimbursement-invoice-ocr.md` +- Preserved historical Issue CSV references in governance/docs rules because + they describe audit history, not new development authorization. + +## Non-Changes + +- No business code changed. +- No frontend pages changed. +- No backend API, Prisma schema, deployment script, production config, + workflow/permission behavior or real data changed. +- `docs/产品设计规则.md` was not changed because it already states that + visual and interaction judgment belongs to `frontend-design`. + +## Verification Plan + +```bash +rg -n "To be filled|Document your project's|active Issue|later Issue|Issue scope|Issue explicitly|separate approved Issue|Scaffold" .trellis/spec || true +python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup +node scripts/qa/check-trellis-governance.mjs +git diff --check +``` + +## Verification Result + +2026-05-29: + +- Placeholder/old-Issue scan returned no findings. +- `python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup` passed. +- `node scripts/qa/check-trellis-governance.mjs` passed. +- `git diff --check` passed. diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/prd.md b/.trellis/tasks/05-29-spec-governance-cleanup/prd.md new file mode 100644 index 00000000..6db8e325 --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/prd.md @@ -0,0 +1,103 @@ +# Spec 治理与去噪审查 + +## Goal + +对当前 `.trellis/spec/` 做一次轻量但系统的治理审查：确认哪些规则仍是稳定工程约束，哪些内容与 `frontend-design`、`docs/` 或任务证据重复，必要时去噪、合并和补强，让后续 AI 开发更容易遵守正确规则。 + +## What I Already Know + +- 用户确认希望按建议执行：先用 `trellis-spec-bootstarp` 做全量体检，再用 `trellis-update-spec` 做具体落地。 +- 最近项目已经明确 Trellis-only，不再使用旧 `hyb-oa-delivery` skill。 +- 前端设计裁决来源已经转向 `frontend-design`，项目内旧前端设计规则如果重复或冲突，应以 `frontend-design` 和当前代码基线为准。 +- `.trellis/spec/hyb-oa/` 已存在项目级 spec：治理、前端、后端、审批、报销/OCR、企微、部署、文档证据、隐私等。 +- `docs/` 仍是业务事实源，spec 不应复制业务文档全文。 +- 当前还有 `05-26-oa-seven-day-trial-live-ops` 任务在进行，本任务不影响真实试运行。 + +## Requirements + +### R1. 先审查，后修改 + +- 先形成 spec 体检报告，列出保留、合并、删除、补强建议。 +- 不在没有依据的情况下大规模重写 `.trellis/spec/`。 +- 每条修改必须能对应到当前项目事实、代码模式、流程约束或近期任务经验。 + +### R2. 明确文档边界 + +- `.trellis/spec/` 只放可复用工程约束、命令/API/状态/权限/部署/隐私等执行规则。 +- `docs/` 继续承载业务规则、公司运营事实、产品规则和手册。 +- `.trellis/tasks/` 继续承载单次任务需求、方案、证据和验收记录。 + +### R3. 前端设计规则去噪 + +- 检查 `.trellis/spec/hyb-oa/frontend-react-vite-design.md` 与 `docs/产品设计规则.md`、`frontend-design` skill 的关系。 +- 保留项目特有的 React/Vite、组件、布局和验证约束。 +- 避免在 spec 中重复大量通用审美规则；冲突时明确以 `frontend-design` 为前端设计裁决来源。 + +### R4. 保留硬边界 + +- 部署、公网检查、隐私、附件、企业微信、权限、审批、报销/OCR 等硬约束不得弱化。 +- 若发现 spec 缺少近期已稳定的执行规则，应补到对应 spec，而不是只留在任务记录。 + +### R5. 验证与收口 + +- 变更后必须通过 Trellis 任务校验、治理校验和 whitespace 检查。 +- 如果只做体检不改 spec，也必须把结论写入本任务 research。 + +## Scope + +- `.trellis/spec/backend/index.md` +- `.trellis/spec/frontend/index.md` +- `.trellis/spec/hyb-oa/frontend-react-vite-design.md` +- `.trellis/spec/hyb-oa/deployment-trialrun.md` +- `.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md` +- 删除 `.trellis/spec/backend/` 和 `.trellis/spec/frontend/` 下默认占位模板文件。 +- 本任务 PRD、implementation notes 和 research 证据。 + +## Acceptance Criteria + +- [x] 已生成 spec 治理体检报告，覆盖 `.trellis/spec/hyb-oa/` 和 `.trellis/spec/guides/`。 +- [x] 已明确 `trellis-spec-bootstarp` 与 `trellis-update-spec` 的使用边界。 +- [x] 已治理重复、过期或冲突的 spec 内容，或明确记录“无需改动”的证据。 +- [x] 已明确 `frontend-design` 与项目本地前端规则的优先级。 +- [x] 未修改业务代码、数据库 schema、生产配置、部署脚本或真实数据。 +- [x] `python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup` 通过。 +- [x] `node scripts/qa/check-trellis-governance.mjs` 通过。 +- [x] `git diff --check` 通过。 + +## Out Of Scope + +- 不重写 `docs/` 业务事实源。 +- 不修改前端页面、后端 API、数据库、权限模型、审批状态机、企业微信配置或部署配置。 +- 不引入新 skill，不删除现有 Trellis skill。 +- 不把 spec 治理变成产品需求重写或公司制度整理。 + +## Test Plan + +```bash +rg -n "To be filled|Document your project's|active Issue|later Issue|Issue scope|Issue explicitly|separate approved Issue|Scaffold" .trellis/spec || true +python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup +node scripts/qa/check-trellis-governance.mjs +git diff --check +``` + +## Technical Notes + +- 主要审查对象： + - `.trellis/spec/hyb-oa/*.md` + - `.trellis/spec/guides/*.md` + - `docs/产品设计规则.md` + - 当前可用 `frontend-design` skill 的职责边界 +- 预期方法： + - `trellis-spec-bootstarp`：用于全量审查和体系边界判断。 + - `trellis-update-spec`：用于把确认后的具体规则写入已有 spec。 + +## Implementation Result + +2026-05-29 已完成： + +- 体检报告：`research/spec-audit.md`。 +- 删除 `.trellis/spec/backend/` 和 `.trellis/spec/frontend/` 下的默认模板占位文件。 +- 保留 backend/frontend 两个 `index.md`，改成指向 `hyb-oa` 真实项目 spec 的短 redirect。 +- 更新 `frontend-react-vite-design.md`，明确本地 spec 不复制 `frontend-design` 的通用审美规则，只保留 hyb-oa 工程约束。 +- 将新开发授权口径从旧 “Issue” 改成 Trellis task。 +- 未修改业务代码、生产配置、部署脚本、数据库或真实数据。 diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md b/.trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md new file mode 100644 index 00000000..63c7e91b --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md @@ -0,0 +1,87 @@ +# Spec 治理体检报告 + +## Method + +按 `trellis-spec-bootstarp` 的口径审查现有 `.trellis/spec/`： + +- 是否描述当前项目真实结构，而不是保留模板占位。 +- 是否把业务事实、任务证据和可复用工程约束分清。 +- 是否与 `frontend-design`、`docs/产品设计规则.md` 和 Trellis-only 口径一致。 +- 是否包含可执行的命令、签名、边界、错误矩阵或测试要求。 + +## Inventory + +当前 spec 分三组： + +- `.trellis/spec/hyb-oa/`：项目真实高信号规则，覆盖治理、前端、后端、审批、报销/OCR、企微、部署、文档证据、隐私。 +- `.trellis/spec/guides/`：跨层思考和复用思考清单。 +- `.trellis/spec/backend/`、`.trellis/spec/frontend/`：除 `index.md` 外，大量仍是 Trellis 默认脚手架，占位文案为 `To be filled by the team`。 + +## Findings + +### F1. hyb-oa 主 spec 应保留 + +`hyb-oa/` 下规则大多是近期任务沉淀出的真实工程约束，包含命令、文件路径、边界、错误行为和测试要求。应作为当前唯一高信号项目 spec 主体保留。 + +代表文件： + +- `project-governance.md` +- `frontend-react-vite-design.md` +- `backend-fastify-prisma.md` +- `deployment-trialrun.md` +- `docs-and-evidence.md` +- `security-privacy.md` + +### F2. backend/frontend 默认脚手架是噪音 + +`backend/` 和 `frontend/` 下多个文件仍含模板问题和 `To be filled by the team`，没有项目约束。它们会让后续 AI 误以为有一套待补充的并行规范。 + +建议： + +- 删除这些占位文件。 +- 保留 `backend/index.md` 和 `frontend/index.md`，把它们改成 redirect/index，只指向 `hyb-oa` 项目真实 spec。 + +### F3. 少量旧 Issue 口径需要改为 Trellis task + +Trellis-only 已是当前治理口径，但部分 spec 仍用 “Issue” 表达新任务授权： + +- `frontend-react-vite-design.md`：`active Issue` +- `deployment-trialrun.md`：`Issue explicitly authorizes`、`separate approved Issue` +- `reimbursement-invoice-ocr.md`：`later Issue`、`Issue scope` + +建议统一改为 “current Trellis task” 或 “separate approved Trellis task”。历史 Issue CSV 只保留为审计材料。 + +### F4. frontend-design 边界已基本正确 + +`docs/产品设计规则.md` 已声明前端视觉裁决交给 `frontend-design`，自身只保留产品体验事实。`frontend-react-vite-design.md` 也已声明 `frontend-design` 是设计 authority。 + +建议只补强一句：本地 spec 保留项目工程约束和组件/测试契约，不复制 `frontend-design` 的通用审美规则。 + +### F5. guides 可暂时保留 + +`guides/` 是思考清单，虽然偏通用，但没有模板占位，也不会与 hyb-oa 主 spec 冲突。暂不治理；后续只有在发现误导时再精简。 + +## Recommended Changes + +1. 删除默认占位 spec 文件： + - `.trellis/spec/backend/database-guidelines.md` + - `.trellis/spec/backend/directory-structure.md` + - `.trellis/spec/backend/error-handling.md` + - `.trellis/spec/backend/logging-guidelines.md` + - `.trellis/spec/backend/quality-guidelines.md` + - `.trellis/spec/frontend/component-guidelines.md` + - `.trellis/spec/frontend/directory-structure.md` + - `.trellis/spec/frontend/hook-guidelines.md` + - `.trellis/spec/frontend/quality-guidelines.md` + - `.trellis/spec/frontend/state-management.md` + - `.trellis/spec/frontend/type-safety.md` +2. 将 `backend/index.md` 和 `frontend/index.md` 改成短 redirect index。 +3. 把新开发授权口径从 Issue 统一改为 Trellis task。 +4. 在 `frontend-react-vite-design.md` 明确不复制 `frontend-design` 通用审美规则。 +5. 跑 `rg "To be filled|Document your project's|active Issue|later Issue|Issue scope"` 验证噪音清除。 + +## Non-Changes + +- 不重写 `hyb-oa/` 主 spec。 +- 不动 `docs/` 业务事实源。 +- 不修改业务代码、部署脚本、生产配置、数据库或测试逻辑。 diff --git a/.trellis/tasks/05-29-spec-governance-cleanup/task.json b/.trellis/tasks/05-29-spec-governance-cleanup/task.json new file mode 100644 index 00000000..c47135cc --- /dev/null +++ b/.trellis/tasks/05-29-spec-governance-cleanup/task.json @@ -0,0 +1,26 @@ +{ + "id": "spec-governance-cleanup", + "name": "spec-governance-cleanup", + "title": "Spec 治理与去噪审查", + "description": "审查并治理 Trellis spec，删除占位噪音，统一 frontend-design 与 Trellis-only 规则边界。", + "status": "in_progress", + "dev_type": null, + "scope": "trellis-spec-governance", + "package": null, + "priority": "P2", + "creator": "shunli", + "assignee": "shunli", + "createdAt": "2026-05-29", + "completedAt": null, + "branch": null, + "base_branch": "main", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [], + "notes": "", + "meta": {} +}