治理 Trellis spec 占位噪音与规则口径（05-29-spec-governance-cleanup）
这个提交包含在：
@@ -1,51 +0,0 @@
|
||||
# Database Guidelines
|
||||
|
||||
> Database patterns and conventions for this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's database conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What ORM/query library do you use?
|
||||
- How are migrations managed?
|
||||
- What are the naming conventions for tables/columns?
|
||||
- How do you handle transactions?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Query Patterns
|
||||
|
||||
<!-- How should queries be written? Batch operations? -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Migrations
|
||||
|
||||
<!-- How to create and run migrations -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
<!-- Table names, column names, index names -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Database-related mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,54 +0,0 @@
|
||||
# Directory Structure
|
||||
|
||||
> How backend code is organized in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's backend directory structure here.
|
||||
|
||||
Questions to answer:
|
||||
- How are modules/packages organized?
|
||||
- Where does business logic live?
|
||||
- Where are API endpoints defined?
|
||||
- How are utilities and helpers organized?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
<!-- Replace with your actual structure -->
|
||||
src/
|
||||
├── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Organization
|
||||
|
||||
<!-- How should new features/modules be organized? -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
<!-- File and folder naming rules -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
<!-- Link to well-organized modules as examples -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,51 +0,0 @@
|
||||
# Error Handling
|
||||
|
||||
> How errors are handled in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's error handling conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What error types do you define?
|
||||
- How are errors propagated?
|
||||
- How are errors logged?
|
||||
- How are errors returned to clients?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Error Types
|
||||
|
||||
<!-- Custom error classes/types -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
<!-- Try-catch patterns, error propagation -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## API Error Responses
|
||||
|
||||
<!-- Standard error response format -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Error handling mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
+11
-15
@@ -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.
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# Logging Guidelines
|
||||
|
||||
> How logging is done in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's logging conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What logging library do you use?
|
||||
- What are the log levels and when to use each?
|
||||
- What should be logged?
|
||||
- What should NOT be logged (PII, secrets)?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Log Levels
|
||||
|
||||
<!-- When to use each level: debug, info, warn, error -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Structured Logging
|
||||
|
||||
<!-- Log format, required fields -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## What to Log
|
||||
|
||||
<!-- Important events to log -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Log
|
||||
|
||||
<!-- Sensitive data, PII, secrets -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,51 +0,0 @@
|
||||
# Quality Guidelines
|
||||
|
||||
> Code quality standards for backend development.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's quality standards here.
|
||||
|
||||
Questions to answer:
|
||||
- What patterns are forbidden?
|
||||
- What linting rules do you enforce?
|
||||
- What are your testing requirements?
|
||||
- What code review standards apply?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
<!-- Patterns that should never be used and why -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Required Patterns
|
||||
|
||||
<!-- Patterns that must always be used -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
<!-- What level of testing is expected -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
<!-- What reviewers should check -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,59 +0,0 @@
|
||||
# Component Guidelines
|
||||
|
||||
> How components are built in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's component conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What component patterns do you use?
|
||||
- How are props defined?
|
||||
- How do you handle composition?
|
||||
- What accessibility standards apply?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Component Structure
|
||||
|
||||
<!-- Standard structure of a component file -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Props Conventions
|
||||
|
||||
<!-- How props should be defined and typed -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Styling Patterns
|
||||
|
||||
<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
<!-- A11y requirements and patterns -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Component-related mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,54 +0,0 @@
|
||||
# Directory Structure
|
||||
|
||||
> How frontend code is organized in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's frontend directory structure here.
|
||||
|
||||
Questions to answer:
|
||||
- Where do components live?
|
||||
- How are features/modules organized?
|
||||
- Where are shared utilities?
|
||||
- How are assets organized?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
<!-- Replace with your actual structure -->
|
||||
src/
|
||||
├── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Organization
|
||||
|
||||
<!-- How should new features be organized? -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
<!-- File and folder naming rules -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
<!-- Link to well-organized modules as examples -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,51 +0,0 @@
|
||||
# Hook Guidelines
|
||||
|
||||
> How hooks are used in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's hook conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What custom hooks do you have?
|
||||
- How do you handle data fetching?
|
||||
- What are the naming conventions?
|
||||
- How do you share stateful logic?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Custom Hook Patterns
|
||||
|
||||
<!-- How to create and structure custom hooks -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Data Fetching
|
||||
|
||||
<!-- How data fetching is handled (React Query, SWR, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
<!-- Hook naming rules (use*, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Hook-related mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
+11
-14
@@ -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.
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# Quality Guidelines
|
||||
|
||||
> Code quality standards for frontend development.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's quality standards here.
|
||||
|
||||
Questions to answer:
|
||||
- What patterns are forbidden?
|
||||
- What linting rules do you enforce?
|
||||
- What are your testing requirements?
|
||||
- What code review standards apply?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
<!-- Patterns that should never be used and why -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Required Patterns
|
||||
|
||||
<!-- Patterns that must always be used -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
<!-- What level of testing is expected -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
<!-- What reviewers should check -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,51 +0,0 @@
|
||||
# State Management
|
||||
|
||||
> How state is managed in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's state management conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What state management solution do you use?
|
||||
- How is local vs global state decided?
|
||||
- How do you handle server state?
|
||||
- What are the patterns for derived state?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## State Categories
|
||||
|
||||
<!-- Local state, global state, server state, URL state -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## When to Use Global State
|
||||
|
||||
<!-- Criteria for promoting state to global -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Server State
|
||||
|
||||
<!-- How server data is cached and synchronized -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- State management mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -1,51 +0,0 @@
|
||||
# Type Safety
|
||||
|
||||
> Type safety patterns in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's type safety conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What type system do you use?
|
||||
- How are types organized?
|
||||
- What validation library do you use?
|
||||
- How do you handle type inference?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Type Organization
|
||||
|
||||
<!-- Where types are defined, shared types vs local types -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
<!-- Type utilities, generics, type guards -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
<!-- any, type assertions, etc. -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"}
|
||||
@@ -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"}
|
||||
@@ -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.
|
||||
@@ -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。
|
||||
- 未修改业务代码、生产配置、部署脚本、数据库或真实数据。
|
||||
@@ -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/` 业务事实源。
|
||||
- 不修改业务代码、部署脚本、生产配置、数据库或测试逻辑。
|
||||
@@ -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": {}
|
||||
}
|
||||
在新工单中引用
屏蔽一个用户