沉淀页面设计规则（page-design-rules-audit）

.trellis/spec/hyb-oa/frontend-react-vite-design.md

@@ -160,6 +160,48 @@ change the visual treatment once while preserving component contracts.
 - Focused Playwright screenshot coverage when changing login, Portal, primary
   PC list pages or command-bar/table styling.
 
+## Convention: Page Template Taxonomy
+
+**What**: hyb-oa frontend pages use six layout templates. New or redesigned
+pages must pick one primary template before implementation:
+
+- `工作台总览`: Portal and mobile home. Compact summary, today's actionable
+  items, conditional progress/blocker/reminder sections.
+- `任务处理列表`: workflow task queues. Pending summary, task list, processed
+  records and advanced filters.
+- `业务台账列表`: reimbursement, contracts, projects, payments, AP and invoices.
+  Page-header primary action, command bar, list/table body and folded ledger
+  tools.
+- `主从工作台`: procurement, assets and inventory checks. Left/index list plus
+  right/current-object detail and actions.
+- `详情工作区`: reimbursement detail, workflow task detail, project detail and
+  future contract detail. Overview, facts/evidence, right-side summary/command
+  panel and history.
+- `管理配置页`: people, organization, master data, approval rules, workflow
+  definitions, feature flags and audit logs. Grouped settings, searchable
+  tables and confirmed destructive/configuration actions.
+
+**Contracts**:
+
+- A page has one primary template. Local sections may reuse shared components,
+  but the page must not mix ledger, configuration, detail and dashboard patterns
+  without an explicit Trellis task.
+- Mobile is the responsive expression of these templates: top status/focus,
+  card list or sectioned detail, bottom primary action. Do not create a PC shell
+  inside mobile routes.
+- B-class business pages should usually choose `业务台账列表` or `主从工作台`.
+  Use a ledger when records open into details; use master-detail when users
+  select one object and edit/process it in the same workspace.
+- A-class task pages must not drift into configuration surfaces. C-class
+  configuration pages must not appear as ordinary employee task pages.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks for changed A-class, mobile or shared
+  template surfaces.
+
 ## Convention: Global Shell And Page Header Baseline
 
 **What**: PC page redesigns should preserve the shared Wave0-2 shell and
@@ -168,8 +210,10 @@ header baseline instead of recreating page-local wrappers:
 - `AppShellLayout` owns the PC shell background and content offset through
   `app-shell` and `app-shell-main`.
 - `Sidebar` and `NavLinks` own role-aware task navigation. The mental model is
-  a short primary task list plus collapsed `更多`; management configuration is
-  represented by one `管理` entry instead of many sidebar rows.
+  a task-first primary list plus collapsed `更多`; enabled OA-owned business
+  ledgers such as contracts, procurement, assets and projects should not be
+  hidden in `更多` by default when the current role has access. Management
+  configuration is represented by one `管理` entry instead of many sidebar rows.
 - `Topbar` is a compact command surface: page title, group badge, user context,
   global search and notifications. Do not expand it back into a large hero.
 - `PageHeader` and `WorkspaceHeader` should use `page-header-shell`,
@@ -187,6 +231,10 @@ point and prevents each route from inventing a different title/action layout.
 - Sidebar entries should be role-aware and task-first for domestic tech startups
   under 10 people; do not expose all permission-allowed modules as a default
   module catalog.
+- Do show enabled, permission-allowed day-to-day business ledgers directly in
+  the primary sidebar, including `合同`, `采购`, `资产` and `项目` when relevant.
+  `更多` is for low-frequency, frozen, staged or occasional entries, not a
+  place to bury common work.
 - Approvers see `待我处理`; ordinary employees should not see `待办` or
   `审批待办` in the sidebar by default.
 - PC leave navigation uses `请假记录` unless the current task explicitly opens OA
@@ -196,8 +244,9 @@ point and prevents each route from inventing a different title/action layout.
 - Finance labels should use work names such as `付款`, `应付账款` and `票据`;
   internal platform words like `AP 运营`, `ERP 集成` and `功能开关` should be
   hidden behind management wording or renamed for users.
-- `更多` is a lightweight collapsed row for low-frequency entries; do not add a
-  sidebar explanation card, subtitle or onboarding copy around it.
+- `更多` is a lightweight collapsed row for low-frequency, frozen, staged or
+  occasional entries; do not add a sidebar explanation card, subtitle or
+  onboarding copy around it.
 - Playwright navigation helpers should use exact names or anchored regex for
   short sidebar labels such as `管理`, otherwise fuzzy role-name matching can
   click longer labels such as `预算管理`.
@@ -220,6 +269,823 @@ point and prevents each route from inventing a different title/action layout.
   `Topbar`, `NavLinks`, `PageHeader`, `WorkspaceHeader`, login, Portal or other
   A-class pages.
 
