Spec: 智能手环供应链尽调重构

Objective

为校园 4G 防拆智能手环建立可审计的元器件成本与方案商尽调体系，使管理层可完成候选池、成本边界与采购策略决策，并使供应商在不接触内部底牌的前提下按统一产品、成本和证据标准响应。

Users

• 内部：管理层、采购、技术、质量、法务。
• 外部：参与项目技术与商务澄清的候选供应商。

Product Baseline

• 场景：6–18 岁学生、校园管理。
• 连接：4G Cat.1 + BLE，内置 eSIM。
• 定位：GPS/北斗 + 信标/AoA 区域定位。
• 传感：PPG、6轴 IMU、贴肤温度。
• 交互：0.96 英寸 TFT、触控、SOS、抬腕亮屏。
• 结构：防拆表带、IP67、150–180mAh、磁吸充电。
• 平台：甲方云直连、MQTT/CoAP、TLS、OTA 与数据合规。
• 合规：无线、进网、电池、材料、生物相容性及儿童数据要求，最终适用性须由检测/法务矩阵确认。

Deliverables

1. 核心元器件成本、替代料和权威来源档案。
2. 行业规模采购基准 BOM 与供应商可实现 BOM。
3. 市场扫描、准入候选池和逐家深度尽调。
4. 索证清单、技术会问题、验厂清单和报价模板。
5. 内部管理层版静态 HTML（9页）。
6. 供应商通用版静态 HTML（8页）。
7. 可下钻的详细文档、证据目录和方法说明。

Information Architecture

Internal

总览｜定义｜成本｜器件｜市场｜选型｜证据｜商务｜路线

Supplier

目标｜定义｜基准｜器件｜能力｜认证｜合作｜计划

页面主题使用 2–4 个汉字；每页包含一个结论、一个主图、至多一个辅助表、一个行动和一个证据入口。

Data Model

Component price record

component_id, price_item_id, comparison_role, category, manufacturer, part_number, package, specification, source_url, source_type, source_grade, currency, unit_price, quantity_break, region, tax_basis, freight_basis, access_date, valid_date, notes

component_id 必须引用 C01–C31 受控组件；price_item_id 用于区分具体料号、渠道、服务或RFQ价格项。 comparison_role 区分可评估候选、仅作非等效参考和RFQ缺口；仅候选记录可进入成本覆盖与量价曲线。

Supplier evidence record

supplier_id, legal_entity, dimension, claim, evidence_state, risk_level, source_url_or_file, source_date, verification_action, owner, status

Evidence states

• 已核验；公开披露；交叉佐证；分析测算；待索证；冲突待裁决。

Risk levels

• R0 已满足；R1 观察；R2 条件准入；R3 阻断。

Cost Method

• 整机首单量与方案商年度元器件合并采购量分开建模。
• 直接采用公开阶梯价，不对缺失阶梯伪造插值；模型插值须明确标为分析测算。
• 公开有标价但未披露数量阶梯时，保留单价并将数量记为空；该记录不进入规模曲线或可实现BOM。
• 公开无 5,000 片价格时，可采用更大公开采购阶梯作为行业规模锚。
• 供应商可实现成本须结合规模、出货、直采、账期和采购渠道证据。
• 币种换算记录汇率来源与日期；税、运费和损耗独立列示。

Technical Direction

• 现状为静态 HTML/CSS/JavaScript + 本地 ECharts，无依赖清单。
• 当前可用运行时：Python 3.14.6、Node.js 24.10.0、npm 11.6.0；仓库内未发现 package.json、pyproject.toml 或 requirements 文件。
• 新版保持静态、可离线、可打印；结构化数据作为唯一内容来源。
• 使用确定性构建脚本生成内部版、供应商版和详细页面；不在运行时访问外部 API。
• 内外版本必须由不同输出目录与数据白名单生成，不通过前端开关隐藏敏感内容。
• 具体构建语言、Markdown 渲染方式和版本在基础任务完成后锁定，并以官方文档验证。
• 构建依赖固定为 Python-Markdown 3.10.3（仅构建期），使用内置 tables、fenced_code、sane_lists 与 toc 扩展生成详细HTML；原始Markdown同时保留。

Code & Content Style

• 页面主题 2–4 个汉字；结论句不使用口号、隐喻或对抗性措辞。
• 正式文本采用“结论—证据—影响—动作”。
• 禁止将未检出写成不存在；禁止把模型称为实际成本或报价水分。
• 金额、日期、数量和料号使用等宽数字并统一单位/小数位。
• 红色只表示阻断、偏离和决策动作；待核验使用赭色；证据与风险编码分离。

Commands

确定性命令： - 环境：python3 -m venv .venv && .venv/bin/python -m pip install --require-hashes -r requirements.txt - 单元测试：.venv/bin/python -m unittest discover -s tests -p 'test_*.py' - 图表逻辑测试：node --test tests/test_report_data.js tests/test_report_charts.js - 数据校验：.venv/bin/python -m scripts.validate_data - 成本复算：.venv/bin/python -m scripts.calculate_costs - 完整构建与校验：.venv/bin/python -m scripts.build_all - 链接与供应商包检查：.venv/bin/python -m scripts.check_outputs - 本地预览：.venv/bin/python -m http.server 8000 -d dist

Project Structure

data/                 结构化来源、价格、BOM、供应商与证据记录
docs/components/      元器件详细档案
docs/suppliers/       供应商详细尽调
docs/methodology/     方法与口径
docs/templates/       RFQ、索证、技术会与验厂模板
docs/spec/            正式规格
scripts/              校验、计算与构建脚本
src/                  HTML/CSS/JS 模板与共用组件
dist/internal/        内部管理层版输出
dist/supplier/        供应商通用版输出
tasks/                实施计划与任务清单

Testing Strategy

• 数据：必填字段、类型、重复、数量阶梯、币种、公式与范围校验。
• 计算：BOM 可由原始价格记录逐项复算，区间和假设可追溯。
• 内容：链接有效、证据状态存在、禁用绝对化/对抗性措辞。
• 权限：供应商输出不得包含内部目标价、排名、BATNA、非公开报价和内部供应商档案。
• 浏览器：桌面、移动、键盘、缩减动效、打印分页、控制台和资源加载。

Boundaries

• Always：记录来源、日期、口径、证据状态；保留冲突；从结构化数据构建。
• Ask first：新增运行时依赖、部署到外部、联系供应商、购买付费数据、改变产品定义。
• Never：伪造批量价；把推断写成事实；在供应商版泄露内部信息；修改第三方压缩库源码。

Success Criteria

• 每一类核心元器件至少有主选、替代路线、数量阶梯、成本区间和可复核来源；无可靠公开价时明确待 RFQ。
• 行业规模 BOM 与供应商可实现 BOM 的每个数字均可追溯、复算并标明假设。
• 市场扫描范围和准入逻辑可复现；约 8–15 家候选均有统一深调档案和证据状态。
• 内部版严格遵守 9 页主题，供应商版严格遵守 8 页主题。
• 供应商版不包含任何内部目标价、其他供应商实名排名、BATNA 或非公开报价。
• 两版在真实浏览器中无控制台错误，关键图表、下钻与打印可用。

Open Questions

• 星迈以外各候选供应商的正式项目周期由供应商自行提交；内部仅保留情景比较。
• 需在研究阶段确认最终受控 BOM 型号、适用认证和测试口径。
• 非公开大批量价格和真实产能只能通过供应商材料、RFQ 与验厂闭环。
• 构建优先使用 Python 标准库与现有本地 ECharts；如 Markdown 渲染确需新增依赖，将先核对官方文档与离线分发影响。