|
|
|
@@ -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
|
|
|
|
|
