西藏巴青项目

牧场管理 — 功能需求

1. 文档说明

项	说明
模块名称	牧场管理
目标	对养殖主体（牧场/养殖户）基础信息进行登记、查询、维护与查阅，支撑产业数据体系中的主体台账与后续业务关联
关联系统	业务后台
修订依据	同目录 `牧场管理功能需求-草稿.md`、界面原型（`Snipaste_2026-05-19_09-27-45.jpg`）

本文档仅描述功能需求与业务规则，不涉及库表结构、接口路径、请求体字段命名、技术栈选型及实现方案。

2. 术语与枚举

2.1 牧场性质（单选）

取值	含义概要
个体	以个人身份经营的养殖主体
企业	以企业法人身份经营的养殖主体

2.2 经营状态（单选）

取值	含义概要
正常	在营，可参与常规业务（默认）
停业	暂停经营，主体档案保留
注销	终止经营，主体档案保留但宜在业务上视为失效

2.3 证件类型与「身份证号」字段含义

界面字段标签可统一为「身份证号」，其业务含义随牧场性质变化：

牧场性质	字段实际含义	校验要求（摘要）
个体	居民身份证号码	18 位居民身份证格式及校验位（末位可为 `X`/`x`），与项目全局身份证规则一致
企业	主体识别号（如统一社会信用代码）	符合企业主体识别号格式（建议 18 位字母数字组合；具体规则与项目全局「企业证照号」规范一致）

保存或提交时，系统须按当前所选牧场性质切换校验规则，错误提示宜区分「身份证格式错误」与「主体识别号格式错误」。

2.4 所属区域

层级： 省、市、县（区）三级行政区划级联选择。
要求： 须选至县级（含）为止，不可仅选省或市即提交（除非产品另行约定「允许只选到市级」）。

2.5 记录说明

本模块为主体台账，单条记录表示一个养殖主体（牧场）。
删除采用逻辑删除：删除后默认不在列表与常规统计中展示，数据可保留供审计或恢复策略（恢复能力若需实现须单独约定）。
地图标点功能本期不实现（见 §3、§8）。

3. 功能范围

本期实现：

牧场的新增、修改、逻辑删除、分页列表查询、详情查看
主体信息、所属区域、负责人与联系方式、经营状态、照片的录入与校验
按牧场名称关键字、牧场性质的列表筛选
列表操作：查看、编辑、删除；不含地图标点

本期不实现：

地图标点、经纬度采集与地图展示
与畜群、存栏、防疫等下游业务的关联维护（若需关联，另出需求）

4. 业务流程概览

flowchart LR
    A[新增牧场] --> B[列表查询/筛选]
    B --> C[查看详情]
    B --> D[修改牧场]
    B --> E[逻辑删除]
    D --> B
    E --> B

登记：录入主体信息、区域与联系方式，可选上传照片 → 形成一条牧场记录；经营状态默认正常。
查询：按名称关键字、牧场性质筛选，分页浏览列表。
维护：对已有记录修改任意业务字段；替换照片时清理旧图（实现阶段约定，需求层要求「不产生孤立文件」）。
查阅：查看单条记录全部字段；列表可进入详情或弹窗查看。
删除：逻辑删除；删除前宜二次确认；删除后默认列表不可见。

5. 详细功能需求

5.1 新增牧场

字段	规则
牧场名称	必填；长度 1～10 个字符（与界面「限 10 字」一致；字符计数与项目全局一致）
牧场性质	必填；单选，取值 §2.1（个体 / 企业）
身份证号	必填；含义与校验见 §2.3；须与当前「牧场性质」一致
所属区域	必填；省、市、县三级级联，须选至县级
详细地址	选填；若有内容，长度不超过 50 个字符
负责人	选填；若有内容，长度不超过 10 个字符
联系方式	必填；须为中国大陆手机号格式（如 11 位、号段规则与项目全局一致）
经营状态	必填；单选，取值 §2.2；新建时默认正常
照片	选填；单张图片；允许后缀 `jpg`、`jpeg`、`png`（可扩展 `webp` 须评审）；单文件 ≤ 10 MB

必填字段汇总： 牧场名称、牧场性质、身份证号（按性质校验）、所属区域（至县级）、联系方式、经营状态。

联动与校验：

切换「牧场性质」时，宜清空或重新校验「身份证号」输入，避免个体证件误用于企业。
各字段校验失败时须给出可区分的错误提示。
若业务要求「牧场名称」在管辖范围内唯一，须在评审时单独约定并写入本节。

5.2 查询牧场列表

关键字： 对「牧场名称」进行模糊匹配；关键字为空时不按名称过滤。
牧场性质： 精确匹配筛选；未选择时不按性质过滤。
经营状态： 本期草稿未要求列表筛选项；若界面提供「经营状态」筛选，则为精确匹配，规则与 §2.2 一致（实现前与产品确认）。
逻辑删除： 默认不展示已逻辑删除记录；是否提供「含已删除」查看能力须单独约定。
分页： 默认 每页 20 条，首页为第一页；单页条数上限与项目列表通用规范一致。
排序： 默认按 创建时间倒序（最新登记在前）；相同时间下次要排序键与项目列表规范一致（若有）。
重置： 支持一键清空查询条件并恢复默认列表（与界面「重置」一致）。

