TaskFlow 功能说明书

本文面向 实施、运维、产品与二次开发，说明系统能力边界、模块划分与技术约定。与 README.md、docs/guide/system-design.md、backend/MICROSERVICES.md 互补；界面操作级说明见同目录《用户使用说明书》。

---

1. 产品定位与总体架构

1.1 定位

TaskFlow 是一套 多站点、RBAC 权限驱动 的业务底座，包含：

• PC 管理端（Web）：Vue 3 + Vite + Naive UI，面向管理员与业务岗位。
• 微信小程序：uni-app，面向工人、生产记录员、财务等移动场景。
• 后端：NestJS 多进程——网关 Gateway、系统服务 Sys、记账服务 Acc；数据层 ZenStack + MySQL，会话与 token 黑名单依赖 Redis。

1.2 逻辑架构

组件	默认端口	职责摘要
Gateway	3000	校验 JWT（多数业务路径）；按前缀转发 Sys/Acc；统一响应体 { code, message, data }；支持免 JWT 白名单
Sys	3001	认证注册登录、用户与组织、多站点、角色权限菜单、字典与审计等
Acc	3002	进销存、生产、库存、结算、记工等业务域 API（按站点隔离）

网关向下游透传 x-user-id、x-site-ids、x-user-roles，供 ZenStack 策略与业务层做数据隔离。

1.3 数据与隔离

• 站点：业务数据与 siteId（当前站点） 绑定；PC 端通过 X-Site-Id 请求头与 siteStore 维护当前站点；小程序通过本地存储站点 id 与请求头对齐。
• 权限：菜单型权限入库；PC 动态路由由 POST /sys/me/router-routes 与前端 route-component-registry 映射；小程序入口由 POST /sys/me/mobile-shell-apps 与本地可合并的静态入口共同决定。

---

2. 系统域（Sys）功能范围

以下为能力清单级描述，具体接口以代码与 OpenAPI/控制器为准。

2.1 认证与账号

• 账号注册、邮箱/手机/账号登录、登出、JWT 访问令牌。
• 用户档案：账号、邮箱、用户名、姓名、头像、部门、角色、站点范围等。
• 会话安全：Redis 会话、401 统一清理与前端跳转登录（含 redirect）。

2.2 组织与多站点

• 租户站点树：创建、编辑、排序、编码；站点成员维护。
• 超级管理员 / 系统管理员 可在 PC 顶栏切换当前站点；普通用户落在可见站点集合内。

2.3 RBAC

• 角色、权限（菜单/API）、权限树与排序；用户绑定多角色、数据范围与站点。
• 菜单 route + component 与前端注册表一致时进入动态路由。

2.4 系统配置与其它

• 应用显示配置（主题、语言、侧栏等，PC 客户端持久化）。
• 数据字典、操作审计（若已启用模块）。
• 文件上传与静态资源访问策略（如统一 /statics 经网关或 Nginx 回源，以部署为准）。

---

3. 记账域（Acc）功能范围

记账域覆盖 进销存、生产、库存、结算、记工 等；以下为常见子域，实施时以当前 schema.zmodel 与已启用模块为准。

3.1 主数据

• 商品（原料/成品等）、BOM、往来单位（供应商/客户/工人等）。
• 工种、工序、计价策略等与记工/结算相关配置。

3.2 仓储与流转

• 入库 / 出库：批次、成本与库存台账 AccStockLedger 等（以模型为准）。
• 库存流水：按站点查询与追溯。

3.3 生产

支持两类模式（详见 docs/guide/system-design.md）：

1. 一次过账：单张生产单扣料、产出、记工一并完成并关账。
2. 在制（WIP）+ 工序报工：开单扣料、报工增减产量与库存、关账重算单位成本；已结算记工支持冲红等（权限受限）。

3.4 结算与记工

• 勾选未结算记工生成结算单；与报工冲红产生的负行在后续结算中冲抵（业务规则以服务端为准）。
• Socket.IO（可选）用于实时通知类能力，部署依赖环境变量。

3.5 其它 Acc 能力

• 任务/工单类占位或扩展模块（以仓库实际代码为准）。
• 记账（Bookkeeping） 若已启用：账本、流水、分类统计等（前后端与 schema 同步维护）。

---

4. 小程序（移动端）功能范围

• 首页九宫格：展示后端下发的「小程序」类应用入口，可与本地常量合并（如「记一笔」等不依赖 RBAC 的入口）。
• 底部 Tab：首页、通知、我的等（以 pages.json 与 tab 配置为准）。
• 角色会话：从入口路径推断或显式设置 worker / recorder / manager 等，用于 Tab 与页面权限展示。
• 站点：多站点时首页左上角选择；请求携带 X-Site-Id。
• 人员认证：未绑定手机号等场景下，引导完成认证后方可使用部分能力（见 credential-gate 等逻辑）。

---

5. PC 管理端功能范围

• 顶栏分区：工作台、记账中心、系统管理等（由 app-shell-systems 与权限共同决定可见分区）。
• 侧栏/顶栏子导航：当前分区下的菜单项，随权限变化。
• 列表与表单：统一分页约定 PageResult / PageQueryDto（前后端对齐）。
• 使用引导：首次进入管理壳或从用户菜单打开，分步说明站点、分区、菜单与个人区（本地存储标记，版本键可 bump 以重新展示）。

---

6. 接口与集成约定（摘要）

• 路径前缀：/api/sys/*、/api/acc/* 经网关默认需 JWT；/api/no-check/... 及环境变量配置的路径可免 JWT。
• 统一响应：{ code, message, data }；列表页 data 内多为 PageResult<T>（records、total、current、size、pages）。
• 写操作风格：常见为 POST .../save、POST .../delete、POST .../page；与具体模块控制器一致。

---

7. 非功能需求与安全

• HTTPS 与密钥：生产环境必须配置合法 TLS、JWT_SECRET 与数据库凭据分离管理。
• 审计：敏感操作依赖后端审计与日志；网关可记录请求耗时与路径。
• 版本与文档：模型变更需 zen:generate 与受控迁移；同步更新 docs/guide/database-tables.md 等设计文档。

---

8. 引导与帮助入口（产品级）

端	行为	存储键（当前版本）
PC	首次登录进入管理壳后自动弹出；用户菜单「使用引导」可再次打开	taskflow_pc_product_guide_v1（localStorage，完成或跳过后写入）
小程序	（已移除首页自动引导；帮助以各页说明与「我的」内提示为准）	—

升级 PC 引导文案或希望老用户再看一遍时，可 bump 键名版本号 并同步更新 frontend/src/shared/lib/product-guide.ts 中的常量。

---

9. 参考文档索引

文档	说明
README.md	仓库结构、常用命令、环境变量入口
docs/guide/system-design.md	系统设计、权限、生产两种模式等
docs/guide/database-tables.md	表用途与 schema 对照
docs/guide/acc-accounting-features.md	记账域功能变更说明
backend/MICROSERVICES.md	端口、转发、探活等
《用户使用说明书》（同目录）	终端用户操作步骤