+## Convention: Action Placement Baseline
+
+**What**: Page actions, filters, ledger tools and destructive commands use one
+system-wide coordinate model. New and redesigned pages should not invent
+page-local action placement.
+
+**Contracts**:
+
+- PC page primary action lives in the page header action area
+  (`WorkspaceHeader` / `PageHeader` actions). Keep one primary action per page
+  surface and at most two visible secondary actions.
+- List filters live in the first command bar below the page header. Search,
+  status, scope and other common filters stay on the left; ledger tools such as
+  export, batch, statistics, templates and advanced filters stay on the right or
+  inside `台账工具` / `更多`.
+- Row-level actions live at the right edge of a table row or at the tail of a
+  card. Prefer `查看详情`, `查看处理` and `继续编辑` over broad verbs that hide the
+  result.
+- Detail pages keep facts and evidence in the main content. High-risk actions
+  such as approve, reject, return, pay, publish, delete and configuration
+  switching live in the right command panel or a clearly separated
+  `detail-action-stack`, with confirmation that includes the current object
+  summary.
+- Form save/submit actions live at the form bottom on PC. Long forms may add a
+  right-side summary command panel, but the same action should not be repeated in
+  unrelated header, row and footer locations.
+- Mobile pages use top status/focus content plus a bottom safe-area action
+  surface for the primary action. Do not copy PC command bars or wide tables
+  into mobile routes.
+- Batch actions only appear after selection, as a contextual command bar or
+  bottom sticky bar.
+- Destructive, financial, approval and configuration-changing actions must be
+  visually and structurally separated from normal navigation/edit actions.
+
+**Why**: hyb-oa targets small teams where one person may switch roles many times
+per day. Stable action coordinates reduce relearning and help a solo developer
+avoid page-by-page exceptions.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks when changing shared page headers,
+  command bars, task lists, detail action panels or mobile bottom actions.
+
+## Convention: State-Driven Actions
+
+**What**: Business actions are derived from explicit object state and current
+actor context. Do not scatter page-local button conditions across route
+components.
+
+**Contracts**:
+
+- Before redesigning a page with mutable business records, define or reference a
+  state matrix. The matrix must cover object state, actor role, primary action,
+  secondary actions, forbidden actions, reason text, risk level and confirmation
+  requirement.
+- Common lifecycle states include draft, submitted, in approval, returned or
+  rejected, approved, pending execution or payment, completed or paid,
+  cancelled, abnormal and archived. Use the business module's real names when
+  they differ.
+- Draft states prioritize edit, submit and delete draft. Do not show approval or
+  payment actions there.
+- In-approval states prioritize progress, withdraw and supplement-material
+  actions. Approve, reject and return actions belong to the current user's
+  workflow task detail, not broad ledger rows.
+- Returned or rejected states prioritize correction and resubmission.
+- Approved-but-not-paid states route payment work to finance or cashier views;
+  ordinary employee views should explain the next step instead of exposing
+  executable payment controls.
+- Payment actions such as mark paid, register payment, cancel payment, batch
+  payment and execute payment live only in payment, finance-processing,
+  payment-batch detail or an explicitly current finance task panel.
+  Reimbursement, procurement, contract and project ledgers/details show payment
+  status, receipt status, `查看付款`, `补回单` or a payment-record link instead
+  of executable payment controls.
+- Paid, completed, archived and cancelled states are read-mostly. Print, export,
+  attachment download and history belong in `更多` or audit paths when allowed.
+- Abnormal states must explain source, impact and next step. A red status label
+  alone is insufficient.
+- Destructive, financial, approval and configuration-changing actions require
+  confirmation that shows the current object summary and writes audit evidence
+  when the backend supports it.
+- The frontend may hide disabled actions or show reason text, but the backend
+  remains the source of truth for permission and state validation.
+- Use destructive lifecycle verbs consistently: `删除` only for drafts,
+  non-effective temporary records or wrong materials that have not entered a
+  business process; `撤回` for initiator withdrawal during allowed workflow
+  states; `取消` when the business will not continue; `作废` when a numbered,
+  signed, paid, published or effective object becomes invalid; `归档` when a
+  completed object is locked for retention. Submitted business records should
+  not be physically deleted from ordinary UI paths.
+
+**Why**: State-driven actions prevent pages from showing buttons that the user
+cannot complete and keep reimbursement, procurement, contracts, assets and
+payments consistent as the system grows.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright coverage for changed state/action behavior, especially
+  draft, rejected/returned, in-approval, approved, paid/completed, cancelled and
+  abnormal states.
+
+## Convention: Role-Scoped Data Surfaces
+
+**What**: The backend is the source of truth for permissions and data scope. The
+frontend shapes the authorized capabilities into the current task role instead
+of exposing every allowed tool at once.
+
+**Contracts**:
+
+- Ordinary employee views default to `我的`, `与我相关`, `我发起` and
+  `需要我补充`. Do not show company-wide ledgers, batch tools, export, audit,
+  configuration, internal IDs or other people's sensitive attachments by
+  default.
+- Initiator views emphasize current status, next step, supplement-material
+  needs, approval/payment progress and whether edit or withdraw is allowed.
+- Approver and processor views emphasize `待我处理` and the current node task.
+  Show approve, reject, return or transfer actions only when the server-backed
+  task assignment says the current user can act.
+- Approval actions such as approve, reject, return and transfer execute only in
+  `待我处理`, workflow task detail, mobile approval detail or an explicitly
+  current task-processing panel. Business ledger rows and ordinary business
+  details use `查看处理`, `查看进度`, `补材料` or a link into the workflow task;
+  they must not duplicate approval action buttons.
+- Finance and cashier views may expose authorized reimbursement, payment,
+  invoice, AP, receipt and exception operations. Full-scope, export, batch,
+  delegated creation and statistics tools belong in `台账工具`, `更多` or
+  role-only panels.
+- Owner and project-lead views emphasize team/project scope, blockers, risks and
+  approvals. They should not drift into system configuration unless the route is
+  a management route.
+- Admin views live under `管理` and cover people, organization, workflow,
+  feature flags, integrations, audit and troubleshooting. Do not mix these
+  controls into ordinary employee paths.
+- Read-only or audit views can show authorized evidence but must not show
+  mutable edit, approval, payment, publish or disable actions.
+- Do not add a global role or identity switcher. Multi-role users do not choose
+  `员工` / `财务` / `管理员` before using the system. Routes infer the most
+  relevant task view by default.
+- Multi-role users may switch scope inside a specific authorized ledger, but the
+  default scope follows the page purpose: reimbursement starts with mine,
+  workflow tasks start with my tasks, ledgers start with relevant or recent
+  records, management starts with management scope. Use route-local scope
+  controls such as `我相关` / `我负责` / `财务处理` / `全范围`.
+- Use explicit controls such as `我的 / 团队 / 全范围` only when the server grants
+  those scopes. Hiding controls in the frontend is not a security boundary.
+- Unauthorized actions should usually be hidden. When explanation is useful,
+  show short natural Chinese reasons such as `当前节点不是你处理`, `已支付单据不可编辑`
+  or `仅财务可导出`.
+
+**Why**: hyb-oa users often wear several hats. Role-scoped surfaces keep one
+person's broad authority from turning every page into an admin console.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Role-focused Playwright coverage when changing visibility for employee,
+  approver, finance/owner or admin paths.
+
+## Convention: User-Facing Identifiers And Copy Semantics
+
+**What**: Ordinary product surfaces use business identifiers and natural
+Chinese. Internal identifiers are auxiliary evidence for audit and
+troubleshooting, not primary user-facing content.
+
+**Contracts**:
+
+- Use business identifiers, names or summaries as primary labels: reimbursement
+  number, purchase request number, contract number, asset number, payment batch
+  number and project name.
+- Do not show UUID, taskId, entityId, permission code, role code, internal state
+  code, raw payload, full local path, API path, database field name, OCR
+  provider, debug trace, Secret or token on ordinary employee, approver,
+  finance or mobile paths.
+- Audit logs, admin troubleshooting, integration failure details, printed
+  evidence and export handoff files may show necessary internal IDs when
+  authorized. Place them in low-priority areas such as `技术信息`, `审计信息` or
+  `排障信息`; never use them as the page title, card title, button label or
+  first ordinary list column.
+- Show one primary identifier for the same object in one surface. Avoid placing
+  business number, UUID, taskId and entityId together unless the route is an
+  audit/troubleshooting route.
+- Translate technical enum values and platform words into natural Chinese:
+  `PENDING_APPROVAL` becomes `审批中`; `REJECTED` becomes `已驳回` or
+  `被退回待补正`; `AP Operations` becomes `应付账款`; `Feature Flag` becomes
+  management wording.
+- Time copy should answer the business question. Prefer `已等待多久`, `接收于`,
+  `提交于`, `支付于` and `归档于` over generic `更新时间` when the user needs to
+  decide what to do.
+- Errors and abnormal states must explain source, impact and next step in
+  natural Chinese. Do not surface only HTTP codes, backend enum names or red
+  badges.
+- Notifications and mobile cards use the shortest useful business identifier or
+  summary. Do not pack long technical IDs into small surfaces.
+
+**Why**: Internal implementation language makes the product feel complex and
+unfamiliar. Business identifiers and natural Chinese keep small-team workflows
+legible.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- UI tests or screenshot review for changed list/detail/notification/mobile
+  surfaces to confirm internal IDs and technical enum names are not visible.
+
+## Convention: Ledger List Defaults
+
+**What**: Business list and ledger pages default to a light, task-oriented list.
+Advanced ledger capabilities remain available but must not dominate the first
+screen.
+
+**Contracts**:
+
+- Keep 3 to 5 high-frequency filters visible by default. Prioritize search,
+  status, scope and date/time; add business-specific filters such as project,
+  person or type only when they are genuinely frequent.
+- The default view must match the route's main job: `我的报销`, `待我处理`,
+  `合同台账`, `资产台账` and similar task nouns. Do not default ordinary users
+  into company-wide management views.
+- Rows and cards must answer what the object is, current state, why it relates
+  to the current user and the next action.
+- Place common filters on the left side of the command bar below the page
+  header. Put export, batch, statistics, templates, full-scope, advanced
+  filters, delegated creation and low-frequency module links in `台账工具`,
+  `更多` or role-only panels.
+- Batch actions appear only after selection, as a contextual command bar or
+  bottom sticky bar. High-risk batch actions such as approve, pay, delete or
+  publish require summary confirmation and result details.
+- Export is not a primary page action. Explain export scope and sensitive
+  content when relevant; finance, contract, asset and invoice exports must stay
+  permissioned and auditable.
+- PC ledgers may use pagination, sorting and density controls. Default columns
+  should be decision-supporting fields only; low-frequency fields belong in
+  details, column configuration or advanced filters.
+- Empty states are status-specific. `没有草稿`, `没有被驳回`, `没有待处理` and
+  `没有异常` should not all share one generic explanatory panel.
+- Mobile routes do not copy PC ledger tools. Use search, status filtering, card
+  lists and one primary action; leave complex analysis, export and broad-scope
+  management to PC.
+- Contract, procurement, project and finance ledgers use a list-to-detail
+  boundary. The list is for discovery, filtering, status reading and navigation.
+  High-risk or sensitive actions such as contract download, archive, payment,
+  export, batch processing, void/cancel and sensitive attachment viewing belong
+  in detail workspaces, detail command panels or `台账工具`, with permission,
+  audit and confirmation.
+- Default ledger scope follows the current task role: ordinary employees see
+  `我发起` / `我相关`, owners and project leads see `我负责` / `项目相关`, finance
+  sees `待复核` / `待付款` / `异常`, and admins may enter or switch to `全范围`.
+  Full scope, export and batch commands stay in `台账工具` or role-only panels,
+  not ordinary first screens.
+- Contract ledgers in V1 are registration, archive, due/renewal reminder and
+  relation surfaces for project, procurement and payment context. Do not design
+  `/contracts-registry` as e-signature, legal-review, clause-library,
+  version-collaboration or full CLM software. If contract approval is needed,
+  link to the OA approval center or a separate future task instead of adding an
+  approval workspace inside the contract ledger.
+- Procurement ledgers in V1 are request, approval, attachment, light
+  acceptance/archive and relation surfaces for project, contract and payment/AP
+  context. Do not design `/purchase-requests` as purchase-order lifecycle,
+  inventory, three-way matching, supplier-lifecycle, tendering or ERP software.
+  Approved procurement means the request was approved; it does not imply paid,
+  received into inventory or converted into a fixed asset.
+- Project pages in V1 are light project ledgers for status, owner/member,
+  milestone/task, risk, delivery-record and related reimbursement, procurement,
+  contract and payment context. Do not design `/projects` as full project
+  management software with Gantt charts, complex dependencies, timesheets,
+  resource scheduling, OKR, portfolio management or large collaboration suites.
+  Project pages summarize and route; source records stay in their business
+  modules.
+- Finance ledgers in V1 are payment-preparation, payment-batch, receipt-audit,
+  AP-status, invoice/OCR-status and agency-accounting handover summaries. Do
+  not design payment, AP or invoice pages as online banking, bank-statement
+  ingestion, ERP/general-ledger, voucher-generation, auto-reconciliation, tax
+  filing or full accounting software. Real payment stays in offline banking or
+  existing finance/accounting workflows; OA records status, evidence and
+  handover summaries.
+- Payment actions require the finance/payment context: amount, payee or target
+  object, source records, offline payment explanation, evidence completeness,
+  receipt requirement and correction boundary. Do not place `标记已付款`,
+  `取消付款`, `批量付款` or `执行付款` directly in reimbursement, procurement,
+  contract or project ledgers/details.
+- Cross-module relation sections are summary-and-route surfaces. Project,
+  procurement, contract, reimbursement, asset and payment pages may show related
+  business number/name, status, amount or quantity, owner, evidence completeness
+  and next-step summary, then link to the owning detail/task/finance page. Do not
+  duplicate the owning module's approval actions, payment actions, invoice/OCR
+  processing, contract-body download, sensitive attachment actions, state machine
+  or batch tools inside another module's relation card.
+
+**Why**: The product's main complexity complaint is too many visible operations.
+Light default ledgers keep daily work simple while preserving advanced finance
+and management workflows.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks when changing list filters, command
+  bars, `台账工具`, batch selection behavior, empty states or mobile list cards.
+
+## Convention: Asset Registry Pages
+
+**What**: Asset pages render `FA` fixed assets as a lightweight responsibility
+ledger inside the unified asset registry, not as a full accounting fixed-asset
+subsystem.
+
+**Contracts**:
+
+- The default `/assets` view answers where the asset is, who uses it, who is
+  responsible for it, what state it is in and whether it needs inventory or
+  handover. Do not lead with depreciation, accounting subjects or ERP sync.
+- Register physical items that must be returned, transferred, inventoried or
+  protected, such as computers, monitors, disks, equipment and security media.
+  Do not create `FA` cards for ordinary consumables.
+- Every `FA` card needs an asset number. Physical assets that can carry labels
+  should expose QR-label status for scan, inventory, assignment and return
+  workflows. Assets that cannot be labeled must still expose serial number,
+  custodian and location as the lookup fallback.
+- Inventory cadence is lightweight: quarterly routine checks by default, event
+  checks for departure, transfer, repair and retirement, and monthly custodian
+  plus location confirmation for high-risk physical assets such as backup disks,
+  security media and critical equipment.
+- Assignment, return and transfer are daily flow actions that admins may record
+  with audit evidence. Disposal actions such as retirement, loss, sale and gift
+  require owner confirmation, a reason and consequence summary. If compensation,
+  money or responsibility is disputed, the asset UI records pending/confirmed
+  outcomes only and must not complete the dispute in one click.
+- Keep acquisition source, business number, owner/custodian, location, status,
+  assignment, return, transfer, repair, retirement, inventory result and
+  handover evidence visible in the business flow.
+- Procurement or reimbursement records may expose an asset-candidate signal, but
+  they must not create an `FA` asset card automatically after approval,
+  submission or payment. The asset registry UI may guide admins from candidates
+  to `新建资产卡片`, but the card is created only after manual verification of
+  delivery, quantity, owner/custodian, consumable status, returns and gifts.
+- Move depreciation, residual value, accounting subject and monthly
+  depreciation voucher concepts out of the OA primary UI unless a later Trellis
+  task explicitly scopes accounting-ledger work.
+- Keep classification maintenance, ERP sync, raw metadata and advanced filters
+  behind management, collapsed or advanced surfaces so they do not dominate the
+  asset list/detail first screen.
+- Mobile asset lookup should prefer QR scan and fall back to asset number or
+  serial number input. Do not require heavy photo inventory unless a later task
+  explicitly scopes it.
+- Asset list/detail UI may show last inventory, next inventory and overdue
+  hints. Do not turn cadence into a complex scheduling/configuration console in
+  the default asset registry view.
+- Disposal commands must be visually separated from assignment/return/transfer
+  commands and use confirmation that shows asset number, name, owner, current
+  custodian, location, reason and effect on asset status.
+- Electronic assets (`EA-DOC`, `EA-SYS`, `EA-REPO`, `EA-BKP`) are metadata and
+  responsibility indexes. Show owner, custodian/admin, permission-recovery
+  requirement, backup or restore-verification date, sensitivity level and
+  archive-location summary. Do not display or store source packages, secrets,
+  tokens, full configs, real full paths or backup contents.
+- `EA-DOC` list/detail views show document name, type, hash or verification
+  summary, sensitivity level, owner, related project/contract/payment and
+  archive-location summary. Contract text, bank statements, certificate
+  originals, customer materials, sensitive quotes, payroll/social-security data
+  and personal identity materials must not appear as ordinary asset-page
+  content; route business originals through their module attachment permissions
+  or offline controlled archive.
+
+**Tests Required**:
+
+- Asset page screenshots or E2E assertions should verify the first screen is
+  asset-list/detail/task oriented, with classification and integration tooling
+  demoted.
+- Mobile asset scan tests should cover lookup, summary and one allowed action;
+  mobile must not expose classification maintenance or full metadata editing.
+  Include QR scan or manual asset-number/serial-number fallback when this
+  surface changes.
+- Electronic asset UI changes should assert that sensitive source/config/backup
+  content and full paths are not visible in ordinary list/detail/mobile views.
+- `EA-DOC` UI changes should assert that high-sensitive originals are not
+  rendered in ordinary asset list/detail/mobile views.
+
+## Convention: Forms, Drafts And Validation
+
+**What**: Long business forms support interruption and recovery. Save draft and
+submit are distinct actions with different consequences.
+
+**Contracts**:
+
+- Long forms should support drafts by default when the business object requires
+  multiple fields, line items or materials, including reimbursements,
+  procurement, contract drafting, asset intake and payment supplement flows.
+- `保存草稿` stores progress only. It must not trigger approval, payment,
+  publishing or external synchronization. `提交` enters the business workflow.
+- Draft save may allow incomplete data, but it must preserve entered fields,
+  line items, attachment references and the recoverable object state.
+- Before submit, run business validation and show a summary confirmation with
+  the object summary, amount or quantity, important contract/asset/payment
+  facts, attachment or invoice completeness, and next node or consequence.
+- Material upload is type-first. Let the user choose or enter the material type
+  before upload, then apply type-specific copy, validation, permissions, audit
+  and display placement. Do not use one generic attachment uploader for PDF
+  invoices, ordinary attachments, contract files, payment receipts, acceptance
+  materials, asset materials and electronic-document indexes.
+- Upload labels must describe the result, such as `上传 PDF 发票`,
+  `补充付款回单`, `上传合同文件`, `补充验收材料` or `登记资产材料`.
+- Validation errors must point to the field, line item, invoice, attachment,
+  contract material or asset section that needs work. A top-level `提交失败`
+  message alone is insufficient.
+- Separate blocking errors from warnings. Blocking errors prevent submit;
+  warnings may allow users to confirm and continue when the business rule
+  permits it.
+- Server-side validation failures must preserve user input and show repair
+  guidance in natural Chinese.
+- Warn before navigation when the form has unsaved changes, including leaving
+  the route, closing a modal, switching record or returning to the list.
+- Autosave can be used as an enhancement, but the visible state must still make
+  clear whether the object is draft, submitted or failed to save.
+- Mobile forms keep only necessary fields, material upload, status explanation
+  and a bottom safe-area primary action. Do not move admin configuration,
+  complex configuration matrices, bulk import or workflow design into mobile
+  forms.
+- Mobile validation messages should appear near the field or material card, and
+  bottom actions must not cover the final input.
+
+**Why**: Small-team users often switch tasks mid-form. Drafts and precise
+validation prevent repeated re-entry and reduce support/debugging cost.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright coverage for draft save, submit validation, unsaved-change
+  protection and server-validation failure paths when changing form behavior.
+
+## Convention: Detail Evidence Layout
+
+**What**: Detail pages use one evidence-first structure so users can understand
+state, facts and consequences before acting.
+
+**Contracts**:
+
+- Use this order for reimbursement, workflow task, procurement, contract, asset,
+  project and payment details: status/next step, business summary, evidence
+  materials, risk or validation signals, approval/processing history, actions.
+- The top overview shows business number or name, current state, critical amount
+  or object facts, current handler or next node, and a clear return path.
+- The first content block is `当前状态与下一步`: explain where the object is,
+  who needs to act, what happens next and whether there are blockers or
+  warnings.
+- The business summary block shows the fields needed before approval or review:
+  requester, amount, project, purchase object, contract counterparty, asset
+  owner, payment batch and similar module facts.
+- Evidence materials sit in the main content, grouped by business meaning:
+  line items, PDF invoices, attachments, contract files, asset photos/numbers,
+  receipts and acceptance materials.
+- Risk or validation sections appear only when there is a real signal such as
+  budget issue, duplicate invoice, missing attachment, contract expiry, asset
+  anomaly or payment failure.
+- Approval and processing history is for traceability. Keep a useful summary
+  visible, but do not let full history crowd out current status and evidence.
+- PC high-risk actions live in the right command panel or separated action
+  stack. Mobile high-risk actions live in the bottom action surface or a
+  confirmation panel.
+- Approve, reject, return, pay, publish, delete and void actions must show the
+  object summary and consequence before execution.
+- When evidence is incomplete, change the primary action to supplement material,
+  view issues or an explained disabled state. Do not leave users guessing from a
+  disabled button alone.
+- List and ledger rows show only evidence completeness summaries, missing
+  evidence hints and a detail entry. Invoice preview, attachment download,
+  contract file viewing, receipt download, evidence deletion and bulk packaging
+  belong in detail workspaces, detail command panels, `台账工具` or authorized
+  audit paths.
+- Sensitive evidence such as invoices, contracts, receipts and attachments must
+  be permissioned; download and export belong in `更多` or audit paths when
+  appropriate.
+- Detail evidence sections group materials by type. Do not mix invoices,
+  ordinary attachments, contract files, receipts, asset materials and
+  electronic-document indexes in one undifferentiated list.
+- Mobile details use a top focus card, sectioned cards and bottom safe-area
+  actions. Do not copy PC two-column detail or wide tables into mobile.
+
+**Why**: Detail pages are the place where users decide whether to approve,
+reject, pay or supplement materials. Consistent evidence order reduces
+misreads and accidental actions.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks when changing detail overview,
+  evidence sections, history placement, right command panels or mobile detail
+  bottom actions.
+
+## Convention: Mobile Lightweight Surfaces
+
+**What**: Mobile and Enterprise WeChat WebView routes are lightweight action
+surfaces. They are not compressed PC management consoles.
+
+**Contracts**:
+
+- Mobile may support lightweight submit, supplement-material, status lookup,
+  task handling, scanning, upload and message-deeplink flows.
+- Keep mobile pages to top status or focus card, card list or sectioned detail,
+  and bottom safe-area primary action.
+- Mobile home should show compact status and today's actionable items. Do not
+  add a full module directory or dashboard.
+- Mobile lists use search/status filtering, cards and one primary action. Do not
+  use wide tables, column configuration, complex multi-column filters,
+  full-scope management, admin configuration, batch export, bulk approval or
+  bulk payment.
+- Mobile details use a focus card, sectioned evidence and bottom actions. Do not
+  copy PC two-column layouts.
+- Mobile forms keep necessary fields, material upload, field-local validation
+  and a bottom action. Do not put admin configuration, workflow configuration,
+  feature flags, statistics dashboards or bulk import into mobile forms.
+- Bottom actions must account for safe area and keyboard overlap. Button text
+  must remain readable on narrow screens.
+- Dangerous mobile actions must open a confirmation panel that shows object
+  summary and consequence.
+- Ordinary mobile paths must not show internal IDs, permission codes,
+  configuration matrices or audit troubleshooting panels.
+- Enterprise WeChat remains the primary owner for daily HR/attendance actions
+  such as leave, missed punch, outing, overtime and check-in. OA mobile shows
+  mirror/history/exception/emergency takeover according to the business
+  boundary.
+
+**Why**: Most mobile use happens from notifications or quick context switches.
+Reducing mobile scope keeps the phone path fast and prevents PC admin
+complexity from leaking into WeChat.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Playwright or screenshot coverage for representative narrow viewports when
+  changing mobile home, mobile lists, mobile details, bottom actions, upload
+  surfaces or Enterprise WeChat WebView flows.
+- If true Enterprise WeChat device validation is unavailable, record it as
+  paused manual validation; do not claim full WebView acceptance.
+
+## Convention: Notifications Versus Tasks
+
+**What**: Task queues and notifications have separate jobs. A task queue is for
+action; a notification center is for event awareness and navigation.
+
+**Contracts**:
+
+- `待我处理` is an action list. Include only items that require the current user
+  to process, supplement material, review, pay, approve, confirm or resolve an
+  exception.
+- Task rows must have a clear next step, object summary, business state and
+  processing entry.
+- Completed items, read-only progress, announcements, successful sync notices
+  and ordinary system messages do not belong in the pending task list.
+- `通知中心` is an event inbox for status changes, reminders, failures, sync
+  results, workflow transitions, invoice/attachment recognition results and
+  Enterprise WeChat delivery results.
+- Notifications should support read/unread, view, jump target and failure
+  explanation. Do not rebuild the full workflow task list inside the
+  notification center.
+- Notification clicks must deep-link to the business detail, workflow task,
+  mobile target page or failure explanation. Do not send users back to a
+  generic notification list as the final destination.
+- Notification copy should explain what happened, who or what is affected, and
+  the next useful step. Do not expose raw payloads, internal state codes or
+  debug fields.
+- Workbench `今日待处理` aggregates only actionable items. Ordinary
+  notifications, read-only progress, completed activity and announcements are
+  not counted as pending work.
+- If a notification represents real work, the backend or aggregation layer
+  should expose it as an explicit task item; the frontend should not infer every
+  notification is a task.
+- The topbar bell is the notification entry. Do not add notification center as a
+  default sidebar row.
+- Enterprise WeChat messages are an external delivery channel. Keep message
+  content desensitized and deep-link into the OA business or task detail.
+
+**Why**: Separating event awareness from action prevents Portal, task queue and
+notification center from showing the same thing in three different ways.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright coverage when changing task aggregation, notification
+  center rows, topbar bell behavior, notification deep links or workbench
+  `今日待处理` counts.
+
+## Convention: Sensitive Data And Exports
+
+**What**: Contracts, finance, invoices, receipts, payments, assets and
+attachments are sensitive by default. Frontend surfaces show the minimum useful
+summary unless a permissioned workflow requires more.
+
+**Contracts**:
+
+- Treat contract text and attachments, quotations, acceptance materials,
+  invoices, receipts, payment information, bank accounts, supplier details,
+  asset serial/location/owner data, personnel records, payroll/performance,
+  audit records, original file names and export files as sensitive.
+- Workbench, notifications, ordinary lists, mobile cards and Enterprise WeChat
+  messages show desensitized summaries only.
+- Ordinary surfaces must not show full bank/account numbers, full local paths,
+  storage paths, raw payloads, full sensitive attachment names, Secrets, tokens
+  or high-sensitive contract/finance details.
+- Previewing contract text, invoices, receipts and attachments requires
+  server-side permission checks. Frontend visibility is not a security boundary.
+- High-sensitive previews should explain context or purpose when useful and
+  record view evidence when the backend supports it.
+- Download, batch download, export, print, attachment packaging, contract text
+  export and finance ledger export must be controlled by server permissions and
+  data scope.
+- Export is never the primary first-screen action. Put exports in `台账工具`,
+  `更多` or role-only finance/admin panels.
+- Before exporting sensitive ledgers, explain scope and sensitive contents.
+  Finance, contract, asset and invoice exports should write audit records.
+- Export file names use business numbers and dates. Do not concatenate complete
+  personal accounts, complete supplier secrets or internal filesystem paths.
+- Audit sensitive operations with actor, time, object, action, scope and result
+  where supported.
+- Permission-denied and failure messages use natural Chinese without leaking
+  full paths, permission codes, raw URLs, payloads, Secrets or tokens.
+
+**Why**: The product is for small teams, but the data is still financial,
+contractual and operationally sensitive. Small team convenience must not turn
+into broad accidental disclosure.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks when changing attachment preview,
+  contract/invoice/receipt surfaces, export controls, mobile summaries,
+  notification copy or permission-denied states.
+
+## Convention: Permission Empty And Error States
+
+**What**: Permission-denied, empty and error states use natural Chinese that
+explains cause and next step. Ordinary users should not inspect platform
+internals to understand what happened.
+
+**Contracts**:
+
+- Hide unauthorized actions by default. If a route is opened directly or the
+  user needs context, show a natural Chinese explanation and a real next step
+  such as returning to workbench, viewing related records or contacting an
+  admin.
+- Empty states are scoped to the current filter, status or section. Explain what
+  is absent and show one useful next step; if there is no real next step, hide
+  the section instead of adding instructional copy.
+- Error states explain business cause, impact and recovery path such as retry,
+  supplement material, return to list or contact admin.
+- Ordinary user paths must not show raw `403`, API route names, permission
+  codes, internal state codes, route stacks, full paths, raw payloads or long
+  technical error dumps.
+- Admin, audit and troubleshooting routes may show the minimum technical
+  details needed to diagnose a problem, but the business reason and next step
+  remain primary.
+- Mobile and notification targets use shorter copy, but must still include
+  cause and next step.
+
+**Why**: Small-team users do not have time to decode implementation details.
+Clear failure states reduce support work and avoid leaking internal platform
+structure.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright or screenshot checks when changing empty states,
+  permission-denied pages, notification failure targets or shared error
+  components.
+
+## Convention: Dangerous Action Confirmation
+
+**What**: Destructive, financial, approval, configuration, batch and external
+sync actions require meaningful confirmation. A generic `确定吗？` dialog is not
+enough.
+
+**Contracts**:
+
+- Treat delete, void, revoke, archive, restore, disable, publish, configuration
+  switching, workflow switching and feature-flag changes as dangerous actions.
+- Treat pay, batch pay, sensitive export, batch download, contract text
+  download and attachment packaging as dangerous or high-sensitive actions.
+- Treat approve, reject, return, transfer, batch approve and batch reject as
+  approval-risk actions that need context before execution.
+- Treat external synchronization, retry external write and Enterprise
+  WeChat/OA emergency-takeover switching as integration-risk actions.
+- Confirmation UI must show object summary: business number, name, requester or
+  counterparty, amount or quantity and current state when relevant.
+- Confirmation UI must explain consequences: target state, reversibility,
+  notifications, payment/approval/configuration impact and external-system
+  effect.
+- Confirmation UI must show impact scope for batch, export, configuration and
+  integration actions: selected count, data range, external system, Enterprise
+  WeChat message or audit scope.
+- Rejection and return require a reason. Payment, publishing, batch and
+  configuration actions may require a confirmation word, explicit checkbox or
+  selected reason when risk is high.
+- Dangerous actions must be visually separated from normal view, edit, save and
+  submit actions.
+- Mobile dangerous actions use bottom or full-screen confirmation panels, not
+  instant execution from an easy-to-mistap control.
+- Confirmation failure must preserve user input and show result details plus the
+  next repair action.
+- Audited actions should record actor, time, object, action, scope, reason and
+  result where backend support exists.
+- Delete, withdraw, cancel, void and archive confirmations must use the exact
+  business verb and explain the target state. Do not label cancel, void or
+  archive as `删除`.
+
+**Why**: These actions can change finance, contracts, workflow, approvals,
+configuration and external integrations. Users need context before execution,
+and support needs an audit trail after execution.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright coverage when changing delete, payment, approval,
+  publish/disable, batch, configuration or external-sync confirmations.
+
+## Convention: Integration Boundary And External Status
+
+**What**: External-system state is conservative. OA shows facts confirmed by its
+own backend and explicit external acknowledgements; it does not present a queued
+request, frontend click or message attempt as final business completion.
+
+**Contracts**:
+
+- OA owns reimbursement, procurement, contracts, projects, payments, AP,
+  invoices, assets, sensitive attachments, audit and OA workflow handling.
+- Enterprise WeChat owns daily HR/attendance actions: check-in, leave, missed
+  punch, outing and overtime. OA shows mirror, history, exception, audit and
+  emergency-takeover records for those domains.
+- ERP, agency accounting, bank, OCR and Enterprise WeChat messages are external
+  capabilities or delivery channels. They do not replace OA server-side
+  permissions or state machines.
+- Show final labels such as `已同步`, `已发送`, `已付款` and `识别完成` only when the
+  relevant external system has returned a clear success acknowledgement.
+- Use in-progress labels such as `同步中`, `等待回执`, `银行处理中`, `识别中` and
+  `消息发送中` when the request has started but is not confirmed.
+- External failures must show source, impact and next step in natural Chinese,
+  such as `银行回执未返回` or `OCR 识别失败，需重新上传 PDF`.
+- Do not expose raw external error codes, payloads, full URLs, secrets, tokens
+  or debug traces to ordinary users.
+- External writes, payment execution, ERP sync, Enterprise WeChat resend and OCR
+  retry must be controlled by permissions and state-driven actions.
+- Retry confirmation should explain which object will be retried, whether it may
+  send duplicate external messages, external-system impact and audit effect.
+- External sync state should not block unrelated primary flows. If it blocks a
+  flow, show the blocker and manual repair path.
+- Ordinary routes show summary, failure reason and next step. Admin, finance or
+  troubleshooting routes may show deeper diagnostics when authorized.
+- HR/attendance routes should default to Enterprise WeChat record, sync mirror
+  or exception handling copy. Do not expose OA daily leave/missed-punch paths
+  unless OA emergency takeover is explicitly enabled.
+- Enterprise WeChat messages carry desensitized summary and OA deeplink only;
+  they do not carry sensitive attachment text or final payment/approval actions.
+- If bank, ERP, agency accounting or another integration is not connected or not
+  confirmed, UI copy must not imply the capability already completed.
+
+**Why**: External integrations are asynchronous and failure-prone. Conservative
+copy prevents users from trusting a state the system has not actually verified.
+
+**Tests Required**:
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- Focused Playwright coverage when changing Enterprise WeChat boundary copy,
+  OCR status, bank/payment callbacks, ERP/accounting sync status, retry
+  controls, external failure messages or integration diagnostics.
+
+## Convention: Verification And User-Testable Claims
+
+**What**: Verification claims must describe the actual validation level. Local
+checks, screenshots and mock Playwright runs do not mean a user can test the
+change online.
+
+**Contracts**:
+
+- Local build passing means only the local code built successfully.
+- Playwright passing means the specified automated path passed in the specified
+  environment and data state.
+- Screenshot review passing means only the captured viewport and state were
+  reviewed.
+- Deployment passing must identify the deployed environment, version or commit
+  and health check result when available.
+- Say `可以线上测试` only after deployment, public access check, key-path smoke
+  testing and necessary screenshot evidence are complete.
+- Before deployment, say `本地验证通过，尚未线上可测`.
+- After deployment but before public access check, say `已部署，公网检查未完成`.
+- If real-device or Enterprise WeChat WebView validation is unavailable, record
+  it as paused manual validation. Do not substitute automation for full WebView
+  acceptance.
+- A-class page changes should keep build, focused Playwright or screenshot
+  evidence according to risk.
+- Changes touching permissions, state machines, approval, payment, Enterprise
+  WeChat, external systems, sensitive downloads or production configuration
+  need rollback or manual repair notes.
+- Updating this design/spec documentation does not mean pages were refactored,
+  deployed or accepted for live trial.
+
+**Why**: This keeps delivery status honest and prevents the user from trying a
+change that has not actually reached a public environment.
+
+**Tests Required**:
+
+- Documentation-only changes: Trellis task validation, governance check and
+  `git diff --check`.
+- Frontend implementation changes: `cd client && npm run typecheck`,
+  `cd client && npm run build`, plus focused Playwright or screenshots based on
+  affected surface.
+
 ## Convention: A-Class PC Task-First Pages
 
 **What**: A-class PC pages such as Portal, approvals, reimbursement list and