列表宜展示： 牧场名称、牧场性质、身份证号（可按脱敏规则展示）、所在区域（省市区拼接）、详细地址、负责人、联系方式（可脱敏）、经营状态、操作列（查看 / 编辑 / 删除）；地图标点入口本期不展示或置灰并提示「暂未开放」。

5.3 修改牧场

可修改项： 牧场名称、牧场性质、身份证号、所属区域、详细地址、负责人、联系方式、经营状态、照片（全部业务字段均可修改）。
保存约束： 须重新满足 §5.1 全部校验；必填项不得为空。
性质变更： 若修改「牧场性质」，须按新性质重新校验「身份证号」；不允许保留与性质不匹配的证件号。
照片替换： 上传新照片并保存成功后，旧照片文件宜从存储中删除，避免残留（与项目附件管理惯例一致）。
经营状态变更： 允许在 正常 / 停业 / 注销 之间变更；是否限制「注销后不可改回正常」须在评审时约定（默认：允许改回，便于纠错）。

5.4 删除牧场（逻辑删除）

允许删除： 具备删除权限的用户可对单条或多条记录执行删除（是否支持批量删除与项目列表惯例一致）。
删除方式： 逻辑删除，非物理抹库；删除后该主体在默认列表与常规统计中不可见。
删除后果：
- 已逻辑删除记录不宜被下游业务当作有效主体引用（若存在关联，须在关联模块约定校验）。
- 照片文件是否立即删除或保留至归档策略，实现阶段与运维约定；需求层要求删除操作可审计（谁、何时删除）。
确认： 删除前宜弹出确认提示，避免误删。
恢复： 是否提供「恢复已删除」管理功能，本期不强制；若需要须单独需求。

5.5 查看牧场详情

展示内容： 牧场名称、牧场性质、身份证号、所属区域（省 / 市 / 县）、详细地址、负责人、联系方式、经营状态、照片（可预览）；宜展示创建人、创建时间、最后修改人、最后修改时间（若系统有审计字段）。
敏感信息： 身份证号、手机号在列表/详情是否脱敏，按项目安全规范与角色权限约定。
交互： 具备编辑权限的用户可从详情进入编辑（见 §5.3）；只读账号仅可查看。

5.6 地图标点（本期不实现）

列表操作列原型含「地图标点」；本期不实现点位采集、地图展示与坐标存储。
若后续实现，须单独修订本文档，约定：坐标字段、与地址关系、权限及是否在「注销」主体上禁止标点等。

6. 操作权限矩阵（汇总）

在已授权前提下：

操作	说明
查看	具备查询权限即可
新增	具备新增权限即可
修改	具备修改权限即可
删除	具备删除权限即可；逻辑删除前确认
地图标点	本期无

菜单与按钮级权限（查询、新增、修改、删除、导出等）按项目角色配置，具体标识在技术方案或权限配置文档中定义。

7. 错误与提示约定

业务与校验错误宜采用项目统一的 code、msg、data 结构呈现，便于前端统一处理。
常见提示宜可区分，例如：
- 必填项缺失、字段超长或格式不符；
- 个体身份证与企业主体识别号校验失败；
- 所属区域未选至县级；
- 照片格式或大小不符；
- 删除确认取消与删除失败原因。

8. 非功能需求（建议）

类别	建议
权限	菜单与按钮：查询、新增、修改、删除；敏感字段完整查看是否分角色
审计	新增、修改、逻辑删除记操作日志
安全	上传照片类型与大小校验；预览与下载鉴权
性能	列表按名称、性质筛选满足后台通用体验
数据质量	行政区划数据与国家标准或项目区划库一致，避免「市辖区」等异常选项
双语	字段标签与提示符合项目 i18n 规范（汉语 + 藏文）
扩展	地图标点、主体与产业业务关联、名称唯一性、已删除恢复

9. 修订说明（相对草稿）

草稿问题	优化处理
条目编号跳跃（1～5 后直接 10～12）	重整为 §5 分节与连续叙述
混入技术栈、接口响应格式	技术栈移除；错误结构保留于 §7（不涉及接口设计）
「身份证号」未区分个体/企业	新增 §2.3 联动校验说明
所属区域、详细地址、负责人必填性不清	区域必填至县；地址、负责人选填；与界面必填项对齐并注明差异
逻辑删除后果未写清	§2.5、§5.2、§5.4 补充默认不可见、关联与审计建议
地图标点写在需求条目中	明确 §3、§5.6 本期不实现
列表缺重置、排序、展示列	§5.2 补充
经营状态仅枚举未说明默认	§2.2 默认「正常」及变更策略
界面称「养殖户」、文档称「牧场」	§1 统一为养殖主体（牧场），允许界面文案沿用「养殖户」

10. 功能需求追溯（自查）

能力	对应章节
新增与字段校验	§5.1、§2.3
列表查询与筛选	§5.2
修改与照片替换	§5.3
逻辑删除	§5.4
详情查看	§5.5
地图标点（不做）	§3、§5.6
权限与错误提示	§6、§7

牧场管理功能需求.md 12KB 文件歷史 原始文件