@@ -296,6 +1162,10 @@ a later Trellis task adds an explicit backend eligibility contract.
   but normal approval remains in Enterprise WeChat.
 - Reimbursement, procurement, travel, contract and other amount/evidence-heavy
   OA-owned tasks should route through `查看处理` first.
+- Business ledgers and ordinary business details must follow the same rule:
+  show the task entry or progress, but do not place `通过`, `驳回`, `退回` or
+  `转审` directly in reimbursement, procurement, contract, project or asset
+  tables/details.
 - Future list-level quick approval requires the backend to expose an explicit
   eligibility flag such as `quickApproveEligible=true`, plus task-domain and
   audit semantics in the current Trellis task. Frontend heuristics based only on
@@ -319,10 +1189,15 @@ training or permission-maintenance surfaces:
   `处理待办`, `提交报销` or `请假`; do not use explanatory entries like
   `了解流程`, and do not route users to settings or notifications as a
   substitute for task guidance.
-- `个人设置` default content is account identity, notification preference and
-  Enterprise WeChat binding. Organization, report line and role summary may be
-  folded under `账号详情`; permission code lists and full employee dossier fields
-  stay out of the default view.
+- `个人设置` default content is personal profile, password/security,
+  notification preference and Enterprise WeChat binding. Organization, report
+  line and role summary may be folded under `账号详情`; permission code lists
+  and full employee dossier fields stay out of the default view.
+- Keep account settings separate from admin configuration. `个人设置` may show
+  personal profile, password/security, notification preferences and Enterprise
+  WeChat binding only. Organization maintenance, role assignment, approval
+  rules, feature flags, master data, audit logs, employee maintenance and
+  system configuration belong under `管理`, not the ordinary profile route.
 
 **Why**: Small teams need fewer default decisions. Persistent onboarding and
 permission-heavy profile pages make ordinary users inspect system